{ "openapi": "3.1.0", "info": { "title": "Communication Platform API", "version": "1.0.0", "description": "Connect your own software - an e-commerce store, a POS, an ERP, a booking engine, a helpdesk - to **Communication Platform** so that it can message your customers on the channels you have connected (WhatsApp, Telegram, email, web chat and more), keep your contacts and leads in step, start automations when something happens in your system, and hear back **in realtime** through signed webhooks whenever a customer replies or a message is delivered.\n\nEverything on this page is done with plain HTTPS and JSON. No SDK is required.\n\n> **Base URL:** `http://localhost:8000/api/v1` · **Format:** JSON in, JSON out · **Auth:** `Authorization: Bearer …` · **Time:** ISO-8601 UTC · **Ids:** UUIDs\n\n---\n\n## 1. Getting started\n\n### 1.1 Create an application\n\nAn *application* is your integration's identity inside Communication Platform. An administrator creates it in the dashboard under **Settings → Developer → Applications** and decides three things:\n\n| Setting | What it controls |\n|---------|------------------|\n| **Scopes** | What the application may do. Each operation below names the scope it needs. Grant only what the integration uses. |\n| **Channels** | Which of the business's connected channels the application may send on and hear about. A store integration usually gets the sales number, not the support line. |\n| **Credentials** | An **API key** (simplest) and/or an **OAuth 2.0 client** (for systems that already speak OAuth). |\n\nThe application's page also holds its **webhook endpoints** (§5) and a log of every delivery.\n\n### 1.2 Authenticate\n\nEvery request carries a bearer token:\n\n```\nAuthorization: Bearer \nAccept: application/json\n```\n\n**Option A - API key.** Shown once when created. Keys are prefixed `omni_live_` (production) or `omni_test_` (a test key that behaves the same but is easy to tell apart in logs). Use the key directly as the bearer token.\n\n**Option B - OAuth 2.0 client credentials.** Exchange the client id and secret for a short-lived access token (`omni_at_…`, one hour), then use that as the bearer token. See `POST /oauth/token`. Request a narrower `scope` than the application holds if a particular server needs less.\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/oauth/token \\\n -H \"Content-Type: application/json\" \\\n -d '{\"grant_type\":\"client_credentials\",\"client_id\":\"…\",\"client_secret\":\"…\"}'\n```\n\nA token that is missing, expired or revoked answers `401 unauthenticated`. A token without the scope an operation needs answers `403 forbidden` with `details.required_scope`.\n\n### 1.3 Read a response\n\nSuccessful responses wrap the payload in `data`. Lists add `meta` and `links`:\n\n```json\n{ \"data\": { … } }\n{ \"data\": [ … ], \"meta\": { \"per_page\": 50, \"has_more\": true }, \"links\": { \"next\": \"…\", \"prev\": null } }\n```\n\nErrors are one shape everywhere - branch on `code`, show `message`, log `request_id`:\n\n```json\n{\n \"error\": {\n \"code\": \"validation_failed\",\n \"message\": \"The to field is required.\",\n \"details\": { \"to\": [\"The to field is required.\"] },\n \"request_id\": \"0f1c6f1e-…\"\n }\n}\n```\n\nEvery response also carries `X-Request-ID`. Quote it when you contact support about a request.\n\n### 1.4 Retry safely (idempotency)\n\nEvery `POST` that creates something (`/messages`, `/contacts`, `/leads`, `/events`) **requires** an `Idempotency-Key` header - any string up to 255 characters that is unique per logical operation, such as your order id plus the action:\n\n```\nIdempotency-Key: order-58213-confirmation\n```\n\nIf a request times out and you send it again with the same key and the same body, Communication Platform returns the **original** response instead of acting twice, and adds `Idempotency-Replayed: true`. The same key with a *different* body is refused with `409 idempotency_conflict`. Keys are kept for 24 hours.\n\n### 1.5 Rate limits\n\nTwo buckets per application, each reported on every response:\n\n| Bucket | Default | Applies to |\n|--------|---------|------------|\n| Requests | 600 / minute | every call |\n| Sends | 100 / minute | `POST /messages` |\n\nHeaders: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (unix seconds). Over the limit you receive `429 rate_limited` with `Retry-After` in seconds - wait that long, then resume. Do not tighten your own loop on a 429.\n\n---\n\n## 2. Connecting an external system - worked example\n\nThis walks an online store through the whole loop: a customer places an order, the store confirms it on WhatsApp, an automation follows up, and the store hears the customer's reply.\n\n### Step 1 - Identify the customer\n\nYou never need our ids to start. A message is addressed by **channel + handle** (a phone number in E.164 for WhatsApp, an email address for email). If Communication Platform has never seen that handle, sending the first message **creates the contact and the conversation for you**.\n\nIf you want the contact to exist with a name and tags first, create it explicitly - and idempotently:\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/contacts \\\n -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: customer-10442\" \\\n -d '{\n \"first_name\": \"Rahul\", \"last_name\": \"Sharma\",\n \"phone\": \"+919876543210\", \"email\": \"rahul@example.com\",\n \"lifecycle_stage\": \"customer\",\n \"tags\": [\"store\", \"repeat-buyer\"],\n \"identities\": [{ \"channel\": \"whatsapp\", \"handle\": \"+919876543210\" }],\n \"custom_fields\": { \"store_customer_id\": \"10442\" }\n }'\n```\n\n`201 Created` returns the contact. If one of the identities already belongs to a contact, the API answers `422 validation_failed` and puts that contact's id in `details.contact_id` - use it rather than creating a second record. A contact needs at least one of `email`, `phone` or an identity, or nothing could ever reach it. Keep the returned `id` against your customer record; the same `Idempotency-Key` on a retry returns the same contact.\n\n### Step 2 - Send the order confirmation\n\nOn WhatsApp a business may only *start* a conversation with an **approved template**; free text is allowed once the customer has written to you in the last 24 hours (the *service window*). Other channels (Telegram, email, web chat) accept free text at any time. So the store sends a template:\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/messages \\\n -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: order-58213-confirmation\" \\\n -d '{\n \"channel\": \"whatsapp\",\n \"to\": \"+919876543210\",\n \"type\": \"template\",\n \"external_reference\": \"order-58213\",\n \"message\": {\n \"template\": \"order_confirmation\",\n \"language\": \"en\",\n \"variables\": [\"Rahul\", \"58213\", \"₹4,299\", \"Thursday\"]\n }\n }'\n```\n\n`202 Accepted` means *queued* - the customer does not have it yet:\n\n```json\n{\n \"data\": {\n \"message_id\": \"3a1d…\", \"status\": \"queued\",\n \"external_reference\": \"order-58213\",\n \"conversation_id\": \"9c0e…\", \"contact_id\": \"b7f2…\", \"connection_id\": \"e51a…\",\n \"request_id\": \"0f1c…\"\n }\n}\n```\n\nStore `message_id`. Delivery is reported by webhooks (`message.sent` → `message.delivered` → `message.read`, or `message.failed`), each carrying your `external_reference` so you can match it without a lookup. You can also poll `GET /messages/{id}`.\n\nWhich templates exist, with their variable slots, comes from `GET /templates`. Only `is_sendable: true` templates can be sent.\n\n### Step 3 - Tell Communication Platform what happened\n\nPost a **named event** whenever something worth reacting to happens in your system - an order is paid, shipped, delivered; a cart is abandoned; an appointment is booked. Events do not send anything by themselves; they are what **automations** listen for (§3):\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/events \\\n -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: order-58213-shipped\" \\\n -d '{\n \"event\": \"order.shipped\",\n \"identity\": { \"channel\": \"whatsapp\", \"external_id\": \"+919876543210\" },\n \"dedupe_key\": \"order-58213-shipped\",\n \"data\": { \"order_id\": \"58213\", \"courier\": \"BlueDart\", \"tracking_url\": \"https://…\", \"eta\": \"Thursday\" }\n }'\n```\n\nThe contact is named by `contact_id` **or** by an identity you know (`channel` + `external_id`). `202` returns `workflows_matched` - how many automations picked the event up.\n\n### Step 4 - Hear the customer back\n\nRegister a webhook endpoint (§5) subscribed to `message.received`. When Rahul replies \"Can I change the delivery address?\", your endpoint receives, within a second or two:\n\n```json\n{\n \"id\": \"evt_8b1c…\",\n \"type\": \"message.received\",\n \"created_at\": \"2026-09-17T09:12:44+00:00\",\n \"data\": {\n \"message\": {\n \"id\": \"d3a0…\", \"direction\": \"inbound\", \"type\": \"text\", \"status\": \"delivered\",\n \"body\": \"Can I change the delivery address?\",\n \"conversation_id\": \"9c0e…\", \"contact_id\": \"b7f2…\", \"connection_id\": \"e51a…\",\n \"attachments\": [], \"received_at\": \"2026-09-17T09:12:43+00:00\"\n }\n }\n}\n```\n\nReply from your own system with `POST /messages` (`type: \"text\"` is fine now - the customer just wrote to you), or let the agents answer in the Communication Platform inbox; either way every message and status lands on the same webhook.\n\n### Step 5 - Keep the CRM in step (optional)\n\nCreate a lead when a quote is requested (`POST /leads`), read a customer's conversation history (`GET /conversations?contact_id=…`), or list contacts changed since your last sync (`GET /contacts?created_after=…`).\n\n---\n\n## 3. Automations from your events\n\nAn **automation** (dashboard → **Automation**) is a workflow with a trigger, optional conditions and a list of actions. Your events reach it through the **\"External API event\"** trigger.\n\n### 3.1 Build one\n\n1. **Automation → New workflow**, choose the trigger **External API event**.\n2. **Event name** - exactly the string your system sends, e.g. `order.shipped`. One workflow per event name; the same event can start several workflows.\n3. Add **conditions** if the workflow should only run for some contacts - by tag, lifecycle stage, channel, country, keyword, time window, assigned agent, or pipeline stage.\n4. Add **actions**, in order. Available actions:\n\n| Action | What it does |\n|--------|--------------|\n| Send message | A text or an approved template on the contact's channel; variables can use event data |\n| Send email | An email to the contact or to a fixed address |\n| Add tag / Update contact | Tag the contact, change a field or the lifecycle stage |\n| Create lead / Update lead | Open a lead in a pipeline, or move an existing one |\n| Assign agent | Route the conversation to an agent or team |\n| Create task | A follow-up for an agent with a due date |\n| Notify | An in-app notification to a user or team |\n| Call webhook | `POST` a JSON body to a URL of yours - the reverse of §5 |\n| Wait | Pause the run for a period before the next action |\n\n5. **Publish**. Draft workflows do not run.\n\n### 3.2 Use the event's data\n\nInside the workflow every value you sent under `data` is available as a placeholder in any text field: `{{data.order_id}}`, `{{data.eta}}`, `{{data.tracking_url}}` - alongside the contact's fields (`{{contact.first_name}}`, `{{contact.phone}}`) and the event name (`{{event}}`). A \"Send message\" action for `order.shipped` might send the template `order_shipped` with the variables `{{contact.first_name}}`, `{{data.order_id}}`, `{{data.eta}}`. An unknown placeholder renders as an empty string, never as literal braces in a customer's message.\n\nThe trigger provides: `event` (the name), `contact_id`, `data` (your object, as sent - nested keys work: `{{data.address.city}}`), `application_id`.\n\n### 3.3 What you get back\n\n- `POST /events` answers `202` with `workflows_matched`. `0` means nothing is listening for that name yet - check the spelling in the workflow.\n- Every run is recorded step by step under **Automation → Runs**, with the input, each action's outcome and any error, so a workflow that did not do what you expected can be read rather than guessed at.\n- If the workflow sends a message you receive the usual `message.*` webhooks for it, so your system can show \"confirmation sent\" without polling.\n\n### 3.4 Re-entry and dedupe\n\nAn event carrying a `dedupe_key` (or the same `Idempotency-Key`) that has already started a run does not start a second one. Sending `order.shipped` twice for the same order is safe.\n\n---\n\n## 4. Reading data\n\n| Need | Call |\n|------|------|\n| Contacts, filtered and paged | `GET /contacts?search=&lifecycle_stage=&tag=&channel=&created_after=&page=&per_page=` |\n| One contact with identities and tags | `GET /contacts/{id}` |\n| Conversations for a contact or a channel | `GET /conversations?contact_id=&connection_id=&status=&limit=&cursor=` |\n| One conversation | `GET /conversations/{id}` |\n| A conversation's messages, newest first | `GET /conversations/{id}/messages?limit=&cursor=` |\n| One message with its delivery times | `GET /messages/{id}` |\n| Sendable templates and their variables | `GET /templates?language=&include_unapproved=` |\n\nConversations and messages page by **cursor**: follow `links.next` until it is `null`. Contacts page by number. You only ever see conversations and messages on channels your application is allow-listed for.\n\n---\n\n## 5. Webhooks - realtime updates\n\nA webhook is an HTTPS endpoint on your side that Communication Platform `POST`s to the moment something happens. It is how your system learns about customer replies, delivery receipts, new contacts and leads without polling.\n\n### 5.1 Subscribe\n\nIn **Settings → Developer → Applications → your application → Webhooks** add an endpoint:\n\n| Field | Meaning |\n|-------|---------|\n| URL | `https://` (required in production). Must answer within **10 seconds**. |\n| Events | Any of the events below, or `*` for all of them |\n| Description | For your own reference |\n\nThe **signing secret** (`whsec_…`) is shown once when the endpoint is created. Store it as you would a password; it is what lets you verify that a delivery really came from Communication Platform (§5.4). It can be rotated at any time from the same page - deliveries signed with the new secret begin immediately.\n\nUse **Send test** on the endpoint to receive a `webhook.test` delivery and confirm your verification code before subscribing to real events.\n\n### 5.2 Events\n\n| Event | When | `data` carries |\n|-------|------|----------------|\n| `message.received` | A customer sent a message | `message` |\n| `message.queued` | A message you or an agent sent was accepted | `message` |\n| `message.sent` | The channel provider accepted it | `message` |\n| `message.delivered` | Delivered to the customer's device | `message` |\n| `message.read` | The customer read it (where the channel reports it) | `message` |\n| `message.failed` | Could not be delivered; `message.error` says why | `message` |\n| `conversation.created` | A new conversation was opened | `conversation` |\n| `conversation.assigned` | Assigned to an agent or team, or unassigned | `conversation`, `previous_user_id`, `previous_team_id` |\n| `conversation.status_changed` | Resolved, closed, reopened or marked pending | `conversation`, `previous_status` |\n| `contact.created` | A contact was created (any source) | `contact` |\n| `contact.updated` | A contact's details, identities or tags changed | `contact` |\n| `lead.created` | A lead was created | `lead` |\n| `lead.stage_changed` | A lead moved between pipeline stages | `lead`, `from_stage`, `to_stage` |\n\nMessage and conversation events are delivered only for channels the application is allow-listed for. Contact and lead events are workspace-wide.\n\nThe full payload of each event, with its schema, is listed under **Webhooks** in the sidebar.\n\n### 5.3 The delivery\n\n```\nPOST https://your-system.example/hooks/communication-platform\nContent-Type: application/json\nUser-Agent: CommunicationPlatform-Webhooks/1.0\nX-Webhook-ID: 6d2c0a84-… ← the event id; the same on every retry\nX-Webhook-Timestamp: 1789981964 ← unix seconds when this attempt was signed\nX-Webhook-Signature: sha256=… ← HMAC-SHA256, see 5.4\nX-Event-ID / X-Event-Type / X-Event-Timestamp ← the same values under their original names\nX-Delivery-ID / X-Delivery-Attempt ← this attempt, 1-based\n```\n\n```json\n{\n \"id\": \"6d2c0a84-…\",\n \"type\": \"message.delivered\",\n \"created_at\": \"2026-09-17T09:13:02+00:00\",\n \"external_reference\": \"order-58213\",\n \"data\": { \"message\": { … } }\n}\n```\n\nRespond with any **2xx** within 10 seconds. Do the work afterwards - queue it, then acknowledge - rather than making Communication Platform wait for your database.\n\n### 5.4 Verify the signature\n\nEvery delivery is signed so that nobody who learns your URL can feed you fake events. Verify **before** trusting the body:\n\n1. Read `X-Webhook-Timestamp` and the **raw** request body (bytes as received - do not re-serialise).\n2. Compute `HMAC-SHA256( secret, timestamp + \".\" + raw_body )`, hex-encoded.\n3. Compare, in constant time, with the value after `sha256=` in `X-Webhook-Signature`.\n4. Reject the delivery if the timestamp is older than **5 minutes** - that is what makes a captured request useless to replay later.\n\n**Node.js**\n\n```js\nimport crypto from \"node:crypto\";\n\nexport function verifyWebhook(req, rawBody, secret) {\n const timestamp = req.headers[\"x-webhook-timestamp\"];\n const signature = req.headers[\"x-webhook-signature\"] ?? \"\";\n if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;\n\n const expected = \"sha256=\" + crypto.createHmac(\"sha256\", secret).update(`${timestamp}.${rawBody}`).digest(\"hex\");\n return expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));\n}\n```\n\n**PHP**\n\n```php\nfunction verifyWebhook(array $headers, string $rawBody, string $secret): bool\n{\n $timestamp = $headers['X-Webhook-Timestamp'] ?? '';\n $signature = $headers['X-Webhook-Signature'] ?? '';\n if ($timestamp === '' || abs(time() - (int) $timestamp) > 300) {\n return false;\n }\n\n $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);\n\n return hash_equals($expected, $signature);\n}\n```\n\n**Python**\n\n```python\nimport hmac, hashlib, time\n\ndef verify_webhook(headers: dict, raw_body: bytes, secret: str) -> bool:\n timestamp = headers.get(\"X-Webhook-Timestamp\", \"\")\n signature = headers.get(\"X-Webhook-Signature\", \"\")\n if not timestamp or abs(time.time() - int(timestamp)) > 300:\n return False\n expected = \"sha256=\" + hmac.new(secret.encode(), f\"{timestamp}.\".encode() + raw_body, hashlib.sha256).hexdigest()\n return hmac.compare_digest(expected, signature)\n```\n\n### 5.5 Retries, ordering and duplicates\n\n- A non-2xx answer, a timeout or a connection failure is retried on a fixed schedule: **1 min, 5 min, 15 min, 1 h, 6 h, 24 h**, then the delivery is marked failed. Every attempt is signed afresh (new timestamp) but keeps the same `X-Webhook-ID`.\n- An endpoint that fails continuously is **disabled** automatically and the application's owner is notified; re-enable it from the dashboard once fixed. The delivery log there lets you **replay** any delivery by hand, with the same event id.\n- Events are **not guaranteed to arrive in order** - a `message.delivered` can overtake a `message.sent` under retry. Use the timestamps inside `data` (`sent_at`, `delivered_at`, …), not arrival order.\n- Because of retries and replays you **may receive the same event twice**. Treat `X-Webhook-ID` (= body `id`) as a dedupe key: record it, and ignore a repeat.\n\n---\n\n## 6. Security\n\n- **Transport.** Production endpoints - ours and yours - are HTTPS only. Webhook URLs must be `https://`.\n- **Credentials.** API keys and OAuth secrets are shown once and stored hashed; we cannot recover them, only issue new ones. Keep them in a secret store, never in client-side code, mobile apps or repositories. Prefer OAuth access tokens (one hour) for servers you do not fully control. Revoke a key the moment you suspect it leaked - **Settings → Developer**.\n- **Least privilege.** Grant an application only the scopes it uses and only the channels it should touch. A `403` with `required_scope` is the API telling you a scope is missing - fix the grant, do not widen it blindly.\n- **Channel allow-list.** An application can only send on, and only hears about, the channels it is allow-listed for. Two applications sharing a workspace never see each other's traffic.\n- **Idempotency keys** make retries safe and make a replayed request harmless; use them on every mutation.\n- **Webhook signatures.** Always verify (§5.4), always check the timestamp window, always compare in constant time. Rotate the secret if you ever suspect it leaked; the old one stops working immediately.\n- **Your endpoint.** Accept only `POST`, only JSON, and only after verification. Do not put secrets in the URL - the URL appears in logs.\n- **Rate limits and request ids.** Respect `Retry-After`. Log `X-Request-ID` on your side; it is the fastest path to an answer from support.\n- **Data.** Provider credentials (WhatsApp tokens and the like) are never exposed through this API. Message media is served through short-lived signed URLs.\n\n---\n\n## 7. Errors\n\n| HTTP | `code` | Meaning |\n|------|--------|---------|\n| 400 | `unsupported_grant_type`, `invalid_scope` | OAuth request problems |\n| 401 | `unauthenticated`, `invalid_client` | No usable credential |\n| 403 | `forbidden` | Missing scope (`details.required_scope`), a channel not on the allow-list, or a suspended application |\n| 404 | `not_found` | No such resource, or not visible to this application |\n| 409 | `idempotency_conflict` | The same `Idempotency-Key` was used with a different body, or is still being processed |\n| 422 | `validation_failed` | A field is wrong; `details` names each one |\n| 422 | `template_not_approved` | The template is not approved or not sendable on that channel |\n| 422 | `outside_service_window` | Free text to a WhatsApp customer who has not written to you in 24 h - send a template |\n| 422 | `channel_unavailable` | The channel is disconnected or paused |\n| 429 | `rate_limited` | Wait `Retry-After` seconds |\n| 502 | `provider_error` | The channel provider rejected the request; `details` carries what it said |\n| 500 | `internal_error` | Ours; quote `request_id` |\n\n---\n\n## 8. Checklist for going live\n\n1. Application created with the right scopes and channels; the **live** API key stored in your secret manager.\n2. Every `POST` sends an `Idempotency-Key`.\n3. A webhook endpoint registered, its secret stored, **Send test** verified, signature and timestamp checks in place, dedupe on `X-Webhook-ID`.\n4. Your handler answers 2xx in under 10 seconds and does the work afterwards.\n5. Templates you send are `is_sendable: true` in `GET /templates`.\n6. Your events have workflows listening (`workflows_matched > 0`), and those workflows are **published**.\n7. `Retry-After` and `X-Request-ID` are honoured and logged.\n" }, "servers": [ { "url": "http://localhost:8000/api/v1", "description": "Communication Platform" } ], "security": [ { "http": [] } ], "paths": { "/contacts": { "get": { "operationId": "contact.index", "tags": [ "Contact" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "Free text over name, phone, email and company." }, { "name": "lifecycle_stage", "in": "query", "schema": { "type": "string", "enum": [ "lead", "prospect", "customer", "churned" ] }, "description": "`lead`, `prospect`, `customer` or `churned`." }, { "name": "tag", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "A tag name; only contacts carrying it." }, { "name": "channel", "in": "query", "schema": { "type": "string", "maxLength": 40 }, "description": "Only contacts with an identity on this channel, e.g. `whatsapp`." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "ISO-8601 date or datetime." }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "1–100 (default 25)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "1-based page number." } ], "responses": { "200": { "description": "A page of contacts. Identities and tags are not included in the list - fetch one contact for those.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "description": "Follow until null." }, "prev": { "type": [ "string", "null" ] } } } } }, "example": { "data": [ { "id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "first_name": "Rahul", "last_name": "Sharma", "name": "Rahul Sharma", "company": "Sharma Traders", "job_title": null, "email": "rahul@example.com", "phone": "+919876543210", "country": "IN", "city": "Pune", "language": "en", "lifecycle_stage": "customer", "opted_out": false, "marketing_opted_out": false, "identities": [ { "channel": "whatsapp", "handle": "+919876543210", "display_name": "Rahul" }, { "channel": "email", "handle": "rahul@example.com", "display_name": null } ], "tags": [ "store", "repeat-buyer" ], "last_activity_at": "2026-09-17T09:12:43+00:00", "created_at": "2026-08-02T14:20:11+00:00" } ], "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }, "links": { "next": null, "prev": null } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid (`validation_failed`, `details` per field) or the send is not allowed right now (`template_not_approved`, `outside_service_window`, `channel_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List contacts", "description": "**Scope:** `contacts.read`\n\nSearch and filter the business's contacts, paged by number. `search` matches name, phone, email and company. `created_after` is the simplest way to sync new contacts into your system on a schedule." }, "post": { "operationId": "contact.store", "tags": [ "Contact" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ], "maxLength": 100 }, "last_name": { "type": [ "string", "null" ], "maxLength": 100 }, "company": { "type": [ "string", "null" ], "maxLength": 255 }, "job_title": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "country": { "type": [ "string", "null" ], "maxLength": 2 }, "city": { "type": [ "string", "null" ], "maxLength": 100 }, "language": { "type": [ "string", "null" ], "maxLength": 10 }, "timezone": { "type": [ "string", "null" ] }, "lifecycle_stage": { "type": "string", "enum": [ "lead", "prospect", "customer", "churned" ] }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 20 }, "identities": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "whatsapp", "telegram", "instagram", "facebook", "email", "phone" ] }, "handle": { "type": "string", "maxLength": 255 } }, "required": [ "channel", "handle" ] }, "maxItems": 10 }, "custom_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "first_name": "Rahul", "last_name": "Sharma", "company": "Sharma Traders", "email": "rahul@example.com", "phone": "+919876543210", "country": "IN", "language": "en", "lifecycle_stage": "customer", "tags": [ "store", "repeat-buyer" ], "identities": [ { "channel": "whatsapp", "handle": "+919876543210" } ], "custom_fields": { "store_customer_id": "10442" } } } } }, "responses": { "201": { "description": "Created, with identities and tags.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "example": { "data": { "id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "first_name": "Rahul", "last_name": "Sharma", "name": "Rahul Sharma", "company": "Sharma Traders", "job_title": null, "email": "rahul@example.com", "phone": "+919876543210", "country": "IN", "city": "Pune", "language": "en", "lifecycle_stage": "customer", "opted_out": false, "marketing_opted_out": false, "identities": [ { "channel": "whatsapp", "handle": "+919876543210", "display_name": "Rahul" }, { "channel": "email", "handle": "rahul@example.com", "display_name": null } ], "tags": [ "store", "repeat-buyer" ], "last_activity_at": "2026-09-17T09:12:43+00:00", "created_at": "2026-08-02T14:20:11+00:00" } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The `Idempotency-Key` was used with a different body, or its first request is still running (`idempotency_conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid (`validation_failed`, `details` per field) or the send is not allowed right now (`template_not_approved`, `outside_service_window`, `channel_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Create a contact", "description": "**Scope:** `contacts.write` · **Header:** `Idempotency-Key` (required)\n\nCreate a contact with a name, handles, tags and your own custom fields ahead of messaging them. At least one of `email`, `phone` or an `identities` entry is required - a contact nobody can reach is not useful.\n\nIf a handle already belongs to a contact the request answers `422 validation_failed` with the existing contact's id in `details.contact_id`; use that id rather than creating a duplicate. **Idempotency-Key is required**; a retry with the same key returns the same contact.\n\nTags that do not exist yet are created. `custom_fields` keys must match custom fields defined in the dashboard (Settings → CRM).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation, up to 255 characters. A retry with the same key and body returns the original response with `Idempotency-Replayed: true`.", "schema": { "type": "string", "maxLength": 255 }, "example": "order-58213-confirmation" } ] } }, "/contacts/{contact}": { "get": { "operationId": "contact.show", "tags": [ "Contact" ], "parameters": [ { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The contact id." } ], "responses": { "200": { "description": "The contact.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "example": { "data": { "id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "first_name": "Rahul", "last_name": "Sharma", "name": "Rahul Sharma", "company": "Sharma Traders", "job_title": null, "email": "rahul@example.com", "phone": "+919876543210", "country": "IN", "city": "Pune", "language": "en", "lifecycle_stage": "customer", "opted_out": false, "marketing_opted_out": false, "identities": [ { "channel": "whatsapp", "handle": "+919876543210", "display_name": "Rahul" }, { "channel": "email", "handle": "rahul@example.com", "display_name": null } ], "tags": [ "store", "repeat-buyer" ], "last_activity_at": "2026-09-17T09:12:43+00:00", "created_at": "2026-08-02T14:20:11+00:00" } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or one this application may not see (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get a contact", "description": "**Scope:** `contacts.read`\n\nOne contact with their identities and tags." } }, "/conversations": { "get": { "operationId": "conversation.index", "tags": [ "Conversation" ], "parameters": [ { "name": "contact_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Only this contact's threads." }, { "name": "connection_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Only threads on this connection." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "description": "`open`, `pending`, `resolved` or `closed`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "From `links.next` of the previous page." } ], "responses": { "200": { "description": "A page of conversations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "description": "Follow until null." }, "prev": { "type": [ "string", "null" ] } } } } }, "example": { "data": [ { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" } ], "meta": { "per_page": 25, "has_more": false }, "links": { "next": null, "prev": null } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid (`validation_failed`, `details` per field) or the send is not allowed right now (`template_not_approved`, `outside_service_window`, `channel_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List conversations", "description": "**Scope:** `messages.read`\n\nThreads on the application's allow-listed connections, newest activity first, paged by cursor. Filter by contact, connection or status. Follow `links.next` until it is `null`." } }, "/conversations/{conversation}": { "get": { "operationId": "conversation.show", "tags": [ "Conversation" ], "parameters": [ { "name": "conversation", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The conversation id." } ], "responses": { "200": { "description": "The conversation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } }, "example": { "data": { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or one this application may not see (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get a conversation", "description": "**Scope:** `messages.read`\n\nOne thread. `404` when it is on a connection the application is not allow-listed for." } }, "/conversations/{conversation}/messages": { "get": { "operationId": "conversation.messages", "tags": [ "Conversation" ], "parameters": [ { "name": "conversation", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The conversation id." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size, 1–100 (default 50)." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "From `links.next` of the previous page." } ], "responses": { "200": { "description": "A page of messages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "description": "Follow until null." }, "prev": { "type": [ "string", "null" ] } } } } }, "example": { "data": [ { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": "order-58213", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "outbound", "type": "template", "status": "delivered", "body": "Hi Rahul, your order 58213 (₹4,299) is confirmed and will arrive by Thursday.", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": null, "sent_at": "2026-09-17T09:05:11+00:00", "delivered_at": "2026-09-17T09:05:14+00:00", "read_at": null, "received_at": null, "failed_at": null, "created_at": "2026-09-17T09:05:10+00:00" } ], "meta": { "per_page": 25, "has_more": false }, "links": { "next": null, "prev": null } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or one this application may not see (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid (`validation_failed`, `details` per field) or the send is not allowed right now (`template_not_approved`, `outside_service_window`, `channel_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List a conversation's messages", "description": "**Scope:** `messages.read`\n\nThe thread's messages, newest first, paged by cursor. Inbound and outbound alike, with attachments listed by id, type and size." } }, "/events": { "post": { "operationId": "event.store", "tags": [ "Event" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "pattern": "^[a-z0-9_.:-]+$", "maxLength": 100 }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "identity": { "type": "object", "properties": { "channel": { "type": "string", "maxLength": 40 }, "external_id": { "type": "string", "maxLength": 255 } } }, "data": { "type": "array", "items": { "type": "string" } }, "dedupe_key": { "type": "string", "maxLength": 255 } }, "required": [ "event" ] }, "example": { "event": "order.shipped", "identity": { "channel": "whatsapp", "external_id": "+919876543210" }, "dedupe_key": "order-58213-shipped", "data": { "order_id": "58213", "courier": "BlueDart", "tracking_url": "https://track.example/58213", "eta": "Thursday" } } } } }, "responses": { "202": { "description": "Accepted. Workflows run asynchronously; watch Automation → Runs in the dashboard, or the webhooks their actions cause.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "event": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "workflows_matched": { "type": "integer" } }, "required": [ "event", "contact_id", "workflows_matched" ] } }, "required": [ "data" ] }, "example": { "data": { "event": "order.shipped", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "workflows_matched": 1 } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or one this application may not see (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The `Idempotency-Key` was used with a different body, or its first request is still running (`idempotency_conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid (`validation_failed`, `details` per field) or the send is not allowed right now (`template_not_approved`, `outside_service_window`, `channel_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Send an event", "description": "**Scope:** `events.send` · **Header:** `Idempotency-Key` (required)\n\nTell the platform that something happened in your system - `order.paid`, `order.shipped`, `appointment.booked`, `cart.abandoned` - so that **automations** listening for that name can act: message the customer, tag them, open a lead, assign an agent, notify a team, or call a URL of yours.\n\nThe event names the contact by `contact_id` **or** by an identity you already know (`identity.channel` + `identity.external_id`, e.g. a WhatsApp number). Either is optional; without one the event still fires, but a workflow has nobody to message.\n\nEverything under `data` is available to the workflow as `{{data.}}` placeholders. `workflows_matched` in the response says how many published workflows listen for this name - `0` means nothing will happen.\n\n**Idempotency-Key is required**, and a `dedupe_key` (your event id) guards the workflow itself: the same key never starts a second run.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation, up to 255 characters. A retry with the same key and body returns the original response with `Idempotency-Replayed: true`.", "schema": { "type": "string", "maxLength": 255 }, "example": "order-58213-confirmation" } ] } }, "/leads": { "post": { "operationId": "lead.store", "tags": [ "Lead" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 255 }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" }, "value": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "expected_close_date": { "type": [ "string", "null" ], "format": "date-time" }, "source_channel": { "type": [ "string", "null" ], "maxLength": 40 } }, "required": [ "contact_id", "title" ] }, "example": { "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "title": "Bulk order - 40 units", "value": 17196000, "currency": "INR", "expected_close_date": "2026-10-01", "source_channel": "whatsapp" } } } }, "responses": { "201": { "description": "Created, at its stage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Lead" } } }, "example": { "data": { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "title": "Bulk order - 40 units", "value": 17196000, "currency": "INR", "status": "open", "source": "api", "pipeline_id": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d", "stage": { "id": "1b2c3d4e-5f6a-4b7c-8d8e-9f0a1b2c3d4e", "name": "Qualified" }, "expected_close_date": "2026-10-01", "created_at": "2026-09-17T09:20:00+00:00" } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or one this application may not see (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The `Idempotency-Key` was used with a different body, or its first request is still running (`idempotency_conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid (`validation_failed`, `details` per field) or the send is not allowed right now (`template_not_approved`, `outside_service_window`, `channel_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Create a lead", "description": "**Scope:** `leads.create` · **Header:** `Idempotency-Key` (required)\n\nOpen a sales opportunity for a contact. Without `pipeline_id` / `stage_id` it lands in the default pipeline's first stage. `value` is in minor units (paise, cents). **Idempotency-Key is required.** A `lead.created` webhook follows; `lead.stage_changed` reports every later move.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation, up to 255 characters. A retry with the same key and body returns the original response with `Idempotency-Replayed: true`.", "schema": { "type": "string", "maxLength": 255 }, "example": "order-58213-confirmation" } ] } }, "/messages": { "post": { "operationId": "message.store", "tags": [ "Message" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "maxLength": 40 }, "connection_id": { "type": [ "string", "null" ], "format": "uuid" }, "to": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "text", "template", "interactive" ] }, "external_reference": { "type": [ "string", "null" ], "maxLength": 255 }, "message": { "type": "object", "properties": { "body": { "type": [ "string", "null" ], "maxLength": 4096 }, "template": { "type": [ "string", "null" ], "maxLength": 512 }, "language": { "type": [ "string", "null" ], "maxLength": 20 }, "variables": { "type": "array", "items": { "type": "string", "maxLength": 1024 } }, "components": { "type": "array", "items": { "type": "string" } }, "interactive": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "buttons", "list" ] }, "body": { "type": "string", "maxLength": 1024 }, "header": { "type": [ "string", "null" ], "maxLength": 60 }, "footer": { "type": [ "string", "null" ], "maxLength": 60 }, "button_label": { "type": [ "string", "null" ], "maxLength": 20 }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 200 }, "title": { "type": "string", "maxLength": 20 } }, "required": [ "id", "title" ] }, "minItems": 1, "maxItems": 3 }, "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "maxLength": 24 }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 200 }, "title": { "type": "string", "maxLength": 24 }, "description": { "type": [ "string", "null" ], "maxLength": 72 } }, "required": [ "id", "title" ] }, "minItems": 1, "maxItems": 10 } }, "required": [ "rows" ] }, "minItems": 1, "maxItems": 10 } } } } } }, "required": [ "channel", "to", "type", "message" ] }, "example": { "channel": "whatsapp", "to": "+919876543210", "type": "template", "external_reference": "order-58213", "message": { "template": "order_confirmation", "language": "en", "variables": [ "Rahul", "58213", "₹4,299", "Thursday" ] } } } } }, "responses": { "202": { "description": "Queued. The ids let you find the conversation and contact; `status` is always `queued` here.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message_id": { "type": "string" }, "request_id": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "status": { "type": "string", "const": "queued" }, "conversation_id": { "type": "string" }, "contact_id": { "type": "string" }, "connection_id": { "type": "string" } }, "required": [ "message_id", "request_id", "external_reference", "status", "conversation_id", "contact_id", "connection_id" ] } }, "required": [ "data" ] }, "example": { "data": { "message_id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "request_id": "0f1c6f1e-2a3b-4c4d-9e5f-6a7b8c9d0e1f", "external_reference": "order-58213", "status": "queued", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8" } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The `Idempotency-Key` was used with a different body, or its first request is still running (`idempotency_conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid (`validation_failed`, `details` per field) or the send is not allowed right now (`template_not_approved`, `outside_service_window`, `channel_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Send a message", "description": "**Scope:** `messages.send (text)` · `templates.send (template)` · **Header:** `Idempotency-Key` (required)\n\nThe one way to message a customer. Address it by **channel and handle** - `whatsapp` + an E.164 phone number, `email` + an address, `telegram` + a username or chat id - and the platform finds or creates the contact and the conversation, then queues the send. The same code path an agent's reply takes.\n\n**Text or template.** On WhatsApp, free text (`type: \"text\"`) is only allowed within 24 hours of the customer's last message; outside that window you must send an approved template (`type: \"template\"`) - see `GET /templates`. Other channels accept text at any time.\n\n**Which number sends it.** If the application is allow-listed for one connection on that channel it is used; with several, pass `connection_id` to choose. A connection not on the allow-list is refused with `403`.\n\n**Idempotency-Key is required.** A retried request with the same key and body returns the original `202` with `Idempotency-Replayed: true` and sends nothing twice.\n\n**What happens next.** `202` means *queued*. Delivery is reported by webhooks - `message.sent`, `message.delivered`, `message.read` or `message.failed` - each carrying your `external_reference`; or poll `GET /messages/{id}`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation, up to 255 characters. A retry with the same key and body returns the original response with `Idempotency-Replayed: true`.", "schema": { "type": "string", "maxLength": 255 }, "example": "order-58213-confirmation" } ] } }, "/messages/{message}": { "get": { "operationId": "message.show", "tags": [ "Message" ], "parameters": [ { "name": "message", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The message id from `POST /messages` or a webhook." } ], "responses": { "200": { "description": "The message.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Message" } } }, "example": { "data": { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": "order-58213", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "outbound", "type": "template", "status": "delivered", "body": "Hi Rahul, your order 58213 (₹4,299) is confirmed and will arrive by Thursday.", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": null, "sent_at": "2026-09-17T09:05:11+00:00", "delivered_at": "2026-09-17T09:05:14+00:00", "read_at": null, "received_at": null, "failed_at": null, "created_at": "2026-09-17T09:05:10+00:00" } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such resource, or one this application may not see (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get a message", "description": "**Scope:** `messages.read or messages.status`\n\nOne message with its delivery timeline (`sent_at`, `delivered_at`, `read_at`, `failed_at`) and, when it failed, the provider's `error`. Only messages on the application's allow-listed connections are visible; anything else is `404`. Prefer webhooks for status - poll this only to reconcile." } }, "/oauth/token": { "post": { "operationId": "oAuth.token", "tags": [ "OAuth" ], "responses": { "200": { "description": "The token. `Cache-Control: no-store` - do not cache it in a shared cache.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] }, "example": { "access_token": "omni_at_9d2f4c…", "token_type": "Bearer", "expires_in": 3600, "scope": "messages.send messages.read webhooks.receive" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Pragma": { "schema": { "type": "string", "const": "no-cache" } } } }, "400": { "description": "`unsupported_grant_type` or `invalid_scope` (an unknown scope, or one the application was not granted).", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "invalid_scope" }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "unsupported_grant_type" }, "error_description": { "type": "string", "const": "Only the client_credentials grant is supported." } }, "required": [ "error", "error_description" ] } ] }, "example": { "error": "invalid_scope", "error_description": "This application has not been granted [contacts.write]." } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "401": { "description": "`invalid_client` - one message whether the id is unknown, the secret is wrong or the client is revoked.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "invalid_client" }, "error_description": { "type": "string", "const": "This application is suspended." } }, "required": [ "error", "error_description" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "invalid_client" }, "error_description": { "type": "string", "const": "Client authentication failed." } }, "required": [ "error", "error_description" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "invalid_client" }, "error_description": { "type": "string", "const": "client_id and client_secret are required." } }, "required": [ "error", "error_description" ] } ] }, "example": { "error": "invalid_client", "error_description": "Client authentication failed." } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get an access token", "description": "The OAuth 2.0 **client credentials** grant. Send your application's `client_id` and `client_secret` - as JSON, as a form body, or as HTTP Basic auth - and receive a bearer token valid for one hour (`expires_in`).\n\nAsk for fewer scopes than the application holds by passing `scope` as a space-separated list; you cannot ask for more. Cache the token and request a new one shortly before it expires; the endpoint is rate-limited per client and per address.\n\nNot needed if you authenticate with an API key - use the key as the bearer token directly.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "grant_type", "client_id", "client_secret" ] }, "example": { "grant_type": "client_credentials", "client_id": "omni_client_7f3a…", "client_secret": "omni_secret_…", "scope": "messages.send messages.read webhooks.receive" } } } } } }, "/templates": { "get": { "operationId": "template.index", "tags": [ "Template" ], "parameters": [ { "name": "connection_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Only templates on this connection." }, { "name": "language", "in": "query", "schema": { "type": "string", "maxLength": 20 }, "description": "Only this language code." }, { "name": "include_unapproved", "in": "query", "schema": { "type": "boolean" }, "description": "`true` to also list pending, rejected and paused templates." } ], "responses": { "200": { "description": "The templates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "description": "Follow until null." }, "prev": { "type": [ "string", "null" ] } } } } }, "example": { "data": [ { "id": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "name": "order_confirmation", "language": "en", "category": "utility", "status": "approved", "is_sendable": true, "variables": [ "{{1}}", "{{2}}", "{{3}}", "{{4}}" ], "components": [ { "type": "BODY", "text": "Hi {{1}}, your order {{2}} ({{3}}) is confirmed and will arrive by {{4}}." } ] } ], "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }, "links": { "next": null, "prev": null } } } } }, "401": { "description": "Missing, expired or revoked credential (`unauthenticated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential lacks the scope (`forbidden`, `details.required_scope`), the channel is not on the application's allow-list, or the application is suspended (`account_suspended`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid (`validation_failed`, `details` per field) or the send is not allowed right now (`template_not_approved`, `outside_service_window`, `channel_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (`rate_limited`); wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "List templates", "description": "**Scope:** `templates.read or templates.send`\n\nThe templates approved on the application's allow-listed connections, with the placeholders each expects. Send one with `POST /messages` using its `name` and `language`. By default only sendable templates are listed." } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "An API key (`omni_live_...` / `omni_test_...`) or an access token from `POST /oauth/token` (`omni_at_...`), sent as `Authorization: Bearer `. Each operation names the scope it needs.", "scheme": "bearer" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } }, "schemas": { "Contact": { "type": "object", "description": "A person the business talks to. Identities are the handles a message can reach them on.", "properties": { "id": { "type": "string", "format": "uuid" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Display name: the full name, or the best handle when no name is known." }, "company": { "type": [ "string", "null" ] }, "job_title": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ], "description": "E.164, e.g. `+919876543210`." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." }, "city": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ], "description": "BCP 47 tag, e.g. `en`, `hi`." }, "lifecycle_stage": { "type": "string", "enum": [ "lead", "prospect", "customer", "churned" ] }, "opted_out": { "type": "boolean", "description": "True when the contact asked not to be messaged; sends are refused." }, "marketing_opted_out": { "type": "boolean", "description": "True when the contact replied STOP to marketing: campaigns skip them, conversation replies still send." }, "identities": { "type": "array", "description": "Present when the contact was loaded with identities (single-contact responses and webhooks).", "items": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "whatsapp", "telegram", "instagram", "facebook", "email", "phone", "linkedin", "webchat" ] }, "handle": { "type": "string", "description": "The phone number, email address, username or provider id on that channel." }, "display_name": { "type": [ "string", "null" ], "description": "The name the channel reports for the handle, when it does." } } } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names. Present when loaded, as above." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." } }, "example": { "id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "first_name": "Rahul", "last_name": "Sharma", "name": "Rahul Sharma", "company": "Sharma Traders", "job_title": null, "email": "rahul@example.com", "phone": "+919876543210", "country": "IN", "city": "Pune", "language": "en", "lifecycle_stage": "customer", "opted_out": false, "marketing_opted_out": false, "identities": [ { "channel": "whatsapp", "handle": "+919876543210", "display_name": "Rahul" }, { "channel": "email", "handle": "rahul@example.com", "display_name": null } ], "tags": [ "store", "repeat-buyer" ], "last_activity_at": "2026-09-17T09:12:43+00:00", "created_at": "2026-08-02T14:20:11+00:00" } }, "Conversation": { "type": "object", "description": "One thread between the business and a contact on one channel connection. A contact has at most one live thread per connection; a customer writing into a resolved thread reopens it.", "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid", "description": "The channel connection (a WhatsApp number, a mailbox, a bot) the thread is on." }, "channel": { "type": "string", "description": "The channel name, e.g. `whatsapp`, `telegram`, `email`, `webchat`." }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ], "description": "`open`: needs an agent · `pending`: waiting on the customer · `resolved`: done, reopens on a reply · `closed`: final." }, "subject": { "type": [ "string", "null" ], "description": "Email threads carry a subject; other channels do not." }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "last_inbound_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "last_outbound_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." } }, "example": { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" } }, "Message": { "type": "object", "description": "One message in a conversation, in either direction, with its delivery timeline.", "properties": { "id": { "type": "string", "format": "uuid" }, "external_reference": { "type": [ "string", "null" ], "description": "Your own reference, echoed from the send request and on every webhook about this message." }, "conversation_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "`inbound` is from the customer." }, "type": { "type": "string", "enum": [ "text", "template", "image", "video", "audio", "document", "location", "contact", "interactive", "order", "system", "unsupported" ] }, "status": { "type": "string", "enum": [ "scheduled", "queued", "sent", "delivered", "read", "failed" ], "description": "Outbound messages move `queued` → `sent` → `delivered` → `read`, or to `failed`. Inbound messages are `delivered`." }, "body": { "type": [ "string", "null" ], "description": "The text, or the rendered template text. Media messages carry the caption here." }, "interactive_reply": { "type": [ "object", "null" ], "description": "Inbound only: the option the customer tapped on a buttons or list message. `payload_id` is the id your interactive message gave the option; `title` is what they saw, also in `body`.", "properties": { "payload_id": { "type": "string" }, "title": { "type": "string" } } }, "reply_to_message_id": { "type": "string", "format": "uuid", "description": "When the message quotes another." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "document" ] }, "mime_type": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "file_name": { "type": [ "string", "null" ] } } } }, "error": { "type": [ "object", "null" ], "description": "Set when `status` is `failed`.", "properties": { "code": { "type": "string", "description": "The provider's error code, e.g. WhatsApp `131047` (re-engagement required)." }, "message": { "type": [ "string", "null" ] } } }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "read_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "received_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." } }, "example": { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": "order-58213", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "outbound", "type": "template", "status": "delivered", "body": "Hi Rahul, your order 58213 (₹4,299) is confirmed and will arrive by Thursday.", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": null, "sent_at": "2026-09-17T09:05:11+00:00", "delivered_at": "2026-09-17T09:05:14+00:00", "read_at": null, "received_at": null, "failed_at": null, "created_at": "2026-09-17T09:05:10+00:00" } }, "Lead": { "type": "object", "description": "A sales opportunity for a contact, sitting at one stage of a pipeline.", "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "value": { "type": "integer", "description": "In minor units of `currency` (paise, cents)." }, "currency": { "type": "string", "description": "ISO 4217, e.g. `INR`." }, "status": { "type": "string", "enum": [ "open", "won", "lost" ] }, "source": { "type": [ "string", "null" ], "description": "Where the lead came from - `api` for leads you create." }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601, UTC." } }, "example": { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "title": "Bulk order - 40 units", "value": 17196000, "currency": "INR", "status": "open", "source": "api", "pipeline_id": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d", "stage": { "id": "1b2c3d4e-5f6a-4b7c-8d8e-9f0a1b2c3d4e", "name": "Qualified" }, "expected_close_date": "2026-10-01", "created_at": "2026-09-17T09:20:00+00:00" } }, "Template": { "type": "object", "description": "A pre-approved message a channel lets the business send to start a conversation. WhatsApp requires one outside the 24-hour service window.", "properties": { "id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid", "description": "The connection the template is approved on. Send with the same `channel`; the platform picks the connection." }, "name": { "type": "string", "description": "What you pass as `message.template`." }, "language": { "type": "string", "description": "What you pass as `message.language`, e.g. `en`, `en_US`, `hi`." }, "category": { "type": [ "string", "null" ], "enum": [ "marketing", "utility", "authentication", null ] }, "status": { "type": "string", "enum": [ "approved", "pending", "rejected", "paused", "disabled" ] }, "is_sendable": { "type": "boolean", "description": "True only for an approved, active template - the only kind `POST /messages` accepts." }, "variables": { "type": "array", "items": { "type": "string" }, "description": "The placeholders in order - pass one value per entry in `message.variables`." }, "components": { "type": "array", "items": { "type": "object" }, "description": "The provider's component definition (header, body, footer, buttons), for rendering a preview." } }, "example": { "id": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "name": "order_confirmation", "language": "en", "category": "utility", "status": "approved", "is_sendable": true, "variables": [ "{{1}}", "{{2}}", "{{3}}", "{{4}}" ], "components": [ { "type": "BODY", "text": "Hi {{1}}, your order {{2}} ({{3}}) is confirmed and will arrive by {{4}}." } ] } }, "Error": { "type": "object", "description": "Every error, whatever the status code, is this envelope.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable, machine-readable. Branch on this, not on `message`." }, "message": { "type": "string", "description": "For a log or a developer, not for an end user." }, "details": { "type": "object", "additionalProperties": true, "description": "Field errors for `validation_failed`, `required_scope` for `forbidden`, `retry_after` for `rate_limited`, `contact_id` for a duplicate identity." }, "request_id": { "type": "string", "description": "Also sent as the `X-Request-ID` header. Quote it to support." } } } }, "example": { "error": { "code": "validation_failed", "message": "The given data was invalid.", "details": { "to": [ "The to field is required." ] }, "request_id": "0f1c6f1e-2a3b-4c4d-9e5f-6a7b8c9d0e1f" } } }, "WebhookEnvelope": { "type": "object", "description": "What every webhook delivery posts. `data` holds the resource the event is about under its own key, plus any event-specific extras.", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The event id - the same on every retry and replay. Your dedupe key." }, "type": { "type": "string", "description": "The event name, e.g. `message.received`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the event happened (not when this attempt was sent)." }, "external_reference": { "type": "string", "description": "Present on message events for a message sent with one." }, "data": { "type": "object", "additionalProperties": true } } } } }, "tags": [ { "name": "OAuth", "description": "Exchange client credentials for a short-lived access token. Only for applications set up with an OAuth client; API keys skip this." }, { "name": "Message", "description": "Send a message to a customer on any connected channel, and read one back with its delivery timeline." }, { "name": "Conversation", "description": "Threads between the business and its contacts on the channels your application is allow-listed for." }, { "name": "Contact", "description": "The people the business talks to. Create them ahead of a message, or let the first message create them." }, { "name": "Lead", "description": "Sales opportunities in the CRM pipeline." }, { "name": "Template", "description": "Pre-approved messages a channel lets you send to start a conversation." }, { "name": "Event", "description": "Tell the platform something happened in your system so an automation can react." } ], "webhooks": { "message.received": { "post": { "summary": "message.received", "description": "A customer sent a message on one of your allow-listed channels.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.received" }, "data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "message.received", "created_at": "2026-09-17T09:12:44+00:00", "data": { "message": { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": null, "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "inbound", "type": "text", "status": "delivered", "body": "Can I change the delivery address?", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": null, "sent_at": null, "delivered_at": null, "read_at": null, "received_at": "2026-09-17T09:12:43+00:00", "failed_at": null, "created_at": "2026-09-17T09:05:10+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "message.queued": { "post": { "summary": "message.queued", "description": "A message you (or an agent) sent was accepted and queued for delivery.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.queued" }, "data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "message.queued", "created_at": "2026-09-17T09:12:44+00:00", "external_reference": "order-58213", "data": { "message": { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": "order-58213", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "outbound", "type": "template", "status": "queued", "body": "Hi Rahul, your order 58213 (₹4,299) is confirmed and will arrive by Thursday.", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": null, "sent_at": "2026-09-17T09:05:11+00:00", "delivered_at": "2026-09-17T09:05:14+00:00", "read_at": null, "received_at": null, "failed_at": null, "created_at": "2026-09-17T09:05:10+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "message.sent": { "post": { "summary": "message.sent", "description": "The channel provider accepted the message.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.sent" }, "data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "message.sent", "created_at": "2026-09-17T09:12:44+00:00", "external_reference": "order-58213", "data": { "message": { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": "order-58213", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "outbound", "type": "template", "status": "sent", "body": "Hi Rahul, your order 58213 (₹4,299) is confirmed and will arrive by Thursday.", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": null, "sent_at": "2026-09-17T09:05:11+00:00", "delivered_at": "2026-09-17T09:05:14+00:00", "read_at": null, "received_at": null, "failed_at": null, "created_at": "2026-09-17T09:05:10+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "message.delivered": { "post": { "summary": "message.delivered", "description": "The provider confirmed delivery to the customer's device.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.delivered" }, "data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "message.delivered", "created_at": "2026-09-17T09:12:44+00:00", "external_reference": "order-58213", "data": { "message": { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": "order-58213", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "outbound", "type": "template", "status": "delivered", "body": "Hi Rahul, your order 58213 (₹4,299) is confirmed and will arrive by Thursday.", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": null, "sent_at": "2026-09-17T09:05:11+00:00", "delivered_at": "2026-09-17T09:05:14+00:00", "read_at": null, "received_at": null, "failed_at": null, "created_at": "2026-09-17T09:05:10+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "message.read": { "post": { "summary": "message.read", "description": "The customer read the message (where the channel reports it).\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.read" }, "data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "message.read", "created_at": "2026-09-17T09:12:44+00:00", "external_reference": "order-58213", "data": { "message": { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": "order-58213", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "outbound", "type": "template", "status": "read", "body": "Hi Rahul, your order 58213 (₹4,299) is confirmed and will arrive by Thursday.", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": null, "sent_at": "2026-09-17T09:05:11+00:00", "delivered_at": "2026-09-17T09:05:14+00:00", "read_at": null, "received_at": null, "failed_at": null, "created_at": "2026-09-17T09:05:10+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "message.failed": { "post": { "summary": "message.failed", "description": "The provider could not deliver the message; `error` says why.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "message.failed" }, "data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "message.failed", "created_at": "2026-09-17T09:12:44+00:00", "external_reference": "order-58213", "data": { "message": { "id": "3a1d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "external_reference": "order-58213", "conversation_id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "direction": "outbound", "type": "template", "status": "failed", "body": "Hi Rahul, your order 58213 (₹4,299) is confirmed and will arrive by Thursday.", "interactive_reply": null, "reply_to_message_id": null, "attachments": [], "error": { "code": "131047", "message": "Re-engagement message: more than 24 hours since the customer last replied. Send a template." }, "sent_at": "2026-09-17T09:05:11+00:00", "delivered_at": null, "read_at": null, "received_at": null, "failed_at": "2026-09-17T09:05:12+00:00", "created_at": "2026-09-17T09:05:10+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "conversation.created": { "post": { "summary": "conversation.created", "description": "A new conversation was opened with a contact on an allow-listed channel.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "conversation.created" }, "data": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "conversation.created", "created_at": "2026-09-17T09:12:44+00:00", "data": { "conversation": { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "conversation.assigned": { "post": { "summary": "conversation.assigned", "description": "A conversation was assigned to an agent or a team, or unassigned.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "conversation.assigned" }, "data": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" }, "previous_user_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The agent it was assigned to before, or null." }, "previous_team_id": { "type": [ "string", "null" ], "description": "The team it was assigned to before, or null." } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "conversation.assigned", "created_at": "2026-09-17T09:12:44+00:00", "data": { "conversation": { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" }, "previous_user_id": null, "previous_team_id": null } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "conversation.status_changed": { "post": { "summary": "conversation.status_changed", "description": "A conversation was resolved, closed, reopened or marked pending.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "conversation.status_changed" }, "data": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" }, "previous_status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "conversation.status_changed", "created_at": "2026-09-17T09:12:44+00:00", "data": { "conversation": { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" }, "previous_status": "open" } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "contact.created": { "post": { "summary": "contact.created", "description": "A contact was created - by an inbound message, an agent, an import or the API.\n\nDelivered to every subscribed endpoint of the workspace.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "contact.created" }, "data": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "contact.created", "created_at": "2026-09-17T09:12:44+00:00", "data": { "contact": { "id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "first_name": "Rahul", "last_name": "Sharma", "name": "Rahul Sharma", "company": "Sharma Traders", "job_title": null, "email": "rahul@example.com", "phone": "+919876543210", "country": "IN", "city": "Pune", "language": "en", "lifecycle_stage": "customer", "opted_out": false, "marketing_opted_out": false, "identities": [ { "channel": "whatsapp", "handle": "+919876543210", "display_name": "Rahul" }, { "channel": "email", "handle": "rahul@example.com", "display_name": null } ], "tags": [ "store", "repeat-buyer" ], "last_activity_at": "2026-09-17T09:12:43+00:00", "created_at": "2026-08-02T14:20:11+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "contact.updated": { "post": { "summary": "contact.updated", "description": "A contact's details, identities or tags changed.\n\nDelivered to every subscribed endpoint of the workspace.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "contact.updated" }, "data": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "contact.updated", "created_at": "2026-09-17T09:12:44+00:00", "data": { "contact": { "id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "first_name": "Rahul", "last_name": "Sharma", "name": "Rahul Sharma", "company": "Sharma Traders", "job_title": null, "email": "rahul@example.com", "phone": "+919876543210", "country": "IN", "city": "Pune", "language": "en", "lifecycle_stage": "customer", "opted_out": false, "marketing_opted_out": false, "identities": [ { "channel": "whatsapp", "handle": "+919876543210", "display_name": "Rahul" }, { "channel": "email", "handle": "rahul@example.com", "display_name": null } ], "tags": [ "store", "repeat-buyer" ], "last_activity_at": "2026-09-17T09:12:43+00:00", "created_at": "2026-08-02T14:20:11+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "lead.created": { "post": { "summary": "lead.created", "description": "A lead was created for a contact.\n\nDelivered to every subscribed endpoint of the workspace.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "lead.created" }, "data": { "type": "object", "properties": { "lead": { "$ref": "#/components/schemas/Lead" } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "lead.created", "created_at": "2026-09-17T09:12:44+00:00", "data": { "lead": { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "title": "Bulk order - 40 units", "value": 17196000, "currency": "INR", "status": "open", "source": "api", "pipeline_id": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d", "stage": { "id": "1b2c3d4e-5f6a-4b7c-8d8e-9f0a1b2c3d4e", "name": "Qualified" }, "expected_close_date": "2026-10-01", "created_at": "2026-09-17T09:20:00+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "lead.stage_changed": { "post": { "summary": "lead.stage_changed", "description": "A lead moved to another pipeline stage.\n\nDelivered to every subscribed endpoint of the workspace.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "lead.stage_changed" }, "data": { "type": "object", "properties": { "lead": { "$ref": "#/components/schemas/Lead" }, "from_stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "to_stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "lead.stage_changed", "created_at": "2026-09-17T09:12:44+00:00", "data": { "lead": { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "title": "Bulk order - 40 units", "value": 17196000, "currency": "INR", "status": "open", "source": "api", "pipeline_id": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d", "stage": { "id": "1b2c3d4e-5f6a-4b7c-8d8e-9f0a1b2c3d4e", "name": "Qualified" }, "expected_close_date": "2026-10-01", "created_at": "2026-09-17T09:20:00+00:00" }, "from_stage": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3e", "name": "New" }, "to_stage": { "id": "1b2c3d4e-5f6a-4b7c-8d8e-9f0a1b2c3d4e", "name": "Qualified" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "bot.started": { "post": { "summary": "bot.started", "description": "A chatbot started talking to a customer on a conversation.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "bot.started" }, "data": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" }, "bot": { "type": "object", "description": "The bot session: its run and workflow, `outcome` (completed, handed_off, timed_out, abandoned, failed - null while it runs), `cancel_reason` when an agent stopped it, and every answer it collected.", "properties": { "run_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "workflow_name": { "type": "string" }, "status": { "type": "string" }, "outcome": { "type": [ "string", "null" ], "enum": [ "completed", "handed_off", "timed_out", "abandoned", "failed", null ] }, "cancel_reason": { "type": [ "string", "null" ] }, "turns": { "type": "integer" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] } } } }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "bot.started", "created_at": "2026-09-17T09:12:44+00:00", "data": { "conversation": { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" }, "bot": { "run_id": "2c1d0e9f-8a7b-4c6d-9e5f-0a1b2c3d4e5f", "workflow_id": "3d2e1f0a-9b8c-4d7e-8f6a-1b2c3d4e5f6a", "workflow_name": "Support menu", "status": "completed", "outcome": "handed_off", "cancel_reason": null, "turns": 2, "answers": [ { "node": "topic", "question": "How can we help?", "answer": "Billing" }, { "node": "email", "question": "Your email?", "answer": "rahul@example.com" } ], "started_at": "2026-09-17T09:10:02+00:00", "finished_at": "2026-09-17T09:12:40+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "bot.handoff": { "post": { "summary": "bot.handoff", "description": "A chatbot handed a conversation to a person; `bot.answers` is what it learned.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "bot.handoff" }, "data": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" }, "bot": { "type": "object", "description": "The bot session: its run and workflow, `outcome` (completed, handed_off, timed_out, abandoned, failed - null while it runs), `cancel_reason` when an agent stopped it, and every answer it collected.", "properties": { "run_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "workflow_name": { "type": "string" }, "status": { "type": "string" }, "outcome": { "type": [ "string", "null" ], "enum": [ "completed", "handed_off", "timed_out", "abandoned", "failed", null ] }, "cancel_reason": { "type": [ "string", "null" ] }, "turns": { "type": "integer" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] } } } }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "bot.handoff", "created_at": "2026-09-17T09:12:44+00:00", "data": { "conversation": { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" }, "bot": { "run_id": "2c1d0e9f-8a7b-4c6d-9e5f-0a1b2c3d4e5f", "workflow_id": "3d2e1f0a-9b8c-4d7e-8f6a-1b2c3d4e5f6a", "workflow_name": "Support menu", "status": "completed", "outcome": "handed_off", "cancel_reason": null, "turns": 2, "answers": [ { "node": "topic", "question": "How can we help?", "answer": "Billing" }, { "node": "email", "question": "Your email?", "answer": "rahul@example.com" } ], "started_at": "2026-09-17T09:10:02+00:00", "finished_at": "2026-09-17T09:12:40+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } }, "bot.completed": { "post": { "summary": "bot.completed", "description": "A chatbot session ended without a handoff - finished, timed out, stopped by an agent or failed; `bot.outcome` says which.\n\nDelivered only when the application is allow-listed for the connection the event happened on.\n\nVerify `X-Webhook-Signature` before trusting the body and answer 2xx within 10 seconds - see *Webhooks* in the overview.", "security": [], "parameters": [ { "name": "X-Webhook-ID", "in": "header", "required": true, "description": "The event id; identical on every retry and replay. Your dedupe key.", "schema": { "type": "string" }, "example": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e" }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed. Reject deliveries older than 5 minutes.", "schema": { "type": "string" }, "example": "1789981964" }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "description": "`sha256=` + hex HMAC-SHA256 of `timestamp + \".\" + raw body` with the endpoint's signing secret.", "schema": { "type": "string" }, "example": "sha256=5f1a…" }, { "name": "X-Event-Type", "in": "header", "required": true, "description": "The event name, also in the body as `type`.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Delivery-Attempt", "in": "header", "required": true, "description": "1 on the first attempt, then 2… on each retry.", "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "bot.completed" }, "data": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" }, "bot": { "type": "object", "description": "The bot session: its run and workflow, `outcome` (completed, handed_off, timed_out, abandoned, failed - null while it runs), `cancel_reason` when an agent stopped it, and every answer it collected.", "properties": { "run_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "workflow_name": { "type": "string" }, "status": { "type": "string" }, "outcome": { "type": [ "string", "null" ], "enum": [ "completed", "handed_off", "timed_out", "abandoned", "failed", null ] }, "cancel_reason": { "type": [ "string", "null" ] }, "turns": { "type": "integer" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "string" }, "question": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] } } } }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } ] }, "example": { "id": "6d2c0a84-1f2e-4b3c-9d4e-5f6a7b8c9d0e", "type": "bot.completed", "created_at": "2026-09-17T09:12:44+00:00", "data": { "conversation": { "id": "9c0e1f2a-3b4c-4d5e-8f60-718293a4b5c6", "contact_id": "b7f2c3a4-5d6e-4f70-8a91-b2c3d4e5f607", "connection_id": "e51a2b3c-4d5e-4f60-8172-8394a5b6c7d8", "channel": "whatsapp", "status": "open", "subject": null, "last_message_at": "2026-09-17T09:12:43+00:00", "last_inbound_at": "2026-09-17T09:12:43+00:00", "last_outbound_at": "2026-09-17T09:05:10+00:00", "resolved_at": null, "closed_at": null, "created_at": "2026-09-17T09:05:08+00:00" }, "bot": { "run_id": "2c1d0e9f-8a7b-4c6d-9e5f-0a1b2c3d4e5f", "workflow_id": "3d2e1f0a-9b8c-4d7e-8f6a-1b2c3d4e5f6a", "workflow_name": "Support menu", "status": "completed", "outcome": "handed_off", "cancel_reason": null, "turns": 2, "answers": [ { "node": "topic", "question": "How can we help?", "answer": "Billing" }, { "node": "email", "question": "Your email?", "answer": "rahul@example.com" } ], "started_at": "2026-09-17T09:10:02+00:00", "finished_at": "2026-09-17T09:12:40+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else, or no answer within 10 seconds, is retried on the schedule 1m · 5m · 15m · 1h · 6h · 24h with the same `id`." } } } } } }