Chatwoot AI Chatbot Setup: Captain vs Building Your Own Agent

Chatwoot can answer customers with AI in two very different ways, and the difference changes your bill by an order of magnitude. Route one is Captain, Chatwoot's built-in AI assistant, which works out of the box on paid plans and bills you in credits. Route two is the Agent Bot API, a free, open-source webhook interface that lets you connect any model you like, including Claude, and pay only raw token costs. This guide compares both routes with real numbers, walks through the custom-agent setup, and covers the handoff rules that decide whether customers get good answers or a frustrating loop.

The two ways to add AI to Chatwoot

Chatwoot is an open-source support inbox. When teams ask about adding an AI chatbot to it, they usually mean one of two things:

• Captain: Chatwoot's own AI product. A customer-facing Assistant that replies in your inboxes and hands off when stuck, plus an agent-facing Copilot that drafts replies and summarizes conversations. It is a paid feature, not part of the free Community Edition for self-hosters.
• Agent Bots: a webhook and REST API built into open-source Chatwoot. Chatwoot forwards each incoming message to an endpoint you run, your code calls any LLM, and the bot replies using its own access token. This works on the free Community Edition, on Chatwoot Cloud, and on every paid plan. Chatwoot's Agent Bots documentation confirms it works on self-hosted installations and cloud alike.

The choice is not really about features. It is about who owns the AI layer. With Captain, Chatwoot owns it: you configure assistants in a UI, feed documents, and pay per credit. With an Agent Bot, you own it: your code, your model, your prompts, your logs, and your token bill.

Captain: what you get and what it costs

Captain is the fast path. An administrator creates an Assistant in the sidebar, connects it to specific inboxes, syncs documents for knowledge, sets guardrails, and it starts replying. Chatwoot's Captain introduction and AI Actions lesson describe the full feature set: FAQ lookup, conversation memory, contact attributes, handoff to human, resolve conversation, and custom tools that call your HTTP endpoints (capped at 15 per account, behind a feature flag).

The pricing mechanics matter more than the feature list:

• Cloud plans: Captain is available on Startups ($19/agent/month), Business ($39), and Enterprise ($99), per the Chatwoot pricing page. It is not on the free Hacker plan and not during the free trial.
• Included credits: 300 credits a month on Startups, 500 on Business, 800 on Enterprise.
• Top-ups: $20 per 1,000 additional credits.
• Credit burn: every AI action consumes credits. Comparisons like Sellio's Chatwoot vs Intercom breakdown note that a single AI reply uses at least one credit, so credits roughly track AI-handled messages.

For self-hosters the picture changes. Captain is not in the Community Edition at all. Per Chatwoot's self-hosted Captain guide, you need a Premium or Enterprise self-hosted licence, then you supply your own OpenAI API key (or an OpenAI-compatible endpoint for a self-hosted model). The Copilot defaults to gpt-4.1-mini and the Assistant to gpt-5.2, though you can override the models. So the self-hosted Captain cost is licence fee plus your own OpenAI token spend on top. One difference from cloud: Chatwoot does not meter Captain credits on self-hosted installations, so there is no credit balance to run dry, but every AI reply bills straight to your OpenAI key.

One more practical detail from Chatwoot's troubleshooting guide: when credits run out, new conversations go straight to your human team with no AI reply at all. Captain fails closed, which is good, but it means an untracked credit balance silently turns the bot off.

The Agent Bot API: the free, open-source route

An Agent Bot is a special bot user you create in Chatwoot and connect to one or more inboxes. From that point:

1. A customer sends a message on any connected channel (live chat, WhatsApp, email, Instagram).
2. Chatwoot POSTs a webhook event to your endpoint with the message content and conversation context.
3. Your service assembles a prompt (system instructions, knowledge-base snippets, conversation history), calls an LLM, and posts the reply back through the Chatwoot API using the bot's access token.
4. If the bot cannot help, it sets the conversation status to open. Chatwoot then routes it to your team with the full transcript.

Two properties make this route attractive. First, it is part of the open-source platform, so it costs nothing in licence fees and works identically on a $20-a-month VM. Second, the model choice is yours. Anthropic's Claude pricing page lists Claude Haiku 5.5 at $0.10 per million input tokens and $0.50 per million output tokens, with Claude Sonnet at $2 and $10 respectively. A support bot on Haiku is almost free at small-business volumes, and you can escalate hard questions to Sonnet inside the same bot. The OpenAI API pricing page sits in the same low-cost tier, with GPT-5 mini at $0.25 in and $2 out per million tokens.

The trade-offs are real. You write and operate the bot service: prompt design, retrieval over your help docs, rate-limit handling, and monitoring. Chatwoot gives you the plumbing, not the brain. If you have no one who can maintain a small web service, Captain or a managed build is the better answer.

