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
| connectionId | The number to send from (required). |
| to / contactId | A phone in international form, or a contact id. One of the two. |
| clientRequestId | Your 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
| connectionId | Only this number’s chats (optional). |
| status | OPEN, PENDING, SNOOZED or RESOLVED (optional). |
| before, limit | Paging: 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
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
}GET/contactsScope contacts:read
Find a contact by phone, or everyone with a tag.
QUERY
| phone | One phone, in international form (optional). |
| tag | A tag’s name (optional). |
| before, limit | Paging. |
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
}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
| phone | International form (required). |
| name, firstName, lastName | Optional. |
| tags | Tag names. Replaces the contact’s tags. |
| attributes | Merged 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"
}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"
}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"
}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
| connectionId | Only this number’s account (optional). |
| status | For example APPROVED (optional). |
| before, limit | Paging. |
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.
| Header | Value |
|---|
| X-CrmDost-Signature | t=<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-Event | The event’s name. |
| X-CrmDost-Delivery | The 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", ""))