API DOCS · WHATSAPP

The WhatsApp API

Send templates and replies from your own systems, keep your contacts in step, read your chats, and have CRM Dost tell your server the moment something happens. It comes with the WhatsApp add-on. Your messages leave from your own number, and Meta bills them to your own account, as they do from the app.

Looking to post leads from a form instead? That needs no key: see posting a lead.

Getting started

  1. In the app, open WhatsApp → Developer. You need the permission to manage the WhatsApp API.
  2. Create a key with only the scopes your system needs, and copy it. It is shown once: CRM Dost keeps only a fingerprint of it.
  3. Call the API from your server. Every path below is under this address:
https://apis.crmdost.com/v1/whatsapp/api
curl -X POST 'https://apis.crmdost.com/v1/whatsapp/api/messages' \
  -H 'Authorization: Bearer crmd_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "connectionId": 7,
    "to": "+919820011223",
    "clientRequestId": "order-4471-confirmation",
    "message": { "type": "text", "text": "Thanks, Riya. Sunday at 11:00 works." }
  }'

Authentication and scopes

Send the key as a bearer token on every call: Authorization: Bearer crmd_live_…. The key alone says which workspace a call is for. It is for server-to-server calls: the API sends no CORS headers, so a browser cannot call it, and a key must never be put in a web page or a mobile app. Revoke a key in the app and it stops working at once.

ScopeWhat it allows
messages:sendSend a template, or a reply while the chat’s 24-hour window is open.
messages:readRead one message and its delivery status.
conversations:readList your numbers, your chats and their messages.
contacts:readList and read contacts.
contacts:writeAdd, update and opt out contacts.
templates:readList your templates and their status at Meta.
automations:runStart an automation whose trigger is the API.

Answers, paging and limits

Bodies are JSON, times are ISO 8601 in UTC, and phones are in international form with a leading +. A success carries what you asked for in data; a refusal carries a machine-readable error.reason and a sentence in message you may show as it is.

{ "statusCode": 200, "message": "OK", "data": { … } }

{ "status": "fail", "statusCode": 409, "message": "This person asked not to be messaged.",
  "error": { "reason": "CONTACT_OPTED_OUT" } }

A list answers { items, nextCursor, total }, newest first. Ask for the next page with before set to the last nextCursor; it is null on the last page. limit is 50 unless you ask, and at most 100.

  • Rate limit: 120 calls a minute per key. Past it the API answers 429 API_RATE_LIMITED with a Retry-After header in seconds.
  • Monthly calls: every call counts against the API calls in your plan. When they are used up, calls answer 409 WHATSAPP_API_QUOTA until the month turns; the Developer page in the app shows how many are left.
  • Meta’s own limits still apply: how many people a number can start chats with in 24 hours, its quality rating, and who has agreed to marketing. A send the rules refuse answers 409 with the reason, and nothing is sent.

Errors

Status and reasonWhen
401 API_KEY_INVALIDThe key is unknown, revoked or past its expiry.
403 API_KEY_SCOPEThe key lacks the scope this route needs. error.required names it.
403 WHATSAPP_ADDON_REQUIREDThe workspace no longer has the WhatsApp add-on.
402 BILLING_EXPIREDThe workspace’s subscription has lapsed.
409 WHATSAPP_API_QUOTAThis month’s API calls are used up. error.limit and error.used say how many.
429 API_RATE_LIMITEDMore than 120 calls in a minute on this key. Wait for Retry-After seconds.
400 INVALID_INPUTA value was refused. error.fields maps each field to a sentence.
400 INVALID_PHONEThe phone number cannot be read. Send it in international form, + and digits.
404 NOT_FOUNDNo such record in your workspace.
400 WINDOW_CLOSEDA free-text reply after the 24-hour window closed. Send a template instead.
409 NUMBER_NOT_READYThe number cannot send right now. Check it in the app under WhatsApp → Settings.
409 CONTACT_OPTED_OUTThe person asked to stop. Nothing automated reaches them.
409 CONTACT_NO_CONSENTA marketing template to someone with no consent on record.
409 CONTACT_CAPPEDMeta is limiting marketing to this person (error 131049). error.retryAt says when to try again.
409 CONTACT_US_MARKETINGMeta does not deliver marketing templates to +1 numbers.
400 META_REJECTEDMeta refused the message. error.metaCode and error.description say why.

