{"openapi":"3.1.0","info":{"title":"Edwyz WA API","version":"3.0.0","summary":"Contacts, conversations, session and template messages, broadcasts and webhooks for a WhatsApp Business workspace.","description":"Authenticate with an API key from Settings, API: Authorization: Bearer wak_... . Limits: 30 requests per 10 seconds per key, lists of 20 by default and 100 at most. Free-form messages need an open 24-hour window; marketing templates need the recipient's opt-in."},"servers":[{"url":"https://wa.edwyz.com/api/ext/v3"}],"tags":[{"name":"Contacts"},{"name":"Conversations"},{"name":"Templates"},{"name":"Broadcasts"},{"name":"Webhooks"},{"name":"Webhook events"}],"security":[{"bearerAuth":[]}],"paths":{"/contacts":{"get":{"operationId":"contacts.list","tags":["Contacts"],"summary":"List contacts, newest first.","description":"Needs an API key holding one of these scopes: contacts:read, contacts:write.","security":[{"bearerAuth":["contacts:read"]},{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:read","contacts:write"],"parameters":[{"name":"page_number","in":"query","required":false,"description":"1-based page. Default 1. page_number x page_size must not exceed 10,000 (400 beyond that).","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}},{"name":"tag","in":"query","required":false,"description":"Only contacts carrying this tag.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Matches name or phone number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok","contact_list","page_number","page_size","total","has_more"],"properties":{"ok":{"const":true},"contact_list":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"window_exhausted":{"type":"boolean","description":"True when more rows exist beyond the 10,000-row paging window. Narrow the list with filters."}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}},"post":{"operationId":"contacts.create","tags":["Contacts"],"summary":"Create a contact. Answers 409 when the phone number or external id already exists.","description":"Needs an API key holding the contacts:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:write"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"Digits with country code; a leading + is optional."},"name":{"type":"string","description":"Display name, up to 200 characters."},"external_id":{"type":"string","description":"Your own identifier, stored as an attribute and usable as external_id:<value> in paths."},"tags":{"type":"array","items":{"type":"string"},"description":"Up to 50 tags."},"custom_params":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"value":{"type":["string","number","boolean","null"]}}},"description":"Contact attributes. A null value removes the attribute on update."},"opt_in":{"type":"boolean","description":"Set true only if the person agreed to receive messages."},"opt_in_source":{"type":"string","description":"Where the consent was collected. Required when opt_in is true."}},"required":["phone_number"]}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"409":{"$ref":"#/components/responses/Error409"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/contacts/count":{"get":{"operationId":"contacts.count","tags":["Contacts"],"summary":"Count contacts, optionally only those with a tag or matching a search.","description":"Needs an API key holding one of these scopes: contacts:read, contacts:write.","security":[{"bearerAuth":["contacts:read"]},{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:read","contacts:write"],"parameters":[{"name":"tag","in":"query","required":false,"description":"Only contacts carrying this tag.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Matches name or phone number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"count":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/contacts/{target}":{"get":{"operationId":"contacts.get","tags":["Contacts"],"summary":"Get one contact by phone number, contact id, external_id:<value> or bsuid:<value>.","description":"Needs an API key holding one of these scopes: contacts:read, contacts:write.","security":[{"bearerAuth":["contacts:read"]},{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:read","contacts:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}},"put":{"operationId":"contacts.update","tags":["Contacts"],"summary":"Change name, tags or attributes. Attributes are merged, tags are replaced when sent.","description":"Needs an API key holding the contacts:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New display name."},"tags":{"type":"array","items":{"type":"string"},"description":"Replaces the full tag list."},"custom_params":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"value":{"type":["string","number","boolean","null"]}}},"description":"Contact attributes. A null value removes the attribute on update."}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}},"delete":{"operationId":"contacts.delete","tags":["Contacts"],"summary":"Delete a contact together with its conversations and messages. This cannot be undone.","description":"Needs an API key holding the contacts:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/contacts/{target}/tags":{"post":{"operationId":"contacts.addTags","tags":["Contacts"],"summary":"Add tags to a contact, keeping the ones it already has.","description":"Needs an API key holding the contacts:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Tags to add."}},"required":["tags"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/contacts/{target}/tags/{tag}":{"delete":{"operationId":"contacts.removeTag","tags":["Contacts"],"summary":"Remove one tag from a contact. Removing a tag the contact lacks succeeds.","description":"Needs an API key holding the contacts:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}},{"name":"tag","in":"path","required":true,"description":"The tag.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/contacts/{target}/attributes":{"put":{"operationId":"contacts.updateAttributes","tags":["Contacts"],"summary":"Merge attributes into a contact without touching name or tags.","description":"Needs an API key holding the contacts:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["contacts:write"]}],"x-accepted-scopes":["contacts:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_params":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"value":{"type":["string","number","boolean","null"]}}},"description":"Contact attributes. A null value removes the attribute on update."}},"required":["custom_params"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/conversations":{"get":{"operationId":"conversations.list","tags":["Conversations"],"summary":"List conversations, most recently active first.","description":"Needs an API key holding one of these scopes: conversations:read, conversations:write.","security":[{"bearerAuth":["conversations:read"]},{"bearerAuth":["conversations:write"]}],"x-accepted-scopes":["conversations:read","conversations:write"],"parameters":[{"name":"page_number","in":"query","required":false,"description":"1-based page. Default 1. page_number x page_size must not exceed 10,000 (400 beyond that).","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"description":"open, pending, solved or blocked.","schema":{"type":"string"}},{"name":"target","in":"query","required":false,"description":"Only conversations of this contact (phone, id, external_id:<value> or bsuid:<value>).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok","conversation_list","page_number","page_size","total","has_more"],"properties":{"ok":{"const":true},"conversation_list":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"window_exhausted":{"type":"boolean","description":"True when more rows exist beyond the 10,000-row paging window. Narrow the list with filters."}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/conversations/{target}":{"get":{"operationId":"conversations.get","tags":["Conversations"],"summary":"One conversation by conversation id, or the most recently active one of a contact (phone, contact id, external_id:<value> or bsuid:<value>).","description":"Needs an API key holding one of these scopes: conversations:read, conversations:write.","security":[{"bearerAuth":["conversations:read"]},{"bearerAuth":["conversations:write"]}],"x-accepted-scopes":["conversations:read","conversations:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"conversation":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/conversations/{target}/messages":{"get":{"operationId":"conversations.messages","tags":["Conversations"],"summary":"Message history, newest first. The target is a conversation id, or a contact whose conversations are all included.","description":"Needs an API key holding one of these scopes: conversations:read, conversations:write.","security":[{"bearerAuth":["conversations:read"]},{"bearerAuth":["conversations:write"]}],"x-accepted-scopes":["conversations:read","conversations:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}},{"name":"page_number","in":"query","required":false,"description":"1-based page. Default 1. page_number x page_size must not exceed 10,000 (400 beyond that).","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok","message_list","page_number","page_size","total","has_more"],"properties":{"ok":{"const":true},"message_list":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"window_exhausted":{"type":"boolean","description":"True when more rows exist beyond the 10,000-row paging window. Narrow the list with filters."}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/conversations/{target}/messages/text":{"post":{"operationId":"conversations.sendText","tags":["Conversations"],"summary":"Send a session (free-form) message to a conversation id or a contact (phone, contact id, external_id:<value> or bsuid:<value>). Needs an open 24-hour window; answers 409 otherwise.","description":"Needs an API key holding one of these scopes: messages:write, conversations:write. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["messages:write"]},{"bearerAuth":["conversations:write"]}],"x-accepted-scopes":["messages:write","conversations:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Message text, up to 4096 characters."},"channel":{"type":"string","description":"Meta phone_number_id to send from. Defaults to your first connected number."},"local_message_id":{"type":"string","description":"Your own id. A repeat of the same id to the same recipient within 24 hours returns the first result and sends nothing; the same id with a different message answers 422."}},"required":["text"]}}}},"responses":{"202":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"message":{"$ref":"#/components/schemas/Message"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"413":{"$ref":"#/components/responses/Error413"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/conversations/{target}/status":{"put":{"operationId":"conversations.setStatus","tags":["Conversations"],"summary":"Change the status of a conversation.","description":"Needs an API key holding the conversations:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["conversations:write"]}],"x-accepted-scopes":["conversations:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"open, pending, solved or blocked."}},"required":["status"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"conversation":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/conversations/{target}/assignee":{"put":{"operationId":"conversations.assign","tags":["Conversations"],"summary":"Assign a conversation to a member of the workspace, or unassign it.","description":"Needs an API key holding the conversations:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["conversations:write"]}],"x-accepted-scopes":["conversations:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":["string","null"],"description":"Id of a workspace member, or null to unassign."}},"required":["user_id"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"conversation":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/conversations/{target}/tags":{"post":{"operationId":"conversations.addTags","tags":["Conversations"],"summary":"Add tags to a conversation, keeping the ones it already has.","description":"Needs an API key holding the conversations:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["conversations:write"]}],"x-accepted-scopes":["conversations:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Up to 10 tags of up to 40 characters each."}},"required":["tags"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"conversation":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/conversations/{target}/tags/{tag}":{"delete":{"operationId":"conversations.removeTag","tags":["Conversations"],"summary":"Remove one tag from a conversation. Removing a tag the conversation lacks succeeds.","description":"Needs an API key holding the conversations:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["conversations:write"]}],"x-accepted-scopes":["conversations:write"],"parameters":[{"name":"target","in":"path","required":true,"description":"Phone number, contact id, external_id:<value>, bsuid:<value> or a conversation id, as the endpoint describes.","schema":{"type":"string"}},{"name":"tag","in":"path","required":true,"description":"The tag.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"conversation":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/messageTemplates":{"get":{"operationId":"templates.list","tags":["Templates"],"summary":"List message templates.","description":"Needs an API key holding one of these scopes: templates:read, messages:write.","security":[{"bearerAuth":["templates:read"]},{"bearerAuth":["messages:write"]}],"x-accepted-scopes":["templates:read","messages:write"],"parameters":[{"name":"page_number","in":"query","required":false,"description":"1-based page. Default 1. page_number x page_size must not exceed 10,000 (400 beyond that).","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"description":"draft, pending, approved, rejected, paused or disabled.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok","message_template_list","page_number","page_size","total","has_more"],"properties":{"ok":{"const":true},"message_template_list":{"type":"array","items":{"$ref":"#/components/schemas/MessageTemplate"}},"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"window_exhausted":{"type":"boolean","description":"True when more rows exist beyond the 10,000-row paging window. Narrow the list with filters."}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/messageTemplates/{id}":{"get":{"operationId":"templates.get","tags":["Templates"],"summary":"One message template by id, with its components and review status.","description":"Needs an API key holding one of these scopes: templates:read, messages:write.","security":[{"bearerAuth":["templates:read"]},{"bearerAuth":["messages:write"]}],"x-accepted-scopes":["templates:read","messages:write"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"message_template":{"$ref":"#/components/schemas/MessageTemplate"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/messageTemplates/send":{"post":{"operationId":"templates.send","tags":["Templates"],"summary":"Send an approved template to up to 100 recipients, including templates with a media header or a link button. Each recipient is answered on its own: accepted means we queued the message for sending, not that it was delivered. Follow delivery with the message.status webhook or the message history.","description":"Needs an API key holding the messages:write scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["messages:write"]}],"x-accepted-scopes":["messages:write"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template_name":{"type":"string","description":"Name of an approved template."},"language":{"type":"string","description":"Template language code. Needed only when the name exists in several languages."},"broadcast_name":{"type":"string","description":"Accepted for compatibility and echoed back; no broadcast record is created."},"channel":{"type":"string","description":"Meta phone_number_id to send from."},"recipients":{"type":"array","items":{"type":"object"},"description":"Each item: phone_number, or bsuid for a person who messaged you through a WhatsApp username (one of the two is required), local_message_id (optional, dedupes for 24 hours), custom_params (array of { name, value } filling {{1}}, {{2}}... in order), header_param (text for a header placeholder, or the public https link of an image, video or document header), button_params (array of { index, value } for link buttons whose url has a placeholder, index counting buttons from 0)."}},"required":["template_name","recipients"]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TemplateSendResult"},{"type":"object","properties":{"ok":{"const":true}}}]}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"413":{"$ref":"#/components/responses/Error413"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/broadcasts":{"get":{"operationId":"broadcasts.list","tags":["Broadcasts"],"summary":"List broadcasts with delivery counts.","description":"Needs an API key holding the broadcasts:read scope.","security":[{"bearerAuth":["broadcasts:read"]}],"x-accepted-scopes":["broadcasts:read"],"parameters":[{"name":"page_number","in":"query","required":false,"description":"1-based page. Default 1. page_number x page_size must not exceed 10,000 (400 beyond that).","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok","broadcast_list","page_number","page_size","total","has_more"],"properties":{"ok":{"const":true},"broadcast_list":{"type":"array","items":{"$ref":"#/components/schemas/Broadcast"}},"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"window_exhausted":{"type":"boolean","description":"True when more rows exist beyond the 10,000-row paging window. Narrow the list with filters."}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/broadcasts/{id}":{"get":{"operationId":"broadcasts.get","tags":["Broadcasts"],"summary":"One broadcast with its delivery status summary.","description":"Needs an API key holding the broadcasts:read scope.","security":[{"bearerAuth":["broadcasts:read"]}],"x-accepted-scopes":["broadcasts:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"broadcast":{"$ref":"#/components/schemas/Broadcast"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/broadcasts/{id}/recipients":{"get":{"operationId":"broadcasts.recipients","tags":["Broadcasts"],"summary":"Per-recipient delivery status.","description":"Needs an API key holding the broadcasts:read scope.","security":[{"bearerAuth":["broadcasts:read"]}],"x-accepted-scopes":["broadcasts:read"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string"}},{"name":"page_number","in":"query","required":false,"description":"1-based page. Default 1. page_number x page_size must not exceed 10,000 (400 beyond that).","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}},{"name":"status","in":"query","required":false,"description":"pending, queued, sent, delivered, read, failed or skipped.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok","recipient_list","page_number","page_size","total","has_more"],"properties":{"ok":{"const":true},"recipient_list":{"type":"array","items":{"$ref":"#/components/schemas/BroadcastRecipient"}},"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"window_exhausted":{"type":"boolean","description":"True when more rows exist beyond the 10,000-row paging window. Narrow the list with filters."}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/webhooks/event-types":{"get":{"operationId":"webhooks.eventTypes","tags":["Webhooks"],"summary":"Event names you can subscribe to.","description":"Needs an API key holding the webhooks:manage scope.","security":[{"bearerAuth":["webhooks:manage"]}],"x-accepted-scopes":["webhooks:manage"],"parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"event_types":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/webhooks":{"get":{"operationId":"webhooks.list","tags":["Webhooks"],"summary":"List webhook subscriptions.","description":"Needs an API key holding the webhooks:manage scope.","security":[{"bearerAuth":["webhooks:manage"]}],"x-accepted-scopes":["webhooks:manage"],"parameters":[{"name":"page_number","in":"query","required":false,"description":"1-based page. Default 1. page_number x page_size must not exceed 10,000 (400 beyond that).","schema":{"type":"integer"}},{"name":"page_size","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok","webhook_list","page_number","page_size","total","has_more"],"properties":{"ok":{"const":true},"webhook_list":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"},"window_exhausted":{"type":"boolean","description":"True when more rows exist beyond the 10,000-row paging window. Narrow the list with filters."}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}},"post":{"operationId":"webhooks.create","tags":["Webhooks"],"summary":"Subscribe a public HTTPS URL. The signing secret is returned once.","description":"Needs an API key holding the webhooks:manage scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["webhooks:manage"]}],"x-accepted-scopes":["webhooks:manage"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public https URL."},"event_types":{"type":"array","items":{"type":"string"},"description":"Names from the event-types endpoint."},"status":{"type":"string","description":"enabled (default) or disabled."}},"required":["url","event_types"]}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"webhook":{"$ref":"#/components/schemas/Webhook"},"signing_secret":{"type":"string","description":"Shown once. Store it to verify deliveries."}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/webhooks/{id}":{"get":{"operationId":"webhooks.get","tags":["Webhooks"],"summary":"One webhook subscription.","description":"Needs an API key holding the webhooks:manage scope.","security":[{"bearerAuth":["webhooks:manage"]}],"x-accepted-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}},"put":{"operationId":"webhooks.update","tags":["Webhooks"],"summary":"Change the URL, events or status. Enabling resets the failure count.","description":"Needs an API key holding the webhooks:manage scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["webhooks:manage"]}],"x-accepted-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"New public https URL."},"event_types":{"type":"array","items":{"type":"string"},"description":"Replaces the subscribed events."},"status":{"type":"string","description":"enabled or disabled."}}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}},"delete":{"operationId":"webhooks.delete","tags":["Webhooks"],"summary":"Delete a subscription and its delivery log.","description":"Needs an API key holding the webhooks:manage scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["webhooks:manage"]}],"x-accepted-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}},"/webhooks/{id}/test":{"post":{"operationId":"webhooks.test","tags":["Webhooks"],"summary":"Queue a signed test event to this subscription.","description":"Needs an API key holding the webhooks:manage scope. Writes are refused with 402 while the workspace trial or subscription has ended.","security":[{"bearerAuth":["webhooks:manage"]}],"x-accepted-scopes":["webhooks:manage"],"parameters":[{"name":"id","in":"path","required":true,"description":"The id.","schema":{"type":"string"}}],"responses":{"202":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"const":true},"delivery_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"413":{"$ref":"#/components/responses/Error413"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"}}}}},"webhooks":{"message.received":{"post":{"operationId":"webhook.message.received","tags":["Webhook events"],"summary":"A customer sends a message","description":"After an incoming WhatsApp message is stored. Reactions and status updates do not use this event. Every delivery is signed; see /docs/webhooks. Answer any 2xx within 10 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"event":{"const":"message.received"},"data":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation the message belongs to."},"channel":{"type":["string","null"],"description":"Meta phone_number_id the message came in on."},"assignedTo":{"type":["string","null"],"description":"User id of the agent the conversation is assigned to, if any."},"contact":{"type":"object","properties":{"id":{"type":"string","description":"Id of the contact in the API."},"phone":{"type":["string","null"],"description":"Phone number with country code. Null for people who message through a WhatsApp username."},"bsuid":{"type":["string","null"],"description":"WhatsApp business-scoped user id (BSUID). Always present once the person has messaged you through WhatsApp; use it as the stable key when phone is null."},"waId":{"type":["string","null"],"description":"WhatsApp id (the phone number as digits), when WhatsApp shared it."},"username":{"type":["string","null"],"description":"WhatsApp username, when known."},"name":{"type":["string","null"],"description":"Display name."}}},"message":{"type":"object","properties":{"id":{"type":"string","description":"WhatsApp message id (wamid)."},"type":{"type":"string","description":"text, image, audio, video, document, sticker, location, contacts, button, interactive or other."},"text":{"type":["string","null"],"description":"Message text or caption, when there is one."},"mediaId":{"type":["string","null"],"description":"WhatsApp media id for media messages."},"mimeType":{"type":["string","null"],"description":"Media type for media messages."},"timestamp":{"type":"string","description":"When WhatsApp says the message was sent, ISO 8601."}}},"referral":{"type":["object","null"],"description":"Present when the chat started from a click-to-WhatsApp ad.","properties":{"sourceType":{"type":["string","null"],"description":"ad or post."},"sourceId":{"type":["string","null"],"description":"Id of the ad or post."},"sourceUrl":{"type":["string","null"],"description":"Link of the ad or post."},"headline":{"type":["string","null"],"description":"Ad headline."},"ctwaClid":{"type":["string","null"],"description":"Click id, for conversion reporting."}}}}}}}]},"example":{"id":"3f1c0b5e-0000-4000-8000-000000000000","event":"message.received","createdAt":"2026-10-27T10:15:00.000Z","data":{"conversationId":"ckconv1","channel":"109876543210987","assignedTo":null,"contact":{"id":"ckcontact1","phone":"+919876543210","bsuid":"IN.13491208655302741918","waId":"919876543210","username":null,"name":"Asha"},"message":{"id":"wamid.HBgM...","type":"text","text":"Hi, is the red one in stock?","mediaId":null,"mimeType":null,"timestamp":"2026-10-27T10:15:00.000Z"},"referral":{"sourceType":"ad","sourceId":"120210000000000","sourceUrl":"https://fb.me/example","headline":"Spring sale","ctwaClid":"ARAk..."}}}}}},"responses":{"200":{"description":"Any 2xx status acknowledges the delivery."}}}},"message.status":{"post":{"operationId":"webhook.message.status","tags":["Webhook events"],"summary":"A message you sent changes status","description":"Each time a message you sent is sent, delivered, read or fails. Statuses can arrive out of order; use timestamp. Every delivery is signed; see /docs/webhooks. Answer any 2xx within 10 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"event":{"const":"message.status"},"data":{"type":"object","properties":{"messageId":{"type":"string","description":"Message id in the API."},"conversationId":{"type":"string","description":"Conversation the message belongs to."},"wamid":{"type":["string","null"],"description":"WhatsApp message id, once WhatsApp has accepted it."},"status":{"type":"string","description":"sent, delivered, read or failed."},"errorCode":{"type":["string","null"],"description":"WhatsApp error code when status is failed."},"timestamp":{"type":"string","description":"ISO 8601 time of the status."},"contact":{"type":"object","properties":{"id":{"type":"string","description":"Id of the recipient in the API."},"phone":{"type":["string","null"],"description":"Phone number with country code. Null for people who message through a WhatsApp username."},"bsuid":{"type":["string","null"],"description":"WhatsApp business-scoped user id (BSUID). Always present once the person has messaged you through WhatsApp; use it as the stable key when phone is null."},"waId":{"type":["string","null"],"description":"WhatsApp id (the phone number as digits), when WhatsApp shared it."},"username":{"type":["string","null"],"description":"WhatsApp username, when known."},"name":{"type":["string","null"],"description":"Display name."}}}}}}}]},"example":{"id":"3f1c0b5e-0000-4000-8000-000000000000","event":"message.status","createdAt":"2026-10-27T10:15:00.000Z","data":{"messageId":"ckmsg1","conversationId":"ckconv1","wamid":"wamid.HBgM...","status":"delivered","errorCode":null,"timestamp":"2026-10-27T10:15:00.000Z","contact":{"id":"ckcontact1","phone":"+919876543210","bsuid":"IN.13491208655302741918","waId":"919876543210","username":null,"name":"Asha"}}}}}},"responses":{"200":{"description":"Any 2xx status acknowledges the delivery."}}}},"template.status":{"post":{"operationId":"webhook.template.status","tags":["Webhook events"],"summary":"A template is reviewed","description":"When Meta approves, rejects, pauses or otherwise changes the review status of one of your templates. Every delivery is signed; see /docs/webhooks. Answer any 2xx within 10 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"event":{"const":"template.status"},"data":{"type":"object","properties":{"templateId":{"type":["string","null"],"description":"Template id in the API, when the template is known here."},"name":{"type":["string","null"],"description":"Template name."},"language":{"type":["string","null"],"description":"Template language code."},"category":{"type":["string","null"],"description":"marketing, utility or authentication."},"status":{"type":"string","description":"approved, rejected, pending, paused or disabled."},"reason":{"type":["string","null"],"description":"Why Meta rejected it, when it did."},"timestamp":{"type":"string","description":"ISO 8601 time we recorded the change."}}}}}]},"example":{"id":"3f1c0b5e-0000-4000-8000-000000000000","event":"template.status","createdAt":"2026-10-27T10:15:00.000Z","data":{"templateId":"cktemplate1","name":"order_update","language":"en","category":"utility","status":"approved","reason":null,"timestamp":"2026-10-27T10:15:00.000Z"}}}}},"responses":{"200":{"description":"Any 2xx status acknowledges the delivery."}}}},"broadcast.completed":{"post":{"operationId":"webhook.broadcast.completed","tags":["Webhook events"],"summary":"A broadcast finishes","description":"Once every recipient of a broadcast has been processed. Delivery numbers can still grow afterwards as receipts arrive. Every delivery is signed; see /docs/webhooks. Answer any 2xx within 10 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"event":{"const":"broadcast.completed"},"data":{"type":"object","properties":{"broadcastId":{"type":"string","description":"Broadcast id in the API."},"name":{"type":["string","null"],"description":"Broadcast name."},"templateId":{"type":["string","null"],"description":"Template the broadcast used."},"completedAt":{"type":"string","description":"ISO 8601 time of completion."},"totals":{"type":"object","properties":{"total":{"type":"integer","description":"Recipients in the broadcast."},"sent":{"type":"integer","description":"Recipients whose message WhatsApp accepted (includes delivered and read)."},"delivered":{"type":"integer","description":"Delivered so far (includes read)."},"read":{"type":"integer","description":"Read so far."},"failed":{"type":"integer","description":"Recipients whose message failed."},"skipped":{"type":"integer","description":"Recipients left out, for example because they opted out."}}}}}}}]},"example":{"id":"3f1c0b5e-0000-4000-8000-000000000000","event":"broadcast.completed","createdAt":"2026-10-27T10:15:00.000Z","data":{"broadcastId":"ckbroadcast1","name":"October offer","templateId":"cktemplate1","completedAt":"2026-10-27T10:15:00.000Z","totals":{"total":120,"sent":118,"delivered":110,"read":64,"failed":2,"skipped":0}}}}}},"responses":{"200":{"description":"Any 2xx status acknowledges the delivery."}}}},"contact.opted_out":{"post":{"operationId":"webhook.contact.opted_out","tags":["Webhook events"],"summary":"A contact opts out","description":"When someone sends STOP, an agent marks the contact as opted out, the API marks the contact as opted out, or a chatbot unsubscribe step runs. We stop all marketing messages to them. Every delivery is signed; see /docs/webhooks. Answer any 2xx within 10 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"event":{"const":"contact.opted_out"},"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"string","description":"Id of the contact in the API."},"phone":{"type":["string","null"],"description":"Phone number with country code. Null for people who message through a WhatsApp username."},"bsuid":{"type":["string","null"],"description":"WhatsApp business-scoped user id (BSUID). Always present once the person has messaged you through WhatsApp; use it as the stable key when phone is null."},"waId":{"type":["string","null"],"description":"WhatsApp id (the phone number as digits), when WhatsApp shared it."},"username":{"type":["string","null"],"description":"WhatsApp username, when known."},"name":{"type":["string","null"],"description":"Display name."}}},"contactId":{"type":"string","description":"Same as contact.id, kept for older integrations."},"phone":{"type":["string","null"],"description":"Same as contact.phone, kept for older integrations."},"optedOutAt":{"type":"string","description":"ISO 8601 time of the opt-out."},"source":{"type":"string","description":"stop_keyword, dashboard, api (a compat API call set opt_in to false) or chatbot (an unsubscribe step in a chatbot flow)."}}}}}]},"example":{"id":"3f1c0b5e-0000-4000-8000-000000000000","event":"contact.opted_out","createdAt":"2026-10-27T10:15:00.000Z","data":{"contact":{"id":"ckcontact1","phone":"+919876543210","bsuid":"IN.13491208655302741918","waId":"919876543210","username":null,"name":"Asha"},"contactId":"ckcontact1","phone":"+919876543210","optedOutAt":"2026-10-27T10:15:00.000Z","source":"stop_keyword"}}}}},"responses":{"200":{"description":"Any 2xx status acknowledges the delivery."}}}},"conversation.status_changed":{"post":{"operationId":"webhook.conversation.status_changed","tags":["Webhook events"],"summary":"A conversation changes status","description":"When a conversation moves between open, pending, solved and blocked, by an agent, the API, an automation or a customer reply that reopens it. Every delivery is signed; see /docs/webhooks. Answer any 2xx within 10 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"event":{"const":"conversation.status_changed"},"data":{"type":"object","properties":{"conversationId":{"type":"string","description":"Conversation id in the API."},"contactId":{"type":["string","null"],"description":"Contact the conversation belongs to."},"from":{"type":["string","null"],"description":"Previous status, when known."},"to":{"type":"string","description":"New status."},"changedBy":{"type":["string","null"],"description":"User id of the person who changed it. Null for automations and customer replies."},"source":{"type":"string","description":"user when a person or API key changed it, system otherwise."},"timestamp":{"type":"string","description":"ISO 8601 time of the change."}}}}}]},"example":{"id":"3f1c0b5e-0000-4000-8000-000000000000","event":"conversation.status_changed","createdAt":"2026-10-27T10:15:00.000Z","data":{"conversationId":"ckconv1","contactId":"ckcontact1","from":"open","to":"solved","changedBy":"ckuser1","source":"user","timestamp":"2026-10-27T10:15:00.000Z"}}}}},"responses":{"200":{"description":"Any 2xx status acknowledges the delivery."}}}},"lead.created":{"post":{"operationId":"webhook.lead.created","tags":["Webhook events"],"summary":"A lead arrives","description":"When a person fills in one of your Meta lead forms and the lead is stored. Every delivery is signed; see /docs/webhooks. Answer any 2xx within 10 seconds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"event":{"const":"lead.created"},"data":{"type":"object","properties":{"leadId":{"type":"string","description":"Lead id in the app."},"status":{"type":"string","description":"new at creation."},"source":{"type":"string","description":"Always meta_lead_form for now."},"formId":{"type":["string","null"],"description":"Meta lead form id."},"campaignId":{"type":["string","null"],"description":"Meta campaign id the lead came from."},"adId":{"type":["string","null"],"description":"Meta ad id the lead came from."},"createdAt":{"type":"string","description":"ISO 8601 time the person submitted the form."},"contact":{"type":["object","null"],"description":"The contact created or matched for this lead, when the form had a phone number.","properties":{"id":{"type":"string","description":"Id of the contact in the API."},"phone":{"type":["string","null"],"description":"Phone number with country code. Null for people who message through a WhatsApp username."},"bsuid":{"type":["string","null"],"description":"WhatsApp business-scoped user id (BSUID). Always present once the person has messaged you through WhatsApp; use it as the stable key when phone is null."},"waId":{"type":["string","null"],"description":"WhatsApp id (the phone number as digits), when WhatsApp shared it."},"username":{"type":["string","null"],"description":"WhatsApp username, when known."},"name":{"type":["string","null"],"description":"Display name."}}},"fields":{"type":"object","description":"The form answers, as field name to text."}}}}}]},"example":{"id":"3f1c0b5e-0000-4000-8000-000000000000","event":"lead.created","createdAt":"2026-10-27T10:15:00.000Z","data":{"leadId":"cklead1","status":"new","source":"meta_lead_form","formId":"5550001112223","campaignId":"120210000000001","adId":"120210000000002","createdAt":"2026-10-27T10:15:00.000Z","contact":{"id":"ckcontact1","phone":"+919876543210","bsuid":"IN.13491208655302741918","waId":"919876543210","username":null,"name":"Asha"},"fields":{"full_name":"Asha","phone_number":"+919876543210","city":"Pune"}}}}}},"responses":{"200":{"description":"Any 2xx status acknowledges the delivery."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (wak_...)","description":"An API key sent as a bearer token. The key must hold one of the scopes an operation lists. Scopes: messages:write (Send session messages and approved templates.) contacts:read (Read contacts.) contacts:write (Create, change and delete contacts. Also allows reading them.) templates:read (Read message templates. Also granted by messages:write.) conversations:read (Read conversations and message history.) conversations:write (Change conversation status, assignee and tags. Also allows reading conversations and sending session text.) broadcasts:read (Read broadcasts and their recipients.) webhooks:manage (Create and change webhook subscriptions.)"}},"schemas":{"Error":{"type":"object","required":["ok","error","timestamp"],"properties":{"ok":{"const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","payment_required","forbidden","not_found","conflict","payload_too_large","unprocessable","rate_limited","internal_error"]},"message":{"type":"string"}}},"timestamp":{"type":"string","format":"date-time"}}},"Contact":{"type":"object","properties":{"id":{"type":"string"},"phone_number":{"type":["string","null"],"description":"Null for people who message through a WhatsApp username."},"external_id":{"type":["string","null"]},"bsuid":{"type":["string","null"],"description":"WhatsApp business-scoped user id."},"username":{"type":["string","null"]},"wa_id":{"type":["string","null"]},"name":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"custom_params":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"value":{"type":["string","number","boolean","null"]}}}},"opt_in":{"type":"boolean"},"opted_out_at":{"type":["string","null"],"format":"date-time"},"created":{"type":["string","null"],"format":"date-time"}}},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["open","pending","solved","blocked"]},"tags":{"type":"array","items":{"type":"string"}},"unread_count":{"type":"integer"},"assigned_to":{"type":["string","null"]},"team_id":{"type":["string","null"]},"window_open":{"type":"boolean","description":"True while a free-form reply is allowed (24 hours after the customer's last message)."},"last_message_at":{"type":["string","null"],"format":"date-time"},"last_inbound_at":{"type":["string","null"],"format":"date-time"},"first_agent_reply_at":{"type":["string","null"],"format":"date-time"},"last_agent_reply_at":{"type":["string","null"],"format":"date-time"},"created":{"type":["string","null"],"format":"date-time"},"contact":{"$ref":"#/components/schemas/Contact"}}},"Message":{"type":"object","additionalProperties":true,"description":"A stored message with its direction, type, body, status and timestamps."},"MessageTemplate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"components":{"type":"array","items":{"type":"object"}},"rejection_reason":{"type":["string","null"]},"created":{"type":["string","null"],"format":"date-time"}}},"Broadcast":{"type":"object","additionalProperties":true},"BroadcastRecipient":{"type":"object","additionalProperties":true},"Webhook":{"type":"object","additionalProperties":true},"TemplateSendResult":{"type":"object","properties":{"success":{"type":"boolean"},"broadcast_id":{"type":"null","description":"Always null: no broadcast record is created for API sends."},"broadcast_name":{"type":["string","null"]},"error":{"type":["string","null"]},"accepted_count":{"type":"integer"},"rejected_count":{"type":"integer"},"delivery_note":{"type":"string"},"recipients":{"type":"array","items":{"type":"object","properties":{"local_message_id":{"type":["string","null"],"description":"Your own id for this recipient, echoed back; null when you sent none."},"phone_number":{"type":["string","null"]},"bsuid":{"type":["string","null"]},"accepted":{"type":"boolean","description":"We took the message and queued it. It is not a delivery confirmation."},"status":{"type":"string"},"message_id":{"type":["string","null"]},"conversation_id":{"type":["string","null"]},"deduplicated":{"type":"boolean"},"errors":{"type":["array","null"],"items":{"type":"string"},"description":"null for an accepted recipient."},"error_status":{"type":["integer","null"],"description":"HTTP-style status of the rejection; null for an accepted recipient."}},"required":["local_message_id","phone_number","bsuid","accepted","status","message_id","conversation_id","deduplicated","errors","error_status"]}}}},"WebhookEnvelope":{"type":"object","required":["id","event","createdAt","data"],"properties":{"id":{"type":"string"},"event":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object"}}}},"responses":{"Error400":{"description":"invalid_request: A field is missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error401":{"description":"unauthorized: Missing, revoked or malformed token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error402":{"description":"payment_required: The workspace trial or subscription has ended, so writes are refused until a plan is chosen. Reads keep working.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error403":{"description":"forbidden: The token has none of the scopes this endpoint accepts, or the workspace is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error404":{"description":"not_found: No such record in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error409":{"description":"conflict: The request clashes with current state, for example a duplicate contact or a closed 24-hour window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error413":{"description":"payload_too_large: The body exceeds 64 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error422":{"description":"unprocessable: Understood but refused, for example the contact opted out or has no phone number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error429":{"description":"rate_limited: Too many requests; wait for Retry-After seconds.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error500":{"description":"internal_error: Something failed on our side. Safe to retry reads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}