Troubleshooting: WhatsApp Connection Issues

WhatsApp uses OAuth to connect Converge to your WhatsApp Business account. If the OAuth token expires or is revoked, messages won't sync.

Check connection status: Go to Settings → Platforms → WhatsApp. Look for the connection status indicator:

• Connected (green): OAuth is active and working
• Disconnected (red): OAuth token expired or was revoked
• Reauth required (yellow): You need to reauthorize with Meta

What causes OAuth issues:

• Token expiration: OAuth tokens typically expire after 60 days. Converge attempts to refresh automatically, but this can fail.
• Access revoked: If you removed Converge from Meta Business Suite, the connection is broken.
• Password changed: Changing your Facebook password can invalidate OAuth tokens.
• Account disabled: If Meta disabled your WhatsApp Business account, integration won't work.

Reconnect OAuth: Click "Reconnect" or "Authorize" to go through the Meta OAuth flow again. Log in with the same Facebook account and grant permissions.

Your WhatsApp Business account itself must be in good standing for messages to sync.

Check in Meta Business Suite: Go to Meta Business Suite → WhatsApp → Account Quality. Look for:

• Account status: Should be "Active" or "Connected"
• Quality issues: Flags or restrictions on your account
• Message limits: Some accounts have daily sending limits

Common account issues:

• Restricted: Account was flagged for policy violations. Contact Meta support to resolve.
• Rate limited: Too many messages sent. Wait 24 hours for limits to reset.
• Phone number blocked: Your business number was blocked by customers. Contact Meta.

WhatsApp Business app: Make sure your WhatsApp Business app is active. Open the app on your phone and verify it's connected. Sometimes the phone app needs to be opened to refresh the connection.

WhatsApp uses webhooks to send messages to Converge. If the webhook subscription fails, messages won't sync.

How to check webhooks: In Meta Business Suite, go to WhatsApp → Manager → Webhooks. Verify:

• Webhook URL: Should be a Converge URL (ends in /webhooks/whatsapp)
• Webhook status: Should be "Enabled" or "Active"
• Subscribed events: Should include "messages" event

Webhook issues:

• Webhook disabled: Re-enable it from Meta Business Suite
• Wrong URL: Disconnect and reconnect WhatsApp in Converge to register the correct webhook
• Webhook verification failed: Converge's webhook endpoint might be down. Check Converge status page.

Test the webhook: Some WhatsApp Business API dashboards have a "Test Webhook" button. Send a test message and verify it reaches Converge.

When you connect WhatsApp through Converge, the final step registers your phone number with Meta's Cloud API. This is where most connection failures happen. Here are the common errors and how to fix them.

"This phone number is linked to an existing WhatsApp account"

This is the most common error. It means your number is still active on the regular WhatsApp app or another WhatsApp Business app on someone's phone.

• Open WhatsApp (or WhatsApp Business) on the phone that has this number
• Go to Settings → Account → Delete Account
• Wait at least 3 minutes after deleting — Meta needs time to release the number
• Go back to Converge and try connecting again

Note: The error message may appear in your local language (e.g., Polish, Vietnamese, German) since Meta localizes error messages. The meaning is the same regardless of language.

"Cannot create certificate" or "Please ensure two-step authentication is disabled"

Two-step verification (2FA) on your WhatsApp number blocks the Cloud API registration.

• Open WhatsApp on your phone
• Go to Settings → Account → Two-step verification → Disable
• Try connecting again in Converge
• You can re-enable 2FA after the connection is established

"This WhatsApp Business account is already connected to another company"

Each WhatsApp Business Account (WABA) can only be connected to one Converge company at a time. If another team or company in Converge already connected this WABA, you'll see this error.

• Ask the other company to disconnect the WABA from their Converge settings first
• Or use a different WhatsApp Business Account with a separate phone number

"Please confirm ownership of this phone number"

Meta needs you to verify ownership before registering the number.

• Make sure the phone number can receive SMS or voice calls
• Complete the phone verification through Meta Business Suite before connecting to Converge

General "Invalid parameter" error:

If you see a generic "Invalid parameter" error without a specific message, try these steps in order:

1. Disconnect any WhatsApp app using this number (wait 3 minutes)
2. Disable two-step verification
3. Verify your Meta Business account is fully verified (not pending)
4. Try the connection again from Converge Settings → Platforms → WhatsApp

It's important to understand that WhatsApp Business API is reply-only. This affects how you use Converge with WhatsApp.

What reply-only means: You can only send messages in response to customer-initiated conversations. You cannot start new conversations or send outbound marketing messages.

24-hour window: Once a customer messages you, you have 24 hours to send free-form replies. After 24 hours, the conversation "expires" and you can only send message templates (which require pre-approval from Meta).

Common confusion:

• "I can't message this customer": If it's been >24 hours since the last message, the conversation expired. You can't send more messages unless the customer messages you again.
• "Why can't I initiate conversations?" This is a WhatsApp policy, not a Converge limitation. WhatsApp intentionally restricts business-initiated messages to prevent spam.

Using message templates: To send messages after the 24-hour window, you must use pre-approved message templates. These templates are reviewed and approved by Meta. Contact support if you need help setting up templates.

Success indicator: When a customer messages your WhatsApp number and it appears in Converge — and when you reply within 24 hours and the customer receives your response — your WhatsApp connection is working correctly within the platform's limitations.