Endpoints

List your numbers

GET/connectionsScope conversations:read

Every WhatsApp number on the workspace. A send names one of them as connectionId.

RESPONSE
[
  {
    "id": 7,
    "displayPhoneNumber": "+91 98200 11223",
    "verifiedName": "Asha Realty",
    "status": "CONNECTED"
  }
]

Send a message

POST/messagesScope messages:send

A template, to start a chat or to write after the 24-hour window has closed, or a free-text reply while it is open. Name the person by to (a phone) or contactId; a phone with no contact gets one. clientRequestId is yours and makes the call safe to repeat: the same id never sends twice, and a repeat answers what happened to the first. A 202 with queued: true means Meta asked us to try again and the message waits in our queue: do not send it again.

BODY
connectionIdThe number to send from (required).
to / contactIdA phone in international form, or a contact id. One of the two.
clientRequestIdYour id for this message, up to 120 characters (required). Keep it for the message’s whole life.
message{ "type": "template", "template": { "name", "language", "params" } } or { "type": "text", "text" }.
REQUEST
POST https://apis.crmdost.com/v1/whatsapp/api/messages

{
  "connectionId": 7,
  "to": "+919820011223",
  "clientRequestId": "order-4471-confirmation",
  "message": {
    "type": "template",
    "template": {
      "name": "site_visit_booked",
      "language": "en",
      "params": [
        "Riya",
        "Saturday at 11:00"
      ]
    }
  }
}
RESPONSE
201 Created
{
  "id": 5120,
  "conversationId": 311,
  "connectionId": 7,
  "contactId": 88,
  "direction": "outbound",
  "type": "template",
  "text": "Hi Riya, your site visit is booked for Saturday at 11:00.",
  "status": "accepted",
  "error": null,
  "clientRequestId": "order-4471-confirmation",
  "occurredAt": "2026-11-04T09:30:12.000Z"
}

Read a message

GET/messages/{id}Scope messages:read

One message and where it has got to: queued, accepted, sent, delivered, read or failed. An inbound message is received.

RESPONSE
{
  "id": 5120,
  "conversationId": 311,
  "connectionId": 7,
  "contactId": 88,
  "direction": "outbound",
  "type": "template",
  "text": "Hi Riya, your site visit is booked for Saturday at 11:00.",
  "status": "accepted",
  "error": null,
  "clientRequestId": "order-4471-confirmation",
  "occurredAt": "2026-11-04T09:30:12.000Z"
}

List conversations

GET/conversationsScope conversations:read

Chats, most recent first. windowOpen says whether a free-text reply can go now.

QUERY
connectionIdOnly this number’s chats (optional).
statusOPEN, PENDING, SNOOZED or RESOLVED (optional).
before, limitPaging: see below.
RESPONSE
{
  "items": [
    {
      "id": 311,
      "connectionId": 7,
      "contactId": 88,
      "phone": "+919820011223",
      "name": "Riya Kapoor",
      "status": "OPEN",
      "assignedTo": 12,
      "lastMessageAt": "2026-11-04T09:30:12.000Z",
      "windowOpen": true
    }
  ],
  "nextCursor": "2026-11-04 09:30:12_311",
  "total": null
}

List a conversation’s messages

GET/conversations/{id}/messagesScope conversations:read

Its messages, newest first, in the same shape as Read a message.

