> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threetone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp troubleshooting

> Separate account setup, authorization, registration, saved preferences, and unavailable execution when diagnosing a WhatsApp issue.

Identify which operation failed before changing account settings. Setup problems and unavailable runtime paths need different responses.

<Note>
  Account setup has a current configuration workflow. Messaging and calling remain planned, and the outbound routes return HTTP `501`. Reconnecting an account does not implement those routes.
</Note>

## Start with the observed result

Have the workspace and phone identifiers, the attempted action, its time, and any error code. Exclude authorization codes, tokens, registration PINs, and customer message bodies from shared diagnostics.

| Symptom | Review next |
| - | - |
| Import account is disabled | Selected workspace, HTTPS, deployed Embedded Signup configuration, and authorization SDK readiness |
| Authorization expired | Account authorization state; a registration retry is not token renewal |
| Registration unconfirmed | Refresh registration status before repeating setup |
| Registration needs attention | Inspect the returned error and use the offered retry only after addressing its cause |
| Preferences save but no reply arrives | Preferences record future behavior; verify channel release availability |
| Outbound request returns `501` | Stop automatic retries; execution is not implemented |

<Steps>
  <Step title="Read the saved account" id="whatsapp-troubleshoot-account">
    Follow [account setup](/agents-platform/deploy/whatsapp/connect-account). Confirm registration, `is_token_expired`, and `assigned_agent_id`. Check the selected workspace before concluding that a connection disappeared.
  </Step>

  <Step title="Resolve uncertain setup outcomes" id="whatsapp-troubleshoot-uncertain">
    Refresh the account list and inspect the record before importing again. Use **Refresh registration status** to check registration. Use **Retry phone registration** only when the current account offers it. Re-read the resulting state rather than relying on a success notification alone.
  </Step>

  <Step title="Escalate with bounded evidence" id="whatsapp-troubleshoot-evidence">
    Record the operation, safe identifiers, response status, and whether the failure concerns setup or execution. For a future provider submission, preserve its message identifier and returned error. Do not report delivery from account registration or from local preference changes.
  </Step>
</Steps>

For later payload diagnosis, compare the selected operation with Meta's [official Cloud API reference collection](https://www.postman.com/meta/whatsapp-business-platform/collection/wlk6lh4/whatsapp-cloud-api) and Threetone's [outbound contract](/agents-platform/deploy/whatsapp/outbound). Their supported request shapes are not interchangeable.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Should I delete and reimport an account to fix a 501?" id="faq-whatsapp-troubleshoot-reimport">No. Deletion changes the account connection and may affect provider setup. It does not release outbound execution.</Accordion>
  <Accordion title="Does Phone registered prove delivery is healthy?" id="faq-whatsapp-troubleshoot-delivery">No. Registration, authorization, provider submission, delivery, and agent processing are separate states.</Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.