By harishmita
By harishmita
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.
1. WhatsApp in Chatwoot
Connect your WhatsApp Business number to Chatwoot and your team can answer WhatsApp chats from a shared inbox, alongside your other channels. You can also send approved template messages, run broadcast campaigns, collect CSAT ratings and take WhatsApp calls. What you can do on WhatsApp | Capability | What it does | Learn more | | ------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------- | | Shared WhatsApp inbox | Customer messages arrive as conversations your team can assign, label, reply to and resolve | 2. Choose how to connect WhatsApp | | Template messages | Start a conversation, or reply after 24 hours, with a message Meta has approved | 7. Templates and the 24-hour window | | Campaigns | Send one approved template to every contact with chosen labels. Business plan and above. | 8. WhatsApp campaigns | | CSAT surveys | Ask for a rating when a conversation is resolved, even after the 24-hour window has closed | 9. CSAT surveys on WhatsApp | | Calling | Customers call your business from WhatsApp and agents answer in the browser | 10. WhatsApp calling | | Account health | See your number's status, messaging limit, display name review and business profile inside Chatwoot | 11. Manage your WhatsApp number | Plan & access | | Chatwoot Cloud | Self-hosted | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | WhatsApp inbox (any connection method) | Startups plan and above, and the free trial. Not available on the free Hacker plan. | Included | | Quick setup with Meta (the fastest way to connect) | Included from the Startups plan. During the free trial, click Request access on the setup screen and submit your use case to turn it on. | Only if your installation has its own Meta app configured for it. Most self-hosted installations use manual setup. | | WhatsApp campaigns: sending | Business plan and above. Available automatically, no request needed. | Not a premium feature. Works on Community Edition and is on by default. | | Campaign analytics | Business plan and above | Enterprise plan only. Your installation's super admin turns on Campaign Analytics in Super Admin › Accounts › open the account › Edit, under Premium features, then clicks Save changes. | | Calling | Business plan and above | Needs a paid self-hosted plan with Enterprise Edition, from v4.15.0. Installing the Enterprise Edition build alone does not enable it. | | Templates, CSAT surveys, account health | Every plan that includes WhatsApp | Included | Who can do what: - Administrators connect inboxes and change inbox settings. - Agents added to the inbox answer conversations and send templates. See Pricing & Plans for what each plan includes. Your connection method decides what you can use Chatwoot connects to WhatsApp in three ways. Choose before you connect, because some features only work with WhatsApp Cloud API. | | Quick setup with Meta(WhatsApp Cloud API) | Manual setup(WhatsApp Cloud API) | Twilio | | -------------------------------------------------- | --------------------------------------------------- | --------------------------------------- | --------------------------------------- | | Setup effort | A few minutes in a Meta window. No developer setup. | Meta app, system user token and webhook | Twilio account, credentials and webhook | | Keep using the WhatsApp Business app on your phone | ✅ (Coexistence) | ❌ | ❌ | | Template messages | ✅ | ✅ | ✅ Twilio content templates | | Campaigns | ✅ | ✅ | ❌ | | CSAT surveys after 24 hours | ✅ | ✅ | ✅ | | Calling | ✅ | ✅ | ❌ | | Account health tab | ✅ | ✅ | ❌ | | Available on | Chatwoot Cloud | Cloud and self-hosted | Cloud and self-hosted | Using 360dialog? 360dialog is no longer offered for new inboxes. Existing 360dialog inboxes keep working for conversations but cannot use campaigns, calling or CSAT templates. How to check what you have - Your inbox type: go to Settings › Inboxes and open your WhatsApp inbox. An Account Health tab means it is a WhatsApp Cloud API inbox. - Quick setup: on the WhatsApp setup screen, a Request access box instead of the connect button means Quick setup is not yet on for your account. - Campaigns: WhatsApp under Campaigns in the sidebar means campaigns are available for your account. - Calling: a Calls tab in the inbox settings means calling is available for your account. Your path through this guide 1. Connect: Choose how to connect WhatsApp, then the page for your method (3, 4 or 5). 2. Learn the one rule that shapes WhatsApp: Templates and the 24-hour window. 3. Add what you need: campaigns (8), CSAT (9), calling (10). 4. Keep it healthy: Manage your WhatsApp number. 5. When something breaks:Troubleshoot WhatsApp.
2. Choose how to connect WhatsApp
Which method is right for you? | Your situation | Use | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | You are on Chatwoot Cloud and connecting a new number | Quick setup with Meta (page 3) | | Your number is in the WhatsApp Business app and you want to keep using the app on your phone | Quick setup with Meta and choose to connect your existing app (page 3). This is called Coexistence. | | Your number is already on the WhatsApp Business Platform (API), you are a tech provider onboarding your own number, or you are self-hosted | Manual setup (page 4) | | You already send SMS or WhatsApp through Twilio and want to keep billing there | Twilio (page 5). Note that campaigns and calling are not available with Twilio. | Not sure which features you need? Check Your connection method decides what you can use in WhatsApp in Chatwoot. Before you start (all methods) - You are an administrator in Chatwoot. - For WhatsApp Cloud API: you can sign in to Facebook with an account that is an admin of the Meta business portfolio that owns (or will own) the WhatsApp Business Account. - Your number can receive a verification SMS or voice call. Landlines need voice verification. Numbers that answer with an automated phone menu (IVR) are not supported by Meta. - You have your business details ready, and a display name that follows Meta's display name guidelines. See Display name in Manage your WhatsApp number. Can I switch methods later? - Quick setup to manual setup: possible in some cases, without losing conversations. Chatwoot support checks eligibility first, and it is not available for numbers using Coexistence (the WhatsApp Business app). See Move a Quick setup inbox to manual setup. - Manual setup to Quick setup: not available from the dashboard. - Between Twilio and WhatsApp Cloud API: this means creating a new inbox. Conversations stay in the old inbox. Start Go to Settings › Inboxes › Add Inbox › WhatsApp. You will see two choices: - WhatsApp Cloud: Quick setup with Meta (or manual setup, via the link at the bottom of that screen) - Twilio
3. Connect with Quick setup with Meta
Quick setup with Meta (also called Embedded Signup) connects your number through a Meta window. Chatwoot sets up the webhook, token and phone number for you. Plan & access - Chatwoot Cloud only. Included from the Startups plan. During the free trial, click Request access, describe how you will use WhatsApp, and click Submit to turn it on. WhatsApp is not available on the free Hacker plan. See Pricing & Plans. - Administrators only. Before you start - Sign in to Facebook with an account that is an admin of the right Meta business portfolio. - Allow pop-ups for Chatwoot and Facebook. - Keeping the WhatsApp Business app (Coexistence): update the app to the latest version and keep the phone online. Coexistence works with the WhatsApp Business app, not the personal WhatsApp app. Meta decides which numbers are eligible. Connect your number 1. Go to Settings › Inboxes › Add Inbox › WhatsApp and choose WhatsApp Cloud. 2. Click Connect with WhatsApp Business. A Meta window opens. 3. In the Meta window, sign in, then choose or create your business portfolio and WhatsApp Business Account. 4. Choose your number: - A new number: enter it and verify it with the code Meta sends by SMS or voice call. - A number in the WhatsApp Business app (Coexistence): choose to connect your existing app, then: 1. Copy the verification code shown in the Meta window. 2. On your phone, open the message from Facebook Business, tap Connect, then Connect to the Business Platform. 3. Tap Confirm and choose whether to share your chat history. 4. Enter the copied code in the app, then finish the steps in the Meta window. 5. When you see WhatsApp Business Account Connected!, add the agents who should answer this inbox. Test it: send a WhatsApp message to your business number from another phone. It should appear as a new conversation. Reply from Chatwoot and check it arrives. With Coexistence, also check the app on your phone still works. What happens next - Templates approved in your WhatsApp Business Account sync to Chatwoot automatically. See Templates and the 24-hour window. - Calling: if calling is available on your plan, Chatwoot tries to turn it on during setup. If your number is not enrolled with Meta's Calling API, the inbox is still created and you can turn calling on later. See WhatsApp calling. - Chat history (Coexistence): Meta syncs history only within 24 hours of connecting. Keep the app open with a stable connection. Large histories take longer. - Meta reviews: Meta may ask you to verify your business (upload documents) and will review your display name. Track both in Account Health. See Manage your WhatsApp number. If Quick setup is unavailable Sometimes Meta restricts Quick setup for all providers. Chatwoot then shows a notice on the setup screen. During that time: - Numbers already on WhatsApp Cloud API can use manual setup. See Connect with WhatsApp Cloud API (manual setup). - Numbers using Coexistence cannot be connected until the restriction lifts. Something went wrong? See Connecting in Troubleshoot WhatsApp. It covers every Meta error code you may see during this flow.
4. 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.
5. Connect WhatsApp through Twilio
Connect a WhatsApp number that you manage in Twilio. Good if you already use Twilio for SMS or WhatsApp and want to keep billing there. 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. - With Twilio you can send templates (Twilio content templates) and CSAT surveys. You cannot use WhatsApp campaigns or WhatsApp calling. See the table in WhatsApp in Chatwoot. Before you start - A Twilio account with a WhatsApp sender (number) approved in Twilio. - Your Twilio Account SID and Auth Token, or an API Key SID and API Key Secret. - Optional: a Messaging Service SID, if you send through a Twilio Messaging Service. To get one, in the Twilio Console go to Messaging › Services › Create Messaging Service, complete the steps, then copy the service's SID. - If you use Twilio Studio, do not replace your webhook with Chatwoot's Callback URL. This stops your Studio flow. Contact support first. Connect your number 1. Go to Settings › Inboxes › Add Inbox › WhatsApp and choose Twilio. 2. Enter an Inbox Name. 3. Enter the Phone Number, starting with + and with no spaces. If you send through a Messaging Service, turn on Use a Twilio Messaging Service instead and enter the Messaging Service SID. The Phone Number field is hidden when this is on. You enter one or the other, not both. 4. Enter your Account SID, and either your Auth Token or (after turning on Use API Key Authentication) your API Key SID and API Key Secret. 5. Check that you entered either the Phone Number or, with Use a Twilio Messaging Service turned on, the Messaging Service SID (see step 3). 6. Click Create Twilio Channel, then add agents. 7. Copy the Callback URL shown in Chatwoot and set it as the incoming message webhook in the Twilio Console: - For a WhatsApp sender: go to Messaging › Senders › WhatsApp Senders and select your sender. In Endpoint configuration, set the webhook URL for incoming messages to the Callback URL and save. - For a Messaging Service: go to Messaging › Services, select your service, then Integration, and paste the URL there. To find the Callback URL later, go to Settings › Inboxes, open your inbox and select the Configuration tab. Test it: send a WhatsApp message to your number from another phone and check it arrives in Chatwoot. Reply and check if it arrives on the phone. What happens next - Templates: approved Twilio content templates sync to Chatwoot. See Twilio content templates in Templates and the 24-hour window.
6. 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
7. Templates and the 24-hour window
The 24-hour window WhatsApp lets you send any message for 24 hours after the customer's last message. After that, you can only send a template: a message Meta has approved in advance. - In Chatwoot, when the window has closed, the reply box shows: You can only reply using a template message due to 24-hour message window restriction - As soon as the customer replies, a new 24-hour window opens and you can type freely again. - To start a conversation with a customer who has not messaged you, you also need a template. Plan & access - Every plan that includes WhatsApp (Startups and above, and the free trial). Works with WhatsApp Cloud API inboxes (Quick setup or manual) and Twilio inboxes. See Pricing & Plans. - Agents in the inbox can send templates. Administrators can sync templates and manage tokens. Where templates come from Templates are created and approved outside Chatwoot, then synced in. | Inbox type | Create templates in | Sync to Chatwoot | | ------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | WhatsApp Cloud API | WhatsApp Manager (Account tools › Message templates). Meta reviews them, usually within 24 hours. | Automatically after some time, or right away with Sync Templates in the inbox's Configuration tab | | Twilio | Twilio Console (Content Template Builder), then submitted to WhatsApp for approval | Automatically, or with the sync button in the inbox settings | Only approved templates of a supported type appear in Chatwoot. Send a template in a conversation 1. Open the conversation and click the template icon in the reply box. 2. The Whatsapp Templates picker opens. Search for and pick a template. 3. Fill in the variables, for example the customer's name or an order number. For media headers, paste a public URL to the image, video or document. 4. Check the message, which updates as you fill in the variables, and click Send Message. Test it: send a template to your own number first and check how it looks on the phone. What a template is made of Templates can include a header, body, footer and buttons: - Header: text, image, video or document - Body: your message, with variables such as the customer's name - Footer: one short line of text - Buttons: quick replies, website links, phone numbers and copy code Some WhatsApp template types cannot be used in Chatwoot yet: authentication (OTP) templates, list, product and catalog templates, carousel templates, location headers, call permission templates, and forms, payments and Flows. Media in a template header The file must be at a public link that Meta can reach, with no login. Meta's limits: | Type | Formats | Maximum size | | -------- | ---------------------------------- | ------------ | | Image | JPEG, PNG | 5 MB | | Video | MP4, 3GPP (H.264 video, AAC audio) | 16 MB | | Document | PDF | 100 MB | Other document types, such as Word, Excel, PowerPoint and text files, can be sent as ordinary messages inside a conversation, but not in a template header. Twilio content templates support text (up to 100 variables), media, quick reply and call-to-action templates. They cannot be used in campaigns. List picker, catalog and carousel templates are not supported. - Use numbered variables, such as 1, 2, 3, in order with no gaps. The number of variables you fill in must match the template. - Check a template's approval status in the Twilio Console, not in WhatsApp Manager. - If sync fails, check that the inbox's Account SID and Auth Token (or API Key SID and API Key Secret) are still valid in Twilio, then sync again. Good practice - Utility templates (order updates, reminders) are for transactional messages. Marketing templates need the customer's opt-in and follow Meta's sending rules. - Keep a small set of well-named templates your team knows how to use. - Meta watches message quality. Too many blocked or ignored messages can lower your messaging limit. See Messaging limit in Manage your WhatsApp number. If templates do not sync (Quick setup inboxes) Sometimes messages still work but templates will not sync. This happens when the connection made during Quick setup loses permission to read your WhatsApp Business Account. You can fix it by giving Chatwoot a Business Management token, used only for syncing templates. Plan & access: Chatwoot Cloud, Quick setup inboxes only (including Coexistence). Manual setup inboxes use their own token, so check that token has whatsapp_business_management instead. You must be an admin in both Chatwoot and the Meta business portfolio. 1. In Meta Business Settings, go to Users › System users and select (or create) an admin system user. A dedicated one, such as Chatwoot template sync, is easiest to manage. 2. Click Assign assets, choose WhatsApp accounts, pick the WhatsApp Business Account connected to Chatwoot, and grant full control. Assign only that account. 3. Click Generate token, choose the Meta app linked to that WhatsApp account, and pick an expiry (60 days is more secure; Never needs less upkeep). 4. Select only whatsapp_business_management and copy the token. Meta may show it only once. 5. In Chatwoot, go to Settings › Inboxes, open the inbox, go to the Configuration tab and find Add Business Management Token. Paste the token and click Add. 6. Click Sync Templates. Treat the token like a password. If you revoke it in Meta, replace it in Chatwoot or template sync will stop. - 60-day token: template sync stops when it expires. Generate a new token and replace the old one. - Never-expiring token: it can still stop working if the system user, app, permission or asset assignment changes. - To replace a token: once a token is saved, the field reads Replace Business Management Token. Paste the new token and click Replace.
8. WhatsApp campaigns
Send one approved template to every contact with the labels you choose, at a scheduled time, and see who received and read it. Plan & access - Chatwoot Cloud: WhatsApp campaigns are available on the Business plan and above. They are on automatically; you do not need to request them. - Self-hosted: It works on all plans. - Campaign analytics: Business plan and above on Cloud. On self-hosted, Enterprise plan only. Your installation's super admin turns on Campaign Analytics in Super Admin › Accounts › open the account › Edit, under Premium features, then clicks Save changes. - Inbox: WhatsApp Cloud API only (Quick setup or manual). Twilio and 360dialog inboxes cannot send campaigns. - Who: administrators. See Pricing & Plans. How to check you have it: open Campaigns in the sidebar. If WhatsApp appears under it, campaigns are available for your account. Before you start At least one approved template in your WhatsApp Cloud API inbox. See Templates and the 24-hour window. Create a campaign 1. Go to Campaigns › WhatsApp and click Create campaign. 2. Basic settings: enter a Title and pick your WhatsApp Inbox. The Account information panel shows the number's messaging tier, account status and quality rating from Meta. 3. Audience: choose one or more Labels. Contacts with any of the labels are included. Click View to see exactly who is included. The panel shows how many customers your WhatsApp account can message. 4. Template: pick an approved template and fill in its header, variables and buttons. Check the Message preview. 5. Click Schedule campaign, pick a time and click Create. Test it: send the first campaign to a test label that contains only your own number. The Live test button at the top of the form is not available yet (its tooltip reads Live test will be available soon). What to expect - The campaign sends once, at the scheduled time. Its status moves from Scheduled to Processing to Completed. - You can edit it while it is Scheduled. Once it starts sending, it cannot be changed. - Contacts without a phone number are skipped. - Only approved templates can be sent. Free-text broadcasts are not possible on WhatsApp. - How many customers you can message in a day is set by Meta's messaging limit, shared across all numbers in your business portfolio. See Manage your WhatsApp number. - When customers reply, a new conversation opens in the inbox and the 24-hour window starts. - Campaign messages sent to a contact appear in their WhatsApp conversation, marked Campaign. See results Analytics is available on the Business plan and above (Cloud), or a paid self-hosted plan. Click View analytics on the campaign to see: - Audience, Submitted to WhatsApp, Delivered, Read, Failed and Skipped - The Deliveries table: each contact's status and, for failures and skips, the Reason. Filter it by status. - While a campaign is still sending, the numbers are partial. Campaigns sent before campaign analytics was introduced have no analytics.Analytics may be unavailable for campaigns sent before delivery tracking was introduced. Good practice - Create a dedicated label for each campaign instead of reusing a broad one. - Use Utility templates for updates and Marketing templates only for contacts who opted in. - Watch your quality rating after each campaign. Many blocks or reports can lower your messaging limit. Troubleshoot | Symptom | Likely cause | What to do | | ----------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No WhatsApp under Campaigns | Your plan does not include campaigns, or you are not an administrator | On Chatwoot Cloud, check you are on the Business plan or above. Check you are signed in as an administrator. If both are true and the tab is still missing, contact Chatwoot support. | | My inbox is not in the list | It is a Twilio or 360dialog inbox | Campaigns need a WhatsApp Cloud API inbox. See Choose how to connect WhatsApp | | This inbox has no approved templates that can be used in a campaign | No approved templates, or they have not synced | Click Sync Templates. See Templates and the 24-hour window | | Some contacts did not receive it | No phone number, missing label, or Meta rejected the message | Open View analytics, filter by Failed or Skipped, and read the reason. For error codes see | | I cannot edit the campaign | It has already started sending | Create a new campaign Troubleshoot WhatsApp |
9. CSAT surveys on WhatsApp
Ask customers to rate your support when a conversation is resolved, even after the 24-hour window has closed. Chatwoot creates the WhatsApp template for you, submits it to Meta and sends it once it is approved. Plan & access - Every plan that includes WhatsApp (Startups and above, and the free trial). Works with WhatsApp Cloud API and Twilio inboxes. See Pricing & Plans . - Administrators set it up. Set it up 1. Go to Settings › Inboxes, open your WhatsApp inbox and go to the CSAT tab. 2. Turn on Enable CSAT. 3. Fill in the Message, the Button text and the Language. The preview shows how it will look in WhatsApp. 4. Save. Chatwoot creates the template and sends it to Meta for review. 5. Wait for the status to show Approved by WhatsApp. Optional: click Check utility fit to see whether Meta is likely to treat your message as Utility, with a suggested rewrite. It is guidance, not a guarantee. Optional: choose which conversations get a survey using label rules. Test it: resolve a test conversation with your own number. You should receive the survey with a button that opens the rating page. Template statuses | Status | Meaning | | ------------------------------ | -------------------------------------------------------------- | | Pending WhatsApp approval | Meta is reviewing the template | | Approved by WhatsApp | Surveys are sent automatically when conversations are resolved | | Meta rejected the template | Meta declined it. Change the message and save to resubmit. | What to expect - One survey per conversation. - Until the template is approved, the survey goes out as a regular message only while the 24-hour window is open. If the window has closed, no survey is sent, and the conversation shows CSAT survey not sent due to outgoing message restrictions. - Meta does not allow editing approved templates. When you change the message, button text or language, Chatwoot asks you to confirm, deletes the current template and submits a new one for approval. Until Meta approves it, surveys follow the rule above. If saving fails, save again, because the previous template may already be deleted. Good practice - Keep the message short and friendly, with clear button text such as "Rate now". - Use label rules so only meaningful conversations get a survey. - Change the template rarely. Each change pauses template surveys until Meta approves the new one.
10. WhatsApp calling
Customers can call your business from WhatsApp, and agents answer in their browser. Agents can also call customers who have agreed to receive calls. Plan & access - Chatwoot Cloud: Business plan and above. Self-hosted: a paid plan with Enterprise Edition, from v4.15.0. Installing the Enterprise Edition build alone does not enable it. See Pricing & Plans. - Inbox: WhatsApp Cloud API only. Both connection methods work, Quick setup and manual setup. Not available for Twilio or 360dialog WhatsApp inboxes. - Your number must be enrolled in Meta's WhatsApp Business Calling API. - Administrators turn it on. Agents in the inbox take and make calls. How to check you have it: open the inbox settings. A Calls tab means calling is available for your account. Turn on calling New inbox: go to Settings › Inboxes › Add Inbox › WhatsApp Call and complete Quick setup. Chatwoot turns calling on during setup. Existing inbox: 1. Go to Settings › Inboxes, open your WhatsApp inbox and go to the Calls tab. 2. Turn on Enable WhatsApp Calling. 3. Optional: edit the Call permission request message that customers see when you ask to call them. 4. Optional: set the other toggles on the Calls tab: - Allow incoming calls: when off, incoming calls are declined automatically, agents are not notified and no conversation is created. Outgoing calls still work. - Record calls: attaches each call's recording to the conversation. - Transcribe recordings: shown when recording is on. Adds a transcript using Captain, and needs audio transcription turned on for your account. If you see Voice calling couldn't be turned on for this number, your number is not enrolled in Meta's Calling API yet. Ask Meta or your WhatsApp Business Solution Provider to enroll it, then try again. Before your first call: each agent must allow microphone access for Chatwoot in their browser. Test it: from another phone, open WhatsApp, find your business and tap call. A call notification should appear in Chatwoot. Taking and making calls - Incoming: a call window shows the caller's name, number and the inbox. Agents can join or reject the call. - Outgoing: in a conversation, click Start WhatsApp call. If the customer has not agreed to receive calls, Chatwoot sends them a call permission request instead: Sent a call permission request to the contact. Try again once they accept. Once they accept, call again. - Call states shown in the conversation: Incoming call, Outgoing call, Call in progress, Call ended, Missed call, No answer. - Recordings are attached to the conversation when available. Transcripts are added if your account has Captain audio transcription turned on. Who gets the call - Assigned conversation: only the assignee's call window rings, whatever their availability status. - Unassigned conversation: inbox agents who are set to Online ring. - No one online: all inbox agents and all administrators ring. The first agent to join takes the call. If the conversation has no assignee, the agent who joins is assigned to it. When an agent starts a call, the conversation is assigned to them if it has no assignee. Good practice - Ask for call permission early in the conversation, not at the moment you need to call. - Make sure agents who take calls are set to online, so calls are not missed. Troubleshoot | Symptom | Likely cause | What to do | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No Calls tab | Your plan does not include calling (Business and above), or the inbox is not WhatsApp Cloud API | Check your plan in Pricing & Plans and your connection method in WhatsApp in Chatwoot | | Voice calling couldn't be turned on | The number is not enrolled in Meta's Calling API | Ask Meta or your provider to enroll it, then try again | | Agent cannot hear or be heard | The browser has no microphone permission | Allow microphone access for Chatwoot in the browser settings | | Call permission request already sent recently | The customer has not answered the last request | Wait for the customer to accept before trying again |
11. Manage your WhatsApp number
See your number's health, messaging limit and business profile without leaving Chatwoot. Plan & access - Every plan that includes WhatsApp (Startups and above, and the free trial), for WhatsApp Cloud API inboxes (Quick setup or manual). Twilio inboxes do not have this tab. check Pricing & Plans - Administrators. Open Account Health Go to Settings › Inboxes, open your WhatsApp inbox and choose the Account Health tab. Click Go to Meta Business Manager to change anything that is managed by Meta. What you will see | Section | What it tells you | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Business profile | The description, address, email and websites customers see in your WhatsApp profile. These are read-only here: change them in Meta's WhatsApp management tools. | | Phone number | Display number, WhatsApp display name and its review status, phone number status, whether Coexistence is on, and the Phone number ID | | Health and capacity | Quality rating (Green, Yellow, Red), Business messaging limit, account mode (Sandbox or Live) and throughput | | Business account | WhatsApp Business Account name and ID, and the business portfolio that owns it | | Webhook Configuration | Whether Meta's callback URL for this number points to this Chatwoot inbox. Webhook configured successfully confirms the setting only, not that messages are arriving. If it shows Webhook not configured or Webhook URL mismatch, click Register Webhook, then send a test message to your number and reply from Chatwoot. | Messaging limit The Business messaging limit is set by Meta: how many unique customers you can message outside the 24-hour window (with templates) in a rolling 24 hours. It is shared by all numbers in your business portfolio. Meta raises it as you send good-quality messages, and can lower it if quality drops. Display name Your display name is the business name customers see. Meta reviews it. | Status in Chatwoot | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Approved | Shown at the top of chats (a name the customer saved can appear instead) | | Not reviewed yet | Saved, but customers may see your number until Meta reviews it. Meta starts the review once you reach a higher messaging limit. | | Under review | Meta is reviewing it. Do not change it again until the review ends. | | Not approved | Meta rejected it. Change it in Meta Business Manager and resubmit. | To get it approved first time: use your real business or brand name, matching your website and Meta Business Manager. Avoid generic words ("Support", "Official"), emojis, symbols, taglines and excessive capitals. After a display name change, Meta may require the number to be registered again before messages flow normally. See Messages stopped arriving in vTroubleshoot WhatsApp. If the connection needs attention - WhatsApp connection needs to be refreshed (Quick setup inboxes): click Reconnect WhatsApp on the inbox, or go to Configuration and click Reconfigure. You need admin access to the WhatsApp Business Account. - WhatsApp access token needs attention (manual setup inboxes): go to Configuration and replace the access token with a valid permanent token.
12. Troubleshoot WhatsApp
Before you change anything: do not delete your WhatsApp account, remove your WhatsApp Business Account or disconnect a provider as a general fix. The right recovery depends on how your number is set up today. Note the full error message, any code, and the screen where it appeared. Connecting First, know how your number is used today: a new number, a number in the WhatsApp Business app (use Coexistence to keep the app), or a number on another API provider (these use different paths). See Choose how to connect WhatsApp. | What you see | Meta code | What it means and what to do | | ------------------------------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Number not eligible, needs more activity in the WhatsApp Business app | 3441045 | A Coexistence eligibility check. Keep using the app normally with real customers and try again later. Meta publishes no minimum. Do not generate fake activity or recreate the account. | | Number not registered with the WhatsApp Business app | 2655095, 2655048 | Check the number and country code, and that it is in the Business app (not personal WhatsApp). For an API-only new number, use the new-number path. | | Update the app | 4563015 | Install the latest WhatsApp Business app and try again. | | Business already sharing this account with a partner | 2655093 | Meta reports that this WhatsApp Business Account is already associated with a partner. This does not confirm that the other provider is still active. Switching partners is not possible in this flow. Contact support before disconnecting anything. | | Already registered with the product, or disconnect your business platform | 3441049, 2655094 | An existing platform connection must be handled first. If you do disconnect on purpose, Meta requires a 15-minute wait before retrying. | | Number not associated with the business you selected | 3441041 | Pick the business portfolio that owns the number. | | Number linked to a Facebook Page | 2655082 | Check Meta Business Suite › Settings › Accounts › Pages. Remove the Page link (after confirming with the Page admin) or use another number. | | Account uses marketing messages | 3441047 | Select a different WhatsApp Business Account. Retrying does not fix it. | | Business or account restricted | 2655089, 3441040, 2388107 | Open Meta Business Support Home, review the restriction and appeal. Do not create new accounts to work around it. | | Verification started with another partner | 2494143 | Continue with that partner, or apply for Meta Business Verification directly. | | Feature unavailable in your region | 3441042 | Check the country code. If correct, this flow is not available for that number yet. | | Code could not be sent or verified | 2388091, 2388093 | Recheck the number and use a method it can receive (landlines need voice). IVR numbers are not supported. | Other connection problems - Account or portfolio missing: sign in with the Facebook account that is an admin of the right portfolio. "User does not have permission" means an existing admin must grant access. - Facebook account too new: wait a few hours, or use an established account with business access. - Business verification in progress: check Meta Business Suite › Security Center. - Display name rejected: see Display name in Manage your WhatsApp number. - Phone number limit reached: pick the existing number if it is already listed, or ask Meta for a higher limit. Do not delete a working number. - "You have guessed too many times": wait about 12 hours. "Requested your code too many times": follow the wait Meta shows. - Coexistence prompt or QR code does not work: use the latest Business app, keep the phone online, keep the signup window open, and check camera permission for QR codes. - Meta window does not open or stops: allow pop-ups, disable blocking extensions, complete any Meta security check, and wait a few minutes after a temporary error. - Meta finished, but no inbox in Chatwoot: refresh and check Settings › Inboxes before trying again. Do not create duplicate inboxes. - Coexistence chat history incomplete: keep the app open online. Meta syncs history only within 24 hours of connecting. Contact support promptly rather than reconnecting. Receiving and sending messages | Symptom | Likely cause | What to do | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Messages stopped arriving, but the number shows Connected and quality is Green | Something in the connection needs attention: registration, permissions or the webhook. This often follows a display name or profile change. After any fix, send a test message to your number and reply from Chatwoot to confirm both directions work. | Contact support first so we can check the registration, permissions and webhook on your existing inbox. If the number does need registering again, you do that yourself in Meta, following Meta's registration process. Do not delete the number or create a new inbox. Coexistence numbers need a different recovery path, so contact support before changing anything. | | No messages arrive after setup | One possible cause: the webhook is not registered or points elsewhere | Open Account Health. If Webhook Configuration shows Webhook not configured or Webhook URL mismatch, click Register Webhook. Then test it: send a message to your number from another phone, check it arrives in Chatwoot, and reply from Chatwoot. If the webhook shows as configured but messages still do not arrive, contact support. For Twilio, check the Callback URL in Twilio (page 5). | | You can only reply using a template message | More than 24 hours since the customer's last message | Send a template. See Templates and the 24-hour window | | A message fails with error 131049 | Meta did not deliver this marketing template to keep engagement healthy. WhatsApp limits how many marketing messages each person receives from all businesses. | Do not resend or click Retry straight away. Wait at least 24 hours before sending this person another marketing template. Utility templates are not affected. If the customer replies, marketing messages within the 24-hour window do not count toward the limit. | | WhatsApp connection needs to be refreshed / Reconnect WhatsApp | The Quick setup connection expired | Click Reconnect WhatsApp. See Manage your WhatsApp number | | WhatsApp access token needs attention | The manual setup token expired or was revoked | Replace it in the inbox's Configuration tab | Templates | Symptom | Likely cause | What to do | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | A template is missing in Chatwoot | Not approved yet, not synced, or a type Chatwoot does not support | Check its status in WhatsApp Manager and click Sync Templates. Check the supported types on page 7. | | Messages work but templates never sync (Quick setup) | The connection lost permission to read your WhatsApp Business Account | Add a Business Management token (page 7) | | Business Management token: Business management token must grant the whatsapp_business_management permission | whatsapp_business_managementwas not selected | Generate a new token with that permission | | Business Management token: no permission to access, or token invalid | The system user lacks the WhatsApp account, or the token expired or belongs to another app | Check the system user's assigned assets and app, then generate a new token | | Token accepted, templates still missing | The token can access a different WhatsApp Business Account | Confirm the system user has the exact account used by the inbox, and the templates exist there | | A template fails to send, or media does not show | Empty variables, a private or broken media link, or a file over Meta's limits | Fill every variable, use a public link, check format and size (page 7) | | A dynamic URL button does not work | Known issue with some dynamic URL button setups | Use a static URL in the template | Contacts and phone numbers Numbers look different in WhatsApp and Chatwoot (Brazil, Mexico, Argentina). These countries changed their mobile number formats, and WhatsApp may still use the old one: - Brazil: a 9 was added after the area code (+55 11 9 8765-4321 vs +55 11 8765-4321). - Argentina: a 9 after the country code may or may not be present (+54 9 11 ... vs +54 11 ...). - Mexico: WhatsApp may add a 1 after the country code (+52 1 ... vs +52 ...). Chatwoot matches both formats to the same contact automatically, so you should not get duplicates. The number may simply look different in the two places. Contact support If you are still stuck, contact Chatwoot support with: - The full error message and code, and a screenshot - The step that failed, and whether the error appeared in Meta or in Chatwoot - Your inbox link, the business phone number with country code, and the time of the attempt with time zone - How the number is used: new, WhatsApp Business app, or another provider - For Coexistence: app version, how long it has been used, and whether it still works on the phone - Your business portfolio ID, WhatsApp Business Account ID and Phone Number ID, labelled Never share your password, access token, verification code or two-step PIN. Hide them in screenshots. Chatwoot cannot override Meta's decisions on restrictions or reviews.