Chatwoot AI Agent Integration: Queues and Human Handoff

Chatwoot AI Agent Integration: Queues and Human Handoff

For a Chatwoot AI agent integration, create an agent bot in your account, connect it to an inbox, and point its webhook at your own service. The service receives the new-message event, decides on a reply, and sends it back through the Chatwoot API. Handoff happens when the agent changes the conversation from pending to open, assigns it to a team or an agent, and leaves a private note summarizing the case.

Key takeaways

• Chatwoot stays your support hub. The AI agent is a separate service that receives events by webhook and acts through the API. It does not replace your team.
• The agent bot lets a conversation start as pending (owned by the bot) and reach the human queue only when its status changes to open.
• Filtering events, ignoring the bot's own messages, and recording what has already been processed prevents duplicate replies and loops.
• Handoff needs written criteria: customer request, out-of-scope topic, low confidence, complaint, and any action with risk.
• Security matters as much as the conversation: minimum-permission token, webhook validation, limited data, and a log of every decision.

How the integration works in practice

The design is simple, and it is worth understanding before you open any settings screen. The customer writes through a channel connected to Chatwoot, such as WhatsApp, your website, or Instagram. Chatwoot creates or updates the conversation and fires a webhook to the URL registered on the agent bot. Your service reads the event, looks up the information the agent is allowed to use, generates a reply, and calls the Chatwoot API to post it in the same conversation.

There are two distinct pieces. The first is the webhook, which is the input: Chatwoot tells you something happened. The second is the application API, which is the output: your service asks Chatwoot to send a message, apply a label, change a status, or assign the conversation. Every API call uses an access token, and that token defines what the agent can do.

Exact field names, endpoints, and menu options change between versions and between the cloud and self-hosted editions. Confirm everything in the official Chatwoot documentation for the version you run. What we describe here is the logic, and the logic holds.

If the channel is WhatsApp, connecting the number to Chatwoot is a separate step with the platform's own rules. The guide on how to integrate AI into your company's WhatsApp covers that layer, and the article on a banned WhatsApp number shows how to avoid putting the channel at risk.

Step by step: from agent bot to first reply

Use this sequence in a test environment, with a separate inbox, before touching real support traffic.

• Step 1: create a dedicated user or token for the agent. Do not reuse an administrator's token. It should have only the permissions the flow requires.
• Step 2: register the agent bot in the account settings and enter your service URL as the webhook destination.
• Step 3: connect the bot to the test inbox. In general, with a bot connected, new conversations arrive as pending, which signals that the bot handles them first.
• Step 4: in your service, receive the event and return a success response quickly. Do the heavy work (calling the model, fetching data) asynchronously, so Chatwoot does not treat the delivery as failed.
• Step 5: filter. Process only new-message events of the incoming type from the customer. Discard messages sent by the bot itself, private notes, and activity events.
• Step 6: build the context from the message text, a short conversation history, and the business rules. Ask the model for the reply.
• Step 7: validate the reply before sending (length, tone, no forbidden promises) and post it through the API as an outgoing message in the original conversation.
• Step 8: log the event identifier, the decision taken, and the reason. Without this record, you cannot audit or improve anything.

What the agent says depends on the instructions it receives. The article on how to write instructions for an AI support agent explains how to separate tone, limits, and handoff cases.

How to avoid duplicate replies and loops

The two most common mistakes in a new integration are the bot answering the same message twice and the bot answering itself. Both have predictable fixes.

First, treat webhook delivery as something that can repeat. Systems that send webhooks usually retry when they do not get a confirmation in time, so the same event can arrive more than once. Stripe's webhook documentation describes this delivery and verification behavior for a well-known provider, and the logic applies to any integration: store the identifier of each message already processed and ignore repeats.

Second, ignore everything that is not an incoming customer message. When the bot posts a reply, Chatwoot generates another event. If your service does not filter by message type, it reacts to its own reply and enters a cycle. The same applies to private notes the agent leaves for the team.

Third, set a limit on automatic replies per conversation. If the bot has already answered a set number of times without resolving the issue, the conversation goes to a human. The article on an AI agent stuck in an infinite loop covers limits on steps, time, and spend.

Finally, handle messages that arrive in sequence. WhatsApp customers often send three short messages instead of one long one. Waiting a short window and grouping them before replying reduces crossed answers.

Queues, teams, and assignment: who receives the conversation

Handoff only works if there is a clear destination. Before you build the transfer, set up the human structure in Chatwoot.

• Teams by topic: for example, sales, support, and billing. Each team has its members and its responsibility.
• Automatic assignment within the team, if your Chatwoot version offers it, to spread conversations among whoever is available.
• Business hours configured on the inbox, so the agent knows what to promise when nobody is online.
• Standardized labels for the handoff reason, such as human requested, complaint, out of scope, or billing question.
• A rule for conversations with no owner: who watches the queue of open, unassigned conversations and how quickly.

