> ## Documentation Index > Fetch the complete documentation index at: https://docs.tawked.com/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp for your applications > Read an application's WhatsApp state, know who connects the number and where, manage its templates and the team that answers on it, all over the partner API. Every partner application has WhatsApp on by default. Sending a template message is the [WhatsApp API](/whatsapp/overview) with `application` set, as [Sending for an application](/partners/sending#whatsapp-with-a-partner-key) describes. This page is the rest: the number, the templates and the team, over `/v1/partner/applications/{external_id}/whatsapp`. Connecting a number itself stays in the consoles, because Meta's Embedded Signup needs a signed-in person in a browser. The API tells you who that person is and gives you the exact page to send them to. ## The WhatsApp state [`GET /v1/partner/applications/{external_id}/whatsapp`](/api-reference/partner/get-the-whatsapp-state) answers the whole picture in one read: ```json theme={"dark"} { "enabled": true, "number": { "phone": "+966550149068", "verified_name": "Flower Shop", "health": "healthy", "stage": { "stage": "ready", "reason": null, "step": null, "meta": null, "url": null }, "quality_rating": "GREEN", "messaging_tier": "TIER_1K", "connected_at": "2026-09-20T10:00:00.000Z", "health_synced_at": "2026-09-26T09:00:00.000Z" }, "connect": { "state": "connected", "who": null, "url": null }, "templates": { "approved": 4, "total": 5 } } ``` | Field | Meaning | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | Whether WhatsApp is on for the application. Tawked staff can turn it off. | | `number` | The connected number, or `null`. `health` is `healthy`, `degraded`, `disconnected`, `pending` or `blocked`; `stage` is the one line the consoles show (`setting_up`, `action_needed`, `add_payment`, `meta_reviewing`, `limited`, `ready`) with a `reason`, and a `url` into Meta's WhatsApp Manager when something must be fixed there. | | `connect` | `state` is `connected`, `ready` (a number can be connected now), `disabled` (WhatsApp is off), `not_active` (the application is rejected, suspended or archived) or `not_configured`. While a number can be connected, `who` says who does it, `partner` (you, from the partner console) or `owner` (the merchant you handed the application to, from their dashboard), and `url` is that page. | | `templates` | `approved` and `total` on the number's WhatsApp Business Account; `null` without a number, or when Meta did not answer. | ## Templates Templates live on Meta, under the number's WhatsApp Business Account; Tawked reads them through Meta and caches the list briefly. Every send names a template, so this is the catalog a send draws from. [`GET .../whatsapp/templates`](/api-reference/partner/list-the-templates) lists them, [`GET .../whatsapp/templates/{template_id}`](/api-reference/partner/get-a-template) reads one by its Meta id: ```json theme={"dark"} { "id": "7000", "name": "order_received_v1", "language": "ar", "category": "UTILITY", "status": "APPROVED", "quality": "GREEN", "rejected_reason": null, "components": [ { "type": "HEADER", "format": "TEXT", "text": "طلبك {{1}}", "buttons": [] }, { "type": "BODY", "format": null, "text": "استلمنا طلبك رقم {{1}} بقيمة {{2}} ريال.", "buttons": [] }, { "type": "BUTTONS", "format": null, "text": null, "buttons": [{ "type": "URL", "text": "تتبع الطلب", "url": "https://flowers.example/orders/{{1}}", "phone_number": null }] } ], "examples": { "header:1": "1042", "body:1": "1042", "body:2": "250", "button:0": "1042" }, "placeholders": { "kind": "POSITIONAL", "header": ["1"], "body": ["1", "2"], "buttons": [{ "index": 0, "type": "URL" }] } } ``` `status` is Meta's: `APPROVED` sends, `PENDING` is in Meta's review, `REJECTED` carries `rejected_reason`, `PAUSED` and `DISABLED` come from quality. `placeholders` is what a send must fill, exactly as `GET /v1/whatsapp/templates` lists it. ### Create, edit, delete [`POST .../whatsapp/templates`](/api-reference/partner/create-a-template) submits a template to Meta's review and answers `201` with its Meta `id` and `status` (`PENDING` at first): ```bash theme={"dark"} curl -X POST https://tawked.com/v1/partner/applications/store_88/whatsapp/templates \ -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: store_88-order_shipped_v1" \ -d '{ "name": "order_shipped_v1", "language": "ar", "category": "UTILITY", "header": "طلبك {{order}}", "body": "طلبك {{order}} في الطريق، يصلك خلال {{days}} أيام.", "footer": "متجر الورد", "buttons": [{ "type": "URL", "text": "تتبع الشحنة", "url": "https://flowers.example/track/{{1}}" }], "examples": { "header:order": "1042", "body:order": "1042", "body:days": "3", "button:0": "1042" } }' ``` | Field | Required | Notes | | ---------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | yes | Lowercase letters, digits and underscores; Meta fixes it at creation. | | `language` | yes | One of `ar`, `en`, `en_US`, `en_GB`, `ur`, `hi`, `bn`, `tl`, `id`, `fr`; fixed at creation. | | `category` | yes | `UTILITY` or `MARKETING`. Authentication templates are not created here: one-time codes go through Verify. | | `header` | no | One line, up to 60 characters, no emoji. | | `body` | yes | Up to 1024 characters. Placeholders are `{{name}}` or `{{1}}`, never at the very start or end, never two in a row. | | `footer` | no | One line, up to 60 characters. | | `buttons` | no | Up to 10 of `QUICK_REPLY` (`text`), `URL` (`text`, `url` starting with `https://`, optionally ending in `{{1}}`) or `PHONE_NUMBER` (`text`, `phone_number` in E.164). | | `examples` | when placeholders exist | One sample value per placeholder, keyed `header:`, `body:`, `button:`; Meta reviews with them. | The same rules as the console's template editor apply, and a refused field answers `400 invalid_request` with `fields` naming it and `errors` giving each field's reasons. What Meta refuses after that answers `422 template_refused` with Meta's own sentence in `message`. [`PATCH .../whatsapp/templates/{template_id}`](/api-reference/partner/update-a-template) takes the same body without `name` and `language` (Meta fixes them) and replaces the template's components; Meta reviews the change again, so an approved template goes back to `PENDING`. Only an `APPROVED`, `REJECTED` or `PAUSED` template can be edited: anything else answers `409 template_not_editable` with the `status`. [`DELETE .../whatsapp/templates/{template_id}`](/api-reference/partner/delete-a-template) removes that one language of the template. Meta's own samples (`hello_world`) can be neither edited nor deleted (`409 template_not_editable` with `META_SAMPLE`). Every template endpoint needs WhatsApp on (`403 whatsapp_not_enabled`) and a connected number (`409 no_whatsapp_number`); when Meta does not answer, `503 templates_unavailable` says nothing was changed. ## The team The people who answer customers on the number in Tawked Chat. [`GET .../whatsapp/team`](/api-reference/partner/list-the-team) lists them with phones masked: ```json theme={"dark"} { "data": [ { "id": "01a0ac2c-267c-7369-baa0-eff305aa5c20", "name": "أحمد", "phone": "+96655•••••67", "chat_role": "administrator", "is_owner": true, "provisioned": true }, { "id": "01a0ac2c-9b1d-7c3e-8a4f-1b2c3d4e5f60", "name": "سالم", "phone": "+96655•••••22", "chat_role": "agent", "is_owner": false, "provisioned": true } ] } ``` The team is the one that runs the number: yours while you run the application, the owner's once you handed it over. [`POST .../whatsapp/team`](/api-reference/partner/add-a-team-member) with `name` and a Saudi mobile `phone` adds an agent on this application (`201`; `200` with the same person when the phone is already on the team) and they sign in to Tawked Chat with that phone. [`DELETE .../whatsapp/team/{member_id}`](/api-reference/partner/remove-a-team-member) takes an agent off this application, and off the team when no application is left. The team owner and its administrators are theirs: `409 not_removable`. | HTTP | `error` | Meaning | | ---- | ------------------ | ------------------------------------------------------------------------------------------------- | | 400 | `invalid_phone` | Not a Saudi mobile. | | 409 | `phone_taken` | The phone belongs to a user elsewhere (an account owner, a member of another team, Tawked staff). | | 409 | `team_full` | The team is at its member limit. | | 409 | `not_removable` | The owner or an administrator. | | 503 | `chat_unavailable` | Tawked Chat did not answer; nothing was changed. | ## With the sandbox key The [sandbox key](/partners/sending#the-sandbox-key) reads all of this and changes none of it: creating, editing or deleting a template and adding or removing a member answer `403 live_key_required`.