Liveblocks Workshop: Set up

This repo contains a demo chat application that allows you to use Liveblocks agents session through n8n, enabling you to build complex AI workflows. Feel free to extend it, and make it your own.

CleanShot.2026-01-21.at.14.09.04.mp4

Explanation

What is n8n?

n8n is a workflow interface that lets you connect together different applications and APIs, ideal for building multi-step AI agents. Working like a flowchart, each item is called a node (not related to Node.js). We've created a set of Liveblocks nodes, that allow you to interact with our APIs via n8n.

Agent sessions

Agent sessions is a new Liveblocks feature we've been developing. Each session is a real-time message store, which allows you to place in any data you like. When data is placed inside, it will update immediately for all connected users.

This project has a chat setup that creates/fetches an agent session for you when a chat message is sent, then triggers your n8n webhook. Within n8n we have a node that lets you add a new message, "Add Agent Message". In our app, we can see that the useAgentSession update hook updates with the new message whenever this is called.

Additionally, agent presence allows you to show the active status of an AI agent, for example "Thinking...", or "Searching...". This project is set up to display a "Thinking..." message when the AI is generating text, and this works using the "Update Presence" node.

The whole flow

Here's how this n8n flow works. The file for the workflow is n8n-chat-workflow.json which you'll import into n8n later.

Set up Node.js

A Node.js version between 22.16-24.X is required.

• If you don't already have Node.js installed, make sure to install v24 from the website.
• If you already have Node.js installed, make sure to use 22.16-24.X. It's easy to switch versions with nvm.

Clone this repo

1. Clone, install, and run this repo.

git clone https://github.com/liveblocks/boilerplate-n8n-hackathon.git
npm install
npm run dev

2. Sign up to https://development.liveblocks.io, create a project in the dashboard, and copy your secret API key.

3. Put your secret key in a .env.local file in the root of this project.

LIVEBLOCKS_SECRET_KEY=sk_...

Set up n8n

1. Install n8n via terminal.

npm install -g n8n

2. Go to http://localhost:5678/ + sign up. If you don't see a sign up page, run n8n user-management:reset.
3. Stop n8n (cmd+c / ctrl+c).
4. Download and install the custom Liveblocks n8n nodes.

cd ~/.n8n
mkdir custom
cd custom
mkdir node_modules
cd node_modules
git clone https://github.com/liveblocks/n8n-nodes
cd n8n-nodes
npm install
npm run build
n8n start

5. Go back to n8n, click the Credentials page, and add credentials for “Liveblocks API”, pasting in your secret key from earlier.

6. Create an "Open AI" credential in the same way—ask our team and we'll give you our OpenAI API key.

Run the pre-built workflow

1. Download the n8n-chat-workflow.json file in this repo.
2. In n8n, go to the Overview page and hit “Create Workflow” in the top-right
3. Open the menu at the top-right and import the n8n-chat-workflow.json file, found at the root of this project.

4. Open the first node, copy the "Production URL", and "Publish" your app.

CleanShot.2026-01-21.at.14.21.53.mp4

5. Paste the Production URL into the .env.local file in the project.

N8N_WEBHOOK_URL=http://localhost:5678/webhook/...

6. You can now use your AI chat!

CleanShot.2026-01-21.at.14.09.04-trimmed.mp4

7. Extend your app! Add more nodes, link up to various apps, for example:

• Read events from your Google Calendar and answer questions.
• Create new issues on Linear, and link to them.
• Generate documents on Notion, and suggest further changes.

...and much more—happy hacking!

Troubleshooting

• Make sure you have Node 22.16 or greater
• Make sure you use a Secret Key from https://development.liveblocks.io
• If n8n seems buggy, try creating a new workflow
• If you need to tunnel for Webhooks, use ngrok or npx localtunnel --port 5678