Notifications quickstart

At the end of this page your number has sent a WhatsApp message to your own phone through the API, and you know how to send your own template with its values.

Ask your coding assistant to add Tawked Notifications to your project.

Open in Cursor

Before you start

A Tawked account with an application that has Notifications on, in review or approved. Sign up if you have none.
The owner or an admin of the account, to connect the number.
A WhatsApp number you control, and a Facebook account that manages your business at Meta.

Connect your number

Open the application, then Notifications → Overview, and press Connect WhatsApp. The console asks where the number is today and the details customers will see, then Meta opens its window: pick or create the business and the number, and confirm it by SMS or a call. Tawked registers the number and opens its Tawked Chat inbox.Meta sends nothing until the WhatsApp Business Account has a payment method. Add a card to that account in Meta and make it the default; the Overview tells you when it finds one.

Create a live key

On the application’s API keys page, press Create a key. Choose the type Live, and under Access either All products or Custom with Notifications set to Send (the notifications:send scope). Copy the key: it shows once. Put it in your server’s environment as TAWKED_KEY.A test key does not work here: every WhatsApp endpoint answers it 403 live_key_required. A live key works while the application is in review, because review holds Verify codes only.

Send Meta's hello_world to your phone

Most new WhatsApp Business Accounts come with Meta’s hello_world template already approved, in en_US, with no placeholders. Send it to your own phone:

curl -X POST https://tawked.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "0551234567", "template": "hello_world", "lang": "en_US" }'

const res = await fetch('https://tawked.com/v1/whatsapp/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TAWKED_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: '0551234567', template: 'hello_world', lang: 'en_US' }),
});
const message = await res.json(); // keep message.id to read the status

$res = Http::withToken(env('TAWKED_KEY'))
    ->post('https://tawked.com/v1/whatsapp/messages', [
        'to' => '0551234567',
        'template' => 'hello_world',
        'lang' => 'en_US',
    ]);
$id = $res->json('id'); // keep the id to read the status

import os, requests

res = requests.post(
    "https://tawked.com/v1/whatsapp/messages",
    headers={"Authorization": f"Bearer {os.environ['TAWKED_KEY']}"},
    json={"to": "0551234567", "template": "hello_world", "lang": "en_US"},
)
message_id = res.json()["id"]  # keep the id to read the status

The answer is 202 Accepted: Meta has taken the message, and it reaches your phone in seconds.

{
  "id": "0f4c9c0e-6d2b-4b8a-9c3e-7a1d2e3f4a5b",
  "status": "accepted",
  "to": "+966551234567",
  "template": "hello_world",
  "lang": "en_US",
  "reference": null,
  "price_halalas": 0,
  "created_at": "2026-09-06T12:00:00+03:00"
}

price_halalas is the fee this send took from your balance, at the price on tawked.com/en/pricing. If your account has no hello_world, skip to step 5 with a template of your own.The likely refusals: 403 insufficient_scope (the key’s access does not include Notifications send), 409 no_whatsapp_number (the number is not connected to this key’s application), 422 unknown_template. Every code is on Errors.

Read the status

Statuses arrive from Meta within about a minute: accepted, then sent, delivered, read, or failed.

curl https://tawked.com/v1/whatsapp/messages/0f4c9c0e-6d2b-4b8a-9c3e-7a1d2e3f4a5b \
  -H "Authorization: Bearer $TAWKED_KEY"

const res = await fetch(`https://tawked.com/v1/whatsapp/messages/${message.id}`, {
  headers: { Authorization: `Bearer ${process.env.TAWKED_KEY}` },
});
const { status, error } = await res.json();

$message = Http::withToken(env('TAWKED_KEY'))
    ->get("https://tawked.com/v1/whatsapp/messages/{$id}")
    ->json();

res = requests.get(
    f"https://tawked.com/v1/whatsapp/messages/{message_id}",
    headers={"Authorization": f"Bearer {os.environ['TAWKED_KEY']}"},
)
status = res.json()["status"]