In practice, the agent hands off in three moves through the API. It applies the reason label, assigns the conversation to the right team (or to a specific agent, when the history points to one), and changes the status from pending to open, which makes it appear in the human queue. Before that, it posts a private note with the summary: who the customer is, what they asked, what has already been answered, and what is missing. The agent who picks it up does not need to reread the whole conversation or ask the customer to repeat anything.

Tell the customer as well. A short message saying the conversation has been passed to the team and someone will continue from there avoids the feeling of being dropped. If it is outside business hours, say so and state when they will hear back. The article on after-hours customer service with AI helps you decide what to answer and what to defer.

When the agent should hand off to a human

Good handoff is a written rule, not the model's impression. A simple decision list that the agent checks on every message is usually enough:

• The customer asked to speak with a person: always transfer, without trying to talk them out of it.
• Complaint, threat to cancel, or mention of a consumer protection agency: transfer with priority.
• Topic outside the authorized knowledge base: transfer instead of improvising.
• Request involving money, a contract, a policy exception, or sensitive data: transfer or require human approval.
• Two attempts in a row without the customer confirming they were helped: transfer.
• Technical failure of the agent or the model: transfer and log the error.

An illustrative scenario shows the flow. Imagine a tile store that receives orders on WhatsApp through Chatwoot. A customer asks about pickup hours, and the agent answers with the registered information. In the next message, the same customer says the piece arrived defective and wants an exchange. The agent recognizes a complaint with an exception request, applies the after-sales label, assigns the conversation to the support team, changes it to open, and leaves the note: customer reports defective piece, pickup hours already provided, awaiting decision on exchange. It tells the customer the case has been passed on and the team will follow up. The support agent opens the conversation with everything at hand.

In this flow, the agent did not decide the exchange, did not promise a deadline, and did not ask for unnecessary data. That boundary is what makes the use defensible. If a decision has a significant effect on the person, it is also worth reading about automated decisions under LGPD and the right to review.

Security, LGPD, and how we apply the method

An agent connected to Chatwoot sees customer conversations and acts on behalf of the company. That calls for access discipline.

• Minimum permission: the agent's token should do only what the flow requires. The OWASP Authorization Cheat Sheet is a useful reference for thinking about least privilege.
• Customer messages are untrusted input. Someone can write instructions trying to make the agent ignore rules or reveal data. OWASP publishes guidance on preventing prompt injection that applies directly here. In practice: the agent should not have tools that can cause harm without approval, and its output must be validated before it reaches the customer. The article on guardrails for AI agents details this check on input, output, and action.
• Webhook protection: restrict who can call your endpoint, use HTTPS, and verify the authenticity of the call with whatever mechanisms your Chatwoot version offers. If there is no signature, a secret in the URL and origin restrictions reduce the risk.
• Limited data: send the model only what is necessary. If the model provider is outside Brazil, assess the legal basis and the transfer safeguards. The article on international data transfer under LGPD when using AI providers explains what to check, and the ANPD is the official source for guidance.
• Logging and retention: keep the decision log for a defined period with restricted access, without copying into it more personal data than needed.

Our method for this type of project follows four moves. Map: understand the current support flow, the queues, the topics, and the baseline for response time and resolution. Limit: define which data the agent sees and which actions it can perform. Pilot: turn on a single real flow, with logs and a success metric agreed beforehand. Hand over: deliver the operation with the handoff rule documented and decide whether to expand, adjust, or stop. To track the pilot, customer support KPIs with AI such as AHT, resolution, and CSAT give operations and management a shared vocabulary.

Frequently asked questions

Does Chatwoot have its own AI, or do I need an external service? It depends on the version and plan you use, so confirm in the official documentation. Either way, the agent bot model with webhook and API lets you connect the AI service of your choice, which gives you control over instructions, data, and costs.

Can the agent reply and then pass the conversation to a human in the same thread? Yes, that is the design. The conversation stays the same: the agent replies, and when the handoff rule fires, it applies a label, assigns a team or agent, changes the status to open, and leaves a private note. The customer stays in the same channel and does not have to start over.

What should I do if the agent gives a customer a wrong answer? Transfer the conversation, fix it with a human, and log the case. Then review the log to see whether the knowledge base lacked information, the instruction was ambiguous, or the handoff rule needs a new criterion. Real errors from the pilot are the best source for adjusting the flow.

Can I connect the agent to all inboxes at once? It is safer to start with one inbox and one type of topic, with an agreed metric and frequent review of conversations. After the pilot, the decision to expand should come from evidence in the log and from the support team, not from enthusiasm for the technology.

Sources

• Stripe: webhook delivery and verification
• OWASP: prompt injection prevention
• OWASP: authorization guidance
• ANPD: Autoridade Nacional de Proteção de Dados