Chatwoot
en
Language
en English pt_BR Portuguese (Brazil) es Spanish de German fr French ar Arabic

12. Troubleshoot WhatsApp

Open in
View as Markdown Open in ChatGPT Open in Claude
harishmita

harishmita

Last updated on Oct 12, 2026

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.