Send WhatsApp messages from your own systems

A REST API over the official WhatsApp Business Platform. Send template and session messages, upload media, manage contacts, and receive every inbound message and status change on your own server through signed webhooks.

Introduction

Everything lives under one base URL. All ids are UUIDs, all timestamps are ISO 8601 in UTC, and every request and response is JSON unless you are uploading a file.

https://chatlineapi.codecano.com/v1

The API is versioned in the path. v1 will not change in a breaking way; new fields may be added, so parse JSON leniently and ignore what you do not recognise.

Quickstart

1. Create an API key

   In the dashboard, open Settings → Developers and create a key. It is shown once, so store it somewhere safe. Give it only the scopes you need — messages:send is enough to send.

2. Send your first message

   Use an approved template, so it works whether or not the customer has messaged you recently.

   cURLNode.jsPHPPython

   bash

   curl -X POST https://chatlineapi.codecano.com/v1/messages \
     -H "Authorization: Bearer $WA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "to": "+919876543210",
       "type": "template",
       "template": {
         "name": "order_update",
         "language": "en",
         "body": [
           { "type": "text", "text": "Priya" },
           { "type": "text", "text": "#84512" }
         ]
       }
     }'

   Copy

3. Receive replies

   Add a webhook endpoint under Settings → Developers → Webhooks and subscribe to message.received and message.status. See Webhooks for the payloads and how to verify the signature.

Authentication

Send your API key as a bearer token on every request. Keys look like wa_live_ followed by 48 hexadecimal characters.

Authorization: Bearer wa_live_0123abcd4567ef89...

Keys belong to a workspace, not to a user, and carry scopes that limit what they can do. A request with a key that lacks the required scope is refused with 403 and a message naming the missing scope.

Rate limits

Each key has its own limit, 60 requests per minute by default, adjustable per key in the dashboard. Every response tells you where you stand.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1789000060

Exceeding the limit returns 429 with a Retry-After header in seconds. Wait that long and retry; do not retry immediately in a loop.

This limit is about your API usage. WhatsApp separately limits how fast a phone number can send and how many conversations you may start per day — the platform handles both for you by queueing and pacing messages, which is why a send returns 202 rather than blocking.

Errors

Every failure has the same shape. Show message to a human; branch on details.code when you need to handle a specific case.

{
  "error": {
    "code": "conflict",
    "message": "The 24-hour window is closed. Only approved template messages can be sent until the customer replies.",
    "details": { "code": "window_closed" },
    "requestId": "9f2a1c44-7b0e-4d33-8a11-6c5e2f7b9d04"
  }
}

Always log requestId. It identifies the exact request in our logs and is the fastest way for support to find what happened.

WhatsApp rules you cannot avoid

These are Meta's rules, not ours. They apply to every message, whether you send it from this API, the dashboard or a campaign.

• Opt-outs are binding. A customer who stops marketing messages, by replying STOP or through WhatsApp's own setting, cannot receive marketing templates. Sends are refused with opted_out. Utility and authentication templates still reach them.
• Templates must be approved. Create and submit them in the dashboard; Meta reviews them. Sending an unapproved template fails with error 132001.
• Quality affects throughput. Meta lowers your messaging limit if people block or report your messages. Watch account.alert webhooks.

Sending messages

One endpoint sends every message type. The type field decides which object is required alongside it. If your workspace has more than one connected number, add from with the number's id from GET /phone-numbers; with a single number you can leave it out.

POST https://chatlineapi.codecano.com/v1/messages

{
  "to": "+919876543210",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": "en",
    "body": [
      { "type": "text", "text": "Priya" },
      { "type": "text", "text": "#84512" }
    ]
  }
}

POST https://chatlineapi.codecano.com/v1/messages

{
  "to": "+919876543210",
  "type": "text",
  "text": { "body": "Your order ships tomorrow.", "previewUrl": false }
}

POST https://chatlineapi.codecano.com/v1/messages

{
  "to": "+919876543210",
  "type": "image",
  "image": { "mediaId": "8f2c1a44-9d0e-4b77-8e3a-6c1d2f5b7a91", "caption": "Your receipt" }
}

POST https://chatlineapi.codecano.com/v1/messages

