Developer API Documentation

Overview

The API is organised around a small number of predictable HTTP endpoints. Every request and response body is JSON. You authenticate with a secret API key that belongs to one WhatsApp Chat CRM account (a tenant), so a key can only ever read and write that account's data.

Quick start

1. Sign in and open Settings → Developer API, then click Generate Key. Copy the key — it starts with whsec_. (Owners can do this; a manager needs the Manage API Keys permission.)
2. Make sure WhatsApp is connected under Meta Settings — message endpoints need it.
3. Send your first request:

A successful call returns 201 (created) or 200 (already existed and was updated):

{
  "success": true,
  "isNewContact": true,
  "contactId": "329cfdf6-a303-44b9-bffc-fc3336caafb5"
}

Authentication

Send your key in the x-api-key header on every request.

x-api-key: whsec_your_secret_key_here

A key identifies the account, not a person, and has full access to every endpoint on this page. Create one key per integration so you can revoke a single one without downtime. Revocation is immediate.

Conventions & limits

Data types

Shared shapes used across endpoints, written as TypeScript so they can be pasted into your project.

type PhoneNumber       = string;  // digits incl. country code: "919876543210"
type Timestamp         = string;  // ISO-8601 UTC
type WhatsAppMessageId = string;  // Meta "wamid", e.g. "wamid.HBgMOTE5ODc2NTQz..."

interface ErrorResponse {
  error: string;                  // code or human-readable message
  message?: string;               // extra explanation on some errors
  [extra: string]: unknown;       // e.g. useTemplateEndpoint, expires_at
}

interface BulkResultItem {
  phone: PhoneNumber;
  success: boolean;
  messageId?: WhatsAppMessageId;  // when success = true
  error?: string;                 // when success = false
}

interface Customer {
  id: string;                     // UUID
  name: string | null;
  phone_number: PhoneNumber;
  last_interacted_at: Timestamp | null;
  created_at: Timestamp;
}

interface Message {
  id: string;
  wamid: WhatsAppMessageId | null;
  context_wamid: WhatsAppMessageId | null;   // set when replying to another message
  direction: "inbound" | "outbound";
  message_type: "text" | "image" | "video" | "document" | "audio" | "template" | "interactive" | string;
  body: string | null;            // JSON *string* when message_type = "template"
  media_url: string | null;       // signed relative link, valid 10 minutes
  status: "sent" | "delivered" | "read" | "failed" | "received" | string;
  is_read: 0 | 1;
  created_at: Timestamp;
}

Errors

Every error is a JSON object with an error field (some add message and extras).

{
  "error": "SUBSCRIPTION_EXPIRED",
  "message": "Your subscription plan has expired. All inbound/outbound services and APIs are halted.",
  "expires_at": "2026-09-01T00:00:00.000Z",
  "rechargeEndpoint": "/api/billing/overview"
}

Incoming-message webhooks

The endpoints above are you → CRM. To be told when a customer writes to you (CRM → you), open Settings → Integrations and add a destination URL. Every incoming customer message is forwarded there as Meta's raw, unmodified WhatsApp Cloud API webhook JSON, so any existing "WhatsApp Cloud API" node, parser or library works unchanged.

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "<WABA_ID>",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "918602505909", "phone_number_id": "<PHONE_NUMBER_ID>" },
        "contacts": [{ "profile": { "name": "Asha Verma" }, "wa_id": "919876543210" }],
        "messages": [{
          "from": "919876543210",
          "id": "wamid.HBgM...",
          "timestamp": "1789755000",
          "type": "text",
          "text": { "body": "Hi, is my order ready?" }
        }]
      }
    }]
  }]
}

Use the Test button on an integration to send a sample event to your URL while you build.

Integration recipes

Billing app → tag expiring customers

for sub in subscriptions.expiring_within(days=5):
    POST /api/v1/customers       { phone_number: sub.phone, external_id: sub.id, full_name: sub.name }   # ensure they exist
    POST /api/v1/customers/tags  { external_id: sub.id, tags: ["2 D Exp"] }

for sub in subscriptions.renewed_today():
    POST /api/v1/customers/tags  { external_id: sub.id, remove_tags: ["2 D Exp"] }

Lead form → CRM, then a welcome template

POST /api/v1/customers { phone_number, full_name, email, field_data: [ ...all other form answers... ] }
POST /api/v1/messages/send-template { to: phone_number, templateName: "welcome", variables: [full_name] }
# A new customer has no open window, so free text would return 409 — always start with a template.

Send a message with automatic fallback

r = POST /api/v1/messages/send { to, message }
if r.status == 409 and r.body.error == "WINDOW_CLOSED":
    POST /api/v1/messages/send-template { to, templateName: "generic_update", variables: [message] }

Retry helper (Node.js)

Best practices

• Keep keys server-side and out of source control. Use environment variables or a secrets manager.
• One key per integration, named after it. Rotate by creating a new key, deploying, then revoking the old one.
• Use HTTPS and set sensible client timeouts (60 s for bulk).
• Retry only what is safe. Retry 429 and generic 5xx with exponential back-off + jitter. Customer and tag calls are idempotent; message sends are not — check before resending.
• Always inspect bulk results[] — HTTP 200 doesn't mean every message went out.
• Store your own external_id on every customer you create so you never depend on phone numbers alone.
• Authenticate your webhook receiver with the Bearer/API-key header option, and respond fast.
• Don't log full phone numbers or message bodies to shared systems without need.

Known limitations

• No pagination or filtering on List customers and Message history.
• Bulk sends run one after another inside a single HTTP request — there is no queue or job id.
• Templates support body variables only.
• A key has access to every endpoint; there are no per-endpoint scopes.
• No endpoints yet for tickets, tasks, or assigning a customer to a staff member.
• Outgoing webhooks have no automatic retries, no signature header, and don't include delivery-status events.

Changelog