Quick start

This page takes you from zero to a sent WhatsApp message. It takes about five minutes.

Before you start, you need a SanadWA account with a connected WhatsApp number, and an approved template. You also need to be an admin of the account, because only admins can create API keys.

1. Create an API key

   In the console, open Settings → Developers → API keys and click New API key.

   • Name: something that tells you where the key is used, for example Order system.
   • Scope: choose Send. It can send messages, start campaigns and read data. If your code will also create contacts or tags, choose Full instead.
   • IP allowlist (optional): leave it empty for now.

   Click Mint key. The console shows the key once. It starts with pk_live_. Copy it and store it in your server’s secret store. You cannot see it again.

   If your plan does not include API access, the console shows an error instead. Contact SanadWA to change your plan.

2. Make your first request

   Put the key in an environment variable on your server, so that it is never written in your code:

   export SANADWA_API_KEY="pk_live_YOUR_KEY"

   Now call GET /health. It does nothing except check your key.

   curl

   curl https://api.sanadwa.com/v1/health \
     -H "Authorization: Bearer $SANADWA_API_KEY"

   Node.js

   // Node.js 18 or later (built-in fetch)
   const res = await fetch("https://api.sanadwa.com/v1/health", {
     headers: { Authorization: `Bearer ${process.env.SANADWA_API_KEY}` },
   });
   console.log(res.status, await res.json());

   Python

   import os
   import requests
   
   res = requests.get(
       "https://api.sanadwa.com/v1/health",
       headers={"Authorization": f"Bearer {os.environ['SANADWA_API_KEY']}"},
       timeout=30,
   )
   print(res.status_code, res.json())

   PHP

   <?php
   $ch = curl_init("https://api.sanadwa.com/v1/health");
   curl_setopt_array($ch, [
       CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SANADWA_API_KEY")],
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_TIMEOUT => 30,
   ]);
   $body = curl_exec($ch);
   echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $body, PHP_EOL;

   A working key returns 200 and a body like this:

   {
     "success": true,
     "tenant_id": 1234,
     "scope": "send",
     "server_time": "2026-11-11T08:00:00.000Z"
   }

   If you get 401, check that the header is exactly Authorization: Bearer followed by the key. See Errors for every error code.

3. Find your phone number id

   Every send needs a phone_number_id: the id of the WhatsApp number you send from. In the console it is called the Sender ID (Settings → Developers → Senders). You can also get it from the API:

   curl https://api.sanadwa.com/v1/phone-numbers \
     -H "Authorization: Bearer $SANADWA_API_KEY"

   {
     "success": true,
     "data": [
       {
         "phone_number_id": "100000000000001",
         "display_phone_number": "+1 202-555-0100",
         "verified_name": "Example Store",
         "name_status": "APPROVED",
         "new_name_status": null,
         "waba_id": "200000000000002",
         "quality_rating": "GREEN",
         "status": "CONNECTED"
       }
     ]
   }

   Copy the phone_number_id.

4. Send a template message

   Use the name and language of one of your approved templates. template_params fills the template’s variables {{1}}, {{2}}, and so on, in order. to_phone is the recipient in E.164 format.

   The Idempotency-Key header makes the request safe to retry: if you send the same request again with the same key, the message is not sent twice. Use a new random value for every new message. See Idempotency.

   curl

   curl https://api.sanadwa.com/v1/messages/template \
     -H "Authorization: Bearer $SANADWA_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "phone_number_id": "100000000000001",
       "to_phone": "+12025550123",
       "template_name": "order_update",
       "template_language": "en",
       "template_params": ["Sara", "A-1042"]
     }'

   Node.js

   import { randomUUID } from "node:crypto";
   
   const res = await fetch("https://api.sanadwa.com/v1/messages/template", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.SANADWA_API_KEY}`,
       "Content-Type": "application/json",
       "Idempotency-Key": randomUUID(),
     },
     body: JSON.stringify({
       phone_number_id: "100000000000001",
       to_phone: "+12025550123",
       template_name: "order_update",
       template_language: "en",
       template_params: ["Sara", "A-1042"],
     }),
   });
   console.log(res.status, await res.json());

   Python

   import os
   import uuid
   import requests
   
   res = requests.post(
       "https://api.sanadwa.com/v1/messages/template",
       headers={
           "Authorization": f"Bearer {os.environ['SANADWA_API_KEY']}",
           "Idempotency-Key": str(uuid.uuid4()),
       },
       json={
           "phone_number_id": "100000000000001",
           "to_phone": "+12025550123",
           "template_name": "order_update",
           "template_language": "en",
           "template_params": ["Sara", "A-1042"],
       },
       timeout=30,
   )
   print(res.status_code, res.json())

   PHP

   <?php
   $payload = [
       "phone_number_id" => "100000000000001",
       "to_phone" => "+12025550123",
       "template_name" => "order_update",
       "template_language" => "en",
       "template_params" => ["Sara", "A-1042"],
   ];
   $ch = curl_init("https://api.sanadwa.com/v1/messages/template");
   curl_setopt_array($ch, [
       CURLOPT_POST => true,
       CURLOPT_HTTPHEADER => [
           "Authorization: Bearer " . getenv("SANADWA_API_KEY"),
           "Content-Type: application/json",
           "Idempotency-Key: " . bin2hex(random_bytes(16)),
       ],
       CURLOPT_POSTFIELDS => json_encode($payload),
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_TIMEOUT => 30,
   ]);
   $body = curl_exec($ch);
   echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $body, PHP_EOL;

   When WhatsApp accepts the message, you get 200:

   {
     "success": true,
     "message_id": "wamid.HBgLMTIwMjU1NTAxMjMVAgARGBI",
     "accepted_at": "2026-11-11T08:00:01.000Z",
     "upstream": {
       "messaging_product": "whatsapp",
       "contacts": [{ "input": "+12025550123", "wa_id": "12025550123" }],
       "messages": [{ "id": "wamid.HBgLMTIwMjU1NTAxMjMVAgARGBI" }]
     }
   }

   Save message_id. You can look up the message’s delivery status with GET /messages/{id}, and webhooks for this message refer to it. See Send a template message.

If you leave out template_language

The API then uses ar (Arabic). If your template is in another language, always send template_language, or WhatsApp rejects the message.

Next steps

• Follow delivery with webhooks.
• Read the full Send a template message guide.
• Learn how to handle errors and rate limits.