Troubleshooting

Before deeper WhatsApp Cloud API troubleshooting, open the connection's Debug tab in Dualhook and run diagnostics. It pulls the latest Meta-side health, webhook routing, and account signals for that connection.

Embedded Signup Completes But IDs Are Missing

Likely causes:

• Popup postMessage did not arrive
• Access did not include expected business assets

What to do:

1. Retry in a browser profile with popups allowed.
2. Complete the flow fully without closing early.
3. Use Dualhook's fallback discovery and finalize the selected WABA/number.

Webhook Verified But No Message Events Arrive

Likely causes:

• Override not active for this connection
• Wrong endpoint URL or environment
• Heartbeat overdue
• Endpoint returns non-200 or times out

What to do:

1. Re-check the connection webhook URL and override status in the dashboard.
2. Send real inbound and outbound tests (not only the synthetic ping).
3. Check heartbeat status and acknowledge if overdue.
4. Check server logs for signature, parsing, or timeout errors.

Messages Arrive at Wrong Endpoint

Likely causes:

• Phone-level callback override taking precedence
• Legacy configuration still active

What to do:

1. Audit phone-level and WABA-level callback settings via Meta Graph API.
2. Standardize per environment and re-subscribe intentionally.

See Webhook Override routing priority for the precedence rules.

Media Webhooks Arrive But No File Is Available

Likely cause:

• The webhook contains media metadata and an ID, not the binary file itself.

What to do:

1. Retrieve media using GET /<MEDIA_ID> — see Upload, Retrieve & Delete Media.
2. Download using the returned temporary URL with bearer auth.

Phone Number Stays PENDING or Says "Not Linked to Your WhatsApp Account"

If Meta shows phone status PENDING, or the health output includes error 141000 saying the phone number is not linked to your WhatsApp account, the number is usually ownership-verified but not fully registered for Cloud API sending yet.

Likely causes:

• SMS or voice OTP verification completed, but Cloud API registration did not.
• The number was added through an add-new-number flow, which does not use the coexistence QR/app-confirmation path.
• The number was deleted and re-added, and a previous two-step verification PIN is still in effect.

What to do:

1. Confirm whether this is coexistence or an add-new-number Cloud API setup. Existing WhatsApp Business App numbers in coexistence use the QR/app-confirmation flow; add-new-number flows do not.
2. Check the phone status in WhatsApp Manager or via Graph API. PENDING means not fully registered; CONNECTED means registration completed.
3. If phone ownership is not verified yet, request and verify the SMS or voice code first.
4. Register the phone on Cloud API with POST /<PHONE_NUMBER_ID>/register and a 6-digit PIN. Meta uses this call to complete registration and enable or confirm two-step verification.
5. If registration fails because a PIN already exists, use the previous PIN or disable/reset two-step verification in WhatsApp Manager, then retry registration.
6. If the number came from Embedded Signup, complete registration within 14 days. After that window, you may need to rerun Embedded Signup.

What does not usually block registration by itself:

• Display name review still pending
• Business verification still pending

Those states can limit messaging capacity, but they are separate from the PENDING or 141000 registration problem.

Quality Drops to LIMITED or BLOCKED

What to do:

1. Pause or throttle risky campaigns.
2. Prioritize utility and authentication traffic.
3. Review template quality, audience targeting, and opt-out handling.
4. Resume scale only after sustained quality recovery.

See Maintain Account Health for a full incident playbook.

Still Stuck? Contact Dualhook Support

If the steps above do not resolve the issue, open the in-app support chat from the Dualhook dashboard.

For the fastest triage, include:

• organization and connection name
• the exact failing step
• expected vs actual behavior
• timestamp and timezone
• screenshots, exported PDFs, or copied error text

That support path is documented in Support, Contact, and Bug Reports.