QUERY
before, limitPaging.
RESPONSE
{
  "items": [
    {
      "id": 5120,
      "conversationId": 311,
      "connectionId": 7,
      "contactId": 88,
      "direction": "outbound",
      "type": "template",
      "text": "Hi Riya, your site visit is booked for Saturday at 11:00.",
      "status": "accepted",
      "error": null,
      "clientRequestId": "order-4471-confirmation",
      "occurredAt": "2026-11-04T09:30:12.000Z"
    }
  ],
  "nextCursor": null,
  "total": null
}

List contacts

GET/contactsScope contacts:read

Find a contact by phone, or everyone with a tag.

QUERY
phoneOne phone, in international form (optional).
tagA tag’s name (optional).
before, limitPaging.
RESPONSE
{
  "items": [
    {
      "id": 88,
      "phone": "+919820011223",
      "name": "Riya Kapoor",
      "firstName": "Riya",
      "lastName": "Kapoor",
      "lead": {
        "id": 1042,
        "name": "Riya Kapoor"
      },
      "tags": [
        {
          "id": 3,
          "name": "Site visit",
          "color": "#E8650A",
          "contactCount": 41
        }
      ],
      "attributes": {
        "city": "Pune"
      },
      "consent": {
        "status": "granted",
        "source": "web_form",
        "at": "2026-11-01T08:00:00.000Z",
        "wording": "Send me updates on WhatsApp"
      },
      "optOut": null,
      "lastInboundAt": "2026-11-03T17:12:00.000Z",
      "lastOutboundAt": "2026-11-04T09:30:12.000Z",
      "conversations": [
        {
          "id": 311,
          "connectionId": 7
        }
      ],
      "createdAt": "2026-11-01T08:00:00.000Z",
      "updatedAt": "2026-11-04T09:30:12.000Z"
    }
  ],
  "nextCursor": null,
  "total": 1
}

Add or update a contact

POST/contactsScope contacts:write

Matched on phone: a new phone answers 201, a known one 200 with the contact updated. Tags are named, and made when they do not exist. Record consent only as the person gave it, with the words they agreed to.

BODY
phoneInternational form (required).
name, firstName, lastNameOptional.
tagsTag names. Replaces the contact’s tags.
attributesMerged into the contact’s. A key is lower case, letters, digits and _; a null value removes it.
consent{ "status": "granted", "source": "web_form", "wording": "…" }, when the person agreed.
REQUEST
POST https://apis.crmdost.com/v1/whatsapp/api/contacts

{
  "phone": "+919820011223",
  "name": "Riya Kapoor",
  "tags": [
    "Site visit"
  ],
  "attributes": {
    "city": "Pune"
  },
  "consent": {
    "status": "granted",
    "source": "web_form",
    "wording": "Send me updates on WhatsApp"
  }
}
RESPONSE
201 Created
{
  "id": 88,
  "phone": "+919820011223",
  "name": "Riya Kapoor",
  "firstName": "Riya",
  "lastName": "Kapoor",
  "lead": {
    "id": 1042,
    "name": "Riya Kapoor"
  },
  "tags": [
    {
      "id": 3,
      "name": "Site visit",
      "color": "#E8650A",
      "contactCount": 41
    }
  ],
  "attributes": {
    "city": "Pune"
  },
  "consent": {
    "status": "granted",
    "source": "web_form",
    "at": "2026-11-01T08:00:00.000Z",
    "wording": "Send me updates on WhatsApp"
  },
  "optOut": null,
  "lastInboundAt": "2026-11-03T17:12:00.000Z",
  "lastOutboundAt": "2026-11-04T09:30:12.000Z",
  "conversations": [
    {
      "id": 311,
      "connectionId": 7
    }
  ],
  "createdAt": "2026-11-01T08:00:00.000Z",
  "updatedAt": "2026-11-04T09:30:12.000Z"
}

Read a contact

GET/contacts/{id}Scope contacts:read

One contact, with its tags, attributes, consent and opt-out.

