WhatsApp for your applications

Every partner application has WhatsApp on by default. Sending a template message is the WhatsApp API with application set, as Sending for an application 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 answers the whole picture in one read:

{
  "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 lists them, GET .../whatsapp/templates/{template_id} reads one by its Meta id:

{
  "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 submits a template to Meta’s review and answers 201 with its Meta id and status (PENDING at first):

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:<key>`, `body:<key>`, `button:<index>`; 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} 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} 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 lists them with phones masked:

{
  "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 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} 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 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.

Get started

Verify

WhatsApp

Partners

For agents

WhatsApp for your applications

The WhatsApp state

Templates

Create, edit, delete

The team

With the sandbox key

​The WhatsApp state

​Templates

​Create, edit, delete

​The team

​With the sandbox key

The WhatsApp state

Templates

Create, edit, delete

The team

With the sandbox key