Setting up an Agent Bot step by step

This is the procedure for a self-hosted Community Edition install (the cloud steps are the same minus the server). Chatwoot's self-hosted installation guide recommends 4+ CPU cores, 8GB RAM, and 50GB SSD for production.

1. Create the bot. In Chatwoot, go to Settings, then Agent Bots, and add a bot with a name and an avatar. Save and copy the bot's access token.
2. Set the webhook URL. Point the bot's outgoing webhook at your service, for example https://bot.yourcompany.com/chatwoot/webhook.
3. Build the webhook handler. Your endpoint receives message_created events. A minimal handler checks the event type, ignores outgoing and private messages, builds the prompt, and calls the model:

curl -X POST https://chat.yourcompany.com/api/v1/accounts/1/conversations/42/messages \
  -H "api_access_token: BOT_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"content": "Our Nairobi office is open 8am to 5pm EAT, Monday to Friday."}'

4. Add knowledge retrieval. Keep your help articles, price lists, and policy documents in a small vector store (pgvector inside the same PostgreSQL instance works fine at this scale). Embed the customer's message, pull the top three to five snippets, and put them in the prompt with an instruction to answer only from that material.
5. Connect the bot to inboxes. Edit each inbox and set the Agent Bot as the first responder, or add it via the inbox's bot integration setting. Start with one low-stakes inbox, like website FAQ questions, before touching WhatsApp or billing conversations.
6. Implement handoff. When confidence is low, the topic is sensitive, or the customer asks for a person, call the conversation update endpoint to set status to open and optionally assign a team:

curl -X POST https://chat.yourcompany.com/api/v1/accounts/1/conversations/42/toggle_status \
  -H "api_access_token: BOT_TOKEN_HERE"

The status flips to open and the team queue picks the conversation up with the full history.

7. Log everything. Store the prompt, retrieved snippets, model, token counts, and outcome for every reply. You will need this the first time the bot answers something wrong and you have to explain why.

A working version of this bot is a few hundred lines of Python or TypeScript. The hard part is not the code; it is the knowledge base and the handoff policy, which is where the next two sections go.

Worked cost example: 3,000 AI-handled conversations a month

Take a 10-agent support team handling about 3,000 conversations a month that the AI answers without human help, averaging 6 AI replies per conversation. That is 18,000 AI replies a month. A typical reply involves roughly 4,000 input tokens (system prompt, retrieved knowledge, conversation history) and 300 output tokens.