RESPONSE
{
  "id": 88,
  "phone": "+919820011223",
  "name": "Riya Kapoor",
  "firstName": "Riya",
  "lastName": "Kapoor",
  "lead": {
    "id": 1042,
    "name": "Riya Kapoor"
  },
  "tags": [
    {
      "id": 3,
      "name": "Site visit",
      "color": "#E8650A",
      "contactCount": 41
    }
  ],
  "attributes": {
    "city": "Pune"
  },
  "consent": {
    "status": "granted",
    "source": "web_form",
    "at": "2026-11-01T08:00:00.000Z",
    "wording": "Send me updates on WhatsApp"
  },
  "optOut": null,
  "lastInboundAt": "2026-11-03T17:12:00.000Z",
  "lastOutboundAt": "2026-11-04T09:30:12.000Z",
  "conversations": [
    {
      "id": 311,
      "connectionId": 7
    }
  ],
  "createdAt": "2026-11-01T08:00:00.000Z",
  "updatedAt": "2026-11-04T09:30:12.000Z"
}

Change a contact

PATCH/contacts/{id}Scope contacts:write

The same fields as Add or update, except phone. Only what you send changes.

REQUEST
PATCH https://apis.crmdost.com/v1/whatsapp/api/contacts/{id}

{
  "attributes": {
    "budget": "80L"
  }
}
RESPONSE
{
  "id": 88,
  "phone": "+919820011223",
  "name": "Riya Kapoor",
  "firstName": "Riya",
  "lastName": "Kapoor",
  "lead": {
    "id": 1042,
    "name": "Riya Kapoor"
  },
  "tags": [
    {
      "id": 3,
      "name": "Site visit",
      "color": "#E8650A",
      "contactCount": 41
    }
  ],
  "attributes": {
    "city": "Pune"
  },
  "consent": {
    "status": "granted",
    "source": "web_form",
    "at": "2026-11-01T08:00:00.000Z",
    "wording": "Send me updates on WhatsApp"
  },
  "optOut": null,
  "lastInboundAt": "2026-11-03T17:12:00.000Z",
  "lastOutboundAt": "2026-11-04T09:30:12.000Z",
  "conversations": [
    {
      "id": 311,
      "connectionId": 7
    }
  ],
  "createdAt": "2026-11-01T08:00:00.000Z",
  "updatedAt": "2026-11-04T09:30:12.000Z"
}

Opt a contact out

POST/contacts/{id}/opt-outScope contacts:write

The person asked to stop, somewhere your system saw it. Nothing automated reaches them again, on any number. 409 ALREADY_SUPPRESSED if they had already.

RESPONSE
{
  "id": 19,
  "phone": "+919820011223",
  "contactId": 88,
  "contactName": "Riya Kapoor",
  "source": "api",
  "reason": null,
  "addedBy": null,
  "createdAt": "2026-11-04T10:02:00.000Z"
}

List templates

GET/templatesScope templates:read

Your templates and their status at Meta. Only an APPROVED one can be sent.

QUERY
connectionIdOnly this number’s account (optional).
statusFor example APPROVED (optional).
before, limitPaging.
RESPONSE (SOME FIELDS LEFT OUT)
{
  "items": [
    {
      "id": 54,
      "name": "site_visit_booked",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED"
    }
  ],
  "nextCursor": null,
  "total": null
}

Start an automation

POST/automations/{id}/startScope automations:run

Runs an automation whose trigger is the API, for one person. variables become the run’s attributes. 409 AUTOMATION_NOT_API when its trigger is something else, AUTOMATION_NOT_ACTIVE when it is switched off, WHATSAPP_AUTOMATION_QUOTA when this month’s runs are used up.

REQUEST
POST https://apis.crmdost.com/v1/whatsapp/api/automations/{id}/start

{
  "connectionId": 7,
  "to": "+919820011223",
  "variables": {
    "order_id": "4471"
  }
}
RESPONSE
202 Accepted
{
  "runId": 9031
}

Webhooks

