WhatsApp Embedded Signup (Coexistence): “Error while pairing Cloud API” right after QR scan

[chris-joey]

Hi everyone,

I’m trying to onboard a WhatsApp number in Chatwoot using Embedded Signup (Coexistence).

Flow works until I scan the QR code in WhatsApp Business app, then it fails with:

“Error while pairing Cloud API”

Has anyone seen this recently and found a fix/workaround?

My setup

Chatwoot version: 4.9.1
Hosting: Self-Hosted
Number currently active in WhatsApp Business app: Yes

Thanks.

[piscespieces]

Hey @chris-joey

I have experienced it probably once?–After about 10 integrations using coexistence.

So far coexistence has been smooth for me–a couple of issues here and there but was able to solve them.

The fix was pretty easy. Just wait a few minutes and try again.

Let me ask the basics: are you a tech provider?

[piscespieces]

Hi @piscespieces, no I am not a tech provider. We are just trying to onboard our current whatsapp business app number onto a self hosted instance of chatwoot for continuity.

That's precisely the issue.

You must be a Meta Tech Provider to onboard your existing WhatsApp Business App phone number to Chatwoot (and use the WhatsApp Business API).

This is called "WhatsApp Coexistence" and there are a few requirements. Check them here

The good news is that you can apply for the Meta Tech Provider status.

There's a learning curve on how to get approved as a Meta Tech Provider but it's possible. I have done it multiple times.

Other options if you don't want to go through the Meta Tech Provider approval process is to:

• stick with Chatwoot cloud
• find a Chatwoot fork that is an approved Meta Tech Provider (on the cheaper side)

[ADVISE-AI]

hey @piscespieces i am a tech provider and facing the same problem first we faced this error

