> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.apologist.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.apologist.ai/_mcp/server. # Chatwoot Integration > How an Agent answers as a Chatwoot Agent Bot, and how staff take over Chatwoot is a multiplexed channel. People message Facebook, a website widget, or another inbox that **Chatwoot** owns. This Agent is attached as a Chatwoot **Agent Bot** and answers first. Staff take over in Chatwoot, which pauses the Agent on that conversation, and assign the conversation back to the bot when they want the Agent to resume. Do not also attach that same inbox as its own Agent channel. Chatwoot already owns the connection. A second channel on the Agent for the same destination would double-reply. ## Purpose Connect an Agent as a Chatwoot Agent Bot, so it can start conversations that staff later take over in Chatwoot. ## Prerequisites * An Agent, configured and answering the way you want. The channel exposes the same Agent, so its instructions, sources, and model all apply. * A Chatwoot account with permission to create Agent Bots and attach them to an inbox. * The **Messaging / Social Channels** capability on the Agent. See [Messaging / Social Channels](/console/interfaces/messaging-social-channels) if that panel is not on the Agent yet. * A plan that includes channels, and permission to update the Agent. A team Manager can create and edit channels. ## How a Conversation Moves Chatwoot keeps the inbox, the visitor, and the staff UI. The Agent never talks to Facebook or the website widget itself. The visitor's message goes to that social or messaging channel, Chatwoot receives it and sends a webhook to this Agent as an Agent Bot, the Agent posts a reply back to Chatwoot, and Chatwoot delivers that reply on the same channel. ![Diagram showing how a message travels through Chatwoot to the Agent and back. A visitor messages a social or messaging channel such as Facebook or a website widget. Chatwoot owns that inbox and sends a webhook to the Agent. The Agent posts a reply back to Chatwoot, and Chatwoot delivers that reply on the same channel to the visitor.](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/apologist.docs.buildwithfern.com/1919ede4245a0c60d936bf408a0ef63c74fa91ac882e6a30b62796e8c540fbe5/docs/assets/images/console/chatwoot-message-path-light.svg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260919%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260919T131013Z&X-Amz-Expires=604800&X-Amz-Signature=3ccf648309e769c709fac1eba0298b65110cf10a2744959860cb2cf487728bab&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)![Diagram showing how a message travels through Chatwoot to the Agent and back. A visitor messages a social or messaging channel such as Facebook or a website widget. Chatwoot owns that inbox and sends a webhook to the Agent. The Agent posts a reply back to Chatwoot, and Chatwoot delivers that reply on the same channel to the visitor.](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/apologist.docs.buildwithfern.com/ded414d65403168e2079e7994821ab4ad3e40beabfa2a3b41afd75ccc025fbf4/docs/assets/images/console/chatwoot-message-path-dark.svg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260919%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260919T131013Z&X-Amz-Expires=604800&X-Amz-Signature=cc72378e6d37c4e185b7063bd73a5c42ebf48c789c857c459a7f95eddaecd0cd&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) A new conversation starts **pending** and assigned to the bot. The Agent answers those inbound messages. When a staff member takes over, Chatwoot opens the conversation (or assigns it to that person) and the Agent pauses. Assigning the conversation back to the Agent Bot returns it to **pending**, and the Agent answers the next inbound message. ![Diagram showing how a Chatwoot conversation moves. A visitor messages Chatwoot while the conversation is pending and assigned to the bot, and the Agent replies. When staff take over, Chatwoot opens the conversation and the Agent pauses. When staff assign the conversation back to the bot, it returns to pending and the Agent replies again.](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/apologist.docs.buildwithfern.com/0a39ea527964ea028b81d479dc7531e45de4a14cf4f4e259a67e4991c46e963b/docs/assets/images/console/chatwoot-flow-light.svg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260919%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260919T131013Z&X-Amz-Expires=604800&X-Amz-Signature=ce4e6be26e440935da824d9668b821ec1cc67da06a359af55df8ca6c9d0c9b40&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)![Diagram showing how a Chatwoot conversation moves. A visitor messages Chatwoot while the conversation is pending and assigned to the bot, and the Agent replies. When staff take over, Chatwoot opens the conversation and the Agent pauses. When staff assign the conversation back to the bot, it returns to pending and the Agent replies again.](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/apologist.docs.buildwithfern.com/7acf1c3ee7d422df0ebc5ad312bd351c8a0ef0fde1b3744e9dd39347ddd4436c/docs/assets/images/console/chatwoot-flow-dark.svg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260919%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260919T131013Z&X-Amz-Expires=604800&X-Amz-Signature=f26fbc3136498ce93dd5bd2a0f7c2edd9d313b7d407b8613be7bbb7173ad154d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) The Agent acknowledges each webhook immediately, then generates the reply in the background. Chatwoot times out in about five seconds if it has to wait, so a conversation that jumps to **Open** with no reply usually means the webhook never reached the Agent or failed authentication, not that the model was slow. ## When the Agent Replies The Agent answers only an incoming public message while the conversation is still **pending** and not assigned to a person. Private notes and the Agent Bot's own outgoing messages are ignored, so the reply does not loop. Replies are posted as Chatwoot outgoing messages. Chatwoot renders Markdown, so HTML from a [Call to Action](/console/orchestration/calls-to-action) or a pause message is converted before it is sent. Model Markdown is left as-is. **Cue Phrase** works the same way as on other channels that have it. Enter one and the Agent replies only when the visitor's message includes it. Leave it empty and the Agent replies to every inbound message it is allowed to answer. If a [guardrail](/console/orchestration/custom-guardrails) or automation pauses the Agent, the Agent also opens the Chatwoot conversation so it leaves the bot queue and waits for staff. ## When Staff Take Over Staff pause and resume the Agent from Chatwoot. They do not need Console for a single conversation. | In Chatwoot | What the Agent Does | | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | A visitor messages while the conversation is pending and not assigned to a person | Answers, then posts the reply through Chatwoot | | A visitor messages after staff have opened or taken the conversation | Stores the message and stays paused | | A staff member replies in the thread | Stores the reply in the transcript, prefixed with `[Staff]`, and pauses | | Staff open, resolve, or snooze the conversation, or assign it to a person | Pauses | | Staff assign the conversation back to the Agent Bot, so it returns to pending | Resumes and answers the next inbound message | | A guardrail or automation pauses the Agent | Opens the Chatwoot conversation so it leaves the bot queue | Taking over can be assigning the conversation to yourself, opening it, or using Chatwoot's reply-box handoff banner. Any of those notifies the Agent. Staff replies stay in the Agent transcript so the next completion can see what a person already said. `[Staff]` marks those lines. Private notes never appear there. Pausing the whole Agent from Console is separate. That control needs a **Default API Key** on the Agent's [API](/console/interfaces/api-and-mcp) page. Conversation pause and resume from Chatwoot do not. ## Conversation Labels Prompt tags from an [Automation](/console/orchestration/automations) stay on the prompt. They become Chatwoot conversation labels only when **Automatically Synchronize Tags** is on for that channel. The toggle is off by default and appears only for Chatwoot. When it is on, Agent adds labels after the prompt tags are written. Additive strategies leave staff labels in place. **Evaluator: Exclusive** replaces Chatwoot labels that match other options from the same Evaluator, then adds the latest option. Chatwoot labels should match the prompt tag slug (for example `urgent-follow-up`), or the tag name if the slug is empty. **Administrator Access Token (for Conversation Labels)** is a Chatwoot administrator Profile access token. When it is set, Agent creates the Settings catalog entry if it is missing, then tags the conversation. Without it, Agent can still tag the conversation, but the chip stays hidden until that catalog entry exists. ## Set Up Chatwoot #### Create the Chatwoot Channel In Console On the Agent, create a channel on the **Chatwoot** platform. The fields sit on the **Connection** tab: | Field | What It Is | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Account ID** | The Chatwoot account id (the number in Chatwoot URLs, `/app/accounts/{id}/...`) | | **Agent Bot Token** | The access token Chatwoot shows after you create the bot. The Agent uses this to post replies and to hand off. You can create the channel first and paste the token after the next step. | | **Chatwoot Base URL** | The Chatwoot origin, for example `https://chat.example.com` or `http://localhost:3000` locally | | **Webhook Secret** | The same HMAC secret you will set on the Agent Bot | | **Administrator Access Token (for Conversation Labels)** | Optional. Needed only if you want Agent to create missing Settings labels so chips are visible. | | **Automatically Synchronize Tags** | Optional, off by default. When on, automation-applied prompt tags are added as Chatwoot conversation labels. | Save, then copy the **Endpoint** from the Agent's **Channels** panel. Replace `{api_key}` with a real Agent API key, or drop `?api_key={api_key}` once **Webhook Secret** is filled. Chatwoot's signature is checked even when the key is present. To create a key, turn on the **API** capability and use the **API Keys** panel. You need **API** only to create the key. The channel itself keeps working off **Messaging / Social Channels**. #### Create a Chatwoot Agent Bot In Chatwoot, open **Settings**, then **Agent Bots**, and create a webhook bot. Paste the channel **Endpoint** as the bot's outgoing webhook URL. Set the same webhook secret you entered in Console, save, and copy the bot access token back into **Agent Bot Token** if you left that field empty. #### Attach the Bot To the Inbox Open the inbox the Agent should answer (a **Website** inbox is the simplest first test) and attach the Agent Bot. New conversations start pending and assigned to the bot, so the Agent replies first. #### Activate And Hand Off A new channel is saved **inactive**. Open it with **Edit**, turn **Active** on, and save. The toggle beside the channel in the Agent's **Channels** panel also has to be on. Send a message from a real Chatwoot contact and confirm the Agent replies. Then take the conversation over in Chatwoot and confirm the Agent stops, assign it back to the bot, and confirm it answers again. ## Troubleshooting * **Visitors get two replies.** The same inbox is connected both as a Chatwoot inbox and as its own Agent channel. Remove the native channel and let Chatwoot own the inbox. * **Chatwoot conversations jump to Open with no Agent reply.** The Agent Bot webhook failed or timed out. Confirm the outgoing URL is reachable from Chatwoot and that the Agent returned 200. The Agent acknowledges immediately, so a jump to Open usually means auth failed or Chatwoot could not reach the endpoint. * **The Agent does not reply, and you have just set the channel up.** Check the channel's own **Active** toggle. A new channel is saved inactive, while the toggle in the Agent's channel list is already on. * **The platform reports that your webhook returned 403.** The request failed authentication, or the payload's Chatwoot account id does not match **Account ID** on the channel. Confirm **Webhook Secret** matches the Agent Bot, or that the endpoint carries a valid `api_key`. * **The Agent replies to everything in a busy inbox.** Set a **Cue Phrase** so it answers only when addressed. * **The Agent ignores every message.** A **Cue Phrase** is set and the messages do not contain it. * **Chatwoot shows no label, or the chip is hidden.** Prompt tags must be written first, and **Automatically Synchronize Tags** must be on for that channel. Without an **Administrator Access Token (for Conversation Labels)**, Agent can still tag the conversation, but the chip stays hidden until the Settings catalog entry exists. * **Staff took over and the Agent kept answering.** The conversation is still **pending** and assigned to the bot. Open it, assign it to yourself, or use the handoff banner so Chatwoot notifies the Agent. ## Next Step Continue to [API And MCP](/console/interfaces/api-and-mcp) to reach the Agent from your own code, or to [Automations](/console/orchestration/automations) to apply prompt tags that Chatwoot can show as labels.