Chat trigger reference
The Chat message received trigger's panel, the fields your workflow receives, the reply format, and how sessions and memory work.
Overview
The Chat message received trigger starts one workflow run for each message a visitor sends to the chatbot it answers, and shows the visitor what the workflow's Respond node returns.
This page covers the trigger. The chatbot itself, including what it says first, where it is shared, the message limits, and each message a visitor can see, is covered in the chatbot reference.
The panel
The trigger's panel picks the chatbot this workflow answers, and nothing else.
| In the panel | What it does |
|---|---|
| Search chatbots… | Opens the list of chatbots this workflow may answer. Each is marked "(live)" or "(draft)". |
| New chatbot | Creates a draft chatbot for this workspace's client and picks it. Uses the name you typed in the search box. |
| Open chatbot | Opens the picked chatbot's builder in a new tab. |
| Change | Clears the pick so you can choose another chatbot. |
Which chatbots are listed
- Agency-brand chatbots, which have no client.
- Chatbots that belong to the client whose workspace the workflow is in.
Another client's chatbots are not listed. A chatbot that a different workflow already answers is listed with "Used by" and that workflow's name, and cannot be picked: one chatbot is answered by one workflow.
What the panel can tell you
| Message | What to do |
|---|---|
| "This chatbot is a draft. Open it to publish." | Click Open chatbot and publish the chatbot. Until then visitors cannot reach it. |
| "This chatbot now belongs to another client, so this workflow no longer answers it. Pick another chatbot or change its client back." | Click Change and pick another chatbot, or set the chatbot's client back. |
| "Selected chatbot is unavailable." | The chatbot was deleted or can no longer be read. Click Change. |
| "No chatbots yet. Create one to answer with this workflow." | Click New chatbot. |
Trigger fields
Every run's $trigger has this shape:
{
"message": "Do you open on Sundays?",
"sessionId": "0b9f6c1e-6f0a-4c56-9d0e-0f3d2a8f5b11",
"metadata": {
"source": "embed",
"pageUrl": "https://www.example.com/pricing",
"locale": "en-US"
}
}| Field | Type | Always present | Description |
|---|---|---|---|
$trigger.message | string | Yes | The visitor's message with surrounding whitespace removed. 1 to 4,000 characters. |
$trigger.sessionId | string | Yes | Identifies one visitor's conversation. The same for every message in that conversation. Use it as the AI Agent memory key. |
$trigger.metadata.source | string | Yes | hosted for the chat link, embed for the widget. |
$trigger.metadata.pageUrl | string | No | The page the widget is on, without its query string. Sent by the widget only. |
$trigger.metadata.locale | string | No | The visitor's first preferred browser language, such as en-US. |
A suggested question a visitor clicks arrives as $trigger.message, exactly like a typed message. The chatbot's first message to the visitor is display only and is never sent to your workflow.
sessionId is created for the visitor, who cannot choose or change it. The fields under
metadata are sent by the visitor's browser and can be made up. Use them for context, such as
answering in the visitor's language, and never to decide what a visitor is allowed to see.
Sessions and memory
Key the AI Agent's memory on $trigger.sessionId. Under a Chat trigger the Memory sub-node suggests it for you and reads Remembering per: Chat visitor. See Remember the conversation.
A session belongs to one browser and one place the chat appears: the widget on two different websites, and the chat link, are separate sessions. It lasts 30 days from the visitor's first message, and reloading the page continues it. If the browser blocks site data for the widget, the session lasts only until the page is reloaded. The browser also keeps the last 50 messages so the conversation is still on screen after a reload. A different browser or device, or a browser whose site data was cleared, starts a new session with an empty conversation.
Reply format
The reply is whatever the workflow's Respond node returns. The chat reads it in one of two ways.
| Respond node Content type | What the visitor sees |
|---|---|
text | The body, exactly as returned. |
json | The text of the field named reply. Other fields are ignored. |
Anything else shows the visitor "Chat is unavailable right now.": a json response with no reply field or a reply that is not text, an xml or empty response, or a run that ends without reaching a Respond node.
A JSON response with the answer under any other name, such as answer or text, shows the
visitor "Chat is unavailable right now."
Replies are shown as plain text. Line breaks are kept. Markdown is not formatted, HTML is shown as written, and web addresses are not clickable. A reply longer than 8,000 characters is cut off with an ellipsis.
Each message gets one reply, shown all at once when the Respond node runs. Nodes after the Respond node keep running in the background.
The workflow has 60 seconds to reach its Respond node. After that the visitor sees "That took too long. Please try again." and the run finishes in the background.
Publishing
- A node that pauses a run, such as a Delay or an approval, cannot come before the Respond node. Publishing is refused until you move it after the Respond node.
- Publishing the workflow does not publish the chatbot. Each has its own status.
A workflow with a Chat trigger and no Respond node still publishes, with this warning: "This trigger waits for a Respond node, but the workflow has none. Callers get an empty acknowledgement." Visitors of that chatbot see "Chat is unavailable right now."
Usage and run history
Each accepted message is one workflow run. It counts toward your plan's usage and is stopped by your run quota and spend cap in the same way as any other run. Runs appear in the workflow's run history with the Webhook label.
How many messages a chatbot accepts per minute and per day, and how many visitors can wait on a reply at once, depend on your plan. See the chatbot limits.
What is not supported
- Replies that appear word by word. A reply arrives whole.
- Replies that take longer than 60 seconds.
- More than one chatbot on one trigger, or more than one workflow answering one chatbot.
- Setting what the chatbot says or where it is shared from the trigger's panel. Those are set in the chatbot builder.