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.

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.