Processing by Api::V1::Accounts::InboxesController#create as JSON
chatwoot_app | I, [2026-03-26T15:47:50.266885 #15] INFO -- : [f550fae8-fab7-40e6-a5c7-55c1e833bcae] Parameters: {"name" => "Mayank Whatsapp", "channel" => {"type" => "whatsapp", "phone_number" => "+918XXXXXXXX", "provider" => "whatsapp_cloud", "provider_config" => {"api_key" => "[FILTERED]", "phone_number_id" => "9XXXXXXXXX", "business_account_id" => "1XXXXXXXX"}}, "account_id" => "4", "inbox" => {"name" => "Mayank Whatsapp"}}
chatwoot_app | I, [2026-03-26T15:47:57.619238 #15] INFO -- : [f550fae8-fab7-40e6-a5c7-55c1e833bcae] [WHATSAPP] Phone number 93XXXXXXXXXX2 code verification status: false
chatwoot_app | W, [2026-03-26T15:47:57.964517 #15] WARN -- : [f550fae8-fab7-40e6-a5c7-55c1e833bcae] [WHATSAPP] Phone registration failed but continuing: Phone registration failed: {"error":{"message":"Register endpoint is not available for SMB businesses.","type":"OAuthException","code":100,"fbtrace_id":"AERH_gFB6e7hbHH44-l1-ZG"}}
chatwoot_app | E, [2026-03-26T15:47:59.785970 #15] ERROR -- : [f550fae8-fab7-40e6-a5c7-55c1e833bcae] [WHATSAPP] Webhook setup failed: Webhook callback override failed: {"error":{"message":"(#100) Before override the current callback uri, your app must be subscribed to receive messages for WhatsApp Business Account","type":"OAuthException","code":100,"fbtrace_id":"AkQMLph3WKQx_GLh6RPHVz7"}}
chatwoot_app | E, [2026-03-26T15:47:59.786087 #15] ERROR -- : [f550fae8-fab7-40e6-a5c7-55c1e833bcae] [WHATSAPP] Webhook setup failed: Webhook setup failed: Webhook callback override failed: {"error":{"message":"(#100) Before override the current callback uri, your app must be subscribed to receive messages for WhatsApp Business Account","type":"OAuthException","code":100,"fbtrace_id":"AkQMLph3WKQx_GLh6RPHVz7"}}

[piscespieces]

@ADVISE-AI have you successfully completed the WhatsApp Business API integration before, or is this the first time you're trying to do it? — Judging by the error messages seems like you haven't subscribed your Chatwoot webhook endpoint for WhatsApp integrations in your Meta App.

[ADVISE-AI]

Yes i am a tech provider there was a mistake from my side i have a dev he does everything right now we have configured but the issue persosts by time out 1500 ms and after connection after some time chats disappeared from dashboard

[ADVISE-AI]

I previously had a dashboard from which i became a tech provider now everything is configured and set up but the chatwoot is extremely slow my dev is saying its some websockets err

[salehmadi97-star]

Hello everyone,

We are experiencing the same issue: “Error while pairing Cloud API” immediately after scanning the QR code.

We can see that the Chatwoot integration successfully creates a WhatsApp account in Meta for the phone number used, and the phone number status shows as “Connected.” However, it appears that this WhatsApp account is not properly linked to a Partner. Specifically, no Partner is created, the WhatsApp account is not assigned to a Partner, and WhatsApp Manager is not enabled for the added phone number.

We tested the same phone number using a trial account on Chatwoot Cloud, and the phone number was added without any issues. In this case, there was no “Error while pairing Cloud API,” and we were able to send and receive messages successfully from both the WhatsApp Cloud API and our WhatsApp Business app.

Note: We noticed a difference between self-hosted Chatwoot and Chatwoot Cloud. During WhatsApp Embedded Signup on Chatwoot Cloud, a WhatsApp account is created, a Tech Provider is assigned to that WhatsApp account, and WhatsApp Manager is enabled automatically.

We have enabled debug mode in Chatwoot; however, we were unable to find any logs or information related to the “Error while pairing Cloud API.”

Thank you and Best Regards,
Saleh

[piscespieces]

Hey, @salehmadi97-star as @viniciustrndd stated

You must be a Meta Tech Provider to onboard existing WhatsApp Business App phone numbers to Chatwoot (or any other WhastApp Business API provider).

That's what we call WhatsApp Coexistence, and one of the requirements is being a Meta Tech Provider.

As I mentioned on a comment above, the good news is that you can apply for the Meta Tech Provider.

I've done it several times. It takes some trial and error at first but it's doable.

The reason why Chatwoot Cloud works and your self hosted instance doesn't is because Chatwoot Cloud IS a Meta Tech Provider. But when you're on a self hosted version you're on your own.

[salehmadi97-star]

Hi Andres,

Thank you so much for the explanations. To confirm my understanding, we need to submit App Review requests for both whatsapp_business_messaging and whatsapp_business_management permissions in order to have them reviewed and approved by Meta, and to obtain advanced access for both permissions.

Could you please also share any guidance or best practices to help us avoid errors during the review submission process, given your experience with multiple submissions?

Best Regards,
Saleh

[piscespieces]

Hi Andres,

Thank you so much for the explanations. To confirm my understanding, we need to submit App Review requests for both whatsapp_business_messaging and whatsapp_business_management permissions in order to have them reviewed and approved by Meta, and to obtain advanced access for both permissions.

Could you please also share any guidance or best practices to help us avoid errors during the review submission process, given your experience with multiple submissions?

Best Regards, Saleh

I'd suggest to read this reddit thread where I actually posted some comments that have been very helpful to people and their Meta App Review process

[viniciustrndd]

Se vocês não têm app aprovado na Meta após enviado para análise não vai funcionar mesmo.

No Chatwoot Cloud funciona justamente porque eles têm app aprovado.

[salehmadi97-star]

Hi @viniciustrndd,

Thank you so much for your reply.

Best Regards,
Saleh

[chris-joey]

Managed to get this working after becoming Tech Provider ✅