Add an endpoint in the app under WhatsApp → Developer → Webhooks, pick its events, and copy its signing secret, which is shown once. CRM Dost then posts each event to it as JSON. Answer with any 2xx within 10 seconds; anything else is tried again 1, 5, 15, 60 and 360 minutes later, then marked failed, and you can send it again from the delivery log. After twenty failed deliveries in a row the endpoint is switched off and the workspace’s WhatsApp admins are told.

An event carries message text and phone numbers, because it goes to your own server. Use an https address that only your systems receive.

HeaderValue
X-CrmDost-Signaturet=<unix seconds>,v1=<signature>: the hex HMAC-SHA256, keyed with the endpoint’s signing secret, of the timestamp, a full stop and the raw body.
X-CrmDost-EventThe event’s name.
X-CrmDost-DeliveryThe delivery’s id. A retry repeats it, so drop a delivery you have already handled.
{
  "id": "evt_…",
  "event": "message.received",
  "occurredAt": "2026-11-04T09:31:40.000Z",
  "connectionId": 7,
  "data": { … }
}
message.receivedA customer wrote to one of your numbers.
DATA
{
  "id": 5120,
  "conversationId": 311,
  "connectionId": 7,
  "contactId": 88,
  "direction": "inbound",
  "type": "text",
  "text": "Can I come on Sunday instead?",
  "status": "received",
  "error": null,
  "clientRequestId": null,
  "occurredAt": "2026-11-04T09:30:12.000Z"
}
message.status_changedA message you sent was delivered, read or failed.
DATA
{
  "id": 5120,
  "conversationId": 311,
  "status": "delivered",
  "error": null,
  "clientRequestId": "order-4471-confirmation"
}
contact.opted_outSomeone asked to stop: a stop word, an opt-out button, WhatsApp’s own setting, or your team.
DATA
{
  "contactId": 88,
  "phone": "+919820011223",
  "source": "keyword"
}
conversation.assignedA chat was given to a person or a team, or taken from them.
DATA
{
  "conversationId": 311,
  "assignedTo": 12,
  "assignedTeamId": null
}

Checking the signature

Check every delivery before you trust it. Compute the HMAC over the raw body, before any JSON parsing changes a byte, and refuse a timestamp more than five minutes old so a captured delivery cannot be replayed.

NODE.JS
const crypto = require('node:crypto');

// rawBody: the request body exactly as received (a Buffer), before any JSON parsing.
function verifyCrmDostSignature(rawBody, header, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
  const fields = {};
  for (const part of String(header || '').split(',')) {
    const at = part.indexOf('=');
    if (at > 0) fields[part.slice(0, at).trim()] = part.slice(at + 1).trim();
  }
  const t = Number(fields.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(fields.v1 || '')) return false;
  if (Math.abs(nowSeconds - t) > 300) return false; // older than 5 minutes: refuse a replay
  const expected = crypto.createHmac('sha256', secret).update(t + '.').update(rawBody).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(fields.v1, 'hex'));
}
app.post('/crmdost/events', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyCrmDostSignature(req.body, req.get('X-CrmDost-Signature'), process.env.CRMDOST_WEBHOOK_SECRET);
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200); // answer within 10 seconds, then do the work
  const event = JSON.parse(req.body.toString('utf8'));
  handleEvent(req.get('X-CrmDost-Delivery'), event); // skip a delivery id you have seen before
});
PYTHON
import hashlib, hmac, time

def verify_crmdost_signature(raw_body: bytes, header: str, secret: str) -> bool:
    fields = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
    try:
        t = int(fields["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > 300:  # older than 5 minutes: refuse a replay
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields.get("v1", ""))
Good to know
  • A message sent through the API shows in the chat in the app, so your team sees what your systems said.
  • The API never returns a lead’s deal value.
  • Zapier and Make work through webhooks: point a Catch Hook step at a webhook endpoint, and call the API from a Webhooks step.
  • Building something we do not cover? Tell us what you need.