{
  "to": "+919876543210",
  "type": "location",
  "location": { "latitude": 18.5204, "longitude": 73.8567, "name": "Pickup point", "address": "FC Road, Pune" }
}

What you get back

Every send returns 202 Accepted with the stored message. It has not reached WhatsApp yet — status is queued and wamid is null until Meta accepts it. Watch it with message status.

{
  "id": "3f1b9c22-0a44-4c1e-9f77-2d5e8b1a6c30",
  "status": "queued",
  "type": "template",
  "to": "919876543210",
  "conversationId": "b7a1c9e4-2f31-4a88-9c0d-5e6f7a8b9c01",
  "contactId": "c2d4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "wamid": null,
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-09-14T10:00:00.000Z",
  "sentAt": null,
  "deliveredAt": null,
  "readAt": null,
  "failedAt": null
}

Message status

A send returns immediately with status: "queued". The message then moves through WhatsApp's lifecycle:

• queued — stored by us, waiting its turn in the send queue.
• accepted — WhatsApp took it and assigned a wamid.
• sent, delivered, read — reported by WhatsApp. read only arrives if the customer has read receipts enabled.
• failed — final. errorCode and errorMessage explain why; see error codes.
• held or paused — WhatsApp is holding the message for a quality review, or the number is paused.

Prefer webhooks over polling. Subscribe to message.status and you are told about every transition. Polling GET /messages/{id} is fine for a one-off check but wasteful at volume.

WhatsApp error codes

When WhatsApp refuses or fails a message, we pass its numeric code through as errorCode, with a plain-language errorMessage. These are the ones you will actually meet.

Message blocked before it left

These come back on POST /messages itself, as a 409 or 400. Nothing was sent and nothing was charged.

Delivery failed at WhatsApp

The message was accepted, then failed. You see these on GET /messages/{id} and in the message.status webhook.

Template problems

Fix the template or the parameters you send with it.

Rate limits and temporary failures

Handled and retried automatically by the platform. You do not need to retry these yourself.

Account problems

These need attention in the dashboard or in WhatsApp Manager; sending stays blocked until they are resolved.

Media problems

Check the file type and size against WhatsApp’s limits before uploading.

API reference

Generated from the same schemas the API validates against, so it cannot drift from the implementation. The machine-readable version is at openapi.json and imports directly into Postman or Insomnia.

Messages

Media

Templates

Contacts

Numbers

Events

Calls

Schemas

Webhooks

Register an endpoint under Settings → Developers → Webhooks, choose the events you care about, and copy the signing secret — it is shown once. We then POST JSON to your URL whenever something happens.

POST https://your-server.example/webhooks/whatsapp
Content-Type: application/json
X-Webhook-Id: 7c1e9a02-4b33-4f81-9d20-8e5a1b6c3d47
X-Webhook-Event: message.received
X-Webhook-Timestamp: 1789000000
X-Webhook-Signature: t=1789000000,v1=9f86d081884c7d659a2feaa0c55ad015...

{
  "id": "7c1e9a02-4b33-4f81-9d20-8e5a1b6c3d47",
  "event": "message.received",
  "createdAt": "2026-09-14T10:00:00.000Z",
  "organizationId": "a3b5c7d9-...",
  "data": { }
}

Verify the signature

Never trust an unsigned request. The header is t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256(secret, "<t>.<raw body>"). Compute it over the raw bytes, before any JSON parsing, compare in constant time, and reject timestamps older than five minutes.

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const app = express();

