{ "openapi": "3.1.0", "info": { "title": "Cogfy Messenger Public API", "version": "1.0.0", "description": "API for interacting with the Cogfy Messenger platform" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "api-key" } } }, "security": [ { "ApiKeyAuth": [] } ], "servers": [ { "url": "https://messenger-public-api.cogfy.com", "description": "Production server" }, { "url": "http://localhost:3100", "description": "Local server" } ], "paths": { "/conversations/{conversationId}": { "get": { "summary": "Get a conversation by ID", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "phoneNumberId": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid" }, "assigneeId": { "type": "string", "format": "uuid" }, "lastMessageId": { "type": "string", "format": "uuid" }, "createDate": { "type": "string", "format": "date-time" }, "serviceWindowExpireDate": { "type": "string", "format": "date-time" } } } } } } } } }, "/conversations/{conversationId}/messages": { "get": { "summary": "Get all messages in a conversation", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "conversationId", "schema": { "type": "string" }, "required": true, "description": "Conversation ID" }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Cursor for pagination" } ], "responses": { "200": { "description": "A list of messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid" }, "assistantId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "broadcastId": { "type": "string", "format": "uuid" }, "whatsappMessageId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" }, "contentData": { "type": "object" }, "toolCallId": { "type": "string" }, "toolCalls": { "type": "string" }, "data": { "type": "string" }, "contextId": { "type": "string" }, "contextFrom": { "type": "string" }, "createDate": { "type": "string", "format": "date-time" }, "sendDate": { "type": "string", "format": "date-time" }, "deliverDate": { "type": "string", "format": "date-time" }, "readDate": { "type": "string", "format": "date-time" }, "promptTokens": { "type": "string" }, "completionTokens": { "type": "string" }, "order": { "type": "number" }, "traceId": { "type": "string" } } } }, "cursors": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "description": "Cursor for newer messages" }, "prev": { "type": [ "string", "null" ], "description": "Cursor for older messages" } } } } } } } } } }, "post": { "summary": "Send a message to a conversation", "tags": [ "Conversations" ], "parameters": [ { "in": "path", "name": "conversationId", "schema": { "type": "string" }, "required": true, "description": "Conversation ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Message content. Required for text messages, optional for media messages." }, "type": { "type": "string", "enum": [ "text", "image", "document" ], "description": "Message type" }, "media": { "type": "object", "properties": { "name": { "type": "string", "description": "Media file name. Optional." }, "mimeType": { "type": "string", "description": "Media MIME type. Required for media messages." }, "base64": { "type": "string", "description": "Media file content in base64 encoding. Required for media messages." } } } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Message ID" } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Conversation not found" }, "500": { "description": "Internal server error" } } } }, "/conversations": { "get": { "summary": "Get all conversations", "tags": [ "Conversations" ], "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Cursor for pagination" } ], "responses": { "200": { "description": "A list of conversations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "phoneNumberId": { "type": "string", "format": "uuid" }, "recipientId": { "type": "string", "format": "uuid" }, "assigneeId": { "type": "string", "format": "uuid" }, "lastMessageId": { "type": "string", "format": "uuid" }, "createDate": { "type": "string", "format": "date-time" }, "serviceWindowExpireDate": { "type": "string", "format": "date-time" } } } }, "cursors": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "description": "Cursor for the next page" } } } } } } } } } } }, "/messages/upload-media": { "post": { "summary": "Upload media to WhatsApp", "description": "Uploads a file to WhatsApp Cloud API. Use the returned id as document.id when calling POST /messages/document.", "tags": [ "Messages" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "from", "file" ], "properties": { "from": { "type": "string", "description": "WhatsApp phone number ID (sender)" }, "file": { "type": "string", "format": "binary" } } } }, "application/json": { "schema": { "type": "object", "required": [ "from", "media" ], "properties": { "from": { "type": "string", "description": "WhatsApp phone number ID (sender)" }, "media": { "type": "object", "required": [ "mimeType", "base64" ], "properties": { "mimeType": { "type": "string", "description": "MIME type of the file (e.g. application/pdf)" }, "base64": { "type": "string", "description": "File bytes as base64 (optional data URL prefix supported)" }, "name": { "type": "string", "description": "Filename hint for upload" } } } } } } } }, "responses": { "200": { "description": "Media uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "WhatsApp media id (use as document.id for send document)" } } } } } } } } }, "/broadcasts": { "get": { "tags": [ "Broadcasts" ], "summary": "List all broadcasts", "parameters": [ { "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor returned by a previous call, used to fetch the next page", "type": "string" }, "description": "Opaque cursor returned by a previous call, used to fetch the next page" } ], "responses": { "200": { "description": "A list of broadcasts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "status", "createDate" ], "additionalProperties": false } }, "cursors": { "type": "object", "properties": { "next": { "description": "Opaque cursor to fetch the next page. Absent when there are no more results", "type": "string" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } }, "post": { "tags": [ "Broadcasts" ], "summary": "Create a new broadcast", "description": "Creates a broadcast for a phone number of the workspace.\n\n**Message type (`type`)** and **recipient source** are independent choices — any combination of them is valid:\n\n- `type: text` sends a free-form text message. It only reaches contacts with an open service window (i.e. that messaged the business recently).\n- `type: template` sends an approved WhatsApp template message. Required to reach recipients that never messaged the business or whose service window is closed.\n\n**Recipient source** — exactly one of the following must be provided, regardless of `type`:\n\n- `contactsQuery`: filters contacts already registered in the workspace by tag. The broadcast is created with status `pending` and the recipients are resolved asynchronously; once resolved it moves to `ready` (or `scheduled`).\n- `contacts`: an explicit list of recipients sent in the request body, which does not require the contacts to be registered. The broadcast messages are created synchronously and the broadcast is returned already in status `ready` (or `scheduled`, when `scheduleDate` is provided).\n\nA broadcast in status `ready` is only sent after calling `POST /broadcasts/{broadcastId}/send`. A broadcast in status `scheduled` is sent automatically at `scheduleDate`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "default": "text", "description": "`text` sends a free-form text message. `template` sends an approved WhatsApp template message", "type": "string", "enum": [ "text", "template" ] }, "title": { "type": "string", "maxLength": 100, "description": "Broadcast title, used for identification" }, "content": { "description": "Message content. Required when `type` is `text`", "type": "string", "maxLength": 1024 }, "template": { "description": "Template specification. Required when `type` is `template`", "type": "object", "properties": { "whatsAppId": { "type": "string", "minLength": 1, "description": "Id of the approved WhatsApp template message" } }, "required": [ "whatsAppId" ] }, "phoneNumber": { "type": "string", "minLength": 1, "description": "Id or phone number of the sender phone number" }, "contactsQuery": { "description": "Filter for contacts already registered in the workspace. Mutually exclusive with `contacts`", "type": "object", "properties": { "tags": { "description": "Recipients are the contacts that have all the given tags", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } } } } } }, "contacts": { "description": "Explicit list of recipients. Mutually exclusive with `contactsQuery`", "minItems": 1, "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "type": "string", "minLength": 1, "description": "Recipient WhatsApp number, digits only, including country code" }, "variables": { "description": "Values for the named parameters of the WhatsApp template, keyed by parameter name", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "phoneNumber" ] } }, "scheduleDate": { "description": "When provided, the broadcast is scheduled to be sent automatically at this date. Must be in the future", "type": "string" }, "batchSize": { "default": 5, "description": "Number of messages sent per batch", "type": "integer", "minimum": 1, "maximum": 1000 }, "batchInterval": { "default": 1, "description": "Interval in minutes between batches", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "allowedSendTimeStart": { "default": "08:00", "description": "Start of the time window in which batches may be sent (HH:MM)", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "allowedSendTimeEnd": { "default": "18:00", "description": "End of the time window in which batches may be sent (HH:MM)", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "allowedSendTimeTimezone": { "default": "America/Sao_Paulo", "description": "IANA timezone used to evaluate the allowed send time window", "type": "string" }, "whatsappApi": { "default": "cloud_api", "description": "WhatsApp API used to deliver the messages", "type": "string", "enum": [ "cloud_api", "mm_api" ] } }, "required": [ "title", "phoneNumber" ] }, "examples": { "templateWithExplicitContacts": { "summary": "Template broadcast for an explicit list of recipients", "value": { "type": "template", "title": "Appointment reminder", "template": { "whatsAppId": "1234567890" }, "phoneNumber": "5511999998888", "scheduleDate": "2026-10-30T13:00:00Z", "contacts": [ { "phoneNumber": "5599888887777", "variables": { "NAME": "John" } }, { "phoneNumber": "5599888886666", "variables": { "NAME": "Mary" } } ] } }, "textWithContactsQuery": { "summary": "Text broadcast for tagged contacts", "value": { "type": "text", "title": "Weekly update", "content": "Hello!", "phoneNumber": "5511999998888", "contactsQuery": { "tags": [ { "name": "customers" } ] } } }, "templateWithContactsQuery": { "summary": "Template broadcast for tagged contacts", "value": { "type": "template", "title": "Promotional campaign", "template": { "whatsAppId": "1234567890" }, "phoneNumber": "5511999998888", "contactsQuery": { "tags": [ { "name": "leads" } ] } } } } } } }, "responses": { "201": { "description": "Broadcast created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`pending` when the recipients still have to be resolved from `contactsQuery`, `ready` when the broadcast is ready to be sent and `scheduled` when it will be sent at `scheduleDate`" }, "scheduleDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "batchSize": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "batchInterval": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "allowedSendTimeStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedSendTimeEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowedSendTimeTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "type", "title", "status", "scheduleDate", "batchSize", "batchInterval", "allowedSendTimeStart", "allowedSendTimeEnd", "allowedSendTimeTimezone", "createDate" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Phone number not found" } } } }, "/broadcasts/{broadcastId}": { "get": { "tags": [ "Broadcasts" ], "summary": "Get a broadcast by ID", "parameters": [ { "in": "path", "name": "broadcastId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "responses": { "200": { "description": "Broadcast details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "status", "createDate" ], "additionalProperties": false } } } }, "404": { "description": "Broadcast not found" } } } }, "/broadcasts/{broadcastId}/send": { "post": { "tags": [ "Broadcasts" ], "summary": "Send a broadcast by ID", "parameters": [ { "in": "path", "name": "broadcastId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "responses": { "204": { "description": "Broadcast sent successfully" }, "404": { "description": "Broadcast not found" }, "409": { "description": "Broadcast is not in a status that can be sent" } } } }, "/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "Lists the contacts of the workspace, 25 per page.\n\nAny query parameter other than `cursor`, `waId` and `phoneNumber` is treated as a filter on a custom contact property of the workspace — e.g. `?plan=premium` returns the contacts whose `plan` property equals `premium`.\n\nWhen more results are available, `cursors.next` is returned. Pass it back as `cursor` to fetch the next page; the original filters are preserved by the cursor.", "parameters": [ { "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor returned by a previous call, used to fetch the next page", "type": "string" }, "description": "Opaque cursor returned by a previous call, used to fetch the next page" }, { "in": "query", "name": "waId", "schema": { "description": "Filters by the WhatsApp id of the contact", "type": "string" }, "description": "Filters by the WhatsApp id of the contact" }, { "in": "query", "name": "phoneNumber", "schema": { "description": "Filters by the phone number of the contact", "type": "string" }, "description": "Filters by the phone number of the contact" } ], "responses": { "200": { "description": "A page of contacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "waId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "WhatsApp id of the contact" }, "waProfileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name in the WhatsApp profile of the contact" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occupation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "birthdate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "age": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "createDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updateDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "customProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Values of the custom contact properties of the workspace, keyed by property name" } }, "required": [ "id", "waId", "waProfileName", "firstName", "lastName", "email", "phone", "occupation", "gender", "birthdate", "age", "notes", "tags", "createDate", "updateDate", "customProperties" ], "additionalProperties": false } }, "cursors": { "type": "object", "properties": { "next": { "description": "Opaque cursor to fetch the next page. Absent when there are no more results", "type": "string" } }, "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "description": "Creates a contact in the workspace.\n\nTags are linked by `id` or `name` and must already exist in the workspace — unknown tags are ignored. Use `PATCH /contacts/{contactId}/tags` to create tags on demand.\n\n`customProperties` are keyed by property name and only properties already defined in the workspace are persisted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occupation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "birthdate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "age": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "description": "Tags to link to the contact. Only existing tags are linked", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Id of an existing tag", "type": "string" }, "name": { "description": "Name of an existing tag", "type": "string" } } } }, "customProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Values for the custom contact properties of the workspace, keyed by property name" } } }, "examples": { "complete": { "summary": "Contact with tags and custom properties", "value": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "5511999998888", "occupation": "Developer", "notes": "Met at the conference", "tags": [ { "name": "customers" } ], "customProperties": { "plan": "premium" } } }, "minimal": { "summary": "Contact with a phone number only", "value": { "phone": "5511999998888" } } } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created contact" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" } } } }, "/contacts/{contactId}": { "get": { "tags": [ "Contacts" ], "summary": "Get a contact by id", "parameters": [ { "in": "path", "name": "contactId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "responses": { "200": { "description": "Contact details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "waId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "WhatsApp id of the contact" }, "waProfileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name in the WhatsApp profile of the contact" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occupation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "birthdate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "age": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "createDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updateDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "customProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Values of the custom contact properties of the workspace, keyed by property name" } }, "required": [ "id", "waId", "waProfileName", "firstName", "lastName", "fullName", "email", "phone", "occupation", "gender", "birthdate", "age", "notes", "tags", "createDate", "updateDate", "customProperties" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Contact not found" } } }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Updates the given fields of a contact. Omitted fields are left untouched; sending `null` clears the field.\n\nTags are linked by `id` or `name` and must already exist in the workspace — unknown tags are ignored. Use `PATCH /contacts/{contactId}/tags` to create tags on demand.", "parameters": [ { "in": "path", "name": "contactId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occupation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "birthdate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "age": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "description": "Only tags that already exist in the workspace are linked", "type": "object", "properties": { "add": { "description": "Tags to link to the contact, keeping the current ones", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Id of an existing tag", "type": "string" }, "name": { "description": "Name of an existing tag", "type": "string" } } } }, "remove": { "description": "Tags to unlink from the contact", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Id of an existing tag", "type": "string" }, "name": { "description": "Name of an existing tag", "type": "string" } } } }, "set": { "description": "Replaces all tags of the contact. When provided, `add` and `remove` are ignored", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Id of an existing tag", "type": "string" }, "name": { "description": "Name of an existing tag", "type": "string" } } } } } }, "customProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "Values for the custom contact properties of the workspace, keyed by property name" } } }, "examples": { "fields": { "summary": "Update contact fields", "value": { "firstName": "John", "occupation": "Engineering Manager" } }, "tags": { "summary": "Add and remove tags", "value": { "tags": { "add": [ { "name": "customers" } ], "remove": [ { "name": "leads" } ] } } } } } } }, "responses": { "204": { "description": "Contact updated successfully" }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Contact not found" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "parameters": [ { "in": "path", "name": "contactId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the deleted contact" } }, "required": [ "id" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Contact not found" } } } }, "/contacts/{contactId}/tags": { "patch": { "tags": [ "Contacts" ], "summary": "Update the tags of a contact", "description": "Links and unlinks tags of a contact. Each tag is referenced by `id` or by `name`.\n\nUnlike the `tags` field of `PATCH /contacts/{contactId}`, a tag referenced by `name` is created when it does not exist yet, and referencing an `id` that does not exist in the workspace returns `404`.\n\nWhen `set` is provided it replaces all tags of the contact and `add`/`remove` are ignored. At most 10 tags per field.", "parameters": [ { "in": "path", "name": "contactId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "add": { "description": "Tags to link to the contact, keeping the current ones", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Id of an existing tag", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the tag. The tag is created when it does not exist yet", "type": "string", "minLength": 1 } } } }, "remove": { "description": "Tags to unlink from the contact", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Id of an existing tag", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the tag. The tag is created when it does not exist yet", "type": "string", "minLength": 1 } } } }, "set": { "description": "Replaces all tags of the contact. When provided, `add` and `remove` are ignored", "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Id of an existing tag", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the tag. The tag is created when it does not exist yet", "type": "string", "minLength": 1 } } } } } }, "examples": { "addAndRemove": { "summary": "Add and remove tags", "value": { "add": [ { "name": "customers" } ], "remove": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } }, "set": { "summary": "Replace all tags", "value": { "set": [ { "name": "customers" }, { "name": "vip" } ] } } } } } }, "responses": { "204": { "description": "Tags updated successfully" }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Contact or tag not found" } } } }, "/conversation-sessions/enqueue": { "post": { "tags": [ "Conversation sessions" ], "summary": "Enqueue a conversation session", "description": "Enqueues the open conversation session for a contact into a queue and persists the observation as transfer_observation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "waId": { "type": "string", "minLength": 1, "description": "Contact WhatsApp ID" }, "phoneNumberWaId": { "type": "string", "minLength": 1, "description": "Business phone WhatsApp ID" }, "queueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Queue id" }, "observation": { "type": "string", "minLength": 1, "maxLength": 400, "description": "Observation persisted on the session as transfer_observation" } }, "required": [ "waId", "phoneNumberWaId", "queueId", "observation" ] } } } }, "responses": { "200": { "description": "Session enqueued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string" }, "currentQueueId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "enqueueDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "ticketId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "transferObservation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "conversationId", "status", "currentQueueId", "enqueueDate", "ticketId", "transferObservation" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Queue, conversation, or open session not found" }, "500": { "description": "Internal server error" } } } }, "/messages/text": { "post": { "tags": [ "Messages" ], "summary": "Send text message", "description": "Requires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "text": { "type": "object", "properties": { "body": { "type": "string", "description": "Message body" } }, "required": [ "body" ], "description": "Text content of the message" } }, "required": [ "from", "to", "text" ] }, "examples": { "text": { "summary": "Simple text message", "value": { "from": "5511999998888", "to": "5599888887777", "text": { "body": "Hello!" } } } } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/image": { "post": { "tags": [ "Messages" ], "summary": "Send image message", "description": "Provide either `id`, for a media previously uploaded through `POST /messages/upload-media`, or `link`, a public URL WhatsApp can download from.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "image": { "description": "The image to send. Provide either `id` or `link`", "type": "object", "properties": { "id": { "description": "Id of a media uploaded through `POST /messages/upload-media`", "type": "string" }, "link": { "description": "Public URL of the media", "type": "string", "format": "uri" }, "caption": { "description": "Caption shown with the image", "type": "string" } } } }, "required": [ "from", "to" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/video": { "post": { "tags": [ "Messages" ], "summary": "Send video message", "description": "Provide either `id`, for a media previously uploaded through `POST /messages/upload-media`, or `link`, a public URL WhatsApp can download from.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "video": { "description": "The video to send. Provide either `id` or `link`", "type": "object", "properties": { "id": { "description": "Id of a media uploaded through `POST /messages/upload-media`", "type": "string" }, "link": { "description": "Public URL of the media", "type": "string", "format": "uri" }, "caption": { "description": "Caption shown with the video", "type": "string" } } } }, "required": [ "from", "to" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/audio": { "post": { "tags": [ "Messages" ], "summary": "Send audio message", "description": "Provide either `id`, for a media previously uploaded through `POST /messages/upload-media`, or `link`, a public URL WhatsApp can download from.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "audio": { "description": "The audio to send. Provide either `id` or `link`", "type": "object", "properties": { "id": { "description": "Id of a media uploaded through `POST /messages/upload-media`", "type": "string" }, "link": { "description": "Public URL of the media", "type": "string", "format": "uri" } } } }, "required": [ "from", "to" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/document": { "post": { "tags": [ "Messages" ], "summary": "Send document message", "description": "Provide either `id`, for a media previously uploaded through `POST /messages/upload-media`, or `link`, a public URL WhatsApp can download from.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "document": { "description": "The document to send. Provide either `id` or `link`", "type": "object", "properties": { "id": { "description": "Id of a media uploaded through `POST /messages/upload-media`", "type": "string" }, "link": { "description": "Public URL of the media", "type": "string", "format": "uri" }, "caption": { "description": "Caption shown with the document", "type": "string" }, "filename": { "description": "File name shown to the recipient", "type": "string" } } } }, "required": [ "from", "to" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/sticker": { "post": { "tags": [ "Messages" ], "summary": "Send sticker message", "description": "Provide either `id`, for a media previously uploaded through `POST /messages/upload-media`, or `link`, a public URL WhatsApp can download from.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "sticker": { "description": "The sticker to send. Provide either `id` or `link`", "type": "object", "properties": { "id": { "description": "Id of a media uploaded through `POST /messages/upload-media`", "type": "string" }, "link": { "description": "Public URL of the media", "type": "string", "format": "uri" } } } }, "required": [ "from", "to" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/location": { "post": { "tags": [ "Messages" ], "summary": "Send location message", "description": "Requires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "location": { "type": "object", "properties": { "longitude": { "type": "number", "description": "Longitude of the location" }, "latitude": { "type": "number", "description": "Latitude of the location" }, "name": { "description": "Name of the location", "type": "string" }, "address": { "description": "Address of the location", "type": "string" } }, "required": [ "longitude", "latitude" ], "description": "The location to send" } }, "required": [ "from", "to", "location" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/contacts": { "post": { "tags": [ "Messages" ], "summary": "Send contacts message", "description": "Sends one or more contact cards.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "contacts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "object", "properties": { "formatted_name": { "type": "string", "description": "Full name as it should be displayed" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "middle_name": { "type": "string" }, "suffix": { "type": "string" }, "prefix": { "type": "string" } }, "required": [ "formatted_name" ] }, "phones": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string" }, "type": { "description": "Phone type, e.g. CELL, HOME or WORK", "type": "string" }, "wa_id": { "description": "WhatsApp id of the phone number", "type": "string" } }, "required": [ "phone" ] } }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string" }, "type": { "description": "Address type, e.g. HOME or WORK", "type": "string" } } } }, "birthday": { "description": "Birthday in YYYY-MM-DD format", "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "type": { "description": "Email type, e.g. HOME or WORK", "type": "string" } } } }, "org": { "type": "object", "properties": { "company": { "type": "string" }, "department": { "type": "string" }, "title": { "type": "string" } } }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "description": "URL type, e.g. HOME or WORK", "type": "string" } } } } }, "required": [ "name" ] }, "description": "Contact cards to send" } }, "required": [ "from", "to", "contacts" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/reaction": { "post": { "tags": [ "Messages" ], "summary": "Send reaction message", "description": "Reacts to a message previously exchanged in the conversation. `reaction.message_id` is the WhatsApp id of the message being reacted to, and must belong to the workspace. Send an empty `emoji` to remove a reaction.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "reaction": { "description": "The reaction to send", "type": "object", "properties": { "message_id": { "description": "WhatsApp id of the message being reacted to", "type": "string" }, "emoji": { "description": "Emoji of the reaction. Send an empty string to remove it", "type": "string" } } } }, "required": [ "from", "to" ] } } } }, "responses": { "200": { "description": "Reaction sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data or missing `reaction.message_id`" }, "401": { "description": "Unauthorized" }, "404": { "description": "Reacted message or sender phone number not found" } } } }, "/messages/template": { "post": { "tags": [ "Messages" ], "summary": "Send template message", "description": "Sends an approved WhatsApp template message. This is the only message type that reaches recipients that never messaged the business or whose service window is closed.\n\nWhen the template contains a FLOW button, the request must include the matching `button` component with `sub_type: flow`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "template": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the approved WhatsApp template" }, "language": { "type": "object", "properties": { "code": { "type": "string", "description": "Language code of the template, e.g. `pt_BR`" } }, "required": [ "code" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Component type, e.g. `header`, `body` or `button`" }, "sub_type": { "description": "Button sub type, e.g. `flow` or `url`", "type": "string" }, "index": { "description": "Index of the button, starting at 0", "type": "integer", "minimum": 0, "maximum": 2 }, "parameters": { "description": "Parameters that fill the component placeholders", "type": "array", "items": {} }, "cards": { "description": "Cards of a carousel template", "type": "array", "items": { "type": "object", "properties": { "card_index": { "type": "number" }, "components": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Component type, e.g. `header`, `body` or `button`" }, "sub_type": { "description": "Button sub type, e.g. `flow` or `url`", "type": "string" }, "index": { "description": "Index of the button, starting at 0", "type": "integer", "minimum": 0, "maximum": 2 }, "parameters": { "description": "Parameters that fill the component placeholders", "type": "array", "items": {} } }, "required": [ "type" ] } } }, "required": [ "card_index" ] } } }, "required": [ "type" ] } } }, "required": [ "name", "language" ] } }, "required": [ "from", "to", "template" ] }, "examples": { "positional": { "summary": "Template with positional body parameters", "value": { "from": "5511999998888", "to": "5599888887777", "template": { "name": "appointment_reminder", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "John" } ] } ] } } } } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" }, "contact": { "type": "object", "properties": { "waId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "WhatsApp id of the recipient" }, "waUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "waId" ], "additionalProperties": false } }, "required": [ "id", "contact" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/interactive/button": { "post": { "tags": [ "Messages" ], "summary": "Send interactive button message", "description": "Sends up to 3 reply buttons.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "interactive": { "type": "object", "properties": { "type": { "default": "button", "type": "string", "const": "button" }, "header": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image", "video", "document" ] }, "text": { "type": "string" } }, "required": [ "type" ] }, "body": { "type": "object", "properties": { "text": { "type": "string" } } }, "footer": { "type": "object", "properties": { "text": { "type": "string" } } }, "action": { "type": "object", "properties": { "buttons": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "reply": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "minLength": 1, "maxLength": 20 } }, "required": [ "id", "title" ] } }, "required": [ "type", "reply" ] }, "description": "Up to 3 reply buttons" } }, "required": [ "buttons" ] } }, "required": [ "body", "action" ] } }, "required": [ "from", "to", "interactive" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/interactive/cta_url": { "post": { "tags": [ "Messages" ], "summary": "Send interactive CTA URL message", "description": "Sends a message with a button that opens a URL.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "interactive": { "type": "object", "properties": { "type": { "default": "cta_url", "type": "string", "const": "cta_url" }, "header": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image", "video", "document" ] }, "text": { "type": "string" } }, "required": [ "type" ] }, "body": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "footer": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "action": { "type": "object", "properties": { "name": { "default": "cta_url", "type": "string", "const": "cta_url" }, "parameters": { "type": "object", "properties": { "display_text": { "type": "string", "description": "Label of the button" }, "url": { "type": "string", "format": "uri", "description": "URL opened when the button is tapped" } }, "required": [ "display_text", "url" ] } }, "required": [ "parameters" ] } }, "required": [ "body", "action" ] } }, "required": [ "from", "to", "interactive" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/interactive/list": { "post": { "tags": [ "Messages" ], "summary": "Send interactive list message", "description": "Sends a message with a list of selectable options.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "interactive": { "type": "object", "properties": { "type": { "default": "list", "type": "string", "const": "list" }, "header": { "type": "object", "properties": { "type": { "type": "string", "const": "text" } }, "required": [ "type" ] }, "body": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "footer": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "action": { "type": "object", "properties": { "button": { "type": "string", "description": "Label of the button that opens the list" }, "sections": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 24 }, "rows": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "maxLength": 24 }, "description": { "type": "string" } }, "required": [ "id", "title" ] } } }, "required": [ "title", "rows" ] } } }, "required": [ "button", "sections" ] } }, "required": [ "body", "action" ] } }, "required": [ "from", "to", "interactive" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/interactive/flow": { "post": { "tags": [ "Messages" ], "summary": "Send interactive flow message", "description": "Sends a message with a button that opens a published WhatsApp flow.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "interactive": { "type": "object", "properties": { "type": { "default": "flow", "type": "string", "const": "flow" }, "header": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image", "video", "document" ] } }, "required": [ "type" ] }, "body": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "footer": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "action": { "type": "object", "properties": { "name": { "default": "flow", "type": "string", "const": "flow" }, "parameters": { "type": "object", "properties": { "flow_cta": { "type": "string", "description": "Label of the button that opens the flow" }, "flow_name": { "type": "string", "description": "Name of the published WhatsApp flow" }, "flow_message_version": { "default": 3, "type": "number" }, "flow_action": { "default": "navigate", "type": "string", "enum": [ "navigate", "data_exchange" ] }, "flow_action_payload": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "flow_cta", "flow_name" ] } }, "required": [ "parameters" ] } }, "required": [ "body", "action" ] } }, "required": [ "from", "to", "interactive" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/interactive/carousel": { "post": { "tags": [ "Messages" ], "summary": "Send interactive carousel message", "description": "Sends up to 10 cards, each with its own header and action.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "interactive": { "type": "object", "properties": { "type": { "default": "carousel", "type": "string", "const": "carousel" }, "body": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 1024 } }, "required": [ "text" ] }, "action": { "type": "object", "properties": { "cards": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "card_index": { "type": "number" }, "type": { "type": "string", "const": "cta_url" }, "header": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image" ] }, "text": { "description": "Header text. Required when `type` is `text`", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "description": "Header image. Required when `type` is `image`", "anyOf": [ { "type": "object", "properties": { "link": { "type": "string", "format": "uri" } }, "required": [ "link" ] }, { "type": "null" } ] } }, "required": [ "type" ] }, "body": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 160 } }, "required": [ "text" ] }, "action": { "type": "object", "properties": { "name": { "type": "string", "const": "cta_url" }, "parameters": { "type": "object", "properties": { "display_text": { "type": "string", "maxLength": 20, "description": "Label of the button" }, "url": { "type": "string", "format": "uri", "description": "URL opened when the button is tapped" } }, "required": [ "display_text", "url" ] }, "buttons": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "quick_reply" }, "quick_reply": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 256 }, "title": { "type": "string", "maxLength": 20 } }, "required": [ "id", "title" ] } }, "required": [ "type", "quick_reply" ] } }, { "type": "null" } ] } } } }, "required": [ "card_index", "type", "header", "action" ] }, "description": "Up to 10 cards" } }, "required": [ "cards" ] } }, "required": [ "body", "action" ] } }, "required": [ "from", "to", "interactive" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/interactive/order_details": { "post": { "tags": [ "Messages" ], "summary": "Send interactive order details message", "description": "Sends an order summary with payment instructions. Amounts are integers scaled by `offset` — `{ value: 1050, offset: 100 }` means 10.50.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "interactive": { "type": "object", "properties": { "type": { "default": "order_details", "type": "string", "const": "order_details" }, "header": { "type": "object", "properties": { "type": { "type": "string", "const": "image" } }, "required": [ "type" ] }, "body": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 1024 } }, "required": [ "text" ] }, "footer": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "action": { "type": "object", "properties": { "name": { "default": "review_and_pay", "type": "string", "const": "review_and_pay" }, "parameters": { "type": "object", "properties": { "reference_id": { "type": "string", "maxLength": 35, "description": "Your reference for the order" }, "type": { "type": "string", "enum": [ "digital-goods", "physical-goods" ] }, "payment_type": { "default": "br", "type": "string", "const": "br" }, "payment_settings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "pix_dynamic_code", "payment_link", "boleto" ] }, "pix_dynamic_code": { "type": "object", "properties": { "code": { "type": "string" }, "merchant_name": { "type": "string" }, "key": { "type": "string" }, "key_type": { "type": "string", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ] } }, "required": [ "code", "merchant_name", "key", "key_type" ] }, "payment_link": { "type": "object", "properties": { "uri": { "type": "string", "format": "uri" } }, "required": [ "uri" ] }, "boleto": { "type": "object", "properties": { "digitable_line": { "type": "string" } }, "required": [ "digitable_line" ] } }, "required": [ "type" ] } }, "currency": { "default": "BRL", "type": "string", "const": "BRL" }, "total_amount": { "type": "object", "properties": { "value": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "default": 100, "type": "number", "const": 100 }, "description": { "type": "string", "maxLength": 60 } }, "required": [ "value" ] }, "order": { "type": "object", "properties": { "status": { "default": "pending", "type": "string", "const": "pending" }, "catalog_id": { "type": "string" }, "expiration": { "type": "object", "properties": { "timestamp": { "type": "string" }, "description": { "type": "string", "maxLength": 300 } }, "required": [ "timestamp", "description" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "retailer_id": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "object", "properties": { "value": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "default": 100, "type": "number", "const": 100 }, "description": { "type": "string", "maxLength": 60 } }, "required": [ "value" ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sale_amount": { "type": "object", "properties": { "value": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "default": 100, "type": "number", "const": 100 }, "description": { "type": "string", "maxLength": 60 } }, "required": [ "value" ] } }, "required": [ "retailer_id", "name", "amount" ] } }, "subtotal": { "type": "object", "properties": { "value": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "default": 100, "type": "number", "const": 100 }, "description": { "type": "string", "maxLength": 60 } }, "required": [ "value" ] }, "tax": { "type": "object", "properties": { "value": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "default": 100, "type": "number", "const": 100 }, "description": { "type": "string", "maxLength": 60 } }, "required": [ "value" ] }, "shipping": { "type": "object", "properties": { "value": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "default": 100, "type": "number", "const": 100 }, "description": { "type": "string", "maxLength": 60 } }, "required": [ "value" ] }, "discount": { "type": "object", "properties": { "value": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "default": 100, "type": "number", "const": 100 }, "description": { "type": "string", "maxLength": 60 }, "discount_program_name": { "type": "string", "maxLength": 60 } }, "required": [ "value" ] } }, "required": [ "subtotal", "tax" ] } }, "required": [ "reference_id", "type", "payment_settings", "total_amount", "order" ] } }, "required": [ "parameters" ] } }, "required": [ "body", "action" ] } }, "required": [ "from", "to", "interactive" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/interactive/order_status": { "post": { "tags": [ "Messages" ], "summary": "Send interactive order status message", "description": "Updates the status of an order previously sent through `POST /messages/interactive/order_details`, matched by `reference_id`.\n\nRequires an open service window: the recipient must have messaged the business in the last 24 hours. Use `POST /messages/template` to reach recipients outside that window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "description": "WhatsApp id of the sender phone number" }, "to": { "type": "string", "minLength": 1, "description": "Recipient phone number, digits only, including country code" }, "interactive": { "type": "object", "properties": { "type": { "default": "order_status", "type": "string", "const": "order_status" }, "header": { "type": "object", "properties": { "type": { "type": "string", "const": "image" } }, "required": [ "type" ] }, "body": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 1024 } }, "required": [ "text" ] }, "footer": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 60 } }, "required": [ "text" ] }, "action": { "type": "object", "properties": { "name": { "default": "review_order", "type": "string", "const": "review_order" }, "parameters": { "type": "object", "properties": { "reference_id": { "type": "string", "description": "Reference id of the order sent in the order details message" }, "order": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "processing", "partially-shipped", "shipped", "completed", "canceled" ] }, "description": { "type": "string", "maxLength": 120 } }, "required": [ "status" ] }, "payment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "captured", "failed" ] }, "timestamp": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "status" ] } }, "required": [ "reference_id", "order" ] } }, "required": [ "parameters" ] } }, "required": [ "body", "action" ] } }, "required": [ "from", "to", "interactive" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the created message" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sender phone number not found or not linked to a WhatsApp Business Account" } } } }, "/messages/{messageId}": { "get": { "tags": [ "Messages" ], "summary": "Get a message by id", "parameters": [ { "in": "path", "name": "messageId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "responses": { "200": { "description": "Message details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workspaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "userId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "whatsappMessageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the message in the WhatsApp API" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "WhatsApp id of the sender phone number" }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient phone number" }, "role": { "type": "string", "enum": [ "user", "assistant", "tool", "internal" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Delivery status reported by WhatsApp" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Message type, e.g. `text`, `image` or `interactive`" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Textual content of the message, when it has one" }, "contentData": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Type-specific payload of the message" }, "createDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "sendDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "deliverDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "readDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "conversationId", "userId", "whatsappMessageId", "from", "to", "role", "status", "type", "content", "contentData", "createDate", "sendDate", "deliverDate", "readDate" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Message not found" } } } }, "/tags": { "get": { "tags": [ "Tags" ], "summary": "List tags", "description": "Lists every tag of the workspace, ordered by name.", "responses": { "200": { "description": "The tags of the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the tag" }, "name": { "type": "string", "description": "Name of the tag" } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": "Tags of the workspace, ordered by name" } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "Tags" ], "summary": "Create a tag", "description": "Creates a tag in the workspace.\n\nThe name is trimmed before being stored. Tag names are unique within the workspace, so reusing an existing name returns `409`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Name of the tag. Must be unique within the workspace" } }, "required": [ "name" ] }, "examples": { "default": { "summary": "Create a tag", "value": { "name": "customers" } } } } } }, "responses": { "201": { "description": "Tag created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the tag" }, "name": { "type": "string", "description": "Name of the tag" } }, "required": [ "id", "name" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "409": { "description": "A tag with the given name already exists" } } } }, "/tags/{tagId}": { "get": { "tags": [ "Tags" ], "summary": "Get a tag by id", "parameters": [ { "in": "path", "name": "tagId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "responses": { "200": { "description": "Tag details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the tag" }, "name": { "type": "string", "description": "Name of the tag" } }, "required": [ "id", "name" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid tag id" }, "401": { "description": "Unauthorized" }, "404": { "description": "Tag not found" } } }, "patch": { "tags": [ "Tags" ], "summary": "Rename a tag", "description": "Updates the name of a tag. Contacts and conversations linked to the tag keep their link.\n\nThe name is trimmed before being stored. Tag names are unique within the workspace, so reusing an existing name returns `409`.", "parameters": [ { "in": "path", "name": "tagId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Name of the tag. Must be unique within the workspace" } }, "required": [ "name" ] }, "examples": { "default": { "summary": "Rename a tag", "value": { "name": "vip-customers" } } } } } }, "responses": { "200": { "description": "Tag updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the tag" }, "name": { "type": "string", "description": "Name of the tag" } }, "required": [ "id", "name" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid input data" }, "401": { "description": "Unauthorized" }, "404": { "description": "Tag not found" }, "409": { "description": "A tag with the given name already exists" } } }, "delete": { "tags": [ "Tags" ], "summary": "Delete a tag", "description": "Deletes a tag from the workspace. Returns the tag that was deleted.", "parameters": [ { "in": "path", "name": "tagId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "responses": { "200": { "description": "Tag deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Id of the tag" }, "name": { "type": "string", "description": "Name of the tag" } }, "required": [ "id", "name" ], "additionalProperties": false } } } }, "400": { "description": "Bad request, invalid tag id" }, "401": { "description": "Unauthorized" }, "404": { "description": "Tag not found" } } } } } }