{
  "id": "0f4c9c0e-6d2b-4b8a-9c3e-7a1d2e3f4a5b",
  "status": "delivered",
  "to": "+966551234567",
  "template": "hello_world",
  "lang": "en_US",
  "reference": null,
  "price_halalas": 0,
  "error": null,
  "created_at": "2026-09-06T12:00:00+03:00",
  "sent_at": "2026-09-06T12:00:01+03:00",
  "delivered_at": "2026-09-06T12:00:04+03:00",
  "read_at": null,
  "failed_at": null
}

In production, receive the message.* webhooks instead of polling. A failed message carries Meta’s code and message in error, and its fee is refunded.

Send your own template

Create a template on Notifications → Templates and wait for Meta to approve it, usually within minutes. Then list your templates to see the values each one expects:

curl https://tawked.com/v1/whatsapp/templates \
  -H "Authorization: Bearer $TAWKED_KEY"

{
  "data": [
    {
      "name": "order_received_v1",
      "language": "ar",
      "category": "UTILITY",
      "status": "APPROVED",
      "placeholders": {
        "kind": "named",
        "header": [],
        "body": ["name", "order"],
        "buttons": [{ "index": 0, "type": "url" }]
      }
    }
  ]
}

Send it with one value per body placeholder in params, and one entry per URL button in buttons:

curl -X POST https://tawked.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-received" \
  -d '{
    "to": "0551234567",
    "template": "order_received_v1",
    "lang": "ar",
    "params": { "name": "أحمد", "order": "1042" },
    "buttons": [{ "index": 0, "parameter": "1042" }],
    "reference": "order-1042"
  }'

const res = await fetch('https://tawked.com/v1/whatsapp/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TAWKED_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1042-received',
  },
  body: JSON.stringify({
    to: '0551234567',
    template: 'order_received_v1',
    lang: 'ar',
    params: { name: 'أحمد', order: '1042' },
    buttons: [{ index: 0, parameter: '1042' }],
    reference: 'order-1042',
  }),
});

$res = Http::withToken(env('TAWKED_KEY'))
    ->withHeaders(['Idempotency-Key' => 'order-1042-received'])
    ->post('https://tawked.com/v1/whatsapp/messages', [
        'to' => '0551234567',
        'template' => 'order_received_v1',
        'lang' => 'ar',
        'params' => ['name' => 'أحمد', 'order' => '1042'],
        'buttons' => [['index' => 0, 'parameter' => '1042']],
        'reference' => 'order-1042',
    ]);

res = requests.post(
    "https://tawked.com/v1/whatsapp/messages",
    headers={
        "Authorization": f"Bearer {os.environ['TAWKED_KEY']}",
        "Idempotency-Key": "order-1042-received",
    },
    json={
        "to": "0551234567",
        "template": "order_received_v1",
        "lang": "ar",
        "params": {"name": "أحمد", "order": "1042"},
        "buttons": [{"index": 0, "parameter": "1042"}],
        "reference": "order-1042",
    },
)

The likely refusals: 422 template_not_approved (Meta has not approved it yet; message carries its status), 422 invalid_params (a value is missing, extra or has a newline; message names it). Neither is worth retrying as it is.

Before real customers

Send one Idempotency-Key per business event, and retry a 502 or a network error with the same key. See Reliability and limits.
Receive message.* webhooks and verify their signature.
Keep enough balance for your sends, and set the Low-balance alert on Wallet → Balance.
A marketing template never reaches a customer who wrote STOP to your number: it answers 422 consent_opted_out. See Marketing and opt-outs.

Sending messages

Text and image headers, authentication templates, statuses.

Templates

Categories, Meta’s library, quality and pausing.

Webhooks

One signed event per status change.

Tawked Chat

Where your customers’ replies land.

Get started

Verify

Notifications

Webhooks and errors

Partners

Build with AI

Notifications quickstart

Before real customers

Next

Sending messages

Templates

Webhooks

Tawked Chat

​Before real customers

​Next

Sending messages

Templates

Webhooks

Tawked Chat

Before real customers

Next