Hey đź‘‹, how can we help you?
Search for the articles here or browse the categories below.
Browse by topic
Find guides, tutorials, and answers organised by category.
Chatwoot 101
Start here to understand Chatwoot, key concepts, and how the platform helps you manage customer conversations.
Browse
Other channels
Connect and manage channels such as email, WhatsApp, Facebook, Instagram, Telegram, and more.
Browse
Setup account
Set up your account, workspace, teams, users, and basic configuration before going live.
Browse
Website live chat
Learn how to install, configure, and customize the Chatwoot live chat widget on your website or app.
Browse
Voice Channels
Learn how to connect voice providers, manage incoming calls, and configure phone support in Chatwoot.
Browse
Your complete guide to WhatsApp in Chatwoot: connect your number, use templates, campaigns, CSAT surveys and calling, keep your number healthy, and fix common setup and delivery errors.
Browse
Features explained
Understand the main Chatwoot features used for inbox management, conversations, contacts, teams, and workflows.
Browse
Advanced features explained
Explore advanced capabilities such as automation, assignment rules, custom attributes, macros, SLAs, and webhooks.
Browse
Apps and Integrations
Connect Chatwoot with external tools and services to extend your support workflows.
Browse
Reports
Use reports and analytics to measure team performance, conversation volume, response times, and customer support quality.
Browse
Help Center
Create, organize, and publish help center articles so customers can find answers on their own.
Browse
Best practices
Practical recommendations to help your team get better results from Chatwoot.
Browse
Captain
Learn how to set up and use Captain, Chatwoot’s AI agent for customer support.
Browse
Migrations
Guides to help with a smooth transition from other platforms, such as Zendesk, Freshdesk, Intercom, etc, to Chatwoot.
Browse
Other topics
Additional guides and references to help you get the most out of Chatwoot.
Browse
How To
Step-by-step guides for common tasks and specific use cases in Chatwoot.
Browse
Recommended articles
Hand-picked articles to get you started.
Captain AI credits and usage
Discover Captain uses AI credits. Every paid plan includes free credits each month, and you can buy more. Plan & access: Startups, Business or Enterprise. How many credits each plan includes, and the top-up price, are on Pricing & Plans > Captain AI credits. Administrators see usage and buy credits in Billing. Set up & try What uses credits Each of these uses one credit: - An assistant reply to a customer. - A message in the assistant's Playground. - A Copilot request. - An editor action, such as rephrase, summarize or suggest reply. - An audio transcription. Adding documents, approving FAQs, label and priority suggestions from Suggest with Captain, and Captain conditions in automation rules do not use credits. See your usage 1. Go to Settings > Billing. 2. The Captain section shows Credits and Documents used. Click Refresh to update. Buy more credits 1. In Billing > Captain, click Buy more credits. 2. Choose a pack and click Purchase Credits, then confirm. Your saved card is charged straight away. Bought credits: - Are added straight away and used after your monthly plan credits. - Expire after 6 months. - Need an active subscription to be used. - Are non-refundable. Test it After buying, check the new balance in Billing > Captain. Get value - Monthly credits reset at your plan's renewal date. Buying credits or changing plan does not reset usage. - Unused monthly credits do not carry over. If you use more than your monthly credits, the extra comes out of credits you bought. - When you change plan, your balance goes up or down by the difference between the two plans' monthly credits. Your usage stays the same. - Changing your number of seats does not reset usage. - To make credits last: connect the assistant only to inboxes where it helps, use the audience and schedule rules (Control who Captain replies to and when), and turn off AI features you do not use, such as transcription. - A banner warns you when you have used over 80% of your credits. There is no email alert, and credits do not top up automatically. - Usage is one total for the account. It is not split by agent, assistant or feature. To see how each assistant performs, use its Overview (Captain Overview and reports). Troubleshoot Symptom Likely cause What to do New conversations go straight to the team with no assistant reply Credits ran out Buy credits or wait for renewal Assistant says "Transferring to another agent for further assistance." mid-conversation Credits ran out during the conversation Buy credits or wait for renewal Copilot says you are out of Copilot credits Credits ran out Buy credits or wait for renewal Usage did not go to 0 after buying Expected. Usage resets only at renewal; the purchase adds to the balance None Credits are used faster than expected The assistant is on busy inboxes, or AI features are used heavily Narrow the audience or schedule; turn off features you do not need Cannot buy credits You are not an administrator, or no active subscription Ask an administrator; check the subscription More causes: Troubleshoot Captain.
🔥 CaptainSet up custom tools for Captain
Discover Custom tools let the assistant call your own systems during a conversation, for example to check an order, a warranty or a booking, instead of handing off. Plan & access: Business or Enterprise (Pricing & Plans). On Startups, Tools usually shows Upgrade to use tools with Captain. Each assistant has its own list of tools. Administrators create tools, and only administrators can see the saved credentials. Self-hosted: the Super Admin turns on Custom Tools for the account. Set up & try Before you start - An HTTPS endpoint on a public hostname. Chatwoot blocks plain HTTP, IP addresses, localhost, private networks and .local addresses. - The endpoint must accept the connection within 2 seconds and answer within 20 seconds, with a response of 1 MB or less. - Its credentials, if it needs any. Create a tool 1. Go to Captain > Tools and click Create a new tool. First use the assistant switcher at the top to choose the assistant the tool is for. The form opens in a side panel. 2. Fill in: - Tool Name: short, for example "Order Lookup" (55 characters or fewer). - Description: when the assistant should use it, written like a briefing for a new agent. This decides whether the assistant picks the tool. - Method: GET to read data; POST, PUT or PATCH to send or change data; DELETE to remove something. - Endpoint URL: use {{ parameter_name }} for values the assistant fills in, for example https://api.example.com/orders/``{{ order_id }}. - Authentication Type: None, Bearer Token, Basic Auth, or API Key (with Header Name and Header Value). Use this for credentials. - Headers: click Add Header for fixed headers your API needs on every call, such as an API version or tenant ID (up to 16). Values are sent exactly as typed. Chatwoot sets Authorization, Host, Content-Length, Content-Type and any header starting with X-Chatwoot itself, so you cannot add those. - Parameters: click Add Parameter for each value the assistant should get from the customer. Give a name, type, description, and mark Required if needed. - Request Body Template (Optional): for POST, PUT or PATCH. This and the response template are under Templates. The request template is a JSON body. It supports Liquid, for example {{ order_id }} for a parameter. - Response Template (Optional): pick out the fields the assistant needs, for example Order {{ response.order_id }} status: {{ response.status }}. Read the API reply through response, for example {{ response.status }}. Leave the template blank to send Captain the raw JSON. 3. Click Test connection, then Create. Test connection works only for endpoints without templates or a request body. For others, test in the Playground. A green result means your endpoint returned a 2xx status: it is reachable and accepted the credentials. Test it Ask a question in the Playground that needs the tool, for example "Where is order 1234?". Check the reply uses real data. Get value - Custom tools work best for lookups with clear inputs, such as an order status, a booking or a record by ID. - Each assistant can have up to 50 tools. Keep the list short anyway: with many tools the assistant is more likely to pick the wrong one. - Adding, editing, turning off or deleting a tool changes it only for the assistant you are viewing. Tools that existed before tools became per-assistant were copied to every assistant, so check each one. - Running several assistants? Give each only the tools it needs. - Turn a tool off with its toggle instead of deleting it. If a scenario uses it, Chatwoot warns you first. See Set Captain's guardrails, guidelines and scenarios. - Chatwoot sends headers with each call so your system knows the account, conversation, contact email and phone, assistant, and whether the contact is verified. For private data, check the X-Chatwoot-Contact-Inbox-Verified header before answering. Without identity validation, a visitor can type any email into the widget. Tools that return only public data do not need this check. See How to enable identity validation in Chatwoot?. - If your API returns text written by customers, return only the structured fields you need. Captain reads the reply as-is, so free text can contain instructions it might follow. Troubleshoot Symptom Likely cause What to do Connection failed Endpoint unreachable, not HTTPS, or wrong credentials Check the URL and credentials; make sure it is public HTTPS Connection failed with 401 The credentials are wrong Check Authentication Type and the credentials Connection failed with 403 Your API rejected the request Test requests carry no contact headers, so an endpoint that needs them fails the test. Test in the Playground instead Connection failed with 404 Wrong URL path Check the URL path Connection failed with a timeout Your API took longer than 20 seconds to reply, or 2 seconds to connect Speed up the endpoint URL rejected IP address, localhost or private address Use a public hostname A header is rejected It is a header Chatwoot sets itself, a duplicate, or its value has placeholders Remove it, or move credentials to Authentication Type A tool is missing on another assistant Tools belong to one assistant Switch to that assistant and create the tool there Cannot add another tool The assistant already has 50 tools Delete tools it does not use Assistant never uses the tool Description is vague Rewrite the Description to say exactly when to use it Assistant uses the wrong tool Too many tools or overlapping descriptions Remove or disable tools; make descriptions distinct Slow or no answer, then hand-off Endpoint took over 20 seconds or returned over 1 MB Speed up the endpoint; trim the response with a Response Template More causes: Troubleshoot Captain.
đź“ž Voice ChannelsVoice Calling in Chatwoot
Talk to your customers by voice, right from the same inbox where you already handle chats. https://www.youtube.com/watch?v=h_ei5H44BL8 This guide is in three parts: 1. What voice calling is and how it helps: overview on voice calling feature 2. Connecting a voice channel: setup for each provider (Twilio and WhatsApp) 3. Using voice calling day to day: answering, assignments, who gets rung, and what happens after a call 1. What voice calling is and how it helps Voice calling lets your agents make and receive phone calls inside Chatwoot, without juggling a separate phone app. A call lives in the same place as the rest of the conversation, so the chat history, contact details, notes, and the call all sit together in one timeline. 1.1. Why teams use it - One screen for everything. When a customer calls, the agent already sees who they are and what they've talked about before, no asking them to repeat themselves. - No phones to manage. Agents talk through their browser using a headset or the computer's mic and speakers. There's no additional overhead of any new softwares or browser extensions. - Every call is on the record. Each call automatically becomes a message in the conversation, showing whether it was answered, how long it lasted, who picked it up, and, when available, a recording you can replay and a written transcript you can read. - The team shares the load. An incoming call rings the right available agents at once, so customers reach a real person quickly. 1.2. Different ways to receive a call Chatwoot supports voice through two providers. You can use either or both: Provider Best for How the customer reaches you Twilio Voice A traditional business phone line Customer dials your phone number from any phone WhatsApp Calling Businesses already on WhatsApp Customer taps "call" on your business inside the WhatsApp app Note: Voice calling is a premium feature. It must be enabled on your account (the Voice Channel feature) before the options below appear. If you don't see voice settings, contact your account admin or your Chatwoot provider. 2. Connecting a voice channel Setting up voice is an admin task, done once per inbox. Pick the section that matches the provider you want. 2.1. Twilio Voice (a phone-number line) Please follow along this article to setup Twilio Voice: Connecting Twilio voice channel 2.2. WhatsApp Calling Please follow along this article to setup WhatsApp Calling: Connecting WhatsApp voice channel One requirement for agents: their browser must have microphone permission granted for Chatwoot. 3. Using voice calling day to day Once an inbox has voice enabled, calling works the same way for agents no matter which provider is behind it. 3.1. Receiving an incoming call When a customer calls, a floating call widget pops up in the corner of the screen for the agents who should answer, and a ringtone plays. The card shows the caller's name, number, and (when known) their location, plus which channel the call came in on. From that widget an agent can: - Join call: answer and start talking by clicking the green call accept button. - Reject: decline the call (the caller is no longer ringing this agent) by clicking the red call reject button. - Dismiss: quietly hide the popup on this screen without rejecting the call, so other agents can still pick it up. You can do this by clicking the cross button on the top right of the widget. If a teammate (or the same agent in another browser tab) has already grabbed the call, the widget shows "Being handled in another tab" so two people don't answer the same call. While connected, the widget shows a running timer and these controls: - Mute mic / Unmute mic: turn the agent's microphone off and on by clicking in the green mic button. - End call: hang up by clicking on the red call end button. - Go to conversation thread / View chat history: jump to the full conversation while staying on the call by clicking on the "Go to conversation thread" link at the bottom of the widget. This makes it easier for the agent can see the previous history of the conversation or get more details about the contact. 3.2. Notification and call assignments Chatwoot rings the people most likely to help, it does not ring everyone blindly. For an incoming call, it rings in this order of priority: 1. The assigned agent, if the conversation already has one, only they are rung. 2. Otherwise, the online agents in that inbox, everyone who is available gets the call notification at once. 3. Otherwise, all online admins on the account, a last resort so no call goes unanswered. A few rules that follow from this: - Only available (online) agents get a ringing popup for incoming calls. Agents who are offline or busy are skipped. - First to answer wins. There's no queue or round-robin, whoever picks up first takes the call, and for the others it stop ringing and the call notification goes away. - The call is auto-assigned to whoever answers. The conversation becomes theirs, so follow-up stays with the person who handled it. - Outbound calls always belong to the agent who started them. 3.3. Call states (what the labels mean) Every call moves through a simple lifecycle, and the conversation reflects it: What you see Meaning Incoming call / Outgoing call The call is ringing Call in progress Connected and talking Call ended Finished normally No answer ( Contact didn't pick up) Outbound call the customer didn't answer Missed call  ( No agent picked up) Incoming call nobody answered Declined by {agent} An agent rejected the call 3.4. After the call When a call ends, it's saved as a call entry in the conversation timeline, so there's a permanent record. Depending on your setup, that entry can include: - Call summary: Direction (incoming/outgoing), the final status, how long it lasted, and which agent answered (e.g. "You answered", "{agent} answered", or "They answered"). - Recording: For Twilio calls a recording is captured automatically and attached so you can replay it. For WhatsApp calls a recording is attached when it is available. - Transcript: If your account has AI transcription enabled (the Captain integration, subject to available quota), the recording is turned into readable text right inside the call entry, with a Show more / Show less toggle for long calls. A missed or declined call still leaves an entry (e.g. Missed call - No agent picked up), and the agent can use Call back from the conversation to return it. 3.5 Starting an outbound call When an agent misses a call, Chatwoot provides the ability to seamlessly do a callback to the customer from the dashboard. From inside a conversation, the agent can use the call button in the conversation header: You can also start a call from the contact info screen also. Quick troubleshooting - No voice settings appear. The Voice Channel feature isn't enabled on your account — ask your admin or Chatwoot provider. - WhatsApp calling won't turn on. The number isn't enrolled in the WhatsApp Business Calling API yet, or the inbox isn't a WhatsApp Cloud inbox. Onboard the number with Meta / your provider and try again. - The call connects but there's no sound, or it won't start. Check hat the browser has microphone permission for Chatwoot, and that a headset/mic is selected. - A customer says they can't call your WhatsApp number. They may not have accepted the call permission request yet — they'll get one when an agent tries to call, and calls work once they accept.
⚡ Apps and IntegrationsHow to enable video calls with Cloudflare RealtimeKit?
Video calling helps your team connect with customers quickly, understand issues clearly, and provide faster support. Chatwoot supports video calls for website live chat conversations through the Cloudflare RealtimeKit integration. This guide explains how to create the required Cloudflare RealtimeKit credentials, connect them to Chatwoot, and start a video call from a conversation. Note: If you previously used the Dyte integration, use Cloudflare RealtimeKit for new setups. Dyte's legacy infrastructure is being sunset after the Cloudflare acquisition. Prerequisites Before you start, make sure you have: - Access to your Cloudflare account. - Permission to create a RealtimeKit app in Cloudflare. - Permission to create Cloudflare API tokens. - Administrator access to your Chatwoot account. How to create a RealtimeKit app in Cloudflare? Step 1. Open the Cloudflare dashboard and go to Realtime -> RealtimeKit. Step 2. Click the "Create app" button. Step 3. Enter a name for the app. For example, you can use "video-support". Click "Create". Step 4. After the app is created, copy the RealtimeKit App ID. You will need this value when connecting the integration in Chatwoot. How to find your Cloudflare Account ID? Step 1. Go to your Cloudflare account home. Step 2. Click the three-dot menu in the top-right corner. Step 3. Click "Copy account ID". How to create a Cloudflare API token? Step 1. In Cloudflare, go to My Profile -> API Tokens. Step 2. Click "Create Token". Step 3. Under "Custom token", click "Get started". Step 4. Give the token a descriptive name. For example, you can use "video-support". Step 5. Under Permissions, select: - Scope: Account - Permission: Realtime - Access: Admin Step 6. Under Account Resources, select the Cloudflare account you want to use with Chatwoot. You can select "All accounts" if you want the token to work across all accounts you have access to. Step 7. Review the token summary and click "Create Token". Step 8. Copy the API token. Cloudflare shows this token only once, so keep it somewhere safe until you add it to Chatwoot. How to set up the RealtimeKit integration in Chatwoot? Step 1. In Chatwoot, go to Settings -> Applications -> Cloudflare RealtimeKit. Step 2. Click "Configure". Step 3. Click "Connect". Step 4. Enter the following values: - Cloudflare Account ID - RealtimeKit App ID - Cloudflare API Token Step 5. Click "Create". Chatwoot validates the credentials before saving the integration. If any value is incorrect, you will see a specific error for the API token, Account ID, permissions, or RealtimeKit App ID. Once the credentials are saved, the RealtimeKit integration is ready to use. How to video call your customers in Chatwoot? Once the RealtimeKit integration is enabled, you will see the video calling option in website inbox conversations. Step 1. Open a website inbox conversation. Step 2. Click the video camera icon below the reply editor. Step 3. Chatwoot sends a meeting invitation message to the customer. Click "Click here to join" to enter the call. Step 4. The customer can join the same call from the website live chat widget. Step 5. Once both sides join, the agent and customer can continue the conversation over video or voice.
WhatsappConnect with WhatsApp Cloud API (manual setup)
Use manual setup if your number is already on the WhatsApp Business Platform (API), you are a tech provider onboarding your own number, you are self-hosted without Quick setup configured, or Quick setup is unavailable. You connect Chatwoot to your own Meta app. Plan & access - Every plan that includes WhatsApp (Startups and above, and the free trial) on Chatwoot Cloud, and self-hosted. See Pricing & Plans. - Administrators only. - Coexistence (keeping the WhatsApp Business app) is not supported with manual setup. If your number is active in the WhatsApp Business app, do not register it through this flow. Use Quick setup with Meta or contact support. Before you start You need three things from Meta. The guided setup in Chatwoot walks you through each one and links to the right Meta screen: - A Meta app with the WhatsApp use case - Your number's Phone Number ID and WhatsApp Business Account ID - A permanent access token from a Meta system user Connect your number 1. Go to Settings › Inboxes › Add Inbox › WhatsApp and choose WhatsApp Cloud. On the Quick setup screen, click manual setup flow at the bottom. (If Quick setup is unavailable, you go straight to manual setup.) 2. Create or select a Meta app. In Meta Developers, create an app (or pick the one you already use for this number), choose to connect with customers through WhatsApp, and select the business portfolio that owns the number. Click My Meta app is ready. 3. Add your phone number and get its IDs. In your Meta app, open the WhatsApp use case and choose API Setup (Use cases › Connect with customers through WhatsApp › Customize › API Setup). On newer apps, go to Basic setup › Production setup and open Register your WhatsApp phone number instead. In Send and receive messages (or Register your WhatsApp phone number), open the From selector and pick your number, or choose Add phone number, complete the business profile and verify with the code Meta sends by SMS or phone call. Meta changes this screen often. The Phone Number ID and WhatsApp Business Account ID are usually shown near the selected From number. Copy the Phone Number ID and WhatsApp Business Account ID, enter them in Chatwoot and click Next. 4. Generate a permanent access token. In Meta Business Settings, select the business portfolio that owns your WhatsApp Business Account, then go to Users › System users. Create an admin system user (or pick one), assign it your Meta app and WhatsApp Business Account with full control, then click Generate token. Select the Meta app you created, set expiry to Never, select whatsapp_business_management and whatsapp_business_messaging, and copy the token. Meta shows it only once. Back in Chatwoot, paste it as the Permanent access token and click Verify details. 5. Review the business name, number and IDs, change the Inbox name if you like, and click Create inbox. 6. Chatwoot checks Number access, Template access, Webhook callback and Webhook subscription, and sets up the webhook in Meta for you. When all four show Verified, click Continue to add agents. Test it: send a WhatsApp message to your business number from another phone. It should appear in Chatwoot. Reply and check it arrives. Keep your token private. Anyone with it can use your WhatsApp connection. If you replace or revoke it in Meta, update it in the inbox's Configuration tab. If a verification step fails Message What to do This access token is invalid or expired Generate a new permanent token (expiry Never ) and try again Template access not verified The token is missing whatsapp_business_management . Messages will work, but templates will not sync. Generate a token with both permissions. Webhook callback or Webhook subscription not verified Click Retry webhook setup . If it still fails, check the system user has full control of the WhatsApp Business Account. If retrying keeps failing, set the webhook by hand: copy the Webhook URL and Webhook Verification Token shown on the finish screen (the token is also in the inbox's Configuration tab). In your Meta app, go to WhatsApp › Configuration , paste both, click Verify and save , then subscribe to the messages field. Enter the Phone Number ID and WhatsApp Business Account ID Copy both from API Setup in your Meta app. They are different numbers. For anything else, see Troubleshoot WhatsApp. What happens next - Templates approved in your WhatsApp Business Account sync automatically. See Templates and the 24-hour window. - Calling works with manual setup too, once your number is enrolled with Meta's Calling API. See WhatsApp calling. Connecting more than one number Yes, you can. Create a separate Chatwoot inbox for each number. The guided setup configures the webhook routing for each one, so there is nothing to wire up by hand.
WhatsappMove a Quick setup inbox to manual setup
Reconnect an inbox created with Quick setup so it uses your own Meta app instead. Your inbox, conversations and settings stay as they are. When you would do this Chatwoot shows a Manual setup recommended banner on the inbox when Meta restrictions on the shared Quick setup app could affect it. Connecting through your own Meta app protects the inbox from those restrictions. Plan & access - Available on Chatwoot Cloud to administrators only. See Pricing & Plans. - Available when the Manual setup recommended banner appears in the inbox settings. The banner is not a setting you can switch on: it appears for Quick setup (Embedded Signup) WhatsApp Cloud inboxes once your account has been given access, the number is not using Coexistence, and the connection has no authorization error. Contact support to have your inbox assessed. - Not for Coexistence numbers. If your number is also used in the WhatsApp Business app, contact support before doing anything. What changes and what stays Stays the same Is updated Conversations, contacts, collaborators, routing, business hours, CSAT and bot settings, and the customer-facing phone number WhatsApp Business Account ID, Phone Number ID and access token The webhook for your own Meta app is not set up automatically. Contact support before you start, so the webhook is set up for your Meta app before you move the inbox. After the move, test it as described in Check it worked. Before you start Contact support first. Support helps you set up the webhook for your own Meta app. Do not start the move until support confirms the webhook is ready. Get your Meta app, Phone Number ID, WhatsApp Business Account ID and permanent access token ready. Follow the manual setup guide up to Verify details. Your token must include whatsapp_business_messaging. Add whatsapp_business_management too, or templates will not sync. Move the inbox 1. Go to Settings › Inboxes and open the WhatsApp inbox. 2. On the Manual setup recommended banner, click Start manual migration. 3. Before you start: read what will be kept and updated, then continue. 4. Business details: enter the WABA ID and Phone Number ID. The Display phone number is shown for reference and cannot change. 5. Access token: paste your permanent access token. 6. Review migration: check the details and click Reconnect WhatsApp inbox. Chatwoot checks your token, account and number with Meta before changing anything. If a check fails, the inbox keeps its current connection. Check it worked - A new customer message arrives in the inbox - A reply from Chatwoot arrives on the customer's phone - You can send a template - Sync Templates in the Configuration tab brings in your templates