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

# WhatsApp Cloud API

> Configure the WhatsApp Cloud API channel surface in Loong.

# WhatsApp Cloud API

This is a shipped runtime-backed surface: direct sends are implemented, the serve loop is implemented, and the channel can join `gateway run` or `gateway run`.

## At A Glance

| Field                    | Value                  |
| ------------------------ | ---------------------- |
| Catalog id               | `whatsapp`             |
| Config key               | `whatsapp`             |
| Implementation status    | `runtime_backed`       |
| Transport                | `whatsapp_cloud_api`   |
| Aliases                  | `wa`, `whatsapp-cloud` |
| Default send target kind | `address`              |

## Minimal Config

```toml theme={null}
[whatsapp]
enabled = true
webhook_bind = "127.0.0.1:8080"
webhook_path = "/whatsapp/webhook"
access_token_env = "WHATSAPP_ACCESS_TOKEN"
phone_number_id_env = "WHATSAPP_PHONE_NUMBER_ID"
verify_token_env = "WHATSAPP_VERIFY_TOKEN"
app_secret_env = "WHATSAPP_APP_SECRET"
```

## Smoke Test

```bash theme={null}
loong channels send whatsapp --target "+15551234567" --text "hello from loong"
loong channels serve whatsapp
```

## Command Surface

| Operation             | Command                   | Usage or status                                                                  |
| --------------------- | ------------------------- | -------------------------------------------------------------------------------- |
| business send         | `channels send whatsapp`  | Usage: loong channels send whatsapp \[OPTIONS] --target \<TARGET> --text \<TEXT> |
| cloud webhook service | `channels serve whatsapp` | Usage: loong channels serve whatsapp \[OPTIONS]                                  |

## Required Fields For Send

| Requirement            | Config paths                                                                  | Env pointer paths                                                                     | Default env                |
| ---------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------- |
| channel enabled        | `whatsapp.enabled`<br />`whatsapp.accounts.<account>.enabled`                 | none                                                                                  | none                       |
| cloud api access token | `whatsapp.access_token`<br />`whatsapp.accounts.<account>.access_token`       | `whatsapp.access_token_env`<br />`whatsapp.accounts.<account>.access_token_env`       | `WHATSAPP_ACCESS_TOKEN`    |
| phone number id        | `whatsapp.phone_number_id`<br />`whatsapp.accounts.<account>.phone_number_id` | `whatsapp.phone_number_id_env`<br />`whatsapp.accounts.<account>.phone_number_id_env` | `WHATSAPP_PHONE_NUMBER_ID` |

## Required Fields For Serve

| Requirement            | Config paths                                                                  | Env pointer paths                                                                     | Default env                |
| ---------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------- |
| channel enabled        | `whatsapp.enabled`<br />`whatsapp.accounts.<account>.enabled`                 | none                                                                                  | none                       |
| cloud api access token | `whatsapp.access_token`<br />`whatsapp.accounts.<account>.access_token`       | `whatsapp.access_token_env`<br />`whatsapp.accounts.<account>.access_token_env`       | `WHATSAPP_ACCESS_TOKEN`    |
| phone number id        | `whatsapp.phone_number_id`<br />`whatsapp.accounts.<account>.phone_number_id` | `whatsapp.phone_number_id_env`<br />`whatsapp.accounts.<account>.phone_number_id_env` | `WHATSAPP_PHONE_NUMBER_ID` |
| webhook verify token   | `whatsapp.verify_token`<br />`whatsapp.accounts.<account>.verify_token`       | `whatsapp.verify_token_env`<br />`whatsapp.accounts.<account>.verify_token_env`       | `WHATSAPP_VERIFY_TOKEN`    |
| meta app secret        | `whatsapp.app_secret`<br />`whatsapp.accounts.<account>.app_secret`           | `whatsapp.app_secret_env`<br />`whatsapp.accounts.<account>.app_secret_env`           | `WHATSAPP_APP_SECRET`      |

## Gateway And Ownership

This surface can run directly through `channels serve whatsapp`, or under [Gateway And Supervision](/use-loong/gateway-and-supervision) through `gateway run`.

## Operator Notes

* This page documents the current WhatsApp Cloud API business-account lane: outbound sends are shipped and the webhook reply service is also implemented.
* Serve mode needs `verify_token` and `app_secret` in addition to the Cloud API access token and phone number id.
* Keep the Cloud API credential path distinct from the QR-linked [WhatsApp Personal](/use-loong/channel-guides/whatsapp-personal) surface so operators do not confuse Meta business credentials with personal-account pairing.

## Related Docs

* Continue to [WhatsApp Personal](/use-loong/channel-guides/whatsapp-personal) for the QR-linked personal-account bridge lane.
* Continue to [Channel Guides](/use-loong/channel-guides/index) for the full shipped channel matrix.
* Continue to [Channels](/use-loong/channels) for the conceptual surface model.
* Continue to [Channel Setup](/use-loong/channel-setup) for the shared public setup contract.
* Continue to [Gateway And Supervision](/use-loong/gateway-and-supervision) when this surface needs longer-lived runtime ownership.