{ "openapi": "3.1.0", "info": { "title": "ZapZap API", "description": "REST API to connect WhatsApp numbers by QR code and to send, receive and automate messages. Authenticate with the `x-api-key` and `x-api-secret` headers (Settings and API in the dashboard). The channel uses a QR code and is not Meta's official API: WhatsApp can restrict numbers that send unwanted messages. Docs: https://zapzapapi.com/en/docs", "version": "1.0.0", "contact": { "name": "ZapZap API", "url": "https://zapzapapi.com" } }, "servers": [ { "url": "https://api.zapzapapi.com/api/v1" } ], "tags": [ { "name": "Account and Instances" }, { "name": "Send Messages" }, { "name": "Conversations" }, { "name": "Contacts and Profile" }, { "name": "Groups" }, { "name": "Newsletters and Channels" }, { "name": "Campaigns" }, { "name": "Calls" }, { "name": "WhatsApp Business" }, { "name": "Settings" }, { "name": "Webhooks and Events" }, { "name": "Async Queue" }, { "name": "Chatbot and AI" }, { "name": "CRM and Leads" }, { "name": "Chatwoot Integration" }, { "name": "Flows" }, { "name": "Meta Tracking" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "ApiSecret": { "type": "apiKey", "in": "header", "name": "x-api-secret" } } }, "security": [ { "ApiKey": [], "ApiSecret": [] } ], "paths": { "/account": { "get": { "operationId": "management_account", "summary": "Account Details", "description": "Returns your account data: name, email, current balance, billing day, and status.", "tags": [ "Account and Instances" ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "uuid", "name": "João", "email": "joao@email.com", "balance": "150.00", "billing_day": 10, "status": "ACTIVE" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/instances": { "get": { "operationId": "management_list_instances", "summary": "List Instances", "description": "Lists all WhatsApp instances in your account with status, name, phone, and settings.", "tags": [ "Account and Instances" ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "uuid", "name": "minha-instancia", "status": "CONNECTED", "phone_number": "5511999999999" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "post": { "operationId": "management_create_instance", "summary": "Create Instance", "description": "Creates a new WhatsApp instance. Automatically debits the balance (activation fee + prorated amount). The name must contain only letters, numbers, _ and -.", "tags": [ "Account and Instances" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Instance name", "type": "string", "example": "minha-instancia" }, "systemName": { "description": "System name (displayed on WhatsApp)", "type": "string", "example": "Meu App" }, "metadata": { "description": "Free-form data (JSON): link it to your system (e.g. clientId, plan)", "type": "string", "example": "{\"clientId\":\"123\",\"plan\":\"pro\"}" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "instance": { "id": "uuid", "name": "minha-instancia", "status": "PENDING" }, "billing": { "charged": 10.5 } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/instances/cost": { "get": { "operationId": "management_creation_cost", "summary": "Creation Cost", "description": "Returns the cost to create a new instance: activation fee, prorated amount, and required balance.", "tags": [ "Account and Instances" ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "activationFee": 3, "prorate": 7.5, "total": 10.5, "instancePrice": 15, "currentBalance": 150 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/instances/{id}": { "delete": { "operationId": "management_delete_instance", "summary": "Delete Instance", "description": "Deletes (soft delete) an instance. WhatsApp is disconnected and an activation fee waiver is generated for the next creation.", "tags": [ "Account and Instances" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Instância deletada com sucesso" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "get": { "operationId": "management_get_instance", "summary": "Instance Details", "description": "Returns details of a specific instance.", "tags": [ "Account and Instances" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "uuid", "name": "MinhaInstancia", "status": "CONNECTED", "phone_number": "5511999999999" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "put": { "operationId": "management_update_instance", "summary": "Update Instance", "description": "Updates the webhook_url and/or metadata of an instance. The metadata is free-form JSON to link the instance to your system (e.g. customer ID, plan, etc). The metadata is automatically included in the webhooks you receive.", "tags": [ "Account and Instances" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance ID", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "description": "Webhook URL (HTTPS)", "type": "string", "example": "https://meusite.com/webhook" }, "metadata": { "description": "Free-form data (JSON)", "type": "string", "example": "{\"clientId\":\"123\"}" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "uuid", "name": "minha-instancia", "webhook_url": "https://meusite.com/webhook", "metadata": { "clientId": "123" } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/instances/{id}/qrcode": { "get": { "operationId": "management_qrcode", "summary": "Instance QR Code", "description": "Returns the QR Code to connect WhatsApp to the instance. Scan it with your phone.", "tags": [ "Account and Instances" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "connected": true, "instance": { "status": "connected", "profileName": "Nome" } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/instances/{id}/webhook": { "get": { "operationId": "gestao_webhook_get", "summary": "View Webhook", "description": "Returns the webhook URL configured for the instance. The webhook receives real-time events (messages, status, etc).\n\n⚠️ URL WARNING: {id} is already in the path: do NOT add it twice.\n\n✅ Correct: GET /api/v1/instances/YOUR-INSTANCE-ID/webhook\n❌ Wrong: GET /api/v1/YOUR-INSTANCE-ID/instances/YOUR-INSTANCE-ID/webhook (duplicated instanceId)", "tags": [ "Account and Instances" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "webhook_url": "https://meusite.com/webhook", "configured": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "put": { "operationId": "gestao_webhook_put", "summary": "Configure Webhook", "description": "Sets or updates the instance webhook URL. The URL must be public and reachable over HTTPS. Events such as received messages, delivery status, and connection changes will be sent via POST to this URL.\n\n⚠️ URL WARNING: {id} is already in the path: do NOT add it twice.\n\n✅ Correct: PUT /api/v1/instances/YOUR-INSTANCE-ID/webhook\n❌ Wrong: PUT /api/v1/YOUR-INSTANCE-ID/instances/YOUR-INSTANCE-ID/webhook (duplicated instanceId)", "tags": [ "Account and Instances" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "description": "Webhook URL (HTTPS)", "type": "string", "example": "https://meusite.com/webhook" }, "events": { "description": "Events to receive (empty = all)", "type": "string", "example": "messages,status" }, "excludeMessages": { "description": "Exclude own messages", "type": "boolean" } }, "required": [ "webhook_url" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "webhook_url": "https://meusite.com/webhook" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/instances/{id}/webhook/test": { "post": { "operationId": "gestao_webhook_test", "summary": "Test Webhook", "description": "Sends a test event to the configured webhook URL. Returns the status code and response time. Useful to validate that your server is receiving events correctly.\n\n⚠️ URL WARNING: {id} is already in the path: do NOT add it twice.\n\n✅ Correct: POST /api/v1/instances/YOUR-INSTANCE-ID/webhook/test\n❌ Wrong: POST /api/v1/YOUR-INSTANCE-ID/instances/YOUR-INSTANCE-ID/webhook/test (duplicated instanceId)", "tags": [ "Account and Instances" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance ID", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "Alternative URL for testing (optional)", "type": "string", "example": "https://meusite.com/webhook" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "statusCode": 200, "responseTime": 150 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/wa_messages_limits": { "get": { "operationId": "instance_wa_limits", "summary": "New Conversation Limits (WhatsApp)", "description": "Queries the current limit of new conversations that WhatsApp allows starting from this number (the account 'tier'). Useful to track warm-up and avoid blocks from excessive sending.", "tags": [ "Account and Instances" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/carousel": { "post": { "operationId": "send_carousel", "summary": "Send Carousel", "description": "Sends a carousel of cards with an image and action buttons. Each item of the `carousel` array represents a card with `text`, `image`, and `buttons: [{type,text,id}]`.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "text": { "description": "Main message text", "type": "string", "example": "Confira nossas opções:" }, "carousel": { "description": "Cards (JSON array)", "example": [ { "text": "Produto 1", "image": "https://exemplo.com/img.jpg", "buttons": [ { "type": "REPLY", "text": "Quero!", "id": "quero" } ] } ] }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "text", "carousel" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/contact": { "post": { "operationId": "send_contact", "summary": "Send Contact (vCard)", "description": "Sends a contact card (vCard) with name and phone.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Recipient number", "type": "string", "example": "5511999999999" }, "fullName": { "description": "Contact's full name", "type": "string", "example": "João Silva" }, "phoneNumber": { "description": "Phone numbers (comma-separated)", "type": "string", "example": "5511999999999,5511888888888" }, "organization": { "description": "Company / Organization", "type": "string", "example": "Empresa XYZ" }, "email": { "description": "Contact's email", "type": "string", "example": "joao@empresa.com" }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "fullName", "phoneNumber" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/location": { "post": { "operationId": "send_location", "summary": "Send Location", "description": "Sends a geographic location with a map pin. The recipient can open it directly in Google Maps or Apple Maps.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "latitude": { "description": "Latitude", "type": "number", "example": -23.5505 }, "longitude": { "description": "Longitude", "type": "number", "example": -46.6333 }, "name": { "description": "Place name", "type": "string", "example": "Sede da empresa" }, "address": { "description": "Address", "type": "string", "example": "Av. Paulista, 1000 - São Paulo" }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "latitude", "longitude" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/location-button": { "post": { "operationId": "send_location_button", "summary": "Request Location", "description": "Sends a message with a button that asks for the user's location. The share location button is added automatically.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "text": { "description": "Message text", "type": "string", "example": "Compartilhe sua localização para entregarmos seu pedido:" }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "text" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/media": { "post": { "operationId": "send_media", "summary": "Send Media", "description": "Sends a media file to a contact. The file must be accessible at a public URL.\n\nAvailable types:\n• image: Image (JPG, PNG, GIF, WebP). Supports a caption via text.\n• video: Video (MP4, AVI, MOV). Supports a caption via text.\n• audio: Audio as a file (MP3, OGG, WAV). Appears with an audio file icon.\n• ptt: Push-to-Talk: audio that appears as a voice message (microphone bubble). Ideal for humanizing automations.\n• myaudio: Native WhatsApp audio (OGG/Opus). Similar to ptt, use it when you already have the file in the correct format.\n• ptv: Video message (round video note). Always arrives in circular format; 16:9 video is cropped at the center. Ignores the caption (the text field does not appear). Use MP4 H.264. Accepts long durations (tested 15 to 180 s) and size within the media limit.\n• document: Document (PDF, DOCX, XLSX, etc.). Use docName to set the name displayed in the chat.\n• sticker: Animated or static sticker (WebP).\n\nSize limit (sending by URL): image, video, and audio up to ~190 MB; document up to ~500 MB. Above that, WhatsApp rejects it (HTTP 413 / upload error). Note: when sending the file as base64 in the request body through the public API (/api/v1), the limit drops to ~2 MB. Therefore, for larger files, always send by URL.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "type": { "description": "Media type", "type": "string", "enum": [ "image", "video", "videoplay", "audio", "ptt", "myaudio", "ptv", "document", "sticker" ], "default": "image" }, "file": { "description": "File URL", "type": "string", "example": "https://..." }, "text": { "description": "Caption: images and videos", "type": "string", "example": "Descrição da mídia" }, "mentions": { "description": "Tag members (group only)", "type": "string", "example": "all" }, "docName": { "description": "File name: required for document", "type": "string", "example": "arquivo.pdf" }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "type", "file" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/buttons": { "post": { "operationId": "send_buttons", "summary": "Send Reply Buttons", "description": "Sends clickable buttons (up to 3). Each object in the `buttons` array becomes a different button type depending on the field used:\n\n• `text` + `id` → quick reply button (the contact taps it and the text is sent)\n• `text` + `url` → button that opens an external link\n• `text` + `phone` → call button\n• `text` + `copy` → button that copies a code to the clipboard\n\nWithout `image`, the message is sent with only text + buttons (clean header). With `image`, an image appears at the top. WhatsApp limitation: mixing reply with url/phone/copy in the same message may show an 'Open on your phone' notice.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Recipient number (with country code)", "type": "string", "example": "5511999999999" }, "text": { "description": "Message text", "type": "string", "example": "Como podemos ajudar?" }, "buttons": { "description": "Buttons (up to 3). Use text+id for reply, text+url for link, text+phone for call, text+copy for copying a code", "example": [ { "text": "Sim", "id": "yes" }, { "text": "Nosso site", "url": "https://exemplo.com" }, { "text": "Ligar", "phone": "+5511999999999" } ] }, "image": { "description": "Image URL at the top (optional)", "type": "string", "example": "https://exemplo.com/banner.jpg" }, "footer": { "description": "Footer text (optional)", "type": "string", "example": "Escolha uma opção" }, "delay": { "description": "Delay in ms before sending (optional)", "type": "number", "example": 1200 }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "text", "buttons" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageType": "InteractiveMessage", "status": "Pending" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/list": { "post": { "operationId": "send_list", "summary": "Send Options List", "description": "Sends a list menu with sections and selectable items. The contact taps the button and chooses an option.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Recipient number", "type": "string", "example": "5511999999999" }, "text": { "description": "Main text", "type": "string", "example": "Escolha uma opção:" }, "choices": { "description": "Options: use \"[Section]\" for a header and \"Item|id|description\" for each item", "example": [ "[Produtos]", "Camiseta|p1|R$ 50", "Calça|p2|R$ 120" ] }, "listButton": { "description": "Text of the button that opens the list", "type": "string", "example": "Ver opções" }, "footerText": { "description": "Footer (optional)", "type": "string" }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "text", "choices" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageType": "ListMessage", "status": "Pending" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/poll": { "post": { "operationId": "send_poll", "summary": "Send Poll", "description": "Sends a native WhatsApp poll. Contacts vote and the result arrives via webhook.\n\nPoll (type poll): use choices (list of options) and selectableCount (how many the user can select; >1 = multiple choice). WhatsApp accepts 12+ options. Votes arrive through the messages webhook as PollUpdateMessage with the vote field already decrypted (option text); in multiple choice it comes as the comma-separated list of current options, and a removed vote comes empty.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Recipient number", "type": "string", "example": "5511999999999" }, "text": { "description": "Poll question", "type": "string", "example": "Qual o melhor dia?" }, "choices": { "description": "Voting options (array of strings)", "example": [ "Segunda", "Terça", "Quarta" ] }, "selectableCount": { "description": "Votes allowed per person (0 = unlimited)", "type": "string", "default": "1" }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "text", "choices" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageType": "PollCreationMessage", "status": "Pending" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/pix-button": { "post": { "operationId": "send_pix_button", "summary": "Send PIX Button", "description": "Sends a native WhatsApp PIX payment button. The contact can copy the key and pay directly.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "ID of the chat the message will be sent to. It can be a phone number in international format, a group ID (`@g.us`), or a user ID (with `@s.whatsapp.net` or `@lid`).", "type": "string", "example": "5511999999999" }, "pixType": { "description": "PIX key type. Accepted values: CPF, CNPJ, PHONE, EMAIL or EVP", "type": "string", "enum": [ "EMAIL", "CPF", "CNPJ", "PHONE", "EVP" ], "example": "EVP" }, "pixKey": { "description": "PIX key value (CPF/CNPJ/phone/email/EVP)", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "pixName": { "description": "Name displayed as the PIX recipient (default \"Pix\" if empty)", "type": "string", "example": "Loja Exemplo" }, "async": { "description": "Queues the send for asynchronous processing", "type": "boolean" }, "delay": { "description": "Delay in milliseconds before sending (shows \"typing...\" on WhatsApp)", "type": "number", "example": 1200 }, "readchat": { "description": "Marks the chat as read after sending the message", "type": "boolean" }, "readmessages": { "description": "Marks recent messages as read after sending", "type": "boolean" }, "replyid": { "description": "ID of the message being replied to", "type": "string" }, "mentions": { "description": "List of mentioned numbers separated by commas", "type": "string" }, "track_source": { "description": "Tracking source (e.g. chatwoot, internal-crm)", "type": "string" }, "track_id": { "description": "Tracking identifier (accepts duplicate values)", "type": "string" }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "pixType", "pixKey" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/request-payment": { "post": { "operationId": "send_request_payment", "summary": "Request Payment", "description": "Sends a payment request with the native WhatsApp \"Review and pay\" button. You must provide at least one payment method: `pixKey`, `boletoCode`, `paymentLink` or `allowCards: true`. Otherwise, the API returns an error.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "amount": { "description": "Amount (BRL)", "type": "number", "example": 49.9 }, "pixKey": { "description": "PIX key (CPF/CNPJ/phone/email/EVP)", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "pixType": { "description": "PIX key type", "type": "string", "enum": [ "EVP", "CPF", "CNPJ", "PHONE", "EMAIL" ], "default": "EVP" }, "itemName": { "description": "Item name", "type": "string", "example": "Assinatura Plano Ouro" }, "invoiceNumber": { "description": "Invoice number", "type": "string", "example": "PED-123" }, "title": { "description": "Flow title", "type": "string", "example": "Detalhes do pedido" }, "footer": { "description": "Footer", "type": "string", "example": "Loja Exemplo" }, "pixName": { "description": "Recipient name (default: profile name)", "type": "string", "example": "Loja Exemplo" }, "text": { "description": "Message text", "type": "string", "example": "Pagamento referente ao pedido #123" }, "paymentLink": { "description": "External payment link", "type": "string", "example": "https://pagamento.exemplo.com/123" }, "fileUrl": { "description": "Attached file URL", "type": "string", "example": "https://..." }, "fileName": { "description": "Attached file name", "type": "string", "example": "boleto.pdf" }, "boletoCode": { "description": "Boleto code", "type": "string", "example": "34191.79001 01043.510047 91020.150008 8 87350026000" }, "allowCards": { "description": "Allow card", "type": "boolean" }, "currency": { "description": "Currency", "type": "string", "example": "BRL" }, "note": { "description": "Note / Remarks", "type": "string", "example": "Pagamento referente ao pedido #123" }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "amount" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/status": { "post": { "operationId": "send_status", "summary": "Send Status / Story", "description": "Publishes a status/story on WhatsApp (text, image, or video). Visible to all contacts for 24 hours.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Type", "type": "string", "enum": [ "text", "image", "video", "audio", "ptt" ], "default": "text" }, "text": { "description": "Text (for text type)", "type": "string", "example": "Olá mundo!" }, "background_color": { "description": "Background color (text type only)", "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19" ], "default": "19" }, "font": { "description": "Font (text type only)", "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8" ], "default": "0" }, "file": { "description": "File URL (image/video/audio)", "type": "string", "example": "https://..." } }, "required": [ "type" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/send/text": { "post": { "operationId": "send_text", "summary": "Send Text", "description": "Sends a simple text message to a WhatsApp number. The number must include the country code, for example: 5511999999999.", "tags": [ "Send Messages" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "text": { "description": "Message", "type": "string", "example": "Olá! Tudo bem?" }, "mentions": { "description": "Tag members (group only)", "type": "string", "example": "all" }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "replyid": { "description": "ID of the message to reply to", "type": "string", "example": "ABCDEF123456" }, "digitando": { "description": "Shows an automatic \"typing...\" indicator, proportional to the message length, before sending. On by default (humanizes and reduces block risk). Send false to turn it off and reply faster. The response remains synchronous.", "type": "boolean" } }, "required": [ "number", "text" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/archive": { "post": { "operationId": "chat_archive", "summary": "Archive Chat", "description": "Archives a conversation, hiding it from the main WhatsApp list.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Chat number or JID", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "archive": { "description": "Archive", "type": "boolean", "default": true } }, "required": [ "number", "archive" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/block": { "post": { "operationId": "chat_block", "summary": "Block / Unblock Contact", "description": "⚠️ WARNING: Blocks a contact. Do NOT use block: false . it may DISCONNECT the entire instance (known WhatsApp bug). To unblock, use WhatsApp itself.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "block": { "description": "Action", "type": "boolean", "default": true } }, "required": [ "number", "block" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Blocked successfully", "blockList": [ "5511999999999@s.whatsapp.net" ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/blocklist": { "get": { "operationId": "chat_blocklist", "summary": "Blocked List", "description": "Returns all contacts blocked by the instance.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "blocked": [ "5511999999999@s.whatsapp.net" ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/delete": { "post": { "operationId": "chat_delete", "summary": "Delete Chat", "description": "Deletes an entire chat. It can clear only in the app or also in the database.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Chat number in international format.\nFor groups, use the full group ID.\n", "type": "string", "example": "5511999999999" }, "deleteChatDB": { "description": "If true, deletes the chat from the database", "type": "boolean", "example": false }, "deleteMessagesDB": { "description": "If true, deletes all chat messages from the database", "type": "boolean", "example": false }, "deleteChatWhatsApp": { "description": "If true, deletes the chat from WhatsApp.\nFor groups, this operation is not allowed and the chat will only be cleared.\n", "type": "boolean", "example": false }, "clearChatWhatsApp": { "description": "If true, clears the chat conversation on WhatsApp (without leaving the chat).\nWorks for groups and individual conversations.\n", "type": "boolean", "example": false } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "actions": [], "response": "Chat deletion process completed" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/find": { "post": { "operationId": "chat_find", "summary": "Search Chats", "description": "Searches chats with advanced filters: by name, label, status, group, and more.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "operator": { "description": "Logical operator between filters", "type": "string", "enum": [ "AND", "OR" ] }, "sort": { "description": "Sorting (+/- field, e.g. -wa_lastMsgTimestamp)", "type": "string", "example": "-wa_lastMsgTimestamp" }, "limit": { "description": "Maximum number of results to return", "type": "number" }, "offset": { "description": "Number of records to skip (for pagination)", "type": "number" }, "wa_fastid": { "description": "Internal chat ID", "type": "string" }, "wa_chatid": { "description": "Chat ID on WhatsApp", "type": "string" }, "wa_archived": { "description": "Archived?", "type": "boolean" }, "wa_contactName": { "description": "Contact name", "type": "string" }, "wa_name": { "description": "Name on WhatsApp", "type": "string" }, "name": { "description": "Name", "type": "string" }, "wa_isBlocked": { "description": "Blocked?", "type": "boolean" }, "wa_isGroup": { "description": "Is a group?", "type": "boolean" }, "wa_isGroup_admin": { "description": "Is group admin?", "type": "boolean" }, "wa_isGroup_announce": { "description": "Admins-only group?", "type": "boolean" }, "wa_isGroup_member": { "description": "Is group member?", "type": "boolean" }, "wa_isPinned": { "description": "Pinned?", "type": "boolean" }, "wa_label": { "description": "ID of the label applied to the chat. Use the value returned by `/labels`, not the label name.", "type": "string" }, "wa_notes": { "description": "Has notes?", "type": "string" }, "lead_tags": { "description": "Lead tags", "type": "string" }, "lead_isTicketOpen": { "description": "Open ticket?", "type": "boolean" }, "lead_assignedAttendant_id": { "description": "Agent ID", "type": "string" }, "lead_status": { "description": "Lead status", "type": "string" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "chats": [ { "jid": "5511999999999@s.whatsapp.net", "name": "João", "unreadCount": 3 } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/mute": { "post": { "operationId": "chat_mute", "summary": "Mute Chat", "description": "Mutes notifications of a conversation for a period in milliseconds. Example: 86400000 = 24h.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Chat number or JID", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "duration": { "description": "Duration (ms): e.g. 86400000 = 24h", "type": "number", "example": 86400000 } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/notes": { "post": { "operationId": "chat_notes", "summary": "View Chat Notes", "description": "Returns the internal (private) notes associated with a chat.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Full chat JID", "type": "string", "example": "5511999999999@s.whatsapp.net" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "notes": "Notas internas do chat" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/notes/edit": { "post": { "operationId": "chat_notes_edit", "summary": "Edit Chat Notes", "description": "Edits the internal notes of a chat. Notes are visible only to you.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Full chat JID", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "notes": { "description": "Note content to persist in the chat", "type": "string", "example": "Cliente prefere contato no período da tarde" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/notes/refresh": { "post": { "operationId": "chat_notes_refresh", "summary": "Reload Notes", "description": "Reloads the internal WhatsApp notes into the local database.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Full chat JID", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "force": { "description": "Try with `false` first.\nUse `true` only when the standard reload does not work well,\nas this mode performs a new, more complete read of the notes.\n", "type": "boolean", "example": false } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/pin": { "post": { "operationId": "chat_pin", "summary": "Pin / Unpin Chat", "description": "Pins or unpins a conversation at the top of the WhatsApp chat list.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Chat number or JID", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "pin": { "description": "Action", "type": "boolean", "default": true } }, "required": [ "number", "pin" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/read": { "post": { "operationId": "chat_read", "summary": "Mark Chat as Read", "description": "Marks all unread messages in a conversation as read, resetting the unread counter.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Chat number or JID", "type": "string", "example": "5511999999999@s.whatsapp.net" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/delete": { "post": { "operationId": "message_delete", "summary": "Delete Message", "description": "Deletes a sent message for all chat participants. Only messages sent by the instance itself can be deleted.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Message ID", "type": "string", "example": "ABCDEF123456" }, "number": { "description": "Recipient number", "type": "string", "example": "5511999999999" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Timestamp": "2026-04-06T04:50:40Z", "ID": "3EB0C6074918E013090475", "Sender": "..." } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/download": { "post": { "operationId": "message_download", "summary": "Download Media", "description": "Downloads received media (image, video, audio, document) from the message ID. The `id` field must come from the webhook or the `/message/find` endpoint. Note: the transcribe parameter is best-effort and may not return the transcription. For guaranteed audio transcription, use the AI module.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Message ID", "type": "string", "example": "7EB0F01D7244B421048F0706368376E0" }, "return_link": { "description": "Return public file URL", "type": "boolean", "default": true }, "return_base64": { "description": "Return file as base64", "type": "boolean", "default": false }, "generate_mp3": { "description": "For audio: return as MP3 (false = OGG)", "type": "boolean", "default": true }, "transcribe": { "description": "Transcribe audio (best-effort: may not return text)", "type": "boolean", "default": false } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "fileURL": "https://server.example.com/files/abc123.jpg", "mimetype": "image/jpeg" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/edit": { "post": { "operationId": "message_edit", "summary": "Edit Message", "description": "Edits the text of a previously sent message. It appears with an edited indicator for the recipient. Only works with messages sent by the instance itself.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Message ID", "type": "string", "example": "ABCDEF123456" }, "number": { "description": "Recipient number", "type": "string", "example": "5511999999999" }, "text": { "description": "New text", "type": "string", "example": "Texto corrigido..." } }, "required": [ "id", "number", "text" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "3EB0BB655F4F2AFA22FDE3", "messageType": "ExtendedTextMessage", "messageTimestamp": 1775450980468, "status": "Pending" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/find": { "post": { "operationId": "message_find", "summary": "Message History", "description": "Returns the instance message history. Filter by `chatid` to fetch messages from a specific conversation. Supports pagination via `limit` and `offset`.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "chatid": { "description": "Chat ID (JID)", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "id": { "description": "Specific message ID", "type": "string", "example": "ABCDEF123456" }, "limit": { "description": "Limit (default: 100)", "type": "number", "example": 100 }, "offset": { "description": "Offset (pagination)", "type": "number", "example": 0 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messages": [], "total": 0 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/history-sync": { "post": { "operationId": "message_history_sync", "summary": "Sync History", "description": "Requests synchronization of older message history for a chat. Messages arrive via webhook/SSE.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "messageid": { "description": "Reference message ID used to fetch older messages from the chat", "type": "string", "example": "3EB01234567890ABCDEF" }, "number": { "description": "Full chat JID", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "count": { "description": "Desired number of messages in the sync", "type": "number", "example": 20 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "count": 50 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/markread": { "post": { "operationId": "message_markread", "summary": "Mark as Read", "description": "Marks one or more messages as read. Send an array of IDs.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Message IDs", "example": [ "3EB0538DA65A59F6D8A251" ] } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "message_id": "5511999990000:3EB0CECA26BF34A157FC71", "status": "success" } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/presence": { "post": { "operationId": "message_presence", "summary": "Typing Indicator...", "description": "Shows \"typing...\" or \"recording audio...\" to the contact. The indicator disappears automatically after a few seconds.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "presence": { "description": "Type", "type": "string", "enum": [ "composing", "recording", "paused" ], "default": "composing" }, "delay": { "description": "Duration (ms, max. 300000)", "type": "number", "example": 3000 } }, "required": [ "number", "presence" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "ok" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/react": { "post": { "operationId": "message_react", "summary": "React with Emoji", "description": "Sends a reaction (emoji) to an existing message. Send an empty emoji to REMOVE the reaction. The id must be the flattened messageId in the format OWNER:MSGID (e.g. 5511999990000:2A6E2F02CE4125FDBA1B): do not use the Baileys format concatenated with the JID, it will return 404. The confirmation webhook arrives with messageType=ReactionMessage and includes the 'reaction' shortcut in the envelope.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Contact number", "type": "string", "example": "5511999999999" }, "id": { "description": "Message ID (OWNER:MSGID format)", "type": "string", "example": "5511999990000:2A6E2F02CE4125FDBA1B" }, "emoji": { "description": "Reaction emoji (empty = remove): alias: text", "type": "string", "example": "👍" } }, "required": [ "number", "id", "emoji" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageType": "ReactionMessage", "status": "Pending" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/ephemeral": { "post": { "operationId": "chat_ephemeral", "summary": "Disappearing Messages (private chat)", "description": "Turns disappearing (self-deleting) messages on or off in a private conversation. Applies to the next messages in the conversation. Duration in seconds, following the WhatsApp standard: 0 turns it off, 86400 = 24 hours, 604800 = 7 days, 7776000 = 90 days.", "tags": [ "Conversations" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Contact number (with country code)", "type": "string", "example": "5511999999999" }, "duration": { "description": "Duration before disappearing", "type": "string", "enum": [ "0", "86400", "604800", "7776000" ] } }, "required": [ "number", "duration" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/check": { "post": { "operationId": "check_number", "summary": "Check Number", "description": "Checks whether one or more numbers are registered on WhatsApp. Returns JID, verified name, and status.", "tags": [ "Contacts and Profile" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numbers": { "description": "Numbers to check (array)", "type": "string", "example": "[\"5511999999999\", \"5521888888888\"]" } }, "required": [ "numbers" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "query": "5511999999999", "isInWhatsapp": true, "jid": "5511999999999@s.whatsapp.net" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/details": { "post": { "operationId": "chat_details", "summary": "Contact Details", "description": "Returns full details of a contact: name, photo, status, verification, e-commerce.", "tags": [ "Contacts and Profile" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Phone number or group ID", "type": "string", "example": "5511999999999" }, "preview": { "description": "Controls the size of the returned profile image:\n- `true`: Returns the image in preview size (smaller, optimized for listings)\n- `false` (default): Returns the image in full size (original resolution, higher quality)\n", "type": "boolean" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "jid": "5511999999999@s.whatsapp.net", "name": "João", "pushName": "João Silva", "profilePicUrl": "https://..." } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/contact/add": { "post": { "operationId": "contact_add", "summary": "Add Contact", "description": "Adds a new contact to the connected WhatsApp address book with name and number.", "tags": [ "Contacts and Profile" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "description": "Phone (with country code)", "type": "string", "example": "5511999999999" }, "name": { "description": "Full name", "type": "string", "example": "João Silva" } }, "required": [ "phone", "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/contact/remove": { "post": { "operationId": "contact_remove", "summary": "Remove Contact", "description": "Removes a contact from the WhatsApp address book.", "tags": [ "Contacts and Profile" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Phone number in international format with mandatory country code. \nFor Brazil, it must start with 55. Accepts variations with/without the + symbol, \nwith/without parentheses, with/without hyphens, and with/without spaces. Also accepts the WhatsApp \nJID format (@s.whatsapp.net). Does not accept business contacts (@lid) \nor groups (@g.us).\n", "type": "string", "example": "5511999999999" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/contacts": { "get": { "operationId": "contacts_get", "summary": "List Contacts (Fast)", "description": "Lists all contacts saved in the WhatsApp address book.", "tags": [ "Contacts and Profile" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "jid": "5511999999999@s.whatsapp.net", "name": "João" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/contacts/list": { "post": { "operationId": "find_contacts", "summary": "List Contacts", "description": "Searches contacts with pagination. Use limit and offset to navigate.", "tags": [ "Contacts and Profile" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "Limit", "type": "number", "example": 50 }, "offset": { "description": "Offset", "type": "number", "example": 0 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "contacts": [ { "jid": "5511999999999@s.whatsapp.net", "contact_name": "João Silva" } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/profile/image": { "post": { "operationId": "profile_image", "summary": "Change Photo", "description": "Changes your instance profile picture. Send a URL, base64, or \"remove\" to remove it.", "tags": [ "Contacts and Profile" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "description": "URL, base64 or \"remove\"", "type": "string", "example": "https://exemplo.com/logo.jpg" } }, "required": [ "image" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/profile/name": { "post": { "operationId": "profile_name", "summary": "Change Name", "description": "Changes your instance profile name on WhatsApp.", "tags": [ "Contacts and Profile" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "New name (max. 25 characters)", "type": "string", "example": "Minha Empresa" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/community/create": { "post": { "operationId": "community_create", "summary": "Create Community", "description": "Creates a WhatsApp Community, a structure that groups multiple groups under a single central announcements channel. The connected number will be the community owner.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Community name", "type": "string", "example": "Comunidade da Empresa" }, "description": { "description": "Description", "type": "string", "example": "Descrição da comunidade" }, "participants": { "description": "Participants (numbers with country code)", "example": [ "5511999999999" ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "JID": "120363000000000001@g.us", "Name": "Comunidade da Empresa", "IsParent": true, "DefaultSubGroupId": "120363000000000002@g.us", "Participants": [ { "JID": "...", "IsAdmin": true, "IsSuperAdmin": true } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/community/editgroups": { "post": { "operationId": "community_editgroups", "summary": "Manage Community Groups", "description": "Adds or removes groups from an existing community. Use action: add or action: remove with the array of group JIDs.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "community": { "description": "Community JID", "type": "string", "example": "120363000000000001@g.us" }, "action": { "description": "Action", "type": "string", "enum": [ "add", "remove" ], "default": "add" }, "groups": { "description": "Group JIDs (JSON array)", "example": [ "120363000000000000@g.us" ] } }, "required": [ "community", "action", "groups" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "failed": null, "message": "community updated", "success": null } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/create": { "post": { "operationId": "create_group", "summary": "Create Group", "description": "Creates a new WhatsApp group with the given participants. The connected number is automatically added as an admin. Name: min. 1, max. 100 characters. Maximum of 50 participants.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Group name", "type": "string", "example": "Meu Time" }, "participants": { "description": "Participants (JSON array of numbers with country code)", "type": "string", "example": "[\"5511999990001\",\"5511999990002\"]" } }, "required": [ "name", "participants" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "groupJID": "120363000000000000@g.us", "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/info": { "post": { "operationId": "group_info", "summary": "Group Information", "description": "Returns full details of a group: name, description, participants, admins, creation date and settings. Use `getInviteLink: true` to include the invite link in the response.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "getInviteLink": { "description": "Include invite link", "type": "boolean", "default": false } }, "required": [ "groupjid" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "120363000000000000@g.us", "name": "Meu Grupo", "description": "Descrição", "inviteLink": "https://chat.whatsapp.com/...", "participants": [ { "id": "5511...@s.whatsapp.net", "isAdmin": true } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/inviteInfo": { "post": { "operationId": "group_inviteInfo", "summary": "Info from Invite", "description": "Gets information about a group from its invite code or link.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invitecode": { "description": "Invite code or full group URL.\nCan be a short code or the full WhatsApp URL.\n", "type": "string" } }, "required": [ "invitecode" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "jid": "120363000000000000@g.us", "name": "Meu Grupo", "size": 15 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/join": { "post": { "operationId": "group_join", "summary": "Join Group via Link", "description": "Makes the instance join a group using a WhatsApp invite link. Accepts the full URL (https://chat.whatsapp.com/...) or just the code.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invitecode": { "description": "Invite code or URL", "type": "string", "example": "https://chat.whatsapp.com/XXXXXXXXXXXXXXXX" } }, "required": [ "invitecode" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "groupJID": "120363000000000000@g.us" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/leave": { "post": { "operationId": "leave_group", "summary": "Leave Group", "description": "Removes the connected number from the specified group. This action cannot be undone by the system. Also works for leaving communities.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" } }, "required": [ "groupjid" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Group leave successful" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/list": { "get": { "operationId": "list_groups", "summary": "List Groups", "description": "Lists all WhatsApp groups. Returns an array with the JID, name and data of each group.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "groups": [ { "id": "120363000000000000@g.us", "name": "Meu Grupo" } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "post": { "operationId": "group_list", "summary": "Search Groups", "description": "Lists groups with an option to include participants. Returns an object with a \"groups\" array.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "getParticipants": { "description": "Include participants", "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/resetInviteCode": { "post": { "operationId": "group_reset_invite", "summary": "Reset Invite Code", "description": "Generates a new invite code for the group. The previous link will be invalidated.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" } }, "required": [ "groupjid" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "InviteLink": "https://chat.whatsapp.com/YYYYYYYYYYYYYYYY" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/updateAnnounce": { "post": { "operationId": "group_update_announce", "summary": "Admins-Only Mode", "description": "Enables or disables the mode in which only admins can send messages. Ideal for one-way communication channels.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "announce": { "description": "Admins only", "type": "boolean", "default": true } }, "required": [ "groupjid", "announce" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/updateDescription": { "post": { "operationId": "group_update_description", "summary": "Change Group Description", "description": "Changes the group description. An empty description is not allowed.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "description": { "description": "New description (max. 512 characters)", "type": "string", "example": "Descrição do grupo..." } }, "required": [ "groupjid", "description" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/updateImage": { "post": { "operationId": "group_update_image", "summary": "Change Group Photo", "description": "Changes the group image. Send the image URL or \"remove\" to remove it.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "image": { "description": "URL, base64 or \"remove\"", "type": "string", "example": "https://exemplo.com/foto.jpg ou \"remove\"" } }, "required": [ "groupjid", "image" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/updateLocked": { "post": { "operationId": "group_update_locked", "summary": "Lock Group Editing", "description": "When enabled, only admins can change the group name, photo and description.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "locked": { "description": "Lock editing", "type": "boolean", "default": true } }, "required": [ "groupjid", "locked" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/updateName": { "post": { "operationId": "group_update_name", "summary": "Rename Group", "description": "Changes the group display name. Min. 1 and max. 25 characters. Requires the connected number to be an admin.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "name": { "description": "New name (max. 25 characters)", "type": "string", "example": "Nome do grupo" } }, "required": [ "groupjid", "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/updateParticipants": { "post": { "operationId": "group_participants", "summary": "Manage Participants", "description": "Manages group participants. Add, remove, promote or demote.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group ID (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "action": { "description": "Action", "type": "string", "enum": [ "add", "remove", "promote", "demote", "approve", "reject" ], "default": "add" }, "participants": { "description": "Participants (JSON array of numbers with country code)", "type": "string", "example": "[\"5511999990003\"]" } }, "required": [ "groupjid", "action", "participants" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/ephemeral": { "post": { "operationId": "group_ephemeral", "summary": "Disappearing Messages (group)", "description": "Turns disappearing messages on or off in the group. Duration in seconds, WhatsApp standard: 0 turns off, 86400 = 24 hours, 604800 = 7 days, 7776000 = 90 days.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group JID", "type": "string", "example": "120363123456789012@g.us" }, "duration": { "description": "Duration before disappearing", "type": "string", "enum": [ "0", "86400", "604800", "7776000" ] } }, "required": [ "groupjid", "duration" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/updateJoinApproval": { "post": { "operationId": "group_join_approval", "summary": "Require Approval to Join", "description": "Defines whether new members joining the group need admin approval.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group JID", "type": "string", "example": "120363123456789012@g.us" }, "IsJoinApprovalRequired": { "description": "Require approval to join", "type": "boolean" } }, "required": [ "groupjid", "IsJoinApprovalRequired" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/group/updateMemberAddMode": { "post": { "operationId": "group_member_add_mode", "summary": "Who Can Add Members", "description": "Defines who can add new members to the group: only admins or any participant.", "tags": [ "Groups" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "Group JID", "type": "string", "example": "120363123456789012@g.us" }, "MemberAddMode": { "description": "Who can add", "type": "string", "enum": [ "admin_add", "all_member_add" ] } }, "required": [ "groupjid", "MemberAddMode" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/admin/accept": { "post": { "operationId": "newsletter_admin_accept", "summary": "Accept Admin Invite", "description": "Accepts an invitation to be an admin of a channel.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/admin/invite": { "post": { "operationId": "newsletter_admin_invite", "summary": "Invite Channel Admin", "description": "Invites a number to be an admin of a channel. (Note: may return a GraphQL error depending on the WhatsApp version)", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "phone": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/admin/remove": { "post": { "operationId": "newsletter_admin_remove", "summary": "Remove Channel Admin", "description": "Removes an admin from a channel. (Note: may return a GraphQL error depending on the WhatsApp version)", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "phone": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/admin/revoke": { "post": { "operationId": "newsletter_admin_revoke", "summary": "Revoke Admin Invite", "description": "Revokes a pending admin invite. (Note: may return a GraphQL error depending on the WhatsApp version)", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "phone": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/create": { "post": { "operationId": "newsletter_create", "summary": "Create Channel", "description": "Creates a new WhatsApp channel (newsletter).", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Name", "type": "string", "example": "Canal de Promoções" }, "description": { "description": "Description", "type": "string", "example": "Ofertas e novidades da loja" }, "picture": { "description": "URL, raw base64 or data URI of the channel image.", "type": "string", "example": "https://example.com/newsletter.png" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "123", "jid": "120363...@newsletter" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/delete": { "post": { "operationId": "newsletter_delete", "summary": "Delete Channel", "description": "Deletes a channel that you administer.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/description": { "post": { "operationId": "newsletter_description", "summary": "Change Channel Description", "description": "Updates the description of a channel. (Note: may return a GraphQL error depending on the WhatsApp version)", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "description": { "description": "Description", "type": "string", "example": "Atualizações, ofertas e novidades" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/follow": { "post": { "operationId": "newsletter_follow", "summary": "Follow Channel", "description": "Follows a channel to receive its posts.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/info": { "post": { "operationId": "newsletter_info", "summary": "Channel Info", "description": "Gets detailed information about a channel.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Numeric channel ID. If provided without a domain, it will be converted to `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Full channel JID.", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "123", "name": "Meu Canal", "description": "...", "subscribers": 150 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/link": { "post": { "operationId": "newsletter_link", "summary": "Find Channel by Link", "description": "Looks up channel information by invite link/key.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "description": "Channel invite key.", "type": "string", "example": "AbCdEfGhIjKlMn" } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "123", "name": "Canal", "jid": "120363...@newsletter" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/list": { "get": { "operationId": "newsletter_list_get", "summary": "List Channels", "description": "Lists all channels the instance is subscribed to.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "newsletters": [] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/messages": { "post": { "operationId": "newsletter_messages", "summary": "Channel Messages", "description": "Fetches messages published in a channel.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Numeric channel ID. If provided without a domain, it will be converted to `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Full channel JID.", "type": "string", "example": "120363123456789012@newsletter" }, "count": { "description": "Number of messages/posts to fetch.", "type": "number", "example": 20 }, "beforeid": { "description": "Returns messages prior to the given `serverid`.\nUse for backward pagination.\n", "type": "number", "example": 12345 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messages": [] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/messages/delete": { "post": { "operationId": "newsletter_messages_delete", "summary": "Delete Channel Message", "description": "Deletes a message from a channel that you administer.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Numeric channel ID. If provided without a domain, it will be converted to `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Full channel JID.", "type": "string", "example": "120363123456789012@newsletter" }, "messageid": { "description": "Logical message ID in the channel.", "type": "string", "example": "3EB0B4302B3A8A52F7A1" }, "serverid": { "description": "Sequential identifier of the post in the channel.", "type": "number", "example": 12345 }, "count": { "description": "Number of messages fetched per page when locating the post.", "type": "number", "example": 100 }, "maxpages": { "description": "Maximum number of pages fetched when locating the post.", "type": "number", "example": 5 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/messages/edit": { "post": { "operationId": "newsletter_messages_edit", "summary": "Edit Channel Message", "description": "Edits a recent message in a channel that you administer.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Numeric channel ID. If provided without a domain, it will be converted to `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Full channel JID.", "type": "string", "example": "120363123456789012@newsletter" }, "messageid": { "description": "Logical message ID in the channel.", "type": "string", "example": "3EB0B4302B3A8A52F7A1" }, "serverid": { "description": "Sequential identifier of the post in the channel.", "type": "number", "example": 12345 }, "text": { "description": "New text or new caption of the post.", "type": "string", "example": "Post atualizado" }, "count": { "description": "Number of messages fetched per page when locating the post.", "type": "number", "example": 100 }, "maxpages": { "description": "Maximum number of pages fetched when locating the post.", "type": "number", "example": 5 } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/mute": { "post": { "operationId": "newsletter_mute", "summary": "Mute Channel", "description": "Mutes notifications from a channel.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/name": { "post": { "operationId": "newsletter_name", "summary": "Change Channel Name", "description": "Updates the name of a channel. (Note: may return a GraphQL error depending on the WhatsApp version)", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "name": { "description": "Name", "type": "string", "example": "Canal de Promoções VIP" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/owner/transfer": { "post": { "operationId": "newsletter_owner_transfer", "summary": "Transfer Channel Ownership", "description": "Transfers channel ownership to another number.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "phone": { "description": "Number (with country code)", "type": "string", "example": "5511999999999" }, "quitAdmin": { "description": "Leave as admin after transferring", "type": "boolean", "example": false } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/picture": { "post": { "operationId": "newsletter_picture", "summary": "Change Channel Photo", "description": "Updates the photo of a channel. (Note: may return a GraphQL error depending on the WhatsApp version)", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "picture": { "description": "Image URL", "type": "string", "example": "https://example.com/newsletter.png" } }, "required": [ "picture" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/reaction": { "post": { "operationId": "newsletter_reaction", "summary": "React to Channel Post", "description": "Reacts to a channel post.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "serverid": { "description": "Server ID (integer)", "type": "number", "example": 12345 }, "reaction": { "description": "Reaction emoji", "type": "string", "example": "🔥" }, "reactionmessageid": { "description": "Reaction message ID", "type": "string", "example": "3EB0AABBCCDD" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/search": { "post": { "operationId": "newsletter_search", "summary": "Search Channels", "description": "Searches public channels by text, country or category.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "Result limit", "type": "number", "example": 20 }, "view": { "description": "View type", "type": "string", "example": "RECOMMENDED" }, "countryCodes": { "description": "Country codes", "example": [ "BR" ] }, "searchText": { "description": "Search text", "type": "string", "example": "promo" }, "after": { "description": "Cursor (pagination)", "type": "string", "example": "YXJyYXljb25uZWN0aW9uOjE5" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/settings": { "post": { "operationId": "newsletter_settings", "summary": "Channel Settings", "description": "Updates channel settings (e.g. allowed reaction codes). (Note: may return a GraphQL error depending on the WhatsApp version)", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "reactionCodes": { "description": "Allowed reaction codes", "type": "string", "example": "basic" } }, "required": [ "reactionCodes" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/subscribe": { "post": { "operationId": "newsletter_subscribe", "summary": "Subscribe to Channel Updates", "description": "Subscribes to temporary updates of a channel to receive notifications.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/unfollow": { "post": { "operationId": "newsletter_unfollow", "summary": "Unfollow", "description": "Unfollows a channel.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/unmute": { "post": { "operationId": "newsletter_unmute", "summary": "Unmute Channel", "description": "Unmutes notifications from a channel.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/updates": { "post": { "operationId": "newsletter_updates", "summary": "Channel Updates", "description": "Fetches message updates from a channel. (Note: may return a GraphQL error depending on the WhatsApp version)", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Numeric channel ID. If provided without a domain, it will be converted to `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Full channel JID.", "type": "string", "example": "120363123456789012@newsletter" }, "count": { "description": "Maximum number of updates returned.", "type": "number", "example": 50 }, "afterid": { "description": "Returns only updates after the given `serverid`.", "type": "number", "example": 12345 }, "since": { "description": "Cutoff timestamp.\n- If greater than `1000000000000`, it is interpreted as milliseconds.\n- Otherwise, it is interpreted as seconds.\n", "type": "number", "example": 1710000000 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/newsletter/viewed": { "post": { "operationId": "newsletter_viewed", "summary": "Mark as Viewed", "description": "Marks channel posts as viewed.", "tags": [ "Newsletters and Channels" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "Channel/contact JID", "type": "string", "example": "120363123456789012@newsletter" }, "serverids": { "description": "Server IDs (array of integers, e.g. [1, 2, 3])", "example": [ 1, 2, 3 ] } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/sender/advanced": { "post": { "operationId": "sender_advanced", "summary": "Send Batch Campaign", "description": "Sends messages in bulk with content individualized per recipient. Each item in the messages array can have a different number and text.", "tags": [ "Campaigns" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "description": "Messages (array of objects)", "type": "string", "example": "[{\"number\":\"5511999999999\",\"text\":\"Olá!\"}]" }, "delayMin": { "description": "Minimum delay (seconds)", "type": "number", "example": 1 }, "delayMax": { "description": "Maximum delay (seconds)", "type": "number", "example": 5 }, "folder_id": { "description": "Folder ID", "type": "string", "example": "folder_abc123" }, "info": { "description": "Additional information about the campaign", "type": "string", "example": "Campanha lancamento" }, "scheduled_for": { "description": "Schedule for (timestamp in milliseconds or minutes from now)", "type": "number", "example": 1 } }, "required": [ "messages" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 1, "folder_id": "r5eb3b483c43f69", "status": "queued" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/sender/clearall": { "delete": { "operationId": "sender_clearall_delete", "summary": "Clear Entire Queue", "description": "Clears the entire message queue, including pending and in-progress messages.", "tags": [ "Campaigns" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "folders_deleted": 0, "messages_deleted": 0, "status": "processed" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/sender/cleardone": { "post": { "operationId": "sender_cleardone", "summary": "Clear Completed Campaigns", "description": "Removes from the list all campaigns with completed status within the given folder.", "tags": [ "Campaigns" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "description": "Campaign folder ID", "type": "string", "example": "folder_abc123" } }, "required": [ "folder_id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "cleanup started" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/sender/edit": { "post": { "operationId": "sender_edit", "summary": "Control Campaign", "description": "Controls a bulk sending campaign: pause, resume or cancel.", "tags": [ "Campaigns" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "description": "Unique identifier of the sending campaign", "type": "string", "example": "folder_123" }, "action": { "description": "Campaign action", "type": "string", "enum": [ "stop", "continue", "delete" ], "example": "stop" } }, "required": [ "folder_id", "action" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Folder deletion has been initiated", "status": "deleting" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/sender/listfolders": { "get": { "operationId": "sender_listfolders_get", "summary": "List Campaigns", "description": "Lists all bulk sending campaigns/folders. Returns a plain array.", "tags": [ "Campaigns" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "r5819c9fba43b98", "info": "", "status": "scheduled", "scheduled_for": 1775449285668, "delayMax": 3, "delayMin": 1, "log_delivered": 0, "log_failed": 0, "log_played": 0, "log_read": 0, "log_sucess": 0, "log_total": 1, "owner": "5511999999999" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/sender/listmessages": { "post": { "operationId": "sender_listmessages", "summary": "List Campaign Messages", "description": "Returns the messages of a specific campaign with sending status and pagination.", "tags": [ "Campaigns" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "description": "Campaign folder ID", "type": "string", "example": "folder_abc123" } }, "required": [ "folder_id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messages": [ { "id": "5511999990000:3EB01C21C13D0C4BA33F40", "chatid": "5511999990000@s.whatsapp.net", "status": "Sent", "text": "Teste", "messageType": "Conversation", "send_folder_id": "r5819c9fba43b98" } ], "pagination": { "limit": 1000, "offset": 0, "totalRecords": 1 } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/sender/simple": { "post": { "operationId": "sender_simple", "summary": "Send Simple Message", "description": "Sends a message to a list of numbers with a random delay between each send. Returns a folder_id for tracking.", "tags": [ "Campaigns" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numbers": { "description": "Numbers (JSON array)", "type": "string", "example": "[\"5511999999999\",\"5511888888888\"]" }, "type": { "description": "Message type", "type": "string", "enum": [ "text", "image", "video", "document", "audio", "contact", "location" ], "default": "text" }, "text": { "description": "Message text", "type": "string", "example": "Olá! Temos uma promoção..." }, "file": { "description": "Media URL (if not text)", "type": "string", "example": "https://..." }, "folder": { "description": "Campaign name", "type": "string", "example": "promo-abril" }, "delayMin": { "description": "Minimum delay (seconds)", "type": "number", "example": 1 }, "delayMax": { "description": "Maximum delay (seconds)", "type": "number", "example": 5 }, "scheduled_for": { "description": "Schedule for (timestamp in milliseconds)", "type": "number", "example": 1775534400000 }, "info": { "description": "Additional information about the campaign", "type": "string", "example": "Campanha Janeiro" } }, "required": [ "numbers", "type", "delayMin", "delayMax" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 1, "folder_id": "r37d5cc380a7f31", "status": "queued" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/call/make": { "post": { "operationId": "call_make", "summary": "Make Call", "description": "Starts a voice call to a WhatsApp number. The call rings on the destination but does not establish real voice communication.", "tags": [ "Calls" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Contact number in international format (e.g. 5511999999999)", "type": "string", "example": "5511999999999" }, "call_duration": { "description": "Call duration in seconds. After this time the call is ended automatically.", "type": "number", "example": 15 } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "call": { "callCreator": "5511999@s.whatsapp.net", "wasSentByAPI": true }, "response": "Call successful" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/call/reject": { "post": { "operationId": "call_reject", "summary": "Reject Call", "description": "Rejects an incoming call.", "tags": [ "Calls" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "(Optional) Contact number in international format (e.g. 5511999999999)", "type": "string", "example": "5511999999999" }, "id": { "description": "(Optional) Unique ID of the call to reject", "type": "string" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Call rejected" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/business/catalog/delete": { "post": { "operationId": "business_catalog_delete", "summary": "Delete Catalog Product", "description": "Permanently removes products from the WhatsApp Business catalog. Send an array of IDs in the `productIds` field. Note: a timeout (504) may occur if the IDs are invalid.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "description": "Product IDs (array)", "type": "string", "example": "[\"prod_abc123\"]" } }, "required": [ "productIds" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/business/catalog/hide": { "post": { "operationId": "business_catalog_hide", "summary": "Hide Catalog Product", "description": "Hides a product from the public catalog without removing it. ⚠️ May return a 501 error on accounts that do not support this feature. This is a WhatsApp limitation, not an API one.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Product ID", "type": "string", "example": "prod_abc123" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Product hidden" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/business/catalog/info": { "post": { "operationId": "business_catalog_info", "summary": "Product Info", "description": "Returns detailed information about a specific catalog product.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "description": "JID of the catalog to query", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "id": { "description": "The product ID.", "type": "string" } }, "required": [ "jid", "id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "123", "name": "Produto", "price": 9990, "currency": "BRL" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/business/catalog/list": { "post": { "operationId": "business_catalog_list", "summary": "List Product Catalog", "description": "Returns all products registered in the WhatsApp Business catalog of the given JID.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "description": "Catalog JID", "type": "string", "example": "5511999999999@s.whatsapp.net" } }, "required": [ "jid" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": [ { "id": "prod_abc123", "name": "Produto 1", "price": "49.90", "currency": "BRL" } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/business/catalog/show": { "post": { "operationId": "business_catalog_show", "summary": "Show Catalog Product", "description": "Makes a product visible in the public WhatsApp Business catalog. ⚠️ May return a 501 error on accounts that do not support this feature. This is a WhatsApp limitation, not an API one.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Product ID", "type": "string", "example": "prod_abc123" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Product shown" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/business/get/categories": { "get": { "operationId": "business_categories", "summary": "List Business Categories", "description": "Returns the list of categories available for the WhatsApp Business profile.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "categories": [ { "id": "1", "name": "Shopping and Retail" } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/business/get/profile": { "post": { "operationId": "business_profile_get", "summary": "View Business Profile", "description": "Returns the WhatsApp Business profile data: description, address, email, website and categories. Send the `jid` with the number (without @s.whatsapp.net). The number is required.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "description": "Contact JID (required, e.g. 5511999999999@s.whatsapp.net)", "type": "string", "example": "5511999999999" } }, "required": [ "jid" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": { "description": "Loja de produtos...", "address": "Av. Paulista, 1000", "email": "contato@empresa.com" } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/business/update/profile": { "post": { "operationId": "business_profile_update", "summary": "Update Business Profile", "description": "Updates the WhatsApp Business profile data. At least one of the fields `description`, `address` or `email` is required. Note: this endpoint may return 403 forbidden if the instance is not of the Business type.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "Description", "type": "string", "example": "Especialistas em automação WhatsApp" }, "address": { "description": "Address", "type": "string", "example": "Av. Paulista, 1000 - SP" }, "email": { "description": "Email", "type": "string", "example": "contato@empresa.com" }, "websites": { "description": "Websites (array)", "type": "string", "example": "[\"https://empresa.com\"]" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/labels": { "post": { "operationId": "chat_labels", "summary": "Apply Label to Chat", "description": "Manages the labels of a chat. Use `labelids` to set all labels at once, `add_labelid` to add one label, or `remove_labelid` to remove one. Send only one of these fields per request.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Contact number", "type": "string", "example": "5511999999999" }, "labelids": { "description": "Label IDs (array, replaces all)", "type": "string", "example": "[\"1\",\"2\"]" }, "add_labelid": { "description": "Add Label (ID)", "type": "string", "example": "1" }, "remove_labelid": { "description": "Remove Label (ID)", "type": "string", "example": "1" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Label added to chat" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/connect": { "post": { "operationId": "instance_connect", "summary": "Connect Instance", "description": "Connects the instance to WhatsApp. You must scan the QR code after this call.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "description": "Phone number in international format (e.g. 5511999999999). If provided, a pairing code is generated. If omitted, a QR code is generated.", "type": "string", "example": "5511999999999" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "connected": true, "instance": { "id": "raa287d88df6336", "status": "connected", "name": "minha-instancia" }, "response": "Already connected", "status": { "connected": true, "loggedIn": true } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/disconnect": { "post": { "operationId": "instance_disconnect", "summary": "Disconnect Instance", "description": "Disconnects the instance from WhatsApp. You will need to scan the QR code again to reconnect.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "info": "The device has been successfully disconnected from WhatsApp. A new QR code will be required for the next connection.", "instance": { "status": "disconnected", "lastDisconnect": "2026-04-06T04:56:41Z", "lastDisconnectReason": "disconnected by API" }, "response": "Disconnected" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/presence": { "post": { "operationId": "instance_presence", "summary": "Presence Status", "description": "Sets whether the instance appears as online or offline to contacts.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "presence": { "description": "Presence status", "type": "string", "enum": [ "available", "unavailable" ] } }, "required": [ "presence" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Presence updated successfully" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/privacy": { "get": { "operationId": "instance_privacy_get", "summary": "View Privacy", "description": "Returns the account privacy settings: who can add you to groups, see last seen, profile photo and read receipts.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "calladd": "all", "groupadd": "all", "last": "contacts", "online": "all", "profile": "all", "readreceipts": "all", "status": "contacts" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "post": { "operationId": "instance_privacy_set", "summary": "Change Privacy", "description": "Updates the privacy settings. All fields are optional. Send only what you want to change.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupadd": { "description": "Add to groups", "type": "string", "enum": [ "all", "contacts", "contact_blacklist", "none" ] }, "last": { "description": "Last seen", "type": "string", "enum": [ "all", "contacts", "contact_blacklist", "none" ] }, "profile": { "description": "Profile photo", "type": "string", "enum": [ "all", "contacts", "contact_blacklist", "none" ] }, "readreceipts": { "description": "Read receipts", "type": "string", "enum": [ "all", "none" ] }, "online": { "description": "Online status", "type": "string", "enum": [ "all", "match_last_seen" ] }, "calladd": { "description": "Receive calls from", "type": "string", "enum": [ "all", "known" ] }, "status": { "description": "About (status text)", "type": "string", "enum": [ "all", "contacts", "contact_blacklist", "none" ] } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "groupadd": "contacts", "last": "contacts", "profile": "contacts", "readreceipts": "all", "online": "all", "calladd": "all" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/proxy": { "get": { "operationId": "instance_proxy_get", "summary": "View Proxy", "description": "Returns the proxy configuration of the instance.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "enabled": true, "managed": true, "proxy_url": "managed_pool://hidden", "proxy_fallback": "internal_proxy", "last_test_at": 1775449088975, "last_test_error": "", "validation_error": false } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "post": { "operationId": "instance_proxy", "summary": "Configure Proxy", "description": "Sets, changes or REMOVES the instance proxy. The canonical field is `mode`: `custom` (your own proxy, requires proxy_url), `internal` (proxy managed by the service) or `none` (removes the proxy, requires confirm_no_proxy=true). To remove the proxy, send mode=none and confirm_no_proxy=true.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "description": "Proxy strategy", "type": "string", "enum": [ "custom", "internal", "none" ] }, "proxy_url": { "description": "Proxy URL (required when mode=custom). Protocols: http://, https://, socks5://", "type": "string", "example": "http://usuario:senha@host:porta" }, "proxy_fallback": { "description": "Fallback for mode=custom (e.g. internal, never)", "type": "string", "example": "internal" }, "confirm_no_proxy": { "description": "Confirms proxy removal (required when mode=none)", "type": "boolean" }, "rotate_now": { "description": "Rotates the internal proxy immediately (when mode=internal)", "type": "boolean" } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "details": "Proxy removido", "proxy": { "enabled": false }, "restart_requested": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/reset": { "post": { "operationId": "instance_reset", "summary": "Restart Instance", "description": "Restarts the instance runtime. If the instance is disconnected, you will need to scan the QR code again.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "instanceId": "r8ecb82b8e9613c", "resetting": true, "response": "Instance reset started" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/status": { "get": { "operationId": "instance_status", "summary": "Instance Info & Status", "description": "Returns full instance data: name, connected phone number, profile photo and current connection status (disconnected, connecting, connected).", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "instance": { "status": "connected", "name": "minha-instancia", "profileName": "Meu Perfil", "owner": "5511999999999", "msg_delay_min": 1, "msg_delay_max": 3 } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/updateDelaySettings": { "post": { "operationId": "instance_updateDelaySettings", "summary": "Configure Delay", "description": "Sets the minimum and maximum delay between messages in the queue. Returns the full instance object.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "msg_delay_min": { "description": "Minimum delay in seconds (0 = no delay)", "type": "number", "example": 0 }, "msg_delay_max": { "description": "Maximum delay in seconds", "type": "number", "example": 2 } }, "required": [ "msg_delay_min", "msg_delay_max" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "raa287d88df6336", "name": "minha-instancia", "status": "connected", "msg_delay_min": 0, "msg_delay_max": 2 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/updateInstanceName": { "post": { "operationId": "instance_updateInstanceName", "summary": "Rename Instance", "description": "Updates the internal name of the instance. Returns the full instance object.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "New name for the instance", "type": "string", "example": "Minha Nova Instância 2024!@#" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "raa287d88df6336", "name": "Novo Nome", "status": "connected", "profileName": "Meu Perfil", "owner": "5511999999999" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/label/edit": { "post": { "operationId": "label_edit", "summary": "Create / Edit Label", "description": "Creates a new label or edits/deletes an existing one. To create, use labelid \"0\" with name and color. To edit, use the real labelid. Color: number from 0 to 19.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labelid": { "description": "Label ID. Use \"0\" to create a new one.", "type": "string", "example": "0" }, "name": { "description": "Label name", "type": "string", "example": "Cliente VIP" }, "color": { "description": "Color (0 to 19)", "type": "number", "example": 5 }, "delete": { "description": "Delete?", "type": "boolean" } }, "required": [ "labelid", "name" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Label edited successfully" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/labels": { "get": { "operationId": "labels_list", "summary": "List Labels", "description": "Returns all labels created in the instance.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "5511999999999:1", "name": "Nao lidas", "color": 0, "colorHex": "#ff9484", "labelid": "1", "owner": "5511999999999" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/labels/refresh": { "post": { "operationId": "labels_refresh", "summary": "Reload Labels", "description": "Reloads the WhatsApp labels to sync with the local database.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "description": "Try `false` first.\nUse `true` only when the default reload does not work well,\nas this mode performs a more complete re-read of the labels.\n", "type": "boolean", "example": false } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "5511999999999:1", "name": "Nao lidas", "color": 0, "labelid": "1" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/quickreply/edit": { "post": { "operationId": "quickreply_edit", "summary": "Create / Edit Quick Reply", "description": "Creates or updates a quick reply shortcut. When you type \"/\" followed by the shortcut in WhatsApp, the full message is suggested. To edit, send the `id` field.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shortCut": { "description": "Shortcut (e.g. good-morning)", "type": "string", "example": "bom-dia" }, "text": { "description": "Reply text", "type": "string", "example": "Bom dia! Como posso te ajudar hoje?" }, "type": { "description": "Type", "type": "string", "enum": [ "text", "image", "video", "document" ], "default": "text" }, "file": { "description": "File URL (if media)", "type": "string", "example": "https://..." }, "docName": { "description": "Document name", "type": "string", "example": "catalogo.pdf" }, "keywords": { "description": "Keywords (JSON array)", "type": "string", "example": "[\"bom dia\",\"bom-dia\"]" }, "id": { "description": "ID (to edit)", "type": "string", "example": "qr_abc123" }, "delete": { "description": "Delete the quick reply", "type": "boolean" } }, "required": [ "shortCut", "text", "type" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Operation completed successfully", "quickReplies": [ { "id": "r6e84a8016cbd63", "shortCut": "bom-dia", "text": "Bom dia!", "type": "text" } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/quickreply/showall": { "get": { "operationId": "quickreply_list", "summary": "List Quick Replies", "description": "Returns all quick replies configured in the instance.", "tags": [ "Settings" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "r6e84a8016cbd63", "onWhatsApp": false, "docName": "", "file": "", "shortCut": "bom-dia", "text": "Bom dia! Como posso te ajudar?", "type": "text", "owner": "5511999999999" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/sse": { "get": { "operationId": "sse_get", "summary": "Server-Sent Events (SSE)", "description": "Opens a Server-Sent Events connection to receive events in real time.", "tags": [ "Webhooks and Events" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/webhook": { "get": { "operationId": "webhook_get", "summary": "View Instance Webhook", "description": "Returns the webhook configuration of the instance. The response is always an array, even with a single webhook.", "tags": [ "Webhooks and Events" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "url": "https://example.com", "enabled": false, "events": [], "id": "r1234" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "post": { "operationId": "webhook", "summary": "Configure Instance Webhook", "description": "Manages the instance webhooks. Supports simple mode (no action) and multi-webhook mode (with action: add/update/delete). To delete, send id + action \"delete\". Events come DISABLED by default. Enable only the ones you will consume (avoids unnecessary traffic). Only enable high-volume events (presence, history) if you will actually handle them.", "tags": [ "Webhooks and Events" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Unique webhook ID (required for update/delete)", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "enabled": { "description": "Enables/disables the webhook", "type": "boolean", "example": false }, "url": { "description": "URL to receive the events", "type": "string", "example": "https://example.com/webhook" }, "events": { "description": "List of events you want to receive on your webhook. EVERYTHING comes disabled by default: send only the ones you will use. Available: connection (connection), messages (received/sent messages), messages_update (status: delivered/read), history (history on connect, HIGH VOLUME), newsletter_messages (channel messages), call (calls), contacts, groups, chats, labels, chat_labels, presence (online/typing, HIGH VOLUME), blocks (blocks), sender. Example: [\"messages\",\"connection\",\"messages_update\"].", "example": [ "messages", "connection", "messages_update" ] }, "excludeMessages": { "description": "Filters to exclude message types" }, "addUrlEvents": { "description": "Adds the event type as a URL parameter.\n- `false` (default): normal URL\n- `true`: adds the event to the URL (e.g. `/webhook/message`)\n", "type": "boolean" }, "addUrlTypesMessages": { "description": "Adds the message type as a URL parameter.\n- `false` (default): normal URL \n- `true`: adds the message type (e.g. `/webhook/conversation`)\n", "type": "boolean" }, "action": { "description": "Action to perform:\n- add: create a new webhook\n- update: update an existing webhook (requires id)\n- delete: remove a webhook (requires only id)\nIf omitted, operates in simple mode (single webhook)\n", "type": "string", "enum": [ "add", "update", "delete" ] } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "Webhook deleted successfully" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/webhook/errors": { "get": { "operationId": "webhook_errors_get", "summary": "Webhook Errors", "description": "Lists the latest webhook delivery errors.", "tags": [ "Webhooks and Events" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "created": "2026-04-06T04:00:00Z", "url": "https://...", "event": "messages", "error": "timeout" } ] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/instances/{id}/webhook/deliveries": { "get": { "operationId": "gestao_webhook_deliveries", "summary": "Recent Webhook Deliveries", "description": "Lists the latest webhook deliveries of this instance (recent window, for debugging): event, whether it was delivered, HTTP status, latency, attempt number and time. Useful to check whether your endpoint is receiving and responding with 2xx.", "tags": [ "Webhooks and Events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Quantity (max 100)", "schema": { "type": "string", "example": "50" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "deliveries": [ { "delivery_id": "uuid", "event": "messages", "event_id": "abc", "ts": 1725600000000, "ok": true, "status": 200, "latency_ms": 142, "attempt": 1 } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/message/async": { "delete": { "operationId": "message_async_delete", "summary": "Clear Async Queue", "description": "Clears the entire async message queue.", "tags": [ "Async Queue" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Async queue cleared", "stats": { "removed": 0, "pending": 0 } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "get": { "operationId": "message_async_get", "summary": "View Async Queue", "description": "Queries the queue of pending async messages.", "tags": [ "Async Queue" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "queue": { "status": "idle", "pending": 0, "processingNow": false, "acceptingNewMessages": true }, "response": "Async queue status" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/agent/edit": { "post": { "operationId": "agent_edit", "summary": "Create/Edit AI Agent", "description": "Creates, edits or deletes an AI agent for automatic support. Send an empty id to create; filled to edit; delete=true to delete.", "tags": [ "Chatbot and AI" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Agent ID", "type": "string", "example": "Vazio para criar novo" }, "delete": { "description": "Delete", "type": "boolean", "default": false }, "agent": { "description": "Agent (JSON)", "example": { "name": "Assistente", "provider": "openai", "apikey": "sk-...", "model": "gpt-4o-mini", "basePrompt": "Voce é um assistente...", "maxTokens": 2000, "temperature": 70, "diversityLevel": 50, "frequencyPenalty": 30, "presencePenalty": 30, "signMessages": true, "readMessages": true, "maxMessageLength": 500, "typingDelay_seconds": 3, "contextTimeWindow_hours": 24, "contextMaxMessages": 50, "contextMinMessages": 3 } } }, "required": [ "agent" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "read16c9f35642c", "name": "Assistente", "provider": "openai", "model": "gpt-4o-mini", "apikey": "sk-...", "basePrompt": "Voce e um assistente...", "maxTokens": 500, "temperature": 70, "diversityLevel": 0, "frequencyPenalty": 0, "presencePenalty": 0, "signMessages": false, "readMessages": false, "maxMessageLength": 0, "typingDelay_seconds": 0, "contextTimeWindow_hours": 0, "contextMaxMessages": 0, "contextMinMessages": 0 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/agent/list": { "get": { "operationId": "agent_list_get", "summary": "List AI Agents", "description": "Lists all AI agents configured in the instance. Returns an empty array if no agent exists.", "tags": [ "Chatbot and AI" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/function/edit": { "post": { "operationId": "function_edit", "summary": "Create/Edit API Function", "description": "Creates, edits or deletes an API function for integration with external services. Send an empty id to create, filled to edit, delete=true to delete.", "tags": [ "Chatbot and AI" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Function ID. Empty to create a new one, filled to edit an existing one.", "type": "string" }, "delete": { "description": "If true, deletes the function specified by the ID.", "type": "boolean" }, "function": { "description": "Function configuration (JSON)", "example": { "name": "minha_funcao", "description": "Descricao da funcao", "active": false, "method": "GET", "endpoint": "https://api.example.com/endpoint", "headers": {}, "body": {}, "parameters": [] } } }, "required": [ "id", "delete", "function" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "r72440ced9503e3", "name": "minha_funcao", "description": "Descricao da funcao", "active": false, "method": "GET", "endpoint": "https://api.example.com/endpoint", "headers": "{}", "body": "{}", "parameters": "[]" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/function/list": { "get": { "operationId": "function_list_get", "summary": "List API Functions", "description": "Lists all configured API functions. Returns an empty array if no function exists.", "tags": [ "Chatbot and AI" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/knowledge/edit": { "post": { "operationId": "knowledge_edit", "summary": "Create/Edit Knowledge", "description": "Creates or edits a knowledge base for AI agents. (Requires an OpenAI API key configured on the instance)", "tags": [ "Chatbot and AI" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Knowledge ID (empty to create a new one)", "type": "string" }, "delete": { "description": "Defines whether this is a delete operation", "type": "boolean" }, "knowledge": { "description": "Knowledge content" }, "fileType": { "description": "File type when not detected automatically", "type": "string", "enum": [ "pdf", "txt", "html", "csv" ] } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/knowledge/list": { "get": { "operationId": "knowledge_list_get", "summary": "List Knowledge", "description": "Lists the entire knowledge base of the agents. Returns an empty array if no knowledge exists.", "tags": [ "Chatbot and AI" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/trigger/edit": { "post": { "operationId": "trigger_edit", "summary": "Create/Edit Trigger", "description": "Creates, edits or deletes a chatbot trigger. Requires an existing agent (agent_id).", "tags": [ "Chatbot and AI" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Trigger ID", "type": "string", "example": "Vazio para criar novo" }, "delete": { "description": "Delete", "type": "boolean", "default": false }, "trigger": { "description": "Trigger (JSON)", "example": { "active": true, "type": "agent", "agent_id": "id_do_agente", "ignoreGroups": true, "priority": 1, "wordsToStart": "ola|oi|iniciar", "responseDelay_seconds": 3, "lead_field": "", "lead_operator": "", "lead_value": "" } } }, "required": [ "trigger" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "rbcca9c181c1e5a", "active": false, "type": "agent", "agent_id": "read16c9f35642c", "flow_id": "", "quickReply_id": "", "ignoreGroups": true, "lead_field": "", "lead_operator": "", "lead_value": "", "priority": 1, "wordsToStart": "ola|oi", "responseDelay_seconds": 3 } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/trigger/list": { "get": { "operationId": "trigger_list_get", "summary": "List Triggers", "description": "Lists all configured chatbot triggers. Returns an empty array if no trigger exists.", "tags": [ "Chatbot and AI" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chat/editLead": { "post": { "operationId": "chat_editLead", "summary": "Edit Lead", "description": "Edits the lead data of a contact. The ID must include @s.whatsapp.net.", "tags": [ "CRM and Leads" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Chat ID (format: number@s.whatsapp.net)", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "lead_name": { "description": "Lead name", "type": "string", "example": "Joao Silva" }, "lead_email": { "description": "Lead email", "type": "string", "example": "joao@email.com" }, "lead_status": { "description": "Lead status in the funnel", "type": "string", "example": "qualificado" }, "lead_isTicketOpen": { "description": "Ticket open", "type": "boolean" }, "lead_tags": { "description": "Tags (JSON array)", "type": "string", "example": "[\"vip\",\"suporte\"]" }, "lead_notes": { "description": "Notes about the lead", "type": "string", "example": "Cliente interessado..." }, "lead_field01": { "description": "Custom field 01", "type": "string" }, "lead_field02": { "description": "Custom field 02", "type": "string" }, "chatbot_disableUntil": { "description": "Disable chatbot until (UTC timestamp, 0 to re-enable)", "type": "number", "example": 0 }, "lead_personalid": { "description": "Lead Personalid", "type": "string" }, "lead_field03": { "description": "Lead Field03", "type": "string" }, "lead_field04": { "description": "Lead Field04", "type": "string" }, "lead_field05": { "description": "Lead Field05", "type": "string" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "chat": { "lead_name": "Joao", "lead_email": "joao@email.com" }, "source": "local" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/instance/updateFieldsMap": { "post": { "operationId": "instance_updateFieldsMap", "summary": "Custom Lead Fields", "description": "Sets the names of the lead fields. Fields are flat (lead_field01, lead_field02, etc).", "tags": [ "CRM and Leads" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_field01": { "description": "Field 01", "type": "string", "example": "nome" }, "lead_field02": { "description": "Field 02", "type": "string", "example": "email" }, "lead_field03": { "description": "Field 03", "type": "string", "example": "telefone" }, "lead_field04": { "description": "Field 04", "type": "string", "example": "cidade" }, "lead_field05": { "description": "Field 05", "type": "string", "example": "estado" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "raa287d88df6336", "name": "minha-instancia", "fieldsMap": { "lead_field01": "nome", "lead_field02": "email", "lead_field03": "telefone" } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/chatwoot/config": { "get": { "operationId": "chatwoot_config_get", "summary": "View Chatwoot Config", "description": "Returns the current Chatwoot integration configuration, including connection status.", "tags": [ "Chatwoot Integration" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "chatwoot_enabled": false, "chatwoot_url": "", "chatwoot_account_id": 0, "chatwoot_inbox_id": 0, "chatwoot_inbox_name": "minha-instancia", "chatwoot_access_token": "", "chatwoot_ignore_groups": false, "chatwoot_sign_messages": false, "chatwoot_create_new_conversation": false, "integration_status": { "status": "disabled", "message": "Integracao Chatwoot nao esta habilitada", "connection_ok": false, "credentials_ok": false, "inbox_exists": false } } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } }, "put": { "operationId": "chatwoot_config_put", "summary": "Configure Chatwoot", "description": "Updates the Chatwoot integration configuration. Fields use the chatwoot_ prefix. Integration in beta.", "tags": [ "Chatwoot Integration" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chatwoot_enabled": { "description": "Enable integration", "type": "boolean" }, "chatwoot_url": { "description": "Chatwoot URL (without trailing slash)", "type": "string", "example": "https://app.chatwoot.com" }, "chatwoot_access_token": { "description": "Chatwoot access token", "type": "string", "example": "pXXGHHHyJPYHYgWHJHYHgJjj" }, "chatwoot_account_id": { "description": "Chatwoot account ID", "type": "number", "example": 1 }, "chatwoot_inbox_id": { "description": "Chatwoot inbox ID", "type": "number", "example": 5 }, "chatwoot_ignore_groups": { "description": "Ignore groups", "type": "boolean" }, "chatwoot_sign_messages": { "description": "Sign messages", "type": "boolean" }, "chatwoot_create_new_conversation": { "description": "Always create a new conversation", "type": "boolean" } }, "required": [ "chatwoot_enabled" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Chatwoot config updated successfully" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/flows": { "get": { "operationId": "flows_list", "summary": "List Flows", "description": "Lists all of the user's flows, including status (enabled/disabled) and trigger type.", "tags": [ "Flows" ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "flows": [ { "id": "abc-123", "name": "Atendimento Delivery", "description": "Fluxo de atendimento automatico", "enabled": true, "trigger": { "type": "keyword", "value": "menu" }, "created_at": "2026-04-10T12:00:00.000Z", "updated_at": "2026-04-15T18:30:00.000Z" } ] } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/flows/{flowId}/trigger": { "post": { "operationId": "flows_trigger", "summary": "Trigger Flow", "description": "Triggers a flow for a specific contact. The flow must be enabled and the instance connected. Optional variables are available inside the flow as {variable_name}. When it reaches a webhook block, all collected variables (answers, clicks, contact data) are sent to the configured URL.", "tags": [ "Flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "description": "Flow ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "description": "Instance ID", "type": "string", "example": "inst-456" }, "phone": { "description": "Contact phone", "type": "string", "example": "5511999999999" }, "variables": { "description": "Initial variables (JSON object)", "example": { "nome": "Joao", "plano": "premium" } } }, "required": [ "instance_id", "phone" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "execution_id": "exec-789", "status": "waiting_reply", "flow_id": "abc-123", "phone": "5511999999999" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } }, "/{instanceId}/tracking/conversion": { "post": { "operationId": "tracking_conversion", "summary": "Register a sale from an ad lead", "description": "Reports that a lead that came from an ad became a sale. It is what allows Meta to learn who actually buys, instead of optimizing only for who replies to messages. Use it when the payment is confirmed in your system. Calling it twice for the same sale does not duplicate it.", "tags": [ "Meta Tracking" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "WhatsApp instance ID (shown in the dashboard).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "value": { "type": "number" }, "event": { "type": "string" }, "occurred_at": { "type": "string" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "message": "Venda registrada e enviada para a Meta.", "event": "Purchase", "value": 700, "ad_id": "120243748541570695", "lead_status": "won", "status": "queued" } } } }, "400": { "description": "Invalid request (missing or malformed fields)." }, "401": { "description": "Invalid credentials (x-api-key / x-api-secret)." }, "429": { "description": "Rate limit exceeded." } } } } } }