// The raw body is required: parse it as a Buffer, not JSON.
app.post('/webhooks/whatsapp', express.raw({ type: '*/*' }), (req, res) => {
  const header = req.get('X-Webhook-Signature') ?? '';
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const raw = req.body.toString('utf8');

  // Reject anything older than five minutes (replay protection).
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return res.sendStatus(401);

  const expected = createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${parts.t}.${raw}`)
    .digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(parts.v1 ?? '', 'hex');
  if (a.length !== b.length || !timingSafeEqual(a, b)) return res.sendStatus(401);

  const event = JSON.parse(raw);
  // Use event.id for idempotency: retries reuse the same id.
  console.log(event.event, event.data);

  res.sendStatus(200);   // answer within 10 seconds
});

<?php
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_WEBHOOK_SIGNATURE']), $sig); // t=..., v1=...

if (abs(time() - (int) $sig['t']) > 300) { http_response_code(401); exit; }

$expected = hash_hmac('sha256', $sig['t'] . '.' . $raw, getenv('WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1'])) { http_response_code(401); exit; }

$event = json_decode($raw, true);
// $event['id'] is the idempotency key; retries reuse it.
error_log($event['event']);

http_response_code(200);

import hmac, hashlib, time, json
from flask import Flask, request

app = Flask(__name__)

@app.post("/webhooks/whatsapp")
def receive():
    raw = request.get_data()                       # bytes, before any parsing
    parts = dict(p.split("=", 1) for p in request.headers["X-Webhook-Signature"].split(","))

    if abs(time.time() - int(parts["t"])) > 300:   # replay protection
        return "", 401

    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        f"{parts['t']}.".encode() + raw,
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(expected, parts["v1"]):
        return "", 401

    event = json.loads(raw)                        # event["id"] is the idempotency key
    print(event["event"], event["data"])
    return "", 200

Event payloads

The envelope is always the same; data changes per event.

{
  "messageId": "a1b2c3d4-...",
  "conversationId": "b7a1c9e4-...",
  "contact": { "id": "c2d4e6f8-...", "waId": "919876543210", "phoneE164": "+919876543210", "name": "Priya" },
  "phoneNumberId": "d3e5f7a9-...",
  "type": "text",
  "content": { "body": "Is my order ready?" },
  "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgU...",
  "replyToWamid": null,
  "timestamp": "2026-09-14T10:00:00.000Z"
}

{
  "messageId": "3f1b9c22-...",
  "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS...",
  "conversationId": "b7a1c9e4-...",
  "contactId": "c2d4e6f8-...",
  "status": "delivered",
  "errorCode": null,
  "errorMessage": null,
  "timestamp": "2026-09-14T10:00:05.000Z"
}

{
  "templateId": "e4f6a8b0-...",
  "name": "order_update",
  "language": "en",
  "status": "APPROVED",
  "event": "APPROVED",
  "reason": null
}

{
  "contactId": "c2d4e6f8-...",
  "waId": "919876543210",
  "source": "keyword",
  "at": "2026-09-14T10:00:00.000Z"
}

{
  "alertId": "f5a7b9c1-...",
  "severity": "critical",
  "event": "TOKEN_INVALID",
  "title": "WhatsApp connection lost",
  "detail": "Reconnect WhatsApp to continue sending.",
  "phoneNumberId": null
}

{
  "callId": "0d9b6f1e-...",
  "direction": "inbound",
  "status": "ringing",
  "contact": { "id": "c2d4e6f8-...", "waId": "919876543210", "phoneE164": "+919876543210", "name": "Priya" },
  "phoneNumberId": "d3e5f7a9-...",
  "conversationId": "b7a1c9e4-...",
  "userId": null,
  "startedAt": "2026-09-30T10:00:00.000Z",
  "answeredAt": null,
  "endedAt": null,
  "durationSeconds": null,
  "errorCode": null
}

{
  "callId": "0d9b6f1e-...",
  "direction": "inbound",
  "status": "completed",
  "contact": { "id": "c2d4e6f8-...", "waId": "919876543210", "phoneE164": "+919876543210", "name": "Priya" },
  "phoneNumberId": "d3e5f7a9-...",
  "conversationId": "b7a1c9e4-...",
  "userId": "a8c0e2f4-...",
  "startedAt": "2026-09-30T10:00:00.000Z",
  "answeredAt": "2026-09-30T10:00:08.000Z",
  "endedAt": "2026-09-30T10:02:22.000Z",
  "durationSeconds": 134,
  "errorCode": null
}

Retries and failures

If your endpoint does not answer with a 2xx, we retry on a fixed schedule:

Every attempt is recorded with the HTTP status and the first 500 characters of your response, visible under Developers → Delivery log, where you can also replay a delivery once your server is fixed. After 10 consecutive exhausted deliveries the endpoint is disabled automatically and the workspace is notified.