Send and track WhatsApp messages

Send one message with POST https://api.waaru.app/v1/messages and the messages:send scope. The key selects the sending number. A successful request returns HTTP 202 and a Waaru message ID while delivery continues asynchronously.

Using Node.js? The Waaru SDK wraps text and approved-template sends. This page describes the underlying REST requests.

Prepare a safe test

Complete the API setup first. Use a recipient you have permission to message. For a non-template reply, have that person send an inbound message to the same connected business number and confirm the 24-hour customer-service window is open.

If a person owns the conversation in Inbox, API sends stop. An authorized teammate must select Release to API before your server continues. Creating a new key does not change conversation ownership.

Send a text reply

Set WAARU_API_KEY through your secret environment. Save the following as message.json, replacing the example recipient with your permitted test number:

{
  "messaging_product": "whatsapp",
  "to": "+919876543210",
  "type": "text",
  "text": {
    "body": "Thanks. Your enquiry reached the team.",
    "preview_url": false
  }
}

curl --fail-with-body 'https://api.waaru.app/v1/messages' \
  --header "Authorization: Bearer $WAARU_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary @message.json

An accepted response has this shape. Identifiers shown in this guide are illustrative:

{
  "messaging_product": "whatsapp",
  "messageId": "message_example",
  "status": "queued"
}

Save messageId before doing further work. The response also includes X-Waaru-Request-Id for request troubleshooting. It is not a message ID or an idempotency key.

Send an approved template

Use the same endpoint and headers with this payload. Replace the template name, language, and variables with the approved template in your account:

{
  "messaging_product": "whatsapp",
  "to": "+919876543210",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en" },
    "components": [
      {
        "type": "body",
        "parameters": [{ "type": "text", "text": "ORDER-123" }]
      }
    ]
  }
}

The template must exist for the sending number's WhatsApp Business Account with the exact name and language. Create or sync it in Templates first. Components must match its approved content and variable structure. There is no public template-creation endpoint for API keys.

An approved template is required outside the service window. Approval alone does not authorize a send: consent, restrictions, connected sender, template and phone quality, and current provider state still apply. Yellow quality blocks new business-initiated template admission. It does not by itself block an eligible non-template customer-service reply.

Track the result

With messages:read, request GET /v1/messages/:messageId using the ID returned above. Outbound statuses are queued, sent, delivered, read, and failed. A failure can include failureCode. A queued response is not proof that Meta accepted or delivered the message, and delivery does not guarantee a read event.

Use message reads or signed status webhooks to reconcile your application's state.

Avoid duplicate sends

The public send endpoint does not accept a client idempotency key. Keep a send record in your application. After an uncertain timeout, do not automatically replay the POST. If you received a message ID, read its status. Otherwise inspect the relevant conversation, callbacks, and Developer activity before deciding whether another send is needed.

For media, buttons, lists, location, and contact cards, use the message format reference. See errors and retry behavior when admission fails.