ChatOpsManage keys →

API reference

Everything the app does with contacts, conversations, messages and orders, over HTTPS with JSON. Keys are created in Settings → API & webhooks and scoped to read, write or intake.

Basics

Base URL
http://localhost:3000/api/v1
Auth
Authorization: Bearer lf_…
Rate limit
120 requests per minute per key. Over the limit you get 429 with Retry-After.
Pagination
Lists return { data, next_cursor }; pass cursor back to get the next page.
Errors
{ error: { code, message } } with a 4xx or 5xx status. Send refusals use the outbound pipeline's codes: OUTSIDE_WINDOW, NO_CONSENT, TEMPLATE_NOT_APPROVED, …

Endpoints

GET/api/v1/contactsread

List contacts, newest first.

Query
  • limit (≤200)
  • cursor (created_at from the previous page)
  • tag
  • q (name, phone or email)
Example
curl "http://localhost:3000/api/v1/contacts?tag=vip&limit=50" -H "Authorization: Bearer $KEY"
POST/api/v1/contactswrite

Create or update a contact by phone or email. Returns 201 when created, 200 when matched.

Body
{ "name": "Rahul Sharma", "phone": "+919876543210", "email": "rahul@example.com", "tags": ["vip"], "notes": "…", "source": "crm" }
Example
curl -X POST "http://localhost:3000/api/v1/contacts" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"name":"Rahul Sharma","phone":"+919876543210","tags":["vip"]}'
GET/api/v1/conversationsread

List conversations with channel, status, AI mode, lead label and score.

Query
  • status (open | pending | closed)
  • contact_id
  • limit
  • cursor (last_message_at)
Example
curl "http://localhost:3000/api/v1/conversations?status=open" -H "Authorization: Bearer $KEY"
GET/api/v1/conversations/{id}/messagesread

Messages in a conversation, oldest first.

Query
  • limit
  • cursor (created_at)
Example
curl "http://localhost:3000/api/v1/conversations/$ID/messages" -H "Authorization: Bearer $KEY"
POST/api/v1/conversations/{id}/messageswrite

Send a message. Free text needs the 24-hour window to be open; otherwise send an approved template. Consent, approval status and cost rules apply; refusals return 422 with a code.

Body
{ "text": "Hi Rahul, your order is on its way." }
// or
{ "template": { "pack": "ecommerce", "slug": "order_shipped" }, "params": { "customer_name": "Rahul", "order_number": "#1042", "carrier": "Delhivery", "tracking_number": "AWB1" } }
Example
curl -X POST "http://localhost:3000/api/v1/conversations/$ID/messages" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"text":"Hi Rahul, your order is on its way."}'
GET/api/v1/ordersread

Orders synced from the connected store, with items and shipments.

Query
  • contact_id
  • cod (pending | confirmed | cancelled | expired)
  • limit
  • cursor (placed_at)
Example
curl "http://localhost:3000/api/v1/orders?cod=pending" -H "Authorization: Bearer $KEY"
GET/api/v1/templatesread

WhatsApp templates and their approval status.

Example
curl "http://localhost:3000/api/v1/templates" -H "Authorization: Bearer $KEY"
POST/api/v1/leadsintake

Lead intake from a website form, ad platform or property portal. Creates the contact, requirement hints and a WhatsApp thread, and fires lead.captured for workflows.

Body
{ "name": "Priya", "phone": "9876543210", "email": "…", "message": "Looking for a 2BHK in Thane", "source": "website", "project": "Lodha Park", "config": "2BHK", "locality": "Thane West", "budget": "80 lakh", "meta": { "utm_campaign": "diwali" } }
Example
curl -X POST "http://localhost:3000/api/v1/leads" -H "Authorization: Bearer $INTAKE_KEY" -H "Content-Type: application/json" -d '{"name":"Priya","phone":"9876543210","source":"website","config":"2BHK","locality":"Thane West","budget":"80 lakh"}'

Webhooks

Add an endpoint in Settings → API & webhooks and pick the events (or *). Every delivery is a POST with this shape, signed with X-ChatOps-Signature: sha256=<hex HMAC-SHA256 of the raw body with your endpoint secret> (the legacy X-Leadflow-Signature header is sent too for now). Respond 2xx within 10 seconds; ten consecutive failures disable the endpoint.

{
  "id": 12345,
  "type": "order.created",
  "occurred_at": "2026-09-05T10:00:00.000Z",
  "org_id": "…",
  "actor": { "type": "integration", "id": "shopify" },
  "subject": { "type": "order", "id": "…" },
  "data": { "orderId": "…", "orderNumber": "#1042", "total": 1249, "currency": "INR", "paymentMethod": "cod", … }
}
message.receivedmessage.sentmessage.failedconversation.createdconversation.assignedcontact.opted_outlead.scoredlead.capturedapproval.requestedapproval.decidedbooking.createdorder.createdorder.paidorder.fulfilledorder.cancelledcod.requestedcod.confirmedcod.cancelledcod.expiredcheckout.abandonedcheckout.recoveredshipment.updatedshipment.deliveredreturn.requestedpayment.completedcampaign.scheduledcampaign.sent

Verify in Node: crypto.createHmac("sha256", secret).update(rawBody).digest("hex") must equal the part after sha256=.