{"openapi":"3.0.3","info":{"title":"WhatsApp Platform API","version":"1.0.0","description":"Customer-facing REST API for the WhatsApp platform.\n\n**Authentication** — pass your API key as a bearer token:\n`Authorization: Bearer sk_live_...`. Create and manage keys from the\ndashboard. Each key is scoped; a call missing the required scope returns\n`403 INSUFFICIENT_SCOPE`.\n\n**Rate limits** — 120 requests/minute per key. Responses carry\n`X-RateLimit-Remaining`; `429` includes `Retry-After`.\n\n**Webhooks** — register endpoints to receive events. Every delivery carries\n[Standard Webhooks](https://www.standardwebhooks.com) headers: `webhook-id`,\n`webhook-timestamp` and `webhook-signature`. The signature holds\n`v1,<base64 HMAC-SHA256>` keyed with the endpoint's `signing_secret`, and\n`v1a,<base64 Ed25519>`, verifiable with its `public_key`. Both are computed over\n`\"<id>.<timestamp>.<rawBody>\"`, so any Standard Webhooks library verifies v1 as-is.\nThe older `X-Webhook-Signature: t=<unix>,v1=<hex>` over `\"<t>.<rawBody>\"` is still\nsent. Reject timestamps older than 5 minutes.\n\nAn endpoint can also send your own credentials, set with `auth`:\n- `bearer` (`token`)\n- `basic` (`username`, `password`)\n- `api_key` (`headerName`, `value`)\n- `oauth2` client credentials (`tokenUrl`, `clientId`, `clientSecret`, optional\n  `scope` / `audience`, and `clientAuth`: `basic` | `body`)\n\nYou can add up to 10 static `headers` (`[{ name, value }]`). Secrets are write-only:\nresponses show only a `••••abcd` hint, and leaving a secret out on update keeps the\nstored one. When credentials are set, redirects are not followed."},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Your API key, e.g. `sk_live_...`"}},"schemas":{}},"paths":{"/v1/messages":{"post":{"tags":["Messages"],"description":"**Required scope:** `conversations:write` (text and media), or `messagetemplate:write` when `type` is `template`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","type"],"additionalProperties":false,"properties":{"to":{"type":"string","minLength":5,"maxLength":30},"from":{"type":"string","maxLength":64},"type":{"type":"string","enum":["text","template","media"]},"callbackData":{"type":"string","minLength":1,"maxLength":512},"text":{"type":"string","minLength":1,"maxLength":4096},"media":{"type":"object","required":["kind","link"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["image","video","audio","document","sticker"]},"link":{"type":"string","minLength":1,"maxLength":2000},"filename":{"type":"string","maxLength":255},"caption":{"type":"string","maxLength":4096}}},"template":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":512},"language":{"type":"string","minLength":2,"maxLength":16},"parameters":{"type":"array","items":{"type":"string","maxLength":5000},"maxItems":50},"code":{"type":"string","maxLength":15,"description":"AUTHENTICATION templates only: the OTP code. Fills the body {{1}} and the copy-code / one-tap button. Do not also send parameters."},"headerText":{"type":"string","maxLength":5000},"headerMedia":{"type":"object","additionalProperties":false,"properties":{"link":{"type":"string","maxLength":2000},"id":{"type":"string","maxLength":128},"filename":{"type":"string","maxLength":255}}},"headerLocation":{"type":"object","additionalProperties":false,"required":["latitude","longitude","name","address"],"properties":{"latitude":{"type":"string","maxLength":32},"longitude":{"type":"string","maxLength":32},"name":{"type":"string","maxLength":512},"address":{"type":"string","maxLength":1024}}},"couponCode":{"type":"string","maxLength":15},"urlParams":{"type":"array","items":{"type":"string","maxLength":2000},"maxItems":10,"description":"Values for dynamic URL buttons, in button order: the text that replaces {{1}} at the end of each button url (only the suffix, not the full url)."},"ltoExpirationMs":{"type":"integer"},"cards":{"type":"array","maxItems":10},"catalogId":{"type":"string","maxLength":128},"catalogThumbnailProductId":{"type":"string","maxLength":128},"mpm":{"type":"object","additionalProperties":false,"required":["sections"],"properties":{"thumbnailProductId":{"type":"string","maxLength":128},"sections":{"type":"array","maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["title","productRetailerIds"],"properties":{"title":{"type":"string","maxLength":24},"productRetailerIds":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":128}}}}}}}}}}}}}},"x-required-scope":"conversations:write (text and media), or messagetemplate:write when type is template","responses":{"200":{"description":"Default Response"}}}},"/v1/media":{"post":{"tags":["Media"],"description":"**Required scope:** `conversations:write`","x-required-scope":"conversations:write","responses":{"200":{"description":"Default Response"}}}},"/v1/contacts":{"get":{"tags":["Contacts"],"description":"**Required scope:** `contacts:read`","parameters":[{"schema":{"type":"string","maxLength":255},"in":"query","name":"search","required":false},{"schema":{"type":"string","maxLength":1000},"in":"query","name":"tags","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"segmentId","required":false},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false}],"x-required-scope":"contacts:read","responses":{"200":{"description":"Default Response"}}},"post":{"tags":["Contacts"],"description":"**Required scope:** `contacts:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":["string","null"],"maxLength":255},"email":{"type":["string","null"],"maxLength":255},"phone":{"type":["string","null"],"maxLength":30},"bsuid":{"type":["string","null"],"maxLength":255},"customFields":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":5000},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}}}}},"x-required-scope":"contacts:write","responses":{"200":{"description":"Default Response"}}}},"/v1/contacts/{id}":{"get":{"tags":["Contacts"],"description":"**Required scope:** `contacts:read`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"contacts:read","responses":{"200":{"description":"Default Response"}}},"patch":{"tags":["Contacts"],"description":"**Required scope:** `contacts:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":["string","null"],"maxLength":255},"email":{"type":["string","null"],"maxLength":255},"phone":{"type":["string","null"],"maxLength":30},"bsuid":{"type":["string","null"],"maxLength":255},"customFields":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":5000},{"type":"number"},{"type":"boolean"},{"type":"null"}]}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"contacts:write","responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Contacts"],"description":"**Required scope:** `contacts:write`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"contacts:write","responses":{"200":{"description":"Default Response"}}}},"/v1/tags":{"get":{"tags":["Tags"],"description":"**Required scope:** `contacts:read`","x-required-scope":"contacts:read","responses":{"200":{"description":"Default Response"}}},"post":{"tags":["Tags"],"description":"**Required scope:** `contacts:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":64}}}}}},"x-required-scope":"contacts:write","responses":{"200":{"description":"Default Response"}}}},"/v1/contacts/{id}/tags":{"post":{"tags":["Contacts"],"description":"**Required scope:** `contacts:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"add":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50},"remove":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"contacts:write","responses":{"200":{"description":"Default Response"}}}},"/v1/templates":{"get":{"tags":["Templates"],"description":"**Required scope:** `messagetemplate:read`","x-required-scope":"messagetemplate:read","responses":{"200":{"description":"Default Response"}}},"post":{"tags":["Templates"],"description":"**Required scope:** `messagetemplate:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","category","components"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":512},"category":{"type":"string","minLength":1,"maxLength":40},"language":{"type":"string","minLength":2,"maxLength":16},"components":{"type":"array","minItems":1,"maxItems":20}}}}}},"x-required-scope":"messagetemplate:write","responses":{"200":{"description":"Default Response"}}}},"/v1/templates/{id}/submit":{"post":{"tags":["Templates"],"description":"**Required scope:** `messagetemplate:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"numberId":{"type":"string","format":"uuid"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"messagetemplate:write","responses":{"200":{"description":"Default Response"}}}},"/v1/templates/{id}":{"delete":{"tags":["Templates"],"description":"**Required scope:** `messagetemplate:write`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"messagetemplate:write","responses":{"200":{"description":"Default Response"}}}},"/v1/whatsapp-accounts":{"get":{"tags":["WhatsApp Accounts"],"description":"**Required scope:** `whatsappaccounts:read`","x-required-scope":"whatsappaccounts:read","responses":{"200":{"description":"Default Response"}}}},"/v1/pipelines":{"get":{"tags":["Deals"],"description":"**Required scope:** `deals:read`","x-required-scope":"deals:read","responses":{"200":{"description":"Default Response"}}}},"/v1/deals":{"get":{"tags":["Deals"],"description":"**Required scope:** `deals:read`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"pipelineId","required":false}],"x-required-scope":"deals:read","responses":{"200":{"description":"Default Response"}}},"post":{"tags":["Deals"],"description":"**Required scope:** `deals:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contactId","title"],"additionalProperties":false,"properties":{"contactId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":255},"pipelineId":{"type":"string","format":"uuid"},"stageId":{"type":"string","format":"uuid"},"valueMinor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"ownerUserId":{"type":["string","null"],"format":"uuid"},"notes":{"type":["string","null"],"maxLength":5000}}}}}},"x-required-scope":"deals:write","responses":{"200":{"description":"Default Response"}}}},"/v1/deals/{id}":{"patch":{"tags":["Deals"],"description":"**Required scope:** `deals:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"title":{"type":"string","minLength":1,"maxLength":255},"valueMinor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"ownerUserId":{"type":["string","null"],"format":"uuid"},"notes":{"type":["string","null"],"maxLength":5000}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"deals:write","responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Deals"],"description":"**Required scope:** `deals:write`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"deals:write","responses":{"200":{"description":"Default Response"}}}},"/v1/deals/{id}/move":{"post":{"tags":["Deals"],"description":"**Required scope:** `deals:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stageId"],"additionalProperties":false,"properties":{"stageId":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":0,"default":0}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"deals:write","responses":{"200":{"description":"Default Response"}}}},"/v1/broadcasts":{"get":{"tags":["Broadcasts"],"description":"**Required scope:** `broadcasts:read`","x-required-scope":"broadcasts:read","responses":{"200":{"description":"Default Response"}}},"post":{"tags":["Broadcasts"],"description":"**Required scope:** `broadcasts:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","numberId","templateId","variableMap"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"numberId":{"type":"string","format":"uuid"},"templateId":{"type":"string","format":"uuid"},"segmentId":{"type":["string","null"],"format":"uuid"},"contactIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100000},"variableMap":{"type":"object","additionalProperties":{"type":"string","maxLength":5000}},"templateParams":{"type":"object"},"scheduledAt":{"type":["string","null"],"maxLength":40},"sendNow":{"type":"boolean"}}}}}},"x-required-scope":"broadcasts:write","responses":{"200":{"description":"Default Response"}}}},"/v1/broadcasts/{id}":{"get":{"tags":["Broadcasts"],"description":"**Required scope:** `broadcasts:read`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"broadcasts:read","responses":{"200":{"description":"Default Response"}}}},"/v1/broadcasts/{id}/cancel":{"post":{"tags":["Broadcasts"],"description":"**Required scope:** `broadcasts:write`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"broadcasts:write","responses":{"200":{"description":"Default Response"}}}},"/v1/sequences":{"get":{"tags":["Sequences"],"description":"**Required scope:** `sequences:read`","x-required-scope":"sequences:read","responses":{"200":{"description":"Default Response"}}}},"/v1/sequences/{id}/enroll":{"post":{"tags":["Sequences"],"description":"**Required scope:** `sequences:write`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"contactIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100000},"segmentId":{"type":["string","null"],"format":"uuid"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"sequences:write","responses":{"200":{"description":"Default Response"}}}},"/v1/conversations":{"get":{"tags":["Conversations"],"description":"**Required scope:** `conversations:read`","parameters":[{"schema":{"type":"string","enum":["all","open","pending","resolved"],"default":"all"},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["all","whatsapp","instagram","facebook"],"default":"all"},"in":"query","name":"channel","required":false},{"schema":{"type":"string","maxLength":255},"in":"query","name":"search","required":false},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false}],"x-required-scope":"conversations:read","responses":{"200":{"description":"Default Response"}}}},"/v1/conversations/{id}":{"get":{"tags":["Conversations"],"description":"**Required scope:** `conversations:read`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"conversations:read","responses":{"200":{"description":"Default Response"}}}},"/v1/conversations/{id}/messages":{"get":{"tags":["Conversations"],"description":"**Required scope:** `conversations:read`","parameters":[{"schema":{"type":"string","maxLength":255},"in":"query","name":"search","required":false},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"conversations:read","responses":{"200":{"description":"Default Response"}}}},"/v1/messages/{id}":{"get":{"tags":["Messages"],"description":"**Required scope:** `conversations:read`","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256},"in":"path","name":"id","required":true}],"x-required-scope":"conversations:read","responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/events":{"get":{"tags":["Webhooks"],"description":"**Required scope:** `webhooks:manage`","x-required-scope":"webhooks:manage","responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"description":"**Required scope:** `webhooks:manage`","x-required-scope":"webhooks:manage","responses":{"200":{"description":"Default Response"}}},"post":{"tags":["Webhooks"],"description":"**Required scope:** `webhooks:manage`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","minLength":8,"maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.received.new_contact","message.replied","button.clicked","flow.response","session.message.sent","template.message.sent","message.delivered","message.read","message.failed","contact.created","contact.updated","contact.deleted","call.received","call.completed","call.missed","call.failed","deal.created","deal.updated","deal.stage_changed","deal.won","deal.lost","deal.deleted","broadcast.created","broadcast.completed","sequence.enrolled","sequence.completed","order.created","order.status_updated","order.paid","order.payment_failed","lead.customer.message","lead.agent.message"]},"maxItems":50},"description":{"type":["string","null"],"maxLength":255},"payloadFormat":{"type":"string","enum":["native","crm_flat","chatdesq_lead"]},"auth":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["none","bearer","basic","api_key","oauth2"]},"token":{"type":"string","maxLength":4096},"username":{"type":"string","maxLength":256},"password":{"type":"string","maxLength":1024},"headerName":{"type":"string","maxLength":64},"value":{"type":"string","maxLength":4096},"tokenUrl":{"type":"string","maxLength":2048},"clientId":{"type":"string","maxLength":512},"clientSecret":{"type":"string","maxLength":2048},"scope":{"type":["string","null"],"maxLength":1024},"audience":{"type":["string","null"],"maxLength":1024},"clientAuth":{"type":"string","enum":["basic","body"]}}},"headers":{"type":"array","maxItems":10,"items":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":64},"value":{"type":"string","maxLength":4096}}}}}}}}},"x-required-scope":"webhooks:manage","responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/{id}":{"get":{"tags":["Webhooks"],"description":"**Required scope:** `webhooks:manage`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"webhooks:manage","responses":{"200":{"description":"Default Response"}}},"patch":{"tags":["Webhooks"],"description":"**Required scope:** `webhooks:manage`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"url":{"type":"string","minLength":8,"maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.received.new_contact","message.replied","button.clicked","flow.response","session.message.sent","template.message.sent","message.delivered","message.read","message.failed","contact.created","contact.updated","contact.deleted","call.received","call.completed","call.missed","call.failed","deal.created","deal.updated","deal.stage_changed","deal.won","deal.lost","deal.deleted","broadcast.created","broadcast.completed","sequence.enrolled","sequence.completed","order.created","order.status_updated","order.paid","order.payment_failed","lead.customer.message","lead.agent.message"]},"maxItems":50},"description":{"type":["string","null"],"maxLength":255},"isActive":{"type":"boolean"},"payloadFormat":{"type":"string","enum":["native","crm_flat","chatdesq_lead"]},"auth":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["none","bearer","basic","api_key","oauth2"]},"token":{"type":"string","maxLength":4096},"username":{"type":"string","maxLength":256},"password":{"type":"string","maxLength":1024},"headerName":{"type":"string","maxLength":64},"value":{"type":"string","maxLength":4096},"tokenUrl":{"type":"string","maxLength":2048},"clientId":{"type":"string","maxLength":512},"clientSecret":{"type":"string","maxLength":2048},"scope":{"type":["string","null"],"maxLength":1024},"audience":{"type":["string","null"],"maxLength":1024},"clientAuth":{"type":"string","enum":["basic","body"]}}},"headers":{"type":"array","maxItems":10,"items":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":64},"value":{"type":"string","maxLength":4096}}}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"webhooks:manage","responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Webhooks"],"description":"**Required scope:** `webhooks:manage`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"webhooks:manage","responses":{"200":{"description":"Default Response"}}}},"/v1/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"description":"**Required scope:** `webhooks:manage`","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"x-required-scope":"webhooks:manage","responses":{"200":{"description":"Default Response"}}}},"/v1/token/rotate":{"post":{"tags":["Token"],"description":"**Required scope:** `auth:rotatetoken`","x-required-scope":"auth:rotatetoken","responses":{"200":{"description":"Default Response"}}}}},"security":[{"apiKey":[]}]}