• Captain on Business: 18,000 credits minus the 500 included is 17,500 extra credits. At $20 per 1,000, that is about $350 a month on top of the $39 per agent seat fees.
• Custom bot on Claude Haiku 5.5: per reply, 4,000 input tokens cost $0.0004 and 300 output tokens cost $0.00015, so about $0.00055 per reply. Across 18,000 replies, that is roughly $10 a month, plus the VPS Chatwoot already runs on (a capable VM is around $20 a month, as Provenlabs' Chatwoot overview notes).
• Custom bot on Claude Sonnet 5 for harder conversations: about $0.011 per reply, so roughly $198 a month if every reply used Sonnet. A hybrid (Haiku first, Sonnet on retry or low confidence) usually lands between $20 and $60.
• For reference, Intercom Fin charges $0.99 per resolved conversation, per SaaSCompared's 2026 comparison. If 60 percent of those 3,000 conversations count as resolutions, that is 1,800 times $0.99, about $1,782 a month, before seat fees.

The spread is the whole story: roughly $10, $350, and $1,782 a month for the same volume of answered conversations. Captain's premium buys you zero code and a polished admin UI. The custom route buys you the lowest unit cost and full control over the model. Fin prices per outcome, which is simple to budget but expensive at volume. For the full build-versus-buy math on the custom route, including development hours and ongoing maintenance, our AI chatbot development cost guide breaks down what a production bot actually costs to build and run.

Handoff and guardrails that decide whether this works

Both routes live or die on the same rules.

• Handoff is a feature, not a failure. Captain hands off by sending a configurable message and moving the conversation to your team; an Agent Bot does it by setting status to open. Define the triggers explicitly: angry sentiment, billing disputes, anything legal, any request for a human, and two consecutive low-confidence answers.
• Pending versus open. Per the Captain troubleshooting docs, Captain only replies while a conversation is Pending. Once an agent replies or a handoff happens, the conversation is Open and the AI stays silent unless reassigned. Design your custom bot with the same discipline: never let the bot re-enter a conversation a human has taken.
• Scope the first assistant narrowly. Chatwoot's own AI lesson recommends starting with something like pricing and refund questions only, on one inbox, and watching it for a week. This applies doubly to a custom bot, where the failure modes are yours to debug.
• Guardrails before volume. Captain offers guardrails, response guidelines, and audience/schedule controls. For a custom bot, implement the equivalents in the system prompt and in code: a topic allowlist, a maximum of bot replies per conversation before forced handoff, and a business-hours schedule if you want humans to own daytime chats.
• Watch the silence cases. Captain goes silent on open conversations, excluded audiences, and empty credit balances. A custom bot goes silent when your webhook errors. Add a fallback: if your endpoint fails to respond within a few seconds, an automation rule should open the conversation so a human sees it.

Common mistakes

• Letting the bot answer everything on day one. Broad scope produces confident wrong answers, and wrong answers in a support inbox cost more than slow ones. Start with FAQs, expand by topic as the logs prove accuracy.
• No knowledge maintenance. Both Captain and a custom RAG bot answer from your documents. Stale price lists and retired policies are the top cause of bad answers, not the model. Assign someone to review FAQ suggestions and doc freshness weekly.
• Unscoped custom tools. If you give the AI an HTTP tool that can look up accounts or issue refunds, treat it like giving an API key to a new employee. Read-only where possible, idempotent always, and never expose actions whose blast radius you would not accept from a junior agent. Chatwoot caps custom tools at 15 per account for good reason.
• Ignoring the credit meter. Captain teams sometimes discover the bot stopped replying because credits ran out. Set a billing alert, or decide upfront that the custom route's $10-to-$200 token bill is easier to reason about.
• Skipping the transcript review. Neither system tells you what it got wrong unless someone reads conversations. Block 30 minutes a week to review bot-handled transcripts, especially the ones it resolved without handoff.

When each route is the wrong choice

Skip Captain if you self-host the Community Edition and do not want to buy a licence (Captain simply is not there), if you need a model other than OpenAI's, if your data rules require a specific model provider or region, or if your volume makes per-credit pricing worse than raw tokens. It is also the wrong choice if your support questions need reasoning over internal systems via many custom tools; you will hit the 15-tool ceiling.

Skip the custom Agent Bot if nobody on your team can own a small production service, including on-call for its failures. A bot that silently dies at 2am is worse than no bot. Also skip it if you mainly want agent-assist features (drafting, summarizing) rather than customer-facing automation; Captain's Copilot does that with no code, and a DIY Copilot equivalent is a much bigger build than a DIY Assistant.

Skip both if your real problem is that nobody answers the inbox at all. AI on top of an unstaffed support function automates the wrong thing. Fix staffing or routing first; our conversational AI implementation guide covers the operational groundwork, and our AI chatbot pricing models breakdown compares per-seat, per-resolution, and per-token billing across vendors if you are still choosing a platform. If you are unsure whether you even need an agent or a chatbot, our explainer on AI agents versus chatbots helps frame that call.

Frequently asked questions

Is Captain available on self-hosted Chatwoot? Yes, but only on the Premium and Enterprise self-hosted licences, not the free Community Edition. You configure it in the Super Admin console with your own OpenAI API key, and you can point it at an OpenAI-compatible endpoint if you host your own model.

Does the Agent Bot API cost anything? No. It is part of open-source Chatwoot and works on the free Community Edition and on Chatwoot Cloud. You pay only for the server that runs your bot code and the LLM tokens you consume, which for a Haiku-based bot at a few thousand conversations a month is around $10.

Can I use Claude instead of OpenAI with Chatwoot? With an Agent Bot, yes: your webhook code calls the Claude API directly, so any Claude model works. With Captain, the integration is built around OpenAI keys and OpenAI-compatible endpoints, so Claude is not a native option.

How many credits does a Captain conversation use? Chatwoot meters credits per AI action rather than per conversation, and a single reply uses at least one credit. A six-reply conversation costs at least six credits, more if the assistant also summarizes or looks up documents. Extra credits bill at $20 per 1,000.

Can the bot handle WhatsApp conversations in Kenya? Yes. Agent Bots and Captain work on any inbox, including the WhatsApp Business API channel. The bot replies through the same Chatwoot pipeline, so WhatsApp customers get AI answers with the same handoff rules as live chat.

Where to go from here

If you want AI on your support inbox without per-resolution fees, the self-hosted Chatwoot plus custom agent route is the strongest option we know, and it is exactly the kind of system we build and operate. We deploy and manage Chatwoot as part of our managed open-source stack service, and we design the agent layer (prompts, retrieval, handoff policy, Claude integration) through our Claude implementation practice. Talk to us if you want the $10-a-month version done properly, with guardrails, logging, and a handoff policy your team can trust.