@aparte/n8n-chat 0.5.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +598 -507
- package/dist/cdn/chunks/chunk-4MZPEZPE.js +209 -0
- package/dist/cdn/chunks/chunk-4MZPEZPE.js.map +7 -0
- package/dist/cdn/chunks/{chunk-A2H2YABP.js → chunk-HASLYSSG.js} +2 -2
- package/dist/cdn/chunks/{chunk-A2H2YABP.js.map → chunk-HASLYSSG.js.map} +1 -1
- package/dist/cdn/chunks/{chunk-GJ4YMVTA.js → chunk-KPADIE5S.js} +1 -1
- package/dist/cdn/chunks/{chunk-GJ4YMVTA.js.map → chunk-KPADIE5S.js.map} +1 -1
- package/dist/cdn/chunks/{chunk-J2RB5NH4.js → chunk-LGVX5DQP.js} +2 -2
- package/dist/cdn/chunks/{chunk-J2RB5NH4.js.map → chunk-LGVX5DQP.js.map} +1 -1
- package/dist/cdn/chunks/chunk-PPDOW5CO.js +379 -0
- package/dist/cdn/chunks/chunk-PPDOW5CO.js.map +7 -0
- package/dist/cdn/chunks/{chunk-27HPUSEO.js → chunk-XY3GEFGN.js} +2 -2
- package/dist/cdn/chunks/{chunk-27HPUSEO.js.map → chunk-XY3GEFGN.js.map} +1 -1
- package/dist/cdn/chunks/de-VHSIFTGU.js +2 -0
- package/dist/cdn/chunks/de-VHSIFTGU.js.map +7 -0
- package/dist/cdn/chunks/es-CSDZBDZK.js +2 -0
- package/dist/cdn/chunks/es-CSDZBDZK.js.map +7 -0
- package/dist/cdn/chunks/fr-A7LKKK4U.js +2 -0
- package/dist/cdn/chunks/fr-A7LKKK4U.js.map +7 -0
- package/dist/cdn/chunks/{highlight-SCSTGNZJ.js → highlight-IMZBI6FV.js} +2 -2
- package/dist/cdn/chunks/{highlight-SCSTGNZJ.js.map → highlight-IMZBI6FV.js.map} +1 -1
- package/dist/cdn/chunks/it-4UDH2XVX.js +2 -0
- package/dist/cdn/chunks/it-4UDH2XVX.js.map +7 -0
- package/dist/cdn/chunks/{items-TBASSOQ3.js → items-FFNVAESC.js} +3 -3
- package/dist/cdn/chunks/{items-TBASSOQ3.js.map → items-FFNVAESC.js.map} +4 -4
- package/dist/cdn/chunks/ja-5FMFPBXT.js +2 -0
- package/dist/cdn/chunks/ja-5FMFPBXT.js.map +7 -0
- package/dist/cdn/chunks/ko-KXXFK5U7.js +2 -0
- package/dist/cdn/chunks/ko-KXXFK5U7.js.map +7 -0
- package/dist/cdn/chunks/{link-VR62DJAD.js → link-3AMG5PIK.js} +3 -3
- package/dist/cdn/chunks/link-3AMG5PIK.js.map +7 -0
- package/dist/cdn/chunks/{media-O7WQHRGC.js → media-F3HYZLYR.js} +4 -4
- package/dist/cdn/chunks/{media-O7WQHRGC.js.map → media-F3HYZLYR.js.map} +4 -4
- package/dist/cdn/chunks/{order-H7FHTQ2J.js → order-L6GKT5I6.js} +3 -3
- package/dist/cdn/chunks/{order-H7FHTQ2J.js.map → order-L6GKT5I6.js.map} +3 -3
- package/dist/cdn/chunks/{place-TGHDGFFI.js → place-J7BDZGKL.js} +3 -3
- package/dist/cdn/chunks/{place-TGHDGFFI.js.map → place-J7BDZGKL.js.map} +4 -4
- package/dist/cdn/chunks/{plan-JA7466PF.js → plan-BAI6GY4A.js} +3 -3
- package/dist/cdn/chunks/{plan-JA7466PF.js.map → plan-BAI6GY4A.js.map} +4 -4
- package/dist/cdn/chunks/{product-VEI5FUDZ.js → product-VOKQKP4K.js} +3 -3
- package/dist/cdn/chunks/{product-VEI5FUDZ.js.map → product-VOKQKP4K.js.map} +4 -4
- package/dist/cdn/chunks/pt-BR-T2PIW5LH.js +2 -0
- package/dist/cdn/chunks/pt-BR-T2PIW5LH.js.map +7 -0
- package/dist/cdn/chunks/ru-CWHLBHXX.js +2 -0
- package/dist/cdn/chunks/ru-CWHLBHXX.js.map +7 -0
- package/dist/cdn/chunks/{score-QTZEGTBP.js → score-IPBHXWWN.js} +6 -6
- package/dist/cdn/chunks/{score-QTZEGTBP.js.map → score-IPBHXWWN.js.map} +4 -4
- package/dist/cdn/chunks/{stats-CNVSRBY6.js → stats-V6H3J3WL.js} +2 -2
- package/dist/cdn/chunks/{stats-CNVSRBY6.js.map → stats-V6H3J3WL.js.map} +1 -1
- package/dist/cdn/chunks/{stock-2KHFILSB.js → stock-UNSEZYGA.js} +2 -2
- package/dist/cdn/chunks/{stock-2KHFILSB.js.map → stock-UNSEZYGA.js.map} +1 -1
- package/dist/cdn/chunks/{weather-FAK6EHSV.js → weather-4IMAIRYF.js} +2 -2
- package/dist/cdn/chunks/{weather-FAK6EHSV.js.map → weather-4IMAIRYF.js.map} +1 -1
- package/dist/cdn/chunks/zh-CN-UEBLECMR.js +2 -0
- package/dist/cdn/chunks/zh-CN-UEBLECMR.js.map +7 -0
- package/dist/cdn/n8n-chat.js +61 -61
- package/dist/cdn/n8n-chat.js.map +4 -4
- package/dist/create-chat.d.ts +27 -2
- package/dist/index.js +18 -5
- package/dist/index.js.map +1 -1
- package/dist/strings.d.ts +5 -0
- package/dist/style.css +411 -415
- package/dist/theme.css +409 -413
- package/package.json +83 -83
- package/dist/cdn/chunks/chunk-7CJVMXIB.js +0 -356
- package/dist/cdn/chunks/chunk-7CJVMXIB.js.map +0 -7
- package/dist/cdn/chunks/chunk-N7SVHDCW.js +0 -206
- package/dist/cdn/chunks/chunk-N7SVHDCW.js.map +0 -7
- package/dist/cdn/chunks/de-NQDMZC5V.js +0 -2
- package/dist/cdn/chunks/de-NQDMZC5V.js.map +0 -7
- package/dist/cdn/chunks/es-IBJAOBGB.js +0 -2
- package/dist/cdn/chunks/es-IBJAOBGB.js.map +0 -7
- package/dist/cdn/chunks/fr-32HJELG3.js +0 -2
- package/dist/cdn/chunks/fr-32HJELG3.js.map +0 -7
- package/dist/cdn/chunks/it-HHSL2KBW.js +0 -2
- package/dist/cdn/chunks/it-HHSL2KBW.js.map +0 -7
- package/dist/cdn/chunks/ja-2EHR4WNO.js +0 -2
- package/dist/cdn/chunks/ja-2EHR4WNO.js.map +0 -7
- package/dist/cdn/chunks/ko-XONDEFR4.js +0 -2
- package/dist/cdn/chunks/ko-XONDEFR4.js.map +0 -7
- package/dist/cdn/chunks/link-VR62DJAD.js.map +0 -7
- package/dist/cdn/chunks/pt-BR-367NLYVE.js +0 -2
- package/dist/cdn/chunks/pt-BR-367NLYVE.js.map +0 -7
- package/dist/cdn/chunks/ru-ETHLBBSY.js +0 -2
- package/dist/cdn/chunks/ru-ETHLBBSY.js.map +0 -7
- package/dist/cdn/chunks/zh-CN-OGEW5BS2.js +0 -2
- package/dist/cdn/chunks/zh-CN-OGEW5BS2.js.map +0 -7
package/README.md
CHANGED
|
@@ -1,507 +1,598 @@
|
|
|
1
|
-
# @aparte/n8n-chat
|
|
2
|
-
|
|
3
|
-
**n8n's chat widget, drawn by [aparté](https://apartejs.dev).** `createChat()` takes
|
|
4
|
-
[`@n8n/chat`](https://www.npmjs.com/package/@n8n/chat)'s options and mounts the same widget on
|
|
5
|
-
your n8n Chat Trigger — a button in the corner, or a block in your page. Change the import, keep
|
|
6
|
-
your call. And your workflow can answer with **rich cards** — an order, a booking, a product, the
|
|
7
|
-
weather — and offer **quick replies** the visitor clicks. [See it live](https://n8n-chat.apartejs.dev).
|
|
8
|
-
|
|
9
|
-
<p>
|
|
10
|
-
<img src="https://raw.githubusercontent.com/apartejs/n8n-chat/
|
|
11
|
-
<img src="https://raw.githubusercontent.com/apartejs/n8n-chat/
|
|
12
|
-
</p>
|
|
13
|
-
|
|
14
|
-
- Rich cards your workflow writes as text: weather, order and booking, product, place, list, key
|
|
15
|
-
figures, stock, plan, score, media, link. n8n's own chat shows the same answer as a code block.
|
|
16
|
-
- Quick replies your workflow offers the same way: buttons above the input (free times, "Yes" /
|
|
17
|
-
"No"), sent with one click.
|
|
18
|
-
- Extensible: your own cards, and aparté's plugins (maths, diagrams, charts) through `setup`.
|
|
19
|
-
- Every option of `@n8n/chat` 1.43, the same defaults, the same session in the browser — and the
|
|
20
|
-
Chat nodes' messages and buttons of a workflow that answers through response nodes.
|
|
21
|
-
- Ten languages, keyboard and screen-reader access, readable contrast, a dark scheme.
|
|
22
|
-
- About
|
|
23
|
-
- A handle to drive it from your page: `open`, `close`, `toggle`, `send`, `reset`, `setDisabled`,
|
|
24
|
-
`destroy`.
|
|
25
|
-
- MIT. A small grey "Powered by aparté" line sits under the input, linking to [apartejs.dev](https://apartejs.dev).
|
|
26
|
-
|
|
27
|
-
## Install
|
|
28
|
-
|
|
29
|
-
### From a CDN — no build step
|
|
30
|
-
|
|
31
|
-
```html
|
|
32
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@0.
|
|
33
|
-
<script type="module">
|
|
34
|
-
import { createChat } from 'https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@0.
|
|
35
|
-
|
|
36
|
-
createChat({ webhookUrl: 'https://your-n8n.example.com/webhook/<id>/chat' });
|
|
37
|
-
</script>
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
`dist/cdn/n8n-chat.js` is one module with aparté inside it. What only some pages need is fetched
|
|
41
|
-
when used, from beside it: a language other than English, and the code highlighter with the first
|
|
42
|
-
code block. Keep the version in the URL: the widget you tested is the widget your visitors get.
|
|
43
|
-
|
|
44
|
-
### From npm
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
npm install @aparte/n8n-chat
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
```ts
|
|
51
|
-
import { createChat } from '@aparte/n8n-chat';
|
|
52
|
-
import '@aparte/n8n-chat/style.css';
|
|
53
|
-
|
|
54
|
-
const chat = createChat({ webhookUrl: 'https://your-n8n.example.com/webhook/<id>/chat' });
|
|
55
|
-
chat.open();
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
## Coming from `@n8n/chat`
|
|
59
|
-
|
|
60
|
-
Replace the stylesheet and the import; the call stays as it is:
|
|
61
|
-
|
|
62
|
-
```diff
|
|
63
|
-
- <link href="https://cdn.jsdelivr.net/npm/@n8n/chat/dist/style.css" rel="stylesheet" />
|
|
64
|
-
+ <link href="https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@0.
|
|
65
|
-
<script type="module">
|
|
66
|
-
- import { createChat } from 'https://cdn.jsdelivr.net/npm/@n8n/chat/dist/chat.bundle.es.js';
|
|
67
|
-
+ import { createChat } from 'https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@0.
|
|
68
|
-
createChat({ webhookUrl: 'https://your-n8n.example.com/webhook/<id>/chat' });
|
|
69
|
-
</script>
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
The session is kept where n8n's widget keeps it (`localStorage`, key `n8n-chat/sessionId`), so a
|
|
73
|
-
visitor keeps their conversation across the switch. `enableStreaming` needs no tuning: a streamed
|
|
74
|
-
answer and a whole one are both read.
|
|
75
|
-
|
|
76
|
-
## Set up the workflow
|
|
77
|
-
|
|
78
|
-
In the **Chat Trigger** node:
|
|
79
|
-
|
|
80
|
-
1. Turn on **Make Chat Publicly Available**. The production URL that ends in `/chat` is your
|
|
81
|
-
`webhookUrl`.
|
|
82
|
-
2. Put your site's origin in **Allowed Origins (CORS)**.
|
|
83
|
-
3. Choose how it answers, under **Response Mode**:
|
|
84
|
-
- **Streaming** — the AI Agent streams its answer as it writes it;
|
|
85
|
-
- **When Last Node Finishes** — one whole answer;
|
|
86
|
-
- **Using Response Nodes** — Chat nodes send the messages, and can ask questions with buttons
|
|
87
|
-
(see [Response nodes and buttons](#response-nodes-and-buttons)).
|
|
88
|
-
4. **Publish** the workflow.
|
|
89
|
-
|
|
90
|
-
To show a visitor's earlier messages after a reload, attach a memory to the agent, set **Load
|
|
91
|
-
Previous Session** to **From Memory**, and connect that memory to the Chat Trigger as well: with the
|
|
92
|
-
memory on the agent only, n8n answers that request with an error.
|
|
93
|
-
|
|
94
|
-
## Options
|
|
95
|
-
|
|
96
|
-
| Option | What it does | Default |
|
|
97
|
-
| --- | --- | --- |
|
|
98
|
-
| `webhookUrl` | the Chat Trigger's production URL, ending in `/chat` | required |
|
|
99
|
-
| `webhookConfig` | `headers` sent with every request, read each time (a refreshed token is sent); `method` is accepted, every request is a POST | `{}` |
|
|
100
|
-
| `target` | where it mounts: an element, or a selector | `'#n8n-chat'` |
|
|
101
|
-
| `mode` | `'window'` (a button in the corner) or `'embedded'` (a block in the page, filling its target; `'fullscreen'`, `@n8n/chat`'s name for it, works too) | `'window'` |
|
|
102
|
-
| `showWindowCloseButton` | a ✕ in the header, in window mode | `false` |
|
|
103
|
-
| `showWelcomeScreen` | a screen with a "New Conversation" button first | `false` |
|
|
104
|
-
| `loadPreviousSession` | keep the session in the browser and show its earlier messages | `true` |
|
|
105
|
-
| `sessionId` | use this session instead of the stored one | — |
|
|
106
|
-
| `chatInputKey`, `chatSessionKey` | the body fields the workflow reads | `'chatInput'`, `'sessionId'` |
|
|
107
|
-
| `defaultLanguage` | the language, as a tag (`'de'`, `'pt-BR'`) | `'en'` |
|
|
108
|
-
| `i18n` | the chrome's words by language, over the built-in ones | — |
|
|
109
|
-
| `locale` | the chat's own words, for a language not shipped | — |
|
|
110
|
-
| `initialMessages` | messages shown first, from the assistant | n8n's two |
|
|
111
|
-
| `messageHistory` | a conversation to show when n8n has none (text, `type: 'component'`, `transparent`) | — |
|
|
112
|
-
| `messageComponents` | functions that draw `type: 'component'` history messages | — |
|
|
113
|
-
| `metadata` | sent with every message, as `metadata` in the trigger's output | — |
|
|
114
|
-
| `allowFileUploads`, `allowedFilesMimeTypes` | let the person attach files, and which (`'image/*,application/pdf'`, extensions too) | `false`, any |
|
|
115
|
-
| `cards` | draw the ` ```card-<name> ` blocks of an answer as [cards](#cards-and-quick-replies-from-a-text-answer); an object gives a card its options (`{ place: { mapTiles } }`) | `true` |
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
chat
|
|
134
|
-
|
|
135
|
-
chat.
|
|
136
|
-
chat.
|
|
137
|
-
chat.
|
|
138
|
-
|
|
139
|
-
chat.
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
shows the
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
````
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
`
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
}
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
.aparte-
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
widget
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
1
|
+
# @aparte/n8n-chat
|
|
2
|
+
|
|
3
|
+
**n8n's chat widget, drawn by [aparté](https://apartejs.dev).** `createChat()` takes
|
|
4
|
+
[`@n8n/chat`](https://www.npmjs.com/package/@n8n/chat)'s options and mounts the same widget on
|
|
5
|
+
your n8n Chat Trigger — a button in the corner, or a block in your page. Change the import, keep
|
|
6
|
+
your call. And your workflow can answer with **rich cards** — an order, a booking, a product, the
|
|
7
|
+
weather — and offer **quick replies** the visitor clicks. [See it live](https://n8n-chat.apartejs.dev).
|
|
8
|
+
|
|
9
|
+
<p>
|
|
10
|
+
<img src="https://raw.githubusercontent.com/apartejs/n8n-chat/v1.0.0/docs/widget-card-order.png" alt="The widget answering where order 1001 is, with the order's card: its items, its status and its total, and a small Powered by aparté line under the input" width="300">
|
|
11
|
+
<img src="https://raw.githubusercontent.com/apartejs/n8n-chat/v1.0.0/docs/widget-card-dark.png" alt="The same widget in its dark scheme, answering about order 1002 with its card" width="300">
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
- Rich cards your workflow writes as text: weather, order and booking, product, place, list, key
|
|
15
|
+
figures, stock, plan, score, media, link. n8n's own chat shows the same answer as a code block.
|
|
16
|
+
- Quick replies your workflow offers the same way: buttons above the input (free times, "Yes" /
|
|
17
|
+
"No"), sent with one click.
|
|
18
|
+
- Extensible: your own cards, and aparté's plugins (maths, diagrams, charts) through `setup`.
|
|
19
|
+
- Every option of `@n8n/chat` 1.43, the same defaults, the same session in the browser — and the
|
|
20
|
+
Chat nodes' messages and buttons of a workflow that answers through response nodes.
|
|
21
|
+
- Ten languages, keyboard and screen-reader access, readable contrast, a dark scheme.
|
|
22
|
+
- About 155 KB compressed on the first load, against about 471 KB (measured 2026-11-10 on 1.0.1; `@n8n/chat` 1.44.7 on 2026-10-31).
|
|
23
|
+
- A handle to drive it from your page: `open`, `close`, `toggle`, `send`, `reset`, `setDisabled`,
|
|
24
|
+
`destroy`.
|
|
25
|
+
- MIT. A small grey "Powered by aparté" line sits under the input, linking to [apartejs.dev](https://apartejs.dev).
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
### From a CDN — no build step
|
|
30
|
+
|
|
31
|
+
```html
|
|
32
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@1.0.1/dist/style.css">
|
|
33
|
+
<script type="module">
|
|
34
|
+
import { createChat } from 'https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@1.0.1/dist/cdn/n8n-chat.js';
|
|
35
|
+
|
|
36
|
+
createChat({ webhookUrl: 'https://your-n8n.example.com/webhook/<id>/chat' });
|
|
37
|
+
</script>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`dist/cdn/n8n-chat.js` is one module with aparté inside it. What only some pages need is fetched
|
|
41
|
+
when used, from beside it: a language other than English, and the code highlighter with the first
|
|
42
|
+
code block. Keep the version in the URL: the widget you tested is the widget your visitors get.
|
|
43
|
+
|
|
44
|
+
### From npm
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm install @aparte/n8n-chat
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
import { createChat } from '@aparte/n8n-chat';
|
|
52
|
+
import '@aparte/n8n-chat/style.css';
|
|
53
|
+
|
|
54
|
+
const chat = createChat({ webhookUrl: 'https://your-n8n.example.com/webhook/<id>/chat' });
|
|
55
|
+
chat.open();
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Coming from `@n8n/chat`
|
|
59
|
+
|
|
60
|
+
Replace the stylesheet and the import; the call stays as it is:
|
|
61
|
+
|
|
62
|
+
```diff
|
|
63
|
+
- <link href="https://cdn.jsdelivr.net/npm/@n8n/chat/dist/style.css" rel="stylesheet" />
|
|
64
|
+
+ <link href="https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@1.0.1/dist/style.css" rel="stylesheet" />
|
|
65
|
+
<script type="module">
|
|
66
|
+
- import { createChat } from 'https://cdn.jsdelivr.net/npm/@n8n/chat/dist/chat.bundle.es.js';
|
|
67
|
+
+ import { createChat } from 'https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@1.0.1/dist/cdn/n8n-chat.js';
|
|
68
|
+
createChat({ webhookUrl: 'https://your-n8n.example.com/webhook/<id>/chat' });
|
|
69
|
+
</script>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The session is kept where n8n's widget keeps it (`localStorage`, key `n8n-chat/sessionId`), so a
|
|
73
|
+
visitor keeps their conversation across the switch. `enableStreaming` needs no tuning: a streamed
|
|
74
|
+
answer and a whole one are both read.
|
|
75
|
+
|
|
76
|
+
## Set up the workflow
|
|
77
|
+
|
|
78
|
+
In the **Chat Trigger** node:
|
|
79
|
+
|
|
80
|
+
1. Turn on **Make Chat Publicly Available**. The production URL that ends in `/chat` is your
|
|
81
|
+
`webhookUrl`.
|
|
82
|
+
2. Put your site's origin in **Allowed Origins (CORS)**.
|
|
83
|
+
3. Choose how it answers, under **Response Mode**:
|
|
84
|
+
- **Streaming** — the AI Agent streams its answer as it writes it;
|
|
85
|
+
- **When Last Node Finishes** — one whole answer;
|
|
86
|
+
- **Using Response Nodes** — Chat nodes send the messages, and can ask questions with buttons
|
|
87
|
+
(see [Response nodes and buttons](#response-nodes-and-buttons)).
|
|
88
|
+
4. **Publish** the workflow.
|
|
89
|
+
|
|
90
|
+
To show a visitor's earlier messages after a reload, attach a memory to the agent, set **Load
|
|
91
|
+
Previous Session** to **From Memory**, and connect that memory to the Chat Trigger as well: with the
|
|
92
|
+
memory on the agent only, n8n answers that request with an error.
|
|
93
|
+
|
|
94
|
+
## Options
|
|
95
|
+
|
|
96
|
+
| Option | What it does | Default |
|
|
97
|
+
| --- | --- | --- |
|
|
98
|
+
| `webhookUrl` | the Chat Trigger's production URL, ending in `/chat` | required |
|
|
99
|
+
| `webhookConfig` | `headers` sent with every request, read each time (a refreshed token is sent); `method` is accepted, every request is a POST | `{}` |
|
|
100
|
+
| `target` | where it mounts: an element, or a selector | `'#n8n-chat'` |
|
|
101
|
+
| `mode` | `'window'` (a button in the corner) or `'embedded'` (a block in the page, filling its target; `'fullscreen'`, `@n8n/chat`'s name for it, works too) | `'window'` |
|
|
102
|
+
| `showWindowCloseButton` | a ✕ in the header, in window mode | `false` |
|
|
103
|
+
| `showWelcomeScreen` | a screen with a "New Conversation" button first | `false` |
|
|
104
|
+
| `loadPreviousSession` | keep the session in the browser and show its earlier messages | `true` |
|
|
105
|
+
| `sessionId` | use this session instead of the stored one | — |
|
|
106
|
+
| `chatInputKey`, `chatSessionKey` | the body fields the workflow reads | `'chatInput'`, `'sessionId'` |
|
|
107
|
+
| `defaultLanguage` | the language, as a tag (`'de'`, `'pt-BR'`) | `'en'` |
|
|
108
|
+
| `i18n` | the chrome's words by language, over the built-in ones | — |
|
|
109
|
+
| `locale` | the chat's own words, for a language not shipped | — |
|
|
110
|
+
| `initialMessages` | messages shown first, from the assistant | n8n's two |
|
|
111
|
+
| `messageHistory` | a conversation to show when n8n has none (text, `type: 'component'`, `transparent`) | — |
|
|
112
|
+
| `messageComponents` | functions that draw `type: 'component'` history messages | — |
|
|
113
|
+
| `metadata` | sent with every message, as `metadata` in the trigger's output | — |
|
|
114
|
+
| `allowFileUploads`, `allowedFilesMimeTypes` | let the person attach files, and which (`'image/*,application/pdf'`, extensions too) | `false`, any |
|
|
115
|
+
| `cards` | draw the ` ```card-<name> ` blocks of an answer as [cards](#cards-and-quick-replies-from-a-text-answer); an object gives a card its options (`{ place: { mapTiles } }`) | `true` |
|
|
116
|
+
| `images` | which [pictures in an answer](#pictures-in-an-answer) load by themselves: every one, or only those from the origins you list (`['https://cdn.example.com']`; the others wait for a click) | every one |
|
|
117
|
+
| `waitingPrefix` | where your n8n serves a Chat node's button links, when the webhook URL does not tell ([buttons](#response-nodes-and-buttons)) | read from the webhook URL |
|
|
118
|
+
| `setup` | `(config) => stop?`: aparté's plugins and your own cards, on this chat ([below](#your-own-cards-and-apartés-plugins)) | — |
|
|
119
|
+
| `enableMessageActions` | "Repost" and "Reuse" on the person's own messages | `false` |
|
|
120
|
+
| `disabled` | block the input (`true`, or n8n's `{ value }`) | `false` |
|
|
121
|
+
| `beforeMessageSent`, `afterMessageSent` | hooks around each message | — |
|
|
122
|
+
| `suggestions` | questions offered above the input until the first message | — |
|
|
123
|
+
| `replies` | show the [quick replies](#quick-replies) an answer offers (a ` ```suggestions ` block) above the input | `true` |
|
|
124
|
+
| `colorScheme` | `'light'`, `'dark'` or `'auto'` (the visitor's) | `'light'` |
|
|
125
|
+
| `fetch` | the `fetch` every request goes through | the global one |
|
|
126
|
+
| `enableStreaming`, `theme` | accepted for compatibility | — |
|
|
127
|
+
|
|
128
|
+
## The handle
|
|
129
|
+
|
|
130
|
+
`createChat()` returns what your page drives it with:
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
const chat = createChat({ webhookUrl });
|
|
134
|
+
|
|
135
|
+
chat.open(); // open the window (close, toggle too)
|
|
136
|
+
chat.send('Where is my order?'); // as the visitor; waits for an answer on its way
|
|
137
|
+
chat.reset(); // a new conversation, in a new session
|
|
138
|
+
chat.setDisabled(true); // block the input, or let the visitor type again
|
|
139
|
+
chat.destroy(); // remove it (unmount does the same)
|
|
140
|
+
|
|
141
|
+
chat.sessionId; // the session the conversation runs in
|
|
142
|
+
chat.element; // the widget's root element
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Response nodes and buttons
|
|
146
|
+
|
|
147
|
+
A Chat Trigger set to **Using Response Nodes** answers through **Chat** nodes placed in the
|
|
148
|
+
workflow. Each message a Chat node sends is drawn as a block of its own. A Chat node that **waits
|
|
149
|
+
for a written reply** gets the visitor's next message. A Chat node that **waits for an approval**
|
|
150
|
+
sends buttons, asked above the input with the labels you gave them; the one chosen goes back to n8n
|
|
151
|
+
and the workflow carries on.
|
|
152
|
+
|
|
153
|
+
**Block User Input**, on that Chat node, decides whether the visitor may write instead of choosing:
|
|
154
|
+
on, the answer has to be a button; off, the words reach n8n as a message and the node goes on as
|
|
155
|
+
not approved — as with n8n's own widget.
|
|
156
|
+
|
|
157
|
+
Up to n8n 2.45, Chat nodes run only when the Chat Trigger's **Mode** is **Hosted Chat**; an
|
|
158
|
+
embedded one stops with "Embedded chat is not supported". n8n 2.46 and 3.0 lift that limit and run
|
|
159
|
+
them in **Embedded** mode too; the widget has been tested with Hosted Chat. A button whose link
|
|
160
|
+
leads off your n8n is not shown, nor one whose link does not resume the running execution. The
|
|
161
|
+
widget reads where n8n's waiting links live from the webhook URL. Set `waitingPrefix` (a path) when
|
|
162
|
+
they live elsewhere: your own `N8N_ENDPOINT_WEBHOOK_WAIT`, or your own `N8N_ENDPOINT_WEBHOOK` (a
|
|
163
|
+
webhook URL that is not `…/webhook/<id>/chat`), where no button shows until you do.
|
|
164
|
+
|
|
165
|
+
## Cards and quick replies, from a text answer
|
|
166
|
+
|
|
167
|
+
n8n's chat carries only text, so anything richer travels as text, with one rule: **a code block
|
|
168
|
+
whose language the widget knows becomes part of the chat; any other is shown as code.** Two
|
|
169
|
+
languages are known: `card-<name>` draws a card, `suggestions` offers quick replies.
|
|
170
|
+
|
|
171
|
+
### Quick replies
|
|
172
|
+
|
|
173
|
+
The choices your workflow just offered, as buttons above the input, so the visitor clicks instead of
|
|
174
|
+
typing: free times, "Return an item", "Yes" / "No".
|
|
175
|
+
|
|
176
|
+
````md
|
|
177
|
+
Which day suits you?
|
|
178
|
+
|
|
179
|
+
```suggestions
|
|
180
|
+
["Tuesday 4", "Wednesday 5", "Thursday 6"]
|
|
181
|
+
```
|
|
182
|
+
````
|
|
183
|
+
|
|
184
|
+
Nothing of the block shows in the message; the replies are the last answer's, a click sends one as
|
|
185
|
+
if it were typed, and they go when a message is sent. A string, or an object's `label`, is both what
|
|
186
|
+
is shown and what is sent: a `prompt` beside it is ignored, so a button never sends words the
|
|
187
|
+
visitor did not read. A reply is 1 to 100 visible characters: a blank one, a longer one or one
|
|
188
|
+
holding invisible characters is left out (the console says so), so a label built from data — a
|
|
189
|
+
long product name — is best shortened.
|
|
190
|
+
The [booking workflow](https://n8n-chat.apartejs.dev/#workflows) offers its days and times this way:
|
|
191
|
+
the agent calls a small **Suggest replies** tool, and a Code node writes the block. `replies: false`
|
|
192
|
+
shows the blocks as code.
|
|
193
|
+
|
|
194
|
+
### Rich cards
|
|
195
|
+
|
|
196
|
+
A card is a code block whose language names the card, holding its fields as JSON, after the
|
|
197
|
+
sentence that answers.
|
|
198
|
+
|
|
199
|
+
````md
|
|
200
|
+
Order 1001 left our warehouse two days ago.
|
|
201
|
+
|
|
202
|
+
```card-order
|
|
203
|
+
{ "number": "1001", "status": "shipped", "total": "68.00", "currency": "EUR",
|
|
204
|
+
"line_items": [{ "name": "Linen shirt", "quantity": 1, "total": "49.00" },
|
|
205
|
+
{ "name": "Canvas tote bag", "quantity": 1, "total": "19.00" }] }
|
|
206
|
+
```
|
|
207
|
+
````
|
|
208
|
+
|
|
209
|
+
The widget draws the block as the card; n8n's own chat, an email or a model reading the history back
|
|
210
|
+
shows the sentence and the code. The cards: `weather`, `order` (a booking too, with
|
|
211
|
+
`"kind": "booking"`), `product`, `place`, `items`, `stats`, `stock`, `plan`, `score`, `media`,
|
|
212
|
+
`link`. Their fields are those of [`@aparte/plugin-cards`](https://apartejs.dev/guides/cards/), whose
|
|
213
|
+
readers also take the shapes shops already return (WooCommerce and Shopify orders, schema.org
|
|
214
|
+
products). Each card's code is fetched the first time an answer uses it.
|
|
215
|
+
|
|
216
|
+
Build the block in a **Code** node from your tool's real result rather than asking the model to
|
|
217
|
+
write JSON: it is exact every time, and a setting can turn it off for a chat that does not draw
|
|
218
|
+
cards. The [shop and booking workflows](https://n8n-chat.apartejs.dev/#workflows) do it that way.
|
|
219
|
+
`cards: false` shows the blocks as code.
|
|
220
|
+
|
|
221
|
+
A card's own options go in `cards`, handed to it when it loads. The place card, for one, draws a map
|
|
222
|
+
of its own and fetches nothing; give it your map tiles and a place with `coordinates` sits on a real
|
|
223
|
+
map:
|
|
224
|
+
|
|
225
|
+
```js
|
|
226
|
+
createChat({
|
|
227
|
+
webhookUrl: 'YOUR_PRODUCTION_URL',
|
|
228
|
+
cards: {
|
|
229
|
+
place: {
|
|
230
|
+
mapTiles: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
|
|
231
|
+
mapAttribution: '© OpenStreetMap contributors',
|
|
232
|
+
},
|
|
233
|
+
},
|
|
234
|
+
});
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Each tile is a request from the visitor's browser to that server, which is why it is your choice:
|
|
238
|
+
OpenStreetMap's tiles need no key but have [a usage policy](https://operations.osmfoundation.org/policies/tiles/)
|
|
239
|
+
against heavy traffic; MapTiler's or Stadia's take your key in the address.
|
|
240
|
+
|
|
241
|
+
## Your own cards, and aparté's plugins
|
|
242
|
+
|
|
243
|
+
The widget is built with [aparté](https://apartejs.dev), and `setup` hands you its config: anything
|
|
244
|
+
aparté does, this chat can do. A card of your own is a `defineCard`, and your workflow sends it as
|
|
245
|
+
` ```card-<its name> `:
|
|
246
|
+
|
|
247
|
+
```js
|
|
248
|
+
import { createChat, defineCard, el } from '@aparte/n8n-chat';
|
|
249
|
+
|
|
250
|
+
const ticket = defineCard({
|
|
251
|
+
name: 'ticket',
|
|
252
|
+
variants: ['card'],
|
|
253
|
+
// A card draws its own padding, from the kit's variable, as the shipped cards do.
|
|
254
|
+
styles: '.aparte-ticket-card { padding: var(--aparte-rich-card-padding) } .aparte-ticket-card .id { font-weight: 600 }',
|
|
255
|
+
icon: '<svg viewBox="0 0 24 24"><path d="M4 6h16v12H4z" fill="none" stroke="currentColor"/></svg>',
|
|
256
|
+
normalize: (raw) => (raw?.id ? { id: String(raw.id), subject: String(raw.subject ?? ''), status: raw.status } : null),
|
|
257
|
+
render: (t) => [el('span', { class: 'id', text: t.id }), el('p', { text: t.subject }), el('small', { text: t.status })],
|
|
258
|
+
skeleton: () => [],
|
|
259
|
+
label: (t) => `Ticket ${t?.id ?? ''}`,
|
|
260
|
+
fallback: (t) => `Ticket ${t.id}: ${t.subject}`,
|
|
261
|
+
});
|
|
262
|
+
|
|
263
|
+
createChat({
|
|
264
|
+
webhookUrl: '…',
|
|
265
|
+
setup: (config) => ticket.setup({ config }),
|
|
266
|
+
});
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Take `defineCard` from the widget's own module, as above, and from the same URL when you load
|
|
270
|
+
it from a CDN (`…/@aparte/n8n-chat@1.0.1/dist/cdn/n8n-chat.js`): the card and the chat then share
|
|
271
|
+
one copy of aparté. A kit loaded from another URL keeps its cards where the chat never looks.
|
|
272
|
+
|
|
273
|
+
````md
|
|
274
|
+
Your ticket is open.
|
|
275
|
+
|
|
276
|
+
```card-ticket
|
|
277
|
+
{ "id": "T-42", "subject": "Refund for order 1001", "status": "Waiting for us" }
|
|
278
|
+
```
|
|
279
|
+
````
|
|
280
|
+
|
|
281
|
+
The same `setup` adds aparté's plugins — maths, diagrams, charts — each in one line:
|
|
282
|
+
|
|
283
|
+
```js
|
|
284
|
+
import { setupKatex } from '@aparte/plugin-katex';
|
|
285
|
+
import 'katex/dist/katex.min.css'; // KaTeX's own sheet: without it a formula shows twice
|
|
286
|
+
import { setupMermaid } from '@aparte/plugin-mermaid';
|
|
287
|
+
|
|
288
|
+
createChat({
|
|
289
|
+
webhookUrl: '…',
|
|
290
|
+
setup: (config) => {
|
|
291
|
+
const stops = [setupKatex({}, config), setupMermaid({}, config)];
|
|
292
|
+
return () => stops.forEach((stop) => stop());
|
|
293
|
+
},
|
|
294
|
+
});
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
What `setup` returns, if a function, runs on `destroy()`.
|
|
298
|
+
|
|
299
|
+
### All of aparté, at three levels
|
|
300
|
+
|
|
301
|
+
The widget's options keep `@n8n/chat`'s names so a page switches without rewriting, but everything
|
|
302
|
+
underneath is aparté, and you can reach it:
|
|
303
|
+
|
|
304
|
+
- **The config** — `setup(config)` hands you the chat's own `AparteConfig`: plugins, cards, segment
|
|
305
|
+
and tool renderers, icons (`config.registerIcons`), the locale (`config.setLocale`), the actions on a
|
|
306
|
+
message (`config.registerAction`). See the [configuration guide](https://apartejs.dev/guides/customization/).
|
|
307
|
+
- **The elements** — `chat.element` is the widget's root; the chat inside it is aparté's
|
|
308
|
+
`<aparte-chat>`, its field `<aparte-composer>`, and their attributes are theirs to set:
|
|
309
|
+
|
|
310
|
+
```js
|
|
311
|
+
const chat = createChat({ webhookUrl: '…' });
|
|
312
|
+
chat.element.querySelector('aparte-composer')?.setAttribute('placeholder', 'Ask about your order…');
|
|
313
|
+
```
|
|
314
|
+
- **The look** — aparté's `--aparte-*` variables, beside n8n's `--chat--*` ones:
|
|
315
|
+
|
|
316
|
+
```css
|
|
317
|
+
/* n8n's variables for what n8n's widget already styles; aparté's for the rest. */
|
|
318
|
+
.aparte-n8n { --chat--message--border-radius: 14px; --aparte-font-family: 'Inter', sans-serif; }
|
|
319
|
+
/* The theme maps some aparté tokens from n8n's on the chat itself: set those there. */
|
|
320
|
+
.aparte-n8n aparte-chat { --aparte-radius-input: 20px; }
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
What does not apply here is what needs the agent's loop in the page — a tool run in the browser, an
|
|
324
|
+
approval of a tool call: an n8n workflow runs its tools itself, on n8n.
|
|
325
|
+
|
|
326
|
+
## The page the visitor is on
|
|
327
|
+
|
|
328
|
+
`metadata` is sent with every message and reaches the workflow as `$json.metadata`. Send the page,
|
|
329
|
+
and the workflow knows which product "this one" is:
|
|
330
|
+
|
|
331
|
+
```js
|
|
332
|
+
createChat({
|
|
333
|
+
webhookUrl: '…',
|
|
334
|
+
metadata: { page: location.href, title: document.title },
|
|
335
|
+
});
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
## In the page, not in a corner
|
|
339
|
+
|
|
340
|
+
`mode: 'embedded'` puts the chat in your page as a block, filling its `target`, which needs a
|
|
341
|
+
height. `'fullscreen'`, `@n8n/chat`'s name for the same mode, works too.
|
|
342
|
+
|
|
343
|
+
```html
|
|
344
|
+
<div id="support-chat" style="height: 600px"></div>
|
|
345
|
+
<script type="module">
|
|
346
|
+
createChat({ webhookUrl: '…', target: '#support-chat', mode: 'embedded' });
|
|
347
|
+
</script>
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
## Files
|
|
351
|
+
|
|
352
|
+
With `allowFileUploads`, the visitor picks, drops or pastes files, and n8n receives them as
|
|
353
|
+
`files`, as from n8n's widget. A file can be removed with the keyboard; a picture or a file the
|
|
354
|
+
visitor sent opens in a new tab.
|
|
355
|
+
|
|
356
|
+
## Pictures in an answer
|
|
357
|
+
|
|
358
|
+
A picture an answer names loads by itself, as in n8n's own widget: nothing to set. If your workflow
|
|
359
|
+
reads content you do not control — e-mails, web pages, a document a visitor sends — name the
|
|
360
|
+
origins your pictures come from. A model steered by such content can write the conversation into a
|
|
361
|
+
picture's address, and the browser fetches it without a click; with `images`, any other picture
|
|
362
|
+
waits behind a link that names its host, until the visitor clicks it. The same list decides a
|
|
363
|
+
media card's video and sound.
|
|
364
|
+
|
|
365
|
+
```js
|
|
366
|
+
createChat({ webhookUrl: '…', images: ['https://cdn.example.com'] });
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
An origin is written with its scheme: `'https://cdn.example.com'` (a bare host allows nothing).
|
|
370
|
+
`'self'` is your page's own origin, `true` or `'*'` every picture, `false` none by itself, and a
|
|
371
|
+
function decides each address (`'load'`, `'hold'` or `'drop'`).
|
|
372
|
+
|
|
373
|
+
## Keeping bots out
|
|
374
|
+
|
|
375
|
+
A public Chat Trigger answers anyone who finds its URL, and every answer can cost you a call to
|
|
376
|
+
your AI model. [Cloudflare Turnstile](https://www.cloudflare.com/application-services/products/turnstile/)
|
|
377
|
+
— free, and usually invisible to people — lets the workflow stop a bot before the model runs. The
|
|
378
|
+
widget needs no option for it: `metadata` is read at each send and `beforeMessageSent` is awaited,
|
|
379
|
+
so the page puts a fresh token in `metadata` before every message.
|
|
380
|
+
|
|
381
|
+
1. In Cloudflare, add a Turnstile widget for your site's hostname. You get a **site key** (for the
|
|
382
|
+
page) and a **secret key** (for n8n).
|
|
383
|
+
2. In the page:
|
|
384
|
+
|
|
385
|
+
```html
|
|
386
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@1.0.1/dist/style.css">
|
|
387
|
+
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
|
|
388
|
+
<div id="turnstile"></div>
|
|
389
|
+
<script type="module">
|
|
390
|
+
import { createChat } from 'https://cdn.jsdelivr.net/npm/@aparte/n8n-chat@1.0.1/dist/cdn/n8n-chat.js';
|
|
391
|
+
|
|
392
|
+
// A Turnstile token is single-use and lasts five minutes: ask for a new one before each message.
|
|
393
|
+
let widgetId;
|
|
394
|
+
let pending;
|
|
395
|
+
function turnstileToken() {
|
|
396
|
+
return new Promise((resolve, reject) => {
|
|
397
|
+
pending = { resolve, reject };
|
|
398
|
+
if (widgetId === undefined) {
|
|
399
|
+
widgetId = turnstile.render('#turnstile', {
|
|
400
|
+
sitekey: '<your site key>',
|
|
401
|
+
execution: 'execute',
|
|
402
|
+
appearance: 'interaction-only', // shown only when Cloudflare needs the visitor to click
|
|
403
|
+
callback: (token) => pending.resolve(token),
|
|
404
|
+
'error-callback': () => pending.reject(new Error('Turnstile could not check this visitor')),
|
|
405
|
+
});
|
|
406
|
+
} else {
|
|
407
|
+
turnstile.reset(widgetId);
|
|
408
|
+
}
|
|
409
|
+
turnstile.execute('#turnstile');
|
|
410
|
+
});
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
const metadata = {};
|
|
414
|
+
createChat({
|
|
415
|
+
webhookUrl: 'https://your-n8n.example.com/webhook/<id>/chat',
|
|
416
|
+
metadata,
|
|
417
|
+
beforeMessageSent: async () => {
|
|
418
|
+
metadata.turnstileToken = await turnstileToken();
|
|
419
|
+
},
|
|
420
|
+
});
|
|
421
|
+
</script>
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
3. In the workflow, between the Chat Trigger and your agent:
|
|
425
|
+
- an **HTTP Request** node: `POST https://challenges.cloudflare.com/turnstile/v0/siteverify`,
|
|
426
|
+
body as JSON:
|
|
427
|
+
`{{ JSON.stringify({ secret: '<your secret key>', response: $json.metadata?.turnstileToken ?? '' }) }}`
|
|
428
|
+
(anyone who can open the workflow can read the secret there);
|
|
429
|
+
- an **If** node on `{{ $json.success }}` is true;
|
|
430
|
+
- on its true branch, an **Edit Fields (Set)** node in JSON mode that gives the trigger's message
|
|
431
|
+
back, so the agent and its memory read `chatInput` and `sessionId` as before:
|
|
432
|
+
`{{ JSON.stringify($('When chat message received').item.json) }}`;
|
|
433
|
+
- then your agent. The false branch ends there: nothing reaches the model.
|
|
434
|
+
|
|
435
|
+
When Cloudflare refuses a visitor, the widget shows its usual "couldn't answer" message and nothing
|
|
436
|
+
is sent. A visitor's reply to a waiting Chat node goes over the execution's WebSocket, which was
|
|
437
|
+
opened by a checked message, so it needs no token. A bot that calls the webhook directly still
|
|
438
|
+
starts an execution, a short one (on n8n Cloud, executions count against your plan); only a proxy in
|
|
439
|
+
front of n8n stops it earlier. Checked on n8n 2.45.7 with Cloudflare's test keys, text messages
|
|
440
|
+
only: with file uploads, check that your agent still receives the files after the Set node.
|
|
441
|
+
|
|
442
|
+
## Languages
|
|
443
|
+
|
|
444
|
+
Ten ship: English, French, Spanish, Portuguese (Brazil), German, Italian, Russian, Japanese, Korean
|
|
445
|
+
and Chinese (Simplified). A page downloads only the language it uses.
|
|
446
|
+
|
|
447
|
+
### Pick one
|
|
448
|
+
|
|
449
|
+
```js
|
|
450
|
+
createChat({
|
|
451
|
+
webhookUrl: '…',
|
|
452
|
+
defaultLanguage: 'fr', // a tag: 'de', 'pt-BR', 'zh-CN'… 'fr-CA' reads in French
|
|
453
|
+
});
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
The header, the first messages, the input and the chat's own words (its buttons, its error card,
|
|
457
|
+
what a screen reader hears) all switch. To follow the visitor's browser, pass
|
|
458
|
+
`defaultLanguage: navigator.language`: a language not shipped reads in English, left to right,
|
|
459
|
+
until you give its words ([below](#another-language-right-to-left-included)); `i18n` words under
|
|
460
|
+
`ar` serve `ar-SA` too.
|
|
461
|
+
|
|
462
|
+
### Change a few words
|
|
463
|
+
|
|
464
|
+
`i18n` takes the header's and the input's words by language, over the built-in ones:
|
|
465
|
+
|
|
466
|
+
```js
|
|
467
|
+
createChat({
|
|
468
|
+
webhookUrl: '…',
|
|
469
|
+
defaultLanguage: 'fr',
|
|
470
|
+
i18n: { fr: { title: 'Bonjour 👋', subtitle: 'Une question sur votre commande ?', inputPlaceholder: 'Votre question…' } },
|
|
471
|
+
initialMessages: ['Bonjour ! Comment puis-je vous aider ?'],
|
|
472
|
+
});
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
The keys: `title`, `subtitle`, `footer`, `inputPlaceholder`, `getStarted`, `closeButtonTooltip`,
|
|
476
|
+
`poweredBy` (`{aparte}` stands for the link), `repostButton` and `reuseButton`.
|
|
477
|
+
|
|
478
|
+
### Another language, right to left included
|
|
479
|
+
|
|
480
|
+
A language that does not ship takes its words from you: `i18n` for the header and the input, and
|
|
481
|
+
aparté's locale, through `setup`, for the chat's own. Arabic, Hebrew, Persian, Urdu and the other
|
|
482
|
+
right-to-left languages turn the whole widget right to left from their tag alone — header, messages,
|
|
483
|
+
input, and the launcher, which moves to the bottom left — even on a left-to-right page. Code, a
|
|
484
|
+
formula or an English answer inside it still read left to right.
|
|
485
|
+
|
|
486
|
+
```js
|
|
487
|
+
createChat({
|
|
488
|
+
webhookUrl: '…',
|
|
489
|
+
defaultLanguage: 'ar',
|
|
490
|
+
i18n: {
|
|
491
|
+
ar: {
|
|
492
|
+
title: 'مرحبا 👋',
|
|
493
|
+
subtitle: 'نحن هنا لمساعدتك.',
|
|
494
|
+
inputPlaceholder: 'اكتب سؤالك…',
|
|
495
|
+
closeButtonTooltip: 'إغلاق',
|
|
496
|
+
poweredBy: 'بدعم من {aparte}',
|
|
497
|
+
},
|
|
498
|
+
},
|
|
499
|
+
initialMessages: ['مرحبا! كيف يمكنني مساعدتك اليوم؟'],
|
|
500
|
+
// The chat's own words, over the English ones: the type lists every key.
|
|
501
|
+
setup: (config) => config.setLocale({ ...config.getLocale(), tag: 'ar', sendButton: 'إرسال', copy: 'نسخ' }),
|
|
502
|
+
});
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
A page that is right to left already (`<html dir="rtl">`) needs nothing more: the widget follows it in
|
|
506
|
+
any language.
|
|
507
|
+
|
|
508
|
+
## Colors
|
|
509
|
+
|
|
510
|
+
Your brand color, in one line. It colors the visitor's bubble, the send button, the links and the
|
|
511
|
+
button in the corner, in light and in dark:
|
|
512
|
+
|
|
513
|
+
```css
|
|
514
|
+
:root {
|
|
515
|
+
--chat--color--secondary: #c2410c;
|
|
516
|
+
}
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
Keep white text readable on it: 4.5:1 or more (n8n's own `#20b69e` gives 2.55:1, which is why the
|
|
520
|
+
default here is `#178272`). Two more lines give the chat its own surroundings:
|
|
521
|
+
|
|
522
|
+
```css
|
|
523
|
+
:root {
|
|
524
|
+
--chat--header--background: #9a3412; /* the bar with the title */
|
|
525
|
+
--chat--body--background: #fbf2ec; /* behind the messages, in light */
|
|
526
|
+
}
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
| Variable | What it changes | When unset |
|
|
530
|
+
| --- | --- | --- |
|
|
531
|
+
| `--chat--color--secondary` | your bubble, the send button, links; tints the dark surfaces | `#178272` |
|
|
532
|
+
| `--chat--color--primary` | the button in the corner, when it should differ | `--secondary`, else n8n's `#e74266` |
|
|
533
|
+
| `--chat--header--background` / `--chat--header--color` | the title bar, in light and in dark | n8n's navy / `#f2f4f8` |
|
|
534
|
+
| `--chat--body--background` | behind the messages (light) | `#f2f4f8` |
|
|
535
|
+
| `--chat--message--bot--background` / `--chat--message--user--background` | one side's bubbles | white / `--secondary` |
|
|
536
|
+
| `--chat--font-family`, `--chat--border-radius`, `--chat--window--width` / `--height` | type, corners, the window | n8n's |
|
|
537
|
+
|
|
538
|
+
Hovers are derived from the color they darken, so one color never hovers back to n8n's green.
|
|
539
|
+
|
|
540
|
+
**Dark.** `colorScheme: 'dark'` always, `'auto'` when the visitor's system is dark (n8n's widget has
|
|
541
|
+
no dark scheme). It keeps your header and tints its navy with your `--secondary`, so the line above
|
|
542
|
+
is enough. For your own dark surfaces, set aparté's variables on the widget when it is dark:
|
|
543
|
+
|
|
544
|
+
```css
|
|
545
|
+
.aparte-n8n[data-aparte-theme='dark'] { /* colorScheme: 'dark' */
|
|
546
|
+
--aparte-bg: #1a100a; /* behind the messages */
|
|
547
|
+
--aparte-surface-1: #2a1a11; /* the field, the cards */
|
|
548
|
+
--aparte-border: #4a2c1d;
|
|
549
|
+
--aparte-message-content-bg-assistant: #2c1b12;
|
|
550
|
+
}
|
|
551
|
+
/* colorScheme: 'auto': the same, inside @media (prefers-color-scheme: dark)
|
|
552
|
+
on .aparte-n8n:not([data-aparte-theme]) */
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
A page that themed n8n's widget keeps its variables; CSS written against n8n's `.chat-*` classes
|
|
556
|
+
does not carry over. Try a color, a header and the dark scheme side by side on
|
|
557
|
+
[n8n-chat.apartejs.dev](https://n8n-chat.apartejs.dev/#demo), which writes the CSS for you. `@aparte/n8n-chat/theme.css` is the n8n
|
|
558
|
+
look alone, for a chat you compose yourself with
|
|
559
|
+
[`@aparte/runner-n8n`](https://apartejs.dev/providers/agent/n8n/) and aparté's React, Vue, Svelte
|
|
560
|
+
or Angular components, inside an `.aparte-n8n` element.
|
|
561
|
+
|
|
562
|
+
## Compared with `@n8n/chat`
|
|
563
|
+
|
|
564
|
+
| | `@n8n/chat` (options checked on 1.43.3, weight on 1.44.7) | `@aparte/n8n-chat` |
|
|
565
|
+
| --- | --- | --- |
|
|
566
|
+
| Drive it from the page | — | `open`, `close`, `toggle`, `send`, `reset`, `setDisabled`, `destroy` |
|
|
567
|
+
| A new conversation | not until the browser's storage is cleared | `reset()` |
|
|
568
|
+
| A tool's steps after a reload | bubbles with raw JSON | left out, as while chatting |
|
|
569
|
+
| An error | the raw message | a sentence in the visitor's language; the workflow's own words and what to fix, on the console |
|
|
570
|
+
| Languages | English | ten, loaded one at a time |
|
|
571
|
+
| Keyboard and screen reader | buttons without names | named controls, a labelled window, a modal sheet on a phone |
|
|
572
|
+
| Contrast of the visitor's bubble | 2.55:1 | 4.7:1 (WCAG AA) |
|
|
573
|
+
| Dark scheme | — | ✓ |
|
|
574
|
+
| Rich cards | the JSON as text | drawn: order, booking, product, weather… |
|
|
575
|
+
| Quick replies offered by an answer | the block as code | buttons above the input |
|
|
576
|
+
| Weight, first load (compressed) | ~471 KB | ~155 KB |
|
|
577
|
+
| License | Sustainable Use License | MIT |
|
|
578
|
+
|
|
579
|
+
## Versions
|
|
580
|
+
|
|
581
|
+
From 1.0.0 the widget follows semantic versioning: the options of `createChat`, the handle it
|
|
582
|
+
returns, what the module exports (the card kit included), the `i18n` keys, the `--chat--*`
|
|
583
|
+
variables, the `.aparte-n8n` root with its `data-aparte-theme`, and the files a page loads
|
|
584
|
+
(`dist/cdn/n8n-chat.js`, `dist/style.css`, `./theme.css`) keep their names, and what they do, until
|
|
585
|
+
2.0. A security fix may refuse what was accepted in any release, and says so first in its notes.
|
|
586
|
+
|
|
587
|
+
The widget depends on **exact** versions of aparté's packages, and moves to a newer aparté only in
|
|
588
|
+
a release of its own. Pin the widget's version in a CDN URL and in your `package.json`, and what you
|
|
589
|
+
tested is what your visitors run.
|
|
590
|
+
|
|
591
|
+
## Links
|
|
592
|
+
|
|
593
|
+
- [n8n-chat.apartejs.dev](https://n8n-chat.apartejs.dev) — the live demo, and workflows to start from.
|
|
594
|
+
- [aparté](https://apartejs.dev) — the library it is built with.
|
|
595
|
+
- [`@aparte/runner-n8n`](https://apartejs.dev/providers/agent/n8n/) — the n8n protocol alone, to put
|
|
596
|
+
an n8n workflow behind a chat you compose yourself.
|
|
597
|
+
|
|
598
|
+
MIT © Paul Richez
|