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.
How AI Credits work in Captain?
This guide explains how AI credits are consumed, how your credits are updated when you top up, when your monthly renewal happens, what happens when you change plans, and how notifications work if your credits run out. How are AI credits consumed? AI credits are deducted whenever an AI action is performed. Examples include: - Captain assistant responses - Copilot lookups - Editor actions (rephrase, summarise, suggest a reply) - Label Suggestions - Any workflow or automation that triggers a model call - Audio transcription Different models consume credits at different rates. At the moment, all actions consume 1 credit per message, since a fixed model configuration only is supported. This will change in the future as more model options are supported, at which point different models may consume different credit amounts per action. If an action cannot be completed due to insufficient credits, a credit failure occurs (explained later). When does usage reset? Usage resets to 0 only during monthly renewal. Usage does NOT reset when: - Topping up credits - Changing your plan - Changing seat count This means you can top up credits at any time without losing track of your current usage cycle. How are AI credits updated? 1. Topping Up Credits When you buy additional credits, they are simply added to your existing balance. Example - Previous credits: 1500 - Top-up: 1000 - New total credits: 2500 No other values change. 2. Monthly Renewal Every plan includes a monthly free credit allowance. At renewal, we adjust usage and credits based on how much you consumed in the previous month. Case A: No usage Usage: 0 â Your total credits do not change. Case B: Usage is less than your monthly free credits - Previous credits: 1500 - Usage: 200 - Monthly free credits: 300 â No deduction is applied. â Total credits stay 1500. â Usage resets to 0. Case C: Usage exceeds your monthly free credits - Previous credits: 1500 - Usage: 600 - Monthly free credits: 500 Overage = 600 â 500 = 100 â Deduct overage from total credits. â New total credits: 1400 â Usage resets to 0. 3. Changing Your Plan When you switch plans, your monthly free credits may increase or decrease. Example - Startup plan: 300 free credits - Business plan: 500 free credits - Enterprise plan: 800 free credits If you switch from Startups to Business, your total credits would increase by 200. Similarly, if you downgrade from Business to Startups, your total credits would decrease by 200. Your usage remains unchanged. Credit Failure (Insufficient Credit Handling) A credit failure occurs when an AI action is triggered but there are not enough credits to perform it. What Happens During Credit Failure - The action is not executed. Any available fallbacks are executed â for example, if the assistant cannot respond, the conversation is transferred directly to an agent. - We log the failed action internally for audit
đ„ CaptainHow to Set Up Custom Tools for Captain?
Custom Tools let Captain call your external APIs during conversations â so it can check warranty status, verify service coverage, or fetch data from your own services without handing off to a human agent. When a customer asks a question, Captain extracts the relevant values from the conversation, inserts them into your API request, and uses the response to form its reply. Custom Tools is available on the Business plan and above. Creating a tool Navigate to Captain -> Tools and click Create a new tool. Fill in the following fields: Tool Name â A short name like "Warranty Lookup" or "Service Area Check" (max 55 characters). Description â Tell Captain when to use this tool. This is the most important field. Write it like you're briefing a support agent: "Checks the warranty status of a product by its serial number." Vague descriptions like "Warranty API" will cause Captain to miss opportunities to use the tool. Method â Choose GET (for fetching data) or POST (for submitting data). Endpoint URL â Your API's URL. Use {{ parameter_name }} to insert values extracted from the conversation: https://api.yourcompany.com/v1/warranty/{{ serial_number }} The URL must use HTTPS, must be a hostname (not an IP address), and cannot point to localhost or private networks. Authentication â Choose how your API authenticates requests: - None â No authentication - Bearer Token â Sends your token in the Authorization header - Basic Auth â Sends a username and password - API Key â Sends a custom header name and value (e.g., X-API-Key) Authentication credentials are only visible to account administrators. Parameters â Define what Captain should extract from the customer's message. Each parameter needs a name, type, and description. For example: serial_number (String) â "The product serial number, found on the back of the device." Request Template (POST only) â A JSON body template using Liquid syntax. Response Template â Controls what Captain sees from your API's response. If left blank, Captain receives the raw JSON. Use Liquid to extract relevant fields, for example: Serial {{ response.serial_number }}: {{ response.warranty_status }}. Expires: {{ response.expiry_date }}. Use response to access the parsed JSON body. Response templates help Captain focus on the relevant data and avoid internal fields like database IDs or debug info. Testing your tool Click Test connection before saving to verify your endpoint is reachable. The test reports the HTTP status code. A green result (HTTP 200â299) means the connection and authentication are working. Note that the test sends the URL without filling in parameter values, so it only verifies that your endpoint is reachable and your credentials are accepted. If the test fails, check the following: - 401 Unauthorised â Your authentication credentials are incorrect. Double-check your bearer token, API key, or username/password. - 403 Forbidden â Your API is rejecting the request. If you require identity verification, note that test requests don't include contact headers. - 404 Not Found â The endpoint URL is wrong. Verify the path and ensure your API is running. - Timeout â Your API took too long to respond. Custom tools have a 30-second timeout; make sure your endpoint responds within that window Context sent with every tool call When Captain calls your API, it includes metadata headers so your backend knows the context: - X-Chatwoot-Account-Id â Your account ID - X-Chatwoot-Conversation-Id â The conversation ID - X-Chatwoot-Contact-Email â The customer's email (if available) - X-Chatwoot-Contact-Inbox-Verified â Whether the customer's identity is HMAC-verified - X-Chatwoot-Assistant-Id â The Captain assistant making the call - X-Chatwoot-Tool-Slug â The tool's internal identifier - X-Chatwoot-Contact-Id â The customer's contact ID - X-Chatwoot-Contact-Phone â The customer's phone number (if available) - X-Chatwoot-Conversation-Display-Id â The conversation's display number You can use these headers to look up the customer in your own system, log which conversations triggered API calls, and verify request authenticity. Security Built-in protections: - All endpoints must use HTTPS - Requests to private IP ranges, localhost, and .local domains are blocked - HTTP redirects are not followed - Responses are capped at 1 MB - Auth credentials are only visible to administrators Identity verification: If your tool returns customer-specific data (orders, billing, account details), your API should check the X-Chatwoot-Contact-Inbox-Verified header. Without HMAC verification enabled on your inbox, a visitor could set any email address in the chat widget. Only return sensitive data when this header is true. For tools that return public data this check is not needed. Prompt injection: If your API returns user-generated content (reviews, forum posts), malicious text could influence Captain's behavior. Use response templates to extract only structured fields, and sanitize content on your API side. Limits - Max tools per account â 15 - Recommended â 10 or fewer. A warning appears above 10; more tools make it harder for Captain to pick the right one. - Tool name length â 55 characters - Response size â 1 MB max - Request timeout â 30 seconds When to use custom tools Custom tools are best suited for structured lookups with predictable inputs â checking system status, fetching schedules, or looking up records by ID. If you already have a dedicated Chatwoot integration for your use case (e.g., Shopify for e-commerce), use that instead â dedicated integrations handle search, fuzzy matching, and data sync more reliably than a single API call. Examples Warranty Lookup When a customer asks whether their product is still under warranty, Captain can check it using the serial number. - Tool Name: Warranty Lookup - Description: Checks the warranty status of a product by its serial number. Use when a customer asks if their product is covered, when the warranty expires, or what type of coverage they have. Service Area Check For businesses that operate in specific regions â customers ask whether service is available at their location. - Tool Name: Service Area Check - Description: Checks whether service or delivery is available in a specific area using the customer's zip code or city name. Custom Tools work best when the inputs are straightforward and the API response is predictable â status checks, lookups, and other structured queries are a great fit.
đ 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.
Whatsapp4. Connect 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, 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 (page 3) 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. In Send and receive messages, open the From selector and pick your number, or choose Add phone number, complete the business profile and verify with the code Meta sends. 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, 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. 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. | | 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, seeTroubleshoot 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.
Whatsapp6. Move 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 - Chatwoot Cloud Pricing & Plans, administrators only. - 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 Get your Meta app, Phone Number ID, WhatsApp Business Account ID and permanent access token ready. Follow steps 2 to 4 in Connect with WhatsApp Cloud API (manual setup). 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