{
"openapi": "3.1.0",
"paths": {
"/instances/{instance_id}/token/{token}/qr-code": {
"get": {
"description": "Retorna o QR code atual como data URL PNG (`data:image/png;base64,...`). Consulte a cada ~10s enquanto o status for `qr`; cada QR expira em `expires_at` e um novo é gerado automaticamente. `value` é `null` quando não há QR disponível (instância já conectada ou sessão ainda não iniciada). Se a instância ainda não estiver rodando, esta rota inicia a sessão e aguarda alguns segundos pelo primeiro QR.",
"operationId": "instance.qrCode",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "QR code atual. Quando não há QR o corpo é `{ \"value\": null, \"connected\": true|false }` (sem `expires_at`).",
"content": {
"application/json": {
"example": {
"value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAAAAACo...",
"expires_at": "2026-08-18T12:01:00.000Z",
"connected": false
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "QR code (base64)",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/qr-code/image": {
"get": {
"description": "Mesmo QR de `GET /qr-code`, mas entregue como imagem PNG (512×512) — útil para exibir direto em uma tag `![]()
`. Responde `404 not_found` quando não há QR disponível (instância conectada ou sessão ainda não iniciada).",
"operationId": "instance.qrCodeImage",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Imagem PNG do QR code.",
"content": {
"image/png": {}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"404": {
"description": "Nenhum QR disponível no momento.",
"content": {
"application/json": {
"example": {
"error": {
"code": "not_found",
"message": "No QR code available for this instance right now"
}
}
}
}
}
},
"summary": "QR code (imagem PNG)",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/phone-code/{phone}": {
"get": {
"description": "Alternativa ao QR: gera o código para a opção \"Conectar com número de telefone\" do WhatsApp. `phone` é o número que será conectado, com DDI e sem símbolos. A sessão precisa estar em `qr` (aguardando pareamento); caso contrário retorna `409 instance_not_connected`.",
"operationId": "instance.phoneCode",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"description": "Número que será conectado (DDI + DDD + número, só dígitos).",
"schema": {
"example": "5511988887777",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Código a ser digitado no celular.",
"content": {
"application/json": {
"example": {
"value": "A1B2C3D4"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Código de pareamento por número",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/status": {
"get": {
"description": "Consulta o status ao vivo no engine (cai para a última visão conhecida se o engine não responder). `status` é um de `created`, `starting`, `qr`, `connecting`, `connected`, `disconnected`, `logged_out`, `banned`, `stopped`. `smartphone_connected` indica se o celular está alcançável. `error` é `null` quando conectada; caso contrário traz uma frase explicando o motivo.",
"operationId": "instance.status",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Status atual da instância. Desconectada: `{ \"connected\": false, \"smartphone_connected\": false, \"status\": \"qr\", \"phone\": null, \"error\": \"You need to scan the QR code\" }`.",
"content": {
"application/json": {
"example": {
"connected": true,
"smartphone_connected": true,
"status": "connected",
"phone": "5511988887777",
"error": null
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Status da conexão",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/me": {
"get": {
"description": "Retorna a instância completa: identificação, `token`, status, número conectado, assinatura, `settings`, `webhooks` e a `api_url` base pronta para uso.",
"operationId": "instance.me",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Instância.",
"content": {
"application/json": {
"example": {
"id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"name": "Atendimento",
"token": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"status": "connected",
"status_reason": null,
"connected": true,
"phone": "5511988887777",
"profile_name": "Wabox",
"platform": "android",
"connected_at": "2026-08-18T12:00:30.000Z",
"disconnected_at": null,
"subscription_status": "active",
"trial_ends_at": "2026-08-20T12:00:00.000Z",
"due_at": "2026-09-18T12:00:00.000Z",
"settings": {
"auto_read_message": false,
"auto_read_status": false,
"call_reject_auto": false,
"call_reject_message": null,
"disable_enqueue_when_disconnected": false,
"delay_message_min_ms": 1000,
"delay_message_max_ms": 3000,
"proxy_url": null
},
"webhooks": {
"received_url": "https://example.com/wabox/received",
"delivery_url": "https://example.com/wabox/delivery",
"message_status_url": "https://example.com/wabox/message-status",
"connected_url": "https://example.com/wabox/connected",
"disconnected_url": "https://example.com/wabox/disconnected",
"chat_presence_url": null,
"notify_sent_by_me": false,
"ignore_groups": false,
"ignore_private": false,
"ignore_text": false,
"ignore_image": false,
"ignore_video": false,
"ignore_audio": false,
"ignore_document": false,
"ignore_received_callback": false,
"ignore_delivery_callback": false,
"ignore_message_status_callback": false,
"ignore_connected_callback": false,
"ignore_disconnected_callback": false,
"ignore_chat_presence_callback": false,
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
},
"api_url": "https://api.wabox.me/instances/8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b/token/3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"created_at": "2026-08-18T11:58:00.000Z",
"updated_at": "2026-08-18T12:00:30.000Z"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Dados e configuração da instância",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/device": {
"get": {
"description": "Número, JID, nome do perfil, plataforma (`android`, `ios`…) e data da conexão do aparelho vinculado. Retorna `409 instance_not_connected` se a instância não estiver conectada.",
"operationId": "instance.device",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Aparelho conectado.",
"content": {
"application/json": {
"example": {
"phone": "5511988887777",
"jid": "5511988887777:12@s.whatsapp.net",
"name": "Wabox",
"platform": "android",
"connected_at": "2026-08-18T12:00:30.000Z"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Dados do celular conectado",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/restart": {
"post": {
"description": "Reinicia a sessão da instância no engine sem deslogar o WhatsApp — a conexão é refeita com as credenciais salvas. Use quando a instância travar em `disconnected` ou após alterar `settings` de sessão. `status` é o status logo após o reinício (normalmente `connecting`).",
"operationId": "instance.restart",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"201": {
"description": "Sessão reiniciada.",
"content": {
"application/json": {
"example": {
"value": true,
"status": "connecting"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Reiniciar a sessão",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/disconnect": {
"post": {
"description": "Desloga a conta do WhatsApp desta instância — o aparelho vinculado é removido e a instância vai para `logged_out`. Para conectar de novo será preciso ler um novo QR code.",
"operationId": "instance.disconnect",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"201": {
"description": "Conta desconectada.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Desconectar (logout do WhatsApp)",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/name": {
"put": {
"description": "Altera o nome exibido no dashboard (1 a 80 caracteres). Não afeta o perfil do WhatsApp.",
"operationId": "instance.rename",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"value"
]
},
"examples": {
"basico": {
"summary": "Renomear",
"value": {
"value": "Atendimento"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Nome atualizado.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Renomear a instância",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/webhooks": {
"get": {
"description": "URLs de cada tipo de webhook (`*_url`, `null` = desativado), filtros (`notify_sent_by_me`, `ignore_*`) e o `secret` de assinatura. `secret` assina toda entrega: header `X-Wabox-Signature: t=,v1=` onde `v1 = HMAC-SHA256(secret, \".\")`. Valide recalculando sobre o corpo bruto da requisição e rejeite timestamps com mais de alguns minutos. `secret` é `null` quando as entregas não são assinadas.",
"operationId": "instance.webhooks",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Configuração de webhooks.",
"content": {
"application/json": {
"example": {
"received_url": "https://example.com/wabox/received",
"delivery_url": "https://example.com/wabox/delivery",
"message_status_url": "https://example.com/wabox/message-status",
"connected_url": "https://example.com/wabox/connected",
"disconnected_url": "https://example.com/wabox/disconnected",
"chat_presence_url": null,
"notify_sent_by_me": false,
"ignore_groups": false,
"ignore_private": false,
"ignore_text": false,
"ignore_image": false,
"ignore_video": false,
"ignore_audio": false,
"ignore_document": false,
"ignore_received_callback": false,
"ignore_delivery_callback": false,
"ignore_message_status_callback": false,
"ignore_connected_callback": false,
"ignore_disconnected_callback": false,
"ignore_chat_presence_callback": false,
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Webhooks: URLs, filtros e secret",
"tags": [
"Instance"
]
},
"put": {
"description": "Atualiza só os campos enviados; os demais ficam como estão. Envie `null` em uma `*_url` para desativar aquele webhook. URLs precisam ser http(s). Retorna a configuração completa após a alteração.",
"operationId": "instance.updateWebhooks",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"received_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"delivery_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"message_status_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"connected_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"disconnected_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"chat_presence_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"notify_sent_by_me": {
"type": "boolean"
},
"ignore_groups": {
"type": "boolean"
},
"ignore_private": {
"type": "boolean"
},
"ignore_text": {
"type": "boolean"
},
"ignore_image": {
"type": "boolean"
},
"ignore_video": {
"type": "boolean"
},
"ignore_audio": {
"type": "boolean"
},
"ignore_document": {
"type": "boolean"
},
"ignore_received_callback": {
"type": "boolean"
},
"ignore_delivery_callback": {
"type": "boolean"
},
"ignore_message_status_callback": {
"type": "boolean"
},
"ignore_connected_callback": {
"type": "boolean"
},
"ignore_disconnected_callback": {
"type": "boolean"
},
"ignore_chat_presence_callback": {
"type": "boolean"
}
}
},
"examples": {
"basico": {
"summary": "Definir URLs e ignorar grupos",
"value": {
"received_url": "https://example.com/wabox/received",
"message_status_url": "https://example.com/wabox/message-status",
"ignore_groups": true
}
},
"desativar": {
"summary": "Desativar um webhook",
"value": {
"chat_presence_url": null
}
}
}
}
}
},
"responses": {
"200": {
"description": "Configuração de webhooks após a alteração.",
"content": {
"application/json": {
"example": {
"received_url": "https://example.com/wabox/received",
"delivery_url": "https://example.com/wabox/delivery",
"message_status_url": "https://example.com/wabox/message-status",
"connected_url": "https://example.com/wabox/connected",
"disconnected_url": "https://example.com/wabox/disconnected",
"chat_presence_url": null,
"notify_sent_by_me": false,
"ignore_groups": true,
"ignore_private": false,
"ignore_text": false,
"ignore_image": false,
"ignore_video": false,
"ignore_audio": false,
"ignore_document": false,
"ignore_received_callback": false,
"ignore_delivery_callback": false,
"ignore_message_status_callback": false,
"ignore_connected_callback": false,
"ignore_disconnected_callback": false,
"ignore_chat_presence_callback": false,
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Atualizar webhooks (parcial)",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/webhooks/secret": {
"post": {
"description": "Gera um novo `secret` de assinatura e passa a usá-lo imediatamente. Entregas já enfileiradas mantêm o secret anterior nas retentativas restantes.",
"operationId": "instance.rotateWebhookSecret",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"201": {
"description": "Novo secret.",
"content": {
"application/json": {
"example": {
"secret": "whsec_0a1b2c3d4e5f60718293a4b5c6d7e8f9"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Rotacionar o secret dos webhooks",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/webhooks/{type}": {
"put": {
"description": "`type` ∈ `received` | `delivery` | `message_status` | `connected` | `disconnected` | `chat_presence`. Body: `{ \"value\": \"https://...\" }` (`null` para desativar). Retorna a configuração completa de webhooks.",
"operationId": "instance.updateWebhook",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "type",
"required": true,
"in": "path",
"description": "Tipo do webhook.",
"schema": {
"enum": [
"received",
"delivery",
"message_status",
"connected",
"disconnected",
"chat_presence"
],
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"nullable": true,
"type": "string",
"format": "uri"
}
},
"required": [
"value"
]
},
"examples": {
"basico": {
"summary": "Definir URL",
"value": {
"value": "https://example.com/wabox/received"
}
},
"desativar": {
"summary": "Desativar",
"value": {
"value": null
}
}
}
}
}
},
"responses": {
"200": {
"description": "Configuração de webhooks após a alteração.",
"content": {
"application/json": {
"example": {
"received_url": "https://example.com/wabox/received",
"delivery_url": "https://example.com/wabox/delivery",
"message_status_url": "https://example.com/wabox/message-status",
"connected_url": "https://example.com/wabox/connected",
"disconnected_url": "https://example.com/wabox/disconnected",
"chat_presence_url": null,
"notify_sent_by_me": false,
"ignore_groups": false,
"ignore_private": false,
"ignore_text": false,
"ignore_image": false,
"ignore_video": false,
"ignore_audio": false,
"ignore_document": false,
"ignore_received_callback": false,
"ignore_delivery_callback": false,
"ignore_message_status_callback": false,
"ignore_connected_callback": false,
"ignore_disconnected_callback": false,
"ignore_chat_presence_callback": false,
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Definir a URL de um webhook",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/settings": {
"get": {
"description": "`auto_read_message`/`auto_read_status`: marcar mensagens/status como lidos automaticamente. `call_reject_auto` + `call_reject_message`: rejeitar chamadas e responder com um texto. `disable_enqueue_when_disconnected`: recusar envios (`409 queue_disabled_while_disconnected`) em vez de enfileirar enquanto desconectada. `delay_message_min_ms`/`delay_message_max_ms`: intervalo aleatório entre envios (anti-ban). `proxy_url`: proxy usado pela sessão.",
"operationId": "instance.settings",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Configurações atuais.",
"content": {
"application/json": {
"example": {
"auto_read_message": false,
"auto_read_status": false,
"call_reject_auto": false,
"call_reject_message": null,
"disable_enqueue_when_disconnected": false,
"delay_message_min_ms": 1000,
"delay_message_max_ms": 3000,
"proxy_url": null
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Configurações da instância",
"tags": [
"Instance"
]
},
"put": {
"description": "Atualiza só os campos enviados e retorna as configurações completas. `delay_message_min_ms` não pode ser maior que `delay_message_max_ms` (`409 conflict`). Configurações de sessão (`auto_read_*`, `call_reject_*`, `proxy_url`) só passam a valer após um `restart`.",
"operationId": "instance.updateSettings",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"auto_read_message": {
"type": "boolean"
},
"auto_read_status": {
"type": "boolean"
},
"call_reject_auto": {
"type": "boolean"
},
"call_reject_message": {
"nullable": true,
"type": "string",
"maxLength": 1000
},
"disable_enqueue_when_disconnected": {
"type": "boolean"
},
"delay_message_min_ms": {
"type": "integer",
"minimum": 0,
"maximum": 15000
},
"delay_message_max_ms": {
"type": "integer",
"minimum": 0,
"maximum": 15000
},
"proxy_url": {
"nullable": true,
"type": "string",
"format": "uri"
}
}
},
"examples": {
"basico": {
"summary": "Leitura automática e intervalo de envio",
"value": {
"auto_read_message": true,
"delay_message_min_ms": 2000,
"delay_message_max_ms": 5000
}
}
}
}
}
},
"responses": {
"200": {
"description": "Configurações após a alteração.",
"content": {
"application/json": {
"example": {
"auto_read_message": true,
"auto_read_status": false,
"call_reject_auto": false,
"call_reject_message": null,
"disable_enqueue_when_disconnected": false,
"delay_message_min_ms": 2000,
"delay_message_max_ms": 5000,
"proxy_url": null
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Atualizar configurações (parcial)",
"tags": [
"Instance"
]
}
},
"/instances/{instance_id}/token/{token}/send-text": {
"post": {
"description": "Suporta resposta (`reply_to_message_id`), menções e edição (`edit_message_id`). Formatação do texto: `*negrito*`, `_itálico_`, `~riscado~` e `` ```mono``` ``.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.\n\nRitmo de envio (anti-ban): cada mensagem espera um atraso aleatório antes de sair (configurações da instância `delay_message_min_ms`/`delay_message_max_ms`, padrão 1–3 s; defina os dois como 0 para desativar), contado a partir do fim da mensagem anterior da mesma instância quando ainda houver uma em andamento. `delay_message` (segundos, 0–15) substitui esse atraso só para esta mensagem e `delay_typing` (segundos, 0–15) mostra \"digitando…\" por esse tempo antes de enviar.",
"operationId": "send.sendText",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 65536,
"description": "Texto da mensagem. Aceita a formatação do WhatsApp (`*negrito*`, `_itálico_`, `~riscado~`, ```` ```mono``` ````)."
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"edit_message_id": {
"description": "Edita a mensagem indicada (só mensagens suas recentes que o engine tem em cache).",
"type": "string",
"minLength": 1
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"message"
]
},
"examples": {
"basico": {
"summary": "Texto simples",
"value": {
"phone": "5511988887777",
"message": "Olá! Seu pedido *#1234* foi confirmado."
}
},
"resposta": {
"summary": "Responder uma mensagem com menção e digitando…",
"value": {
"phone": "120363012345678901-group",
"message": "@5511977776666 pode confirmar?",
"reply_to_message_id": "3EB0F1A2B3C4D5E6F7A8",
"mentioned": [
"5511977776666"
],
"delay_typing": 2
}
},
"editar": {
"summary": "Editar uma mensagem enviada",
"value": {
"phone": "5511988887777",
"message": "Olá! Seu pedido *#1234* foi enviado.",
"edit_message_id": "3EB0A9C6D2F1E4B5A7C8"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar texto",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-link": {
"post": {
"description": "Título, descrição e imagem do preview são definidos por você (não há scraping da página). A URL é acrescentada ao texto quando ainda não estiver nele.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendLink",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 65536
},
"url": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string",
"maxLength": 1000
},
"description": {
"type": "string",
"maxLength": 5000
},
"image": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"message",
"url"
]
},
"examples": {
"basico": {
"summary": "Link com preview",
"value": {
"phone": "5511988887777",
"message": "Veja as novidades no nosso site: https://wabox.me",
"url": "https://wabox.me",
"title": "Wabox — API de WhatsApp",
"description": "Envie e receba mensagens via REST e webhooks.",
"image": "https://wabox.me/og.png"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar texto com preview de link",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-image": {
"post": {
"description": "A mídia pode ser uma URL http(s) (baixada pelo engine), uma `data:` URL ou base64 puro. Use `mime_type`/`file_name` quando o tipo não puder ser inferido. Limites: 16 MB para imagens/áudios/vídeos/stickers, 100 MB para documentos (arquivos maiores falham no webhook `delivery` com `media_invalid`). Envios de mídia são processados um por vez por instância. `edit_message_id` substitui a legenda de uma imagem que esta instância enviou.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendImage",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"image": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"caption": {
"description": "Legenda.",
"type": "string",
"maxLength": 65536
},
"view_once": {
"description": "Visualização única.",
"type": "boolean"
},
"edit_message_id": {
"type": "string",
"minLength": 1
},
"mime_type": {
"description": "Sobrescreve o MIME type detectado.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"file_name": {
"description": "Nome do arquivo (documentos) — também usado para inferir o MIME type.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"image"
]
},
"examples": {
"url": {
"summary": "Imagem por URL",
"value": {
"phone": "5511988887777",
"image": "https://exemplo.com/produto.jpg",
"caption": "Chegou o novo modelo!"
}
},
"base64": {
"summary": "Imagem em base64 (data URL)",
"value": {
"phone": "5511988887777",
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
"caption": "Comprovante",
"file_name": "comprovante.png"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar imagem",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-audio": {
"post": {
"description": "A mídia pode ser uma URL http(s) (baixada pelo engine), uma `data:` URL ou base64 puro. Use `mime_type`/`file_name` quando o tipo não puder ser inferido. Limites: 16 MB para imagens/áudios/vídeos/stickers, 100 MB para documentos (arquivos maiores falham no webhook `delivery` com `media_invalid`). Envios de mídia são processados um por vez por instância. `ptt: true` (padrão) envia como mensagem de voz — convertida para Opus/OGG com waveform quando o engine tem ffmpeg. `delay_typing` mostra \"gravando áudio…\".\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendAudio",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"audio": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"ptt": {
"default": true,
"type": "boolean"
},
"waveform": {
"type": "boolean"
},
"view_once": {
"description": "Visualização única.",
"type": "boolean"
},
"mime_type": {
"description": "Sobrescreve o MIME type detectado.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"file_name": {
"description": "Nome do arquivo (documentos) — também usado para inferir o MIME type.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"audio"
]
},
"examples": {
"url": {
"summary": "Mensagem de voz por URL",
"value": {
"phone": "5511988887777",
"audio": "https://exemplo.com/audio.mp3",
"delay_typing": 3
}
},
"base64": {
"summary": "Arquivo de áudio em base64",
"value": {
"phone": "5511988887777",
"audio": "T2dnUwACAAAAAAAAAAB4Q9kbAAAAAJXUrPMBE09wdXNIZWFkAQE4AYC7AAAAAAA=",
"mime_type": "audio/ogg",
"ptt": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar áudio / mensagem de voz",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-video": {
"post": {
"description": "A mídia pode ser uma URL http(s) (baixada pelo engine), uma `data:` URL ou base64 puro. Use `mime_type`/`file_name` quando o tipo não puder ser inferido. Limites: 16 MB para imagens/áudios/vídeos/stickers, 100 MB para documentos (arquivos maiores falham no webhook `delivery` com `media_invalid`). Envios de mídia são processados um por vez por instância.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendVideo",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"video": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"caption": {
"description": "Legenda.",
"type": "string",
"maxLength": 65536
},
"view_once": {
"description": "Visualização única.",
"type": "boolean"
},
"edit_message_id": {
"type": "string",
"minLength": 1
},
"mime_type": {
"description": "Sobrescreve o MIME type detectado.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"file_name": {
"description": "Nome do arquivo (documentos) — também usado para inferir o MIME type.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"video"
]
},
"examples": {
"basico": {
"summary": "Vídeo MP4 por URL",
"value": {
"phone": "5511988887777",
"video": "https://exemplo.com/demo.mp4",
"caption": "Veja como funciona"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar vídeo",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-ptv": {
"post": {
"description": "A mídia pode ser uma URL http(s) (baixada pelo engine), uma `data:` URL ou base64 puro. Use `mime_type`/`file_name` quando o tipo não puder ser inferido. Limites: 16 MB para imagens/áudios/vídeos/stickers, 100 MB para documentos (arquivos maiores falham no webhook `delivery` com `media_invalid`). Envios de mídia são processados um por vez por instância.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendPtv",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"ptv": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"mime_type": {
"description": "Sobrescreve o MIME type detectado.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"file_name": {
"description": "Nome do arquivo (documentos) — também usado para inferir o MIME type.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"ptv"
]
},
"examples": {
"basico": {
"summary": "Vídeo curto MP4 por URL",
"value": {
"phone": "5511988887777",
"ptv": "https://exemplo.com/recado.mp4"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar vídeo redondo (PTV)",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-gif": {
"post": {
"description": "A mídia pode ser uma URL http(s) (baixada pelo engine), uma `data:` URL ou base64 puro. Use `mime_type`/`file_name` quando o tipo não puder ser inferido. Limites: 16 MB para imagens/áudios/vídeos/stickers, 100 MB para documentos (arquivos maiores falham no webhook `delivery` com `media_invalid`). Envios de mídia são processados um por vez por instância. Envie um MP4; arquivos .gif de verdade são convertidos quando o engine tem ffmpeg.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendGif",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"gif": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"caption": {
"description": "Legenda.",
"type": "string",
"maxLength": 65536
},
"mime_type": {
"description": "Sobrescreve o MIME type detectado.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"file_name": {
"description": "Nome do arquivo (documentos) — também usado para inferir o MIME type.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"gif"
]
},
"examples": {
"basico": {
"summary": "GIF (MP4) por URL",
"value": {
"phone": "5511988887777",
"gif": "https://exemplo.com/festa.mp4",
"caption": "Parabéns!"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar GIF (MP4 com reprodução de GIF)",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-document": {
"post": {
"description": "A mídia pode ser uma URL http(s) (baixada pelo engine), uma `data:` URL ou base64 puro. Use `mime_type`/`file_name` quando o tipo não puder ser inferido. Limites: 16 MB para imagens/áudios/vídeos/stickers, 100 MB para documentos (arquivos maiores falham no webhook `delivery` com `media_invalid`). Envios de mídia são processados um por vez por instância. A extensão pode ir no path (`send-document/pdf`, no estilo z-api) ou no body (`extension`); ela define o nome do arquivo/MIME type quando faltarem (`document.pdf` se `file_name` não for enviado). Extensão inválida (fora de `[a-z0-9]{1,10}`) responde 400 `invalid_request`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendDocument[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "extension",
"required": true,
"in": "path",
"description": "Extensão do arquivo (`pdf`, `xlsx`…). Alternativa ao campo `extension` do body.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"document": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"extension": {
"type": "string",
"pattern": "^[A-Za-z0-9]{1,10}$"
},
"caption": {
"description": "Legenda.",
"type": "string",
"maxLength": 65536
},
"edit_message_id": {
"type": "string",
"minLength": 1
},
"mime_type": {
"description": "Sobrescreve o MIME type detectado.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"file_name": {
"description": "Nome do arquivo (documentos) — também usado para inferir o MIME type.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"document"
]
},
"examples": {
"url": {
"summary": "PDF por URL",
"value": {
"phone": "5511988887777",
"document": "https://exemplo.com/fatura-1234.pdf",
"file_name": "fatura-1234.pdf",
"caption": "Sua fatura de setembro"
}
},
"base64": {
"summary": "PDF em base64 (data URL)",
"value": {
"phone": "5511988887777",
"document": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCg==",
"extension": "pdf",
"file_name": "contrato"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar documento",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-document/{extension}": {
"post": {
"description": "A mídia pode ser uma URL http(s) (baixada pelo engine), uma `data:` URL ou base64 puro. Use `mime_type`/`file_name` quando o tipo não puder ser inferido. Limites: 16 MB para imagens/áudios/vídeos/stickers, 100 MB para documentos (arquivos maiores falham no webhook `delivery` com `media_invalid`). Envios de mídia são processados um por vez por instância. A extensão pode ir no path (`send-document/pdf`, no estilo z-api) ou no body (`extension`); ela define o nome do arquivo/MIME type quando faltarem (`document.pdf` se `file_name` não for enviado). Extensão inválida (fora de `[a-z0-9]{1,10}`) responde 400 `invalid_request`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendDocument[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "extension",
"required": true,
"in": "path",
"description": "Extensão do arquivo (`pdf`, `xlsx`…). Alternativa ao campo `extension` do body.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"document": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"extension": {
"type": "string",
"pattern": "^[A-Za-z0-9]{1,10}$"
},
"caption": {
"description": "Legenda.",
"type": "string",
"maxLength": 65536
},
"edit_message_id": {
"type": "string",
"minLength": 1
},
"mime_type": {
"description": "Sobrescreve o MIME type detectado.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"file_name": {
"description": "Nome do arquivo (documentos) — também usado para inferir o MIME type.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"document"
]
},
"examples": {
"url": {
"summary": "PDF por URL",
"value": {
"phone": "5511988887777",
"document": "https://exemplo.com/fatura-1234.pdf",
"file_name": "fatura-1234.pdf",
"caption": "Sua fatura de setembro"
}
},
"base64": {
"summary": "PDF em base64 (data URL)",
"value": {
"phone": "5511988887777",
"document": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCg==",
"extension": "pdf",
"file_name": "contrato"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar documento (compatibilidade z-api)",
"tags": [
"Messages"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/send-sticker": {
"post": {
"description": "A mídia pode ser uma URL http(s) (baixada pelo engine), uma `data:` URL ou base64 puro. Use `mime_type`/`file_name` quando o tipo não puder ser inferido. Limites: 16 MB para imagens/áudios/vídeos/stickers, 100 MB para documentos (arquivos maiores falham no webhook `delivery` com `media_invalid`). Envios de mídia são processados um por vez por instância. WebP é enviado como está; PNG/JPEG/GIF são convertidos para WebP 512×512 quando o engine tem ffmpeg.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendSticker",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"sticker": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"mime_type": {
"description": "Sobrescreve o MIME type detectado.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"file_name": {
"description": "Nome do arquivo (documentos) — também usado para inferir o MIME type.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"sticker"
]
},
"examples": {
"basico": {
"summary": "Sticker WebP por URL",
"value": {
"phone": "5511988887777",
"sticker": "https://exemplo.com/sticker.webp"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar sticker",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-location": {
"post": {
"description": "A mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendLocation",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"name": {
"type": "string",
"maxLength": 1000
},
"address": {
"type": "string",
"maxLength": 1000
},
"url": {
"type": "string",
"format": "uri"
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"latitude",
"longitude"
]
},
"examples": {
"basico": {
"summary": "Localização com nome e endereço",
"value": {
"phone": "5511988887777",
"latitude": -23.55052,
"longitude": -46.633308,
"name": "Wabox",
"address": "Praça da Sé, São Paulo - SP"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar localização",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-contact": {
"post": {
"description": "Envia um único vCard. Para vários contatos na mesma mensagem use `send-contacts`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendContact",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"contact_name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"contact_phone": {
"type": "string",
"pattern": "^\\d{5,20}$"
},
"contact_description": {
"type": "string",
"maxLength": 1000
},
"vcard": {
"type": "string",
"maxLength": 16384
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"contact_name",
"contact_phone"
]
},
"examples": {
"basico": {
"summary": "Contato",
"value": {
"phone": "5511988887777",
"contact_name": "Maria Silva",
"contact_phone": "5511977776666",
"contact_description": "Atendimento Wabox"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar cartão de contato",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-contacts": {
"post": {
"description": "Até 50 cartões na mesma mensagem.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendContacts",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"contacts": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"phone": {
"type": "string",
"pattern": "^\\d{5,20}$"
},
"description": {
"type": "string",
"maxLength": 1000
},
"vcard": {
"type": "string",
"maxLength": 16384
}
},
"required": [
"name",
"phone"
]
}
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"contacts"
]
},
"examples": {
"basico": {
"summary": "Dois contatos",
"value": {
"phone": "5511988887777",
"contacts": [
{
"name": "Maria Silva",
"phone": "5511977776666",
"description": "Atendimento"
},
{
"name": "João Souza",
"phone": "5511966665555"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar vários contatos em uma mensagem",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-reaction": {
"post": {
"description": "Retorna o id da mensagem que recebeu a reação. Em grupos, informe `participant` (quem enviou a mensagem) e `from_me` quando o engine não conhecer a mensagem. A mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendReaction",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message_id": {
"type": "string",
"minLength": 1
},
"reaction": {
"type": "string",
"minLength": 1,
"maxLength": 16
},
"from_me": {
"description": "Se a mensagem referenciada foi enviada por esta instância. Padrão: o que o engine registrou, senão `false`.",
"type": "boolean"
},
"participant": {
"description": "Grupos: número do participante que enviou a mensagem referenciada.",
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"message_id",
"reaction"
]
},
"examples": {
"basico": {
"summary": "Reagir com emoji",
"value": {
"phone": "5511988887777",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"reaction": "👍"
}
},
"grupo": {
"summary": "Reagir em grupo à mensagem de um participante",
"value": {
"phone": "120363012345678901-group",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"reaction": "❤️",
"participant": "5511977776666",
"from_me": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Ação enfileirada. `message_id`/`id` é o id da mensagem referenciada; o resultado chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Reagir a uma mensagem",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/remove-reaction": {
"post": {
"description": "Envia uma reação vazia para a mensagem informada. A mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.removeReaction",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message_id": {
"type": "string",
"minLength": 1
},
"from_me": {
"description": "Se a mensagem referenciada foi enviada por esta instância. Padrão: o que o engine registrou, senão `false`.",
"type": "boolean"
},
"participant": {
"description": "Grupos: número do participante que enviou a mensagem referenciada.",
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"message_id"
]
},
"examples": {
"basico": {
"summary": "Remover reação",
"value": {
"phone": "5511988887777",
"message_id": "3EB0A9C6D2F1E4B5A7C8"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Ação enfileirada. `message_id`/`id` é o id da mensagem referenciada; o resultado chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Remover sua reação de uma mensagem",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/forward-message": {
"post": {
"description": "Só é possível encaminhar mensagens que esta instância enviou ou recebeu recentemente (o engine mantém um histórico limitado em memória; nada é armazenado em repouso). Caso contrário o webhook `delivery` reporta `message_not_found`. `from_phone` indica o chat de origem quando for diferente do destino. A mensagem encaminhada recebe um id novo, que é o `message_id` retornado.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.forwardMessage",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message_id": {
"type": "string",
"minLength": 1
},
"from_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"message_id"
]
},
"examples": {
"basico": {
"summary": "Encaminhar de outro chat",
"value": {
"phone": "5511988887777",
"message_id": "3EB0F1A2B3C4D5E6F7A8",
"from_phone": "5511977776666"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Encaminhar mensagem",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/pin-message": {
"post": {
"description": "`pin: false` desafixa. `duration_seconds` aceita 86400 (24 h), 604800 (7 dias, padrão) ou 2592000 (30 dias). Não aceita `delay_message`/`delay_typing`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.pinMessage",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message_id": {
"type": "string",
"minLength": 1
},
"pin": {
"default": true,
"type": "boolean"
},
"duration_seconds": {
"default": 604800,
"anyOf": [
{
"type": "number",
"enum": [
86400
]
},
{
"type": "number",
"enum": [
604800
]
},
{
"type": "number",
"enum": [
2592000
]
}
]
},
"from_me": {
"description": "Se a mensagem referenciada foi enviada por esta instância. Padrão: o que o engine registrou, senão `false`.",
"type": "boolean"
},
"participant": {
"description": "Grupos: número do participante que enviou a mensagem referenciada.",
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"required": [
"phone",
"message_id"
]
},
"examples": {
"basico": {
"summary": "Fixar por 7 dias",
"value": {
"phone": "120363012345678901-group",
"message_id": "3EB0A9C6D2F1E4B5A7C8"
}
},
"desafixar": {
"summary": "Desafixar",
"value": {
"phone": "120363012345678901-group",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"pin": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Ação enfileirada. `message_id`/`id` é o id da mensagem referenciada; o resultado chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Fixar ou desafixar mensagem",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/messages": {
"delete": {
"description": "Parâmetros via query string (ou body JSON): `phone`, `message_id`, `owner` opcional (padrão true; `false` apaga a mensagem de outra pessoa quando você é admin do grupo) e `participant`. Não aceita `delay_message`/`delay_typing`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.deleteMessage",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "participant",
"required": false,
"in": "query",
"description": "Grupos: telefone de quem enviou a mensagem (quando `owner=false`).",
"schema": {
"example": "5511977776666"
}
},
{
"name": "owner",
"required": false,
"in": "query",
"description": "Se a mensagem é sua (padrão `true`). `false` apaga a mensagem de outro participante (admins de grupo).",
"schema": {
"example": true
}
},
{
"name": "message_id",
"required": true,
"in": "query",
"description": "Id da mensagem a apagar.",
"schema": {
"example": "3EB0A9C6D2F1E4B5A7C8"
}
},
{
"name": "phone",
"required": true,
"in": "query",
"description": "Chat onde a mensagem está (telefone ou id de grupo).",
"schema": {
"example": "5511988887777"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message_id": {
"type": "string",
"minLength": 1
},
"owner": {
"type": "boolean"
},
"participant": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"required": [
"phone",
"message_id"
]
},
"examples": {
"basico": {
"summary": "Apagar sua mensagem (body em vez de query)",
"value": {
"phone": "5511988887777",
"message_id": "3EB0A9C6D2F1E4B5A7C8"
}
},
"grupo": {
"summary": "Admin apagando a mensagem de um participante",
"value": {
"phone": "120363012345678901-group",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"owner": false,
"participant": "5511977776666"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Ação enfileirada. `message_id`/`id` é o id da mensagem referenciada; o resultado chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Apagar mensagem para todos",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-poll": {
"post": {
"description": "De 2 a 12 opções. `poll_max_options` define quantas opções podem ser marcadas (0 = sem limite; padrão 1). Os votos chegam no webhook `received`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendPoll",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"question": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"options": {
"minItems": 2,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"poll_max_options": {
"default": 1,
"type": "integer",
"minimum": 0,
"maximum": 12
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"question",
"options"
]
},
"examples": {
"basico": {
"summary": "Enquete de escolha única",
"value": {
"phone": "120363012345678901-group",
"question": "Qual horário prefere para a reunião?",
"options": [
"09:00",
"14:00",
"17:00"
],
"poll_max_options": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada. O resultado do envio chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Enviar enquete",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-poll-vote": {
"post": {
"description": "Só é possível votar em enquetes que esta instância enviou ou recebeu. `options` recebe os nomes das opções; um array vazio limpa o voto. Não aceita `delay_message`/`delay_typing`. A mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`.",
"operationId": "send.sendPollVote",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"poll_message_id": {
"type": "string",
"minLength": 1
},
"options": {
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"from_me": {
"description": "Se a mensagem referenciada foi enviada por esta instância. Padrão: o que o engine registrou, senão `false`.",
"type": "boolean"
},
"participant": {
"description": "Grupos: número do participante que enviou a mensagem referenciada.",
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"required": [
"phone",
"poll_message_id",
"options"
]
},
"examples": {
"basico": {
"summary": "Votar em uma opção",
"value": {
"phone": "120363012345678901-group",
"poll_message_id": "3EB0A9C6D2F1E4B5A7C8",
"options": [
"14:00"
],
"participant": "5511977776666",
"from_me": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Voto enfileirado. `message_id`/`id` é o id da mensagem de voto (não o da enquete); o resultado chega no webhook `delivery`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância desconectada com a configuração `disable_enqueue_when_disconnected` ativa (`queue_disabled_while_disconnected`). Nas ações imediatas (`read-message`, `send-presence`), instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_disabled_while_disconnected",
"message": "Instance is disconnected and enqueueing while disconnected is disabled"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Votar em uma enquete",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/read-message": {
"post": {
"description": "Ação imediata: exige a instância conectada e não passa pela fila (responde 409 `instance_not_connected` se estiver offline). Informe `message_id` ou `message_ids` (até 100) e, em grupos, o `participant` que as enviou.",
"operationId": "send.readMessage",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"message_id": {
"type": "string",
"minLength": 1
},
"message_ids": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"participant": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"required": [
"phone"
]
},
"examples": {
"basico": {
"summary": "Uma mensagem",
"value": {
"phone": "5511988887777",
"message_id": "3EB0A9C6D2F1E4B5A7C8"
}
},
"lote": {
"summary": "Várias mensagens de um participante do grupo",
"value": {
"phone": "120363012345678901-group",
"message_ids": [
"3EB0A9C6D2F1E4B5A7C8",
"3EB0F1A2B3C4D5E6F7A8"
],
"participant": "5511977776666"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Recibos de leitura enviados. `read` lista os ids marcados.",
"content": {
"application/json": {
"example": {
"value": true,
"read": [
"3EB0A9C6D2F1E4B5A7C8"
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Marcar mensagens como lidas (ticks azuis)",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/send-presence": {
"post": {
"description": "Ação imediata: exige a instância conectada e não passa pela fila (responde 409 `instance_not_connected` se estiver offline). `composing`/`recording`/`paused` precisam de `phone` (sem ele, 400 `invalid_request`); `available`/`unavailable` são globais. `status` não diferencia maiúsculas de minúsculas. O WhatsApp limpa o \"digitando…\" depois de alguns segundos — repita a chamada para manter.",
"operationId": "send.sendPresence",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"status": {
"type": "string",
"enum": [
"AVAILABLE",
"UNAVAILABLE",
"COMPOSING",
"PAUSED",
"RECORDING"
]
}
},
"required": [
"status"
]
},
"examples": {
"basico": {
"summary": "Digitando em um chat",
"value": {
"phone": "5511988887777",
"status": "composing"
}
},
"online": {
"summary": "Marcar a instância como online",
"value": {
"status": "available"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Presença enviada.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa (`subscription_required`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (`instance_not_connected`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
},
"429": {
"description": "Fila cheia: a instância está desconectada e já há 1000 mensagens aguardando (`queue_full`).",
"content": {
"application/json": {
"example": {
"error": {
"code": "queue_full",
"message": "Queue is full (1000 messages waiting)"
}
}
}
}
}
},
"summary": "Mostrar digitando / gravando / online",
"tags": [
"Messages"
]
}
},
"/instances/{instance_id}/token/{token}/queue": {
"get": {
"description": "Mensagens enviadas pela API que ainda não saíram — normalmente porque a instância está desconectada (elas são entregues em ordem assim que reconectar). Paginado por `page`/`page_size` (máx. 100), do mais antigo para o mais novo. `wabox_id` é o id retornado no envio; `message_id` é o id que a mensagem terá no WhatsApp; `payload` é o conteúdo original.",
"operationId": "queue.list",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "page_size",
"required": false,
"in": "query",
"description": "Itens por página (1–100). Padrão 20.",
"schema": {
"example": 20
}
},
{
"name": "page",
"required": false,
"in": "query",
"description": "Página (a partir de 1). Padrão 1.",
"schema": {
"example": 1
}
}
],
"responses": {
"200": {
"description": "Página da fila.",
"content": {
"application/json": {
"example": {
"data": [
{
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"phone": "5511988887777",
"type": "text",
"payload": {
"type": "text",
"message": "Olá do Wabox!"
},
"created_at": "2026-08-18T12:07:00.000Z"
}
],
"page": 1,
"page_size": 20,
"total": 1
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Listar mensagens na fila",
"tags": [
"Queue"
]
},
"delete": {
"description": "Remove todas as mensagens ainda na fila desta instância; elas não serão enviadas. `removed` é a quantidade descartada. Mensagens já em envio não são afetadas.",
"operationId": "queue.purge",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Fila limpa.",
"content": {
"application/json": {
"example": {
"value": true,
"removed": 3
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Limpar a fila",
"tags": [
"Queue"
]
}
},
"/instances/{instance_id}/token/{token}/queue/{wabox_id}": {
"delete": {
"description": "Descarta uma mensagem específica pelo `wabox_id` retornado no envio. `value` é `false` (e `removed` 0) quando ela não está mais na fila — já foi enviada ou nunca existiu.",
"operationId": "queue.purgeOne",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "wabox_id",
"required": true,
"in": "path",
"description": "`wabox_id` retornado no envio.",
"schema": {
"example": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Resultado da remoção.",
"content": {
"application/json": {
"example": {
"value": true,
"removed": 1
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
}
},
"summary": "Remover uma mensagem da fila",
"tags": [
"Queue"
]
}
},
"/instances/{instance_id}/token/{token}/contacts": {
"get": {
"description": "Contatos conhecidos pelo número conectado (agenda + pessoas vistas em conversas), paginados e ordenados por telefone. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.list",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "q",
"required": false,
"in": "query",
"description": "Filtro por telefone / nome / push name",
"schema": {}
},
{
"name": "page_size",
"required": false,
"in": "query",
"description": "1–500, padrão 100",
"schema": {}
},
{
"name": "page",
"required": false,
"in": "query",
"description": "Página (a partir de 1). Padrão 1.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Lista paginada de contatos.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511988887777",
"lid": "987654321098765@lid",
"name": "Maria Silva",
"short_name": "Maria",
"push_name": "Mari",
"is_business": false,
"in_contacts": true
}
],
"page": 1,
"page_size": 100,
"total": 1
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar contatos",
"tags": [
"Contacts"
]
}
},
"/instances/{instance_id}/token/{token}/contacts/blocked": {
"get": {
"description": "Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.blocked",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Telefones bloqueados.",
"content": {
"application/json": {
"example": {
"data": [
"5511977776666"
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar contatos bloqueados",
"tags": [
"Contacts"
]
}
},
"/instances/{instance_id}/token/{token}/contacts/{phone}": {
"get": {
"description": "Nome na agenda, push name, nome comercial, recado (\"about\") e se o número está no WhatsApp. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.get",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"schema": {
"example": "5511988887777",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Dados do contato.",
"content": {
"application/json": {
"example": {
"phone": "5511988887777",
"lid": "987654321098765@lid",
"name": "Maria Silva",
"short_name": "Maria",
"push_name": "Mari",
"is_business": false,
"in_contacts": true,
"about": "Disponível",
"exists": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Detalhes do contato",
"tags": [
"Contacts"
]
}
},
"/instances/{instance_id}/token/{token}/contacts/{phone}/picture": {
"get": {
"description": "`url` é um link temporário do CDN do WhatsApp; `null` quando o usuário oculta a foto ou não tem uma. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.picture",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"schema": {
"example": "5511988887777",
"type": "string"
}
},
{
"name": "preview",
"required": false,
"in": "query",
"description": "true = miniatura pequena",
"schema": {}
}
],
"responses": {
"200": {
"description": "URL temporária da foto.",
"content": {
"application/json": {
"example": {
"url": "https://pps.whatsapp.net/v/t61.24694-24/abc.jpg?oe=1&oh=2",
"id": "1700000000"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "URL da foto de perfil (usuário ou grupo)",
"tags": [
"Contacts"
]
}
},
"/instances/{instance_id}/token/{token}/profile-picture": {
"get": {
"description": "Igual a `GET /contacts/{phone}/picture`, com o número em `?phone=`. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.profilePicture",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "preview",
"required": false,
"in": "query",
"description": "true = miniatura pequena",
"schema": {}
},
{
"name": "phone",
"required": true,
"in": "query",
"description": "Telefone do usuário ou id do grupo",
"schema": {}
}
],
"responses": {
"200": {
"description": "URL temporária da foto.",
"content": {
"application/json": {
"example": {
"url": "https://pps.whatsapp.net/v/t61.24694-24/abc.jpg?oe=1&oh=2",
"id": "1700000000"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "URL da foto de perfil (compat z-api)",
"tags": [
"Contacts"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
},
"put": {
"description": "Body `{ \"value\": \"\" }` de uma imagem JPEG/PNG; redimensionada para 640px. `mime_type` é opcional (sobrescreve o tipo detectado). Também disponível em `PUT /profile-picture` (compat z-api). Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "profile.setPicture[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"mime_type": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"value"
]
},
"examples": {
"url": {
"summary": "Por URL",
"value": {
"value": "https://exemplo.com/foto.jpg"
}
},
"base64": {
"summary": "Por base64",
"value": {
"value": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
"mime_type": "image/jpeg"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Foto atualizada.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Definir a foto de perfil (compatibilidade z-api)",
"tags": [
"Profile"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/phone-exists/{phone}": {
"get": {
"description": "Retorna `exists` e, quando registrado, o telefone canônico e o JID. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.phoneExists",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"schema": {
"example": "5511988887777",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Resultado da verificação.",
"content": {
"application/json": {
"example": {
"phone": "5511988887777",
"exists": true,
"canonical_phone": "5511988887777",
"jid": "5511988887777@s.whatsapp.net",
"lid": "987654321098765@lid"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Verificar se o número está no WhatsApp",
"tags": [
"Contacts"
]
}
},
"/instances/{instance_id}/token/{token}/phone-exists-batch": {
"post": {
"description": "Cada telefone recebe seu próprio resultado, na mesma ordem enviada. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.phoneExistsBatch",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phones": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
}
},
"required": [
"phones"
]
},
"examples": {
"basico": {
"summary": "Dois números",
"value": {
"phones": [
"5511988887777",
"5511900000000"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Um resultado por telefone.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511988887777",
"exists": true,
"canonical_phone": "5511988887777",
"jid": "5511988887777@s.whatsapp.net",
"lid": "987654321098765@lid"
},
{
"phone": "5511900000000",
"exists": false
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Verificar até 50 números de uma vez",
"tags": [
"Contacts"
]
}
},
"/instances/{instance_id}/token/{token}/contacts/{phone}/block": {
"post": {
"description": "Retorna a lista de bloqueados resultante. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.block",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"schema": {
"example": "5511977776666",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Lista de bloqueados após a ação.",
"content": {
"application/json": {
"example": {
"blocked": [
"5511977776666"
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Bloquear contato",
"tags": [
"Contacts"
]
}
},
"/instances/{instance_id}/token/{token}/contacts/{phone}/unblock": {
"post": {
"description": "Retorna a lista de bloqueados resultante. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.unblock",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"schema": {
"example": "5511977776666",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Lista de bloqueados após a ação.",
"content": {
"application/json": {
"example": {
"blocked": [
"5511977776666"
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Desbloquear contato",
"tags": [
"Contacts"
]
}
},
"/instances/{instance_id}/token/{token}/modify-blocked": {
"put": {
"description": "Body `{ phone, action: \"block\" | \"unblock\" }`. Retorna a lista de bloqueados resultante. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "contacts.modifyBlocked",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"action": {
"type": "string",
"enum": [
"block",
"unblock"
]
}
},
"required": [
"phone",
"action"
]
},
"examples": {
"basico": {
"summary": "Bloquear",
"value": {
"phone": "5511977776666",
"action": "block"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Lista de bloqueados após a ação.",
"content": {
"application/json": {
"example": {
"blocked": [
"5511977776666"
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Bloquear / desbloquear (compat z-api)",
"tags": [
"Contacts"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/profile/name": {
"put": {
"description": "Body `{ \"value\": \"...\" }` (máx. 25 caracteres). Também disponível em `PUT /profile-name` (compat z-api). Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "profile.setName[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 25
}
},
"required": [
"value"
]
},
"examples": {
"basico": {
"summary": "Nome do perfil",
"value": {
"value": "Loja da Maria"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Nome atualizado.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Definir o nome do perfil (push name)",
"tags": [
"Profile"
]
}
},
"/instances/{instance_id}/token/{token}/profile-name": {
"put": {
"description": "Body `{ \"value\": \"...\" }` (máx. 25 caracteres). Também disponível em `PUT /profile-name` (compat z-api). Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "profile.setName[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 25
}
},
"required": [
"value"
]
},
"examples": {
"basico": {
"summary": "Nome do perfil",
"value": {
"value": "Loja da Maria"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Nome atualizado.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Definir o nome do perfil (push name) (compatibilidade z-api)",
"tags": [
"Profile"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/profile/about": {
"put": {
"description": "Body `{ \"value\": \"...\" }` (máx. 139 caracteres; string vazia limpa o recado). Também disponível em `PUT /profile-description` (compat z-api). Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "profile.setAbout[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"maxLength": 139
}
},
"required": [
"value"
]
},
"examples": {
"basico": {
"summary": "Recado",
"value": {
"value": "Atendimento de segunda a sexta, das 9h às 18h."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Recado atualizado.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Definir o recado (\"about\")",
"tags": [
"Profile"
]
}
},
"/instances/{instance_id}/token/{token}/profile-description": {
"put": {
"description": "Body `{ \"value\": \"...\" }` (máx. 139 caracteres; string vazia limpa o recado). Também disponível em `PUT /profile-description` (compat z-api). Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "profile.setAbout[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"maxLength": 139
}
},
"required": [
"value"
]
},
"examples": {
"basico": {
"summary": "Recado",
"value": {
"value": "Atendimento de segunda a sexta, das 9h às 18h."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Recado atualizado.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Definir o recado (\"about\") (compatibilidade z-api)",
"tags": [
"Profile"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/profile/picture": {
"put": {
"description": "Body `{ \"value\": \"\" }` de uma imagem JPEG/PNG; redimensionada para 640px. `mime_type` é opcional (sobrescreve o tipo detectado). Também disponível em `PUT /profile-picture` (compat z-api). Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "profile.setPicture[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"mime_type": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"value"
]
},
"examples": {
"url": {
"summary": "Por URL",
"value": {
"value": "https://exemplo.com/foto.jpg"
}
},
"base64": {
"summary": "Por base64",
"value": {
"value": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
"mime_type": "image/jpeg"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Foto atualizada.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Definir a foto de perfil",
"tags": [
"Profile"
]
},
"delete": {
"description": "Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "profile.removePicture",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Foto removida.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Remover a foto de perfil",
"tags": [
"Profile"
]
}
},
"/instances/{instance_id}/token/{token}/groups": {
"post": {
"description": "Você é adicionado como super admin automaticamente. Participantes que não puderam ser adicionados aparecem na lista de participantes do grupo retornado. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.create[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"participants": {
"minItems": 1,
"maxItems": 1024,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"description": {
"type": "string",
"maxLength": 2048
},
"announce": {
"type": "boolean"
},
"locked": {
"type": "boolean"
},
"join_approval_required": {
"type": "boolean"
},
"member_add_mode": {
"type": "string",
"enum": [
"admin_add",
"all_member_add"
]
},
"ephemeral_seconds": {
"anyOf": [
{
"type": "number",
"enum": [
0
]
},
{
"type": "number",
"enum": [
86400
]
},
{
"type": "number",
"enum": [
604800
]
},
{
"type": "number",
"enum": [
7776000
]
}
]
}
},
"required": [
"name",
"participants"
]
},
"examples": {
"basico": {
"summary": "Grupo com dois participantes",
"value": {
"name": "Equipe Wabox",
"participants": [
"5511988887777",
"5511977776666"
],
"description": "Grupo de testes"
}
},
"somente_admins": {
"summary": "Só admins enviam mensagens e editam o grupo",
"value": {
"name": "Avisos",
"participants": [
"5511988887777"
],
"announce": true,
"locked": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Grupo criado (metadados + participantes).",
"content": {
"application/json": {
"example": {
"id": "120363012345678901-group",
"name": "Equipe Wabox",
"description": "Grupo de testes",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [
{
"phone": "5511999998888",
"lid": "123456789012345@lid",
"is_admin": true,
"is_super_admin": true
},
{
"phone": "5511988887777",
"is_admin": false,
"is_super_admin": false
}
],
"participant_count": 2,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "all_member_add",
"ephemeral_seconds": 0,
"is_community": false,
"suspended": false
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Criar grupo",
"tags": [
"Groups"
]
},
"get": {
"description": "Grupos dos quais o número participa. Os participantes são omitidos, a menos que `include_participants=true`. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.list",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "include_participants",
"required": false,
"in": "query",
"description": "`true` inclui a lista de participantes de cada grupo (padrão `false`).",
"schema": {}
}
],
"responses": {
"200": {
"description": "Lista de grupos em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "120363012345678901-group",
"name": "Equipe Wabox",
"description": "Grupo de testes",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [],
"participant_count": 2,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "all_member_add",
"ephemeral_seconds": 0,
"is_community": false,
"suspended": false
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar grupos",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/create-group": {
"post": {
"description": "Você é adicionado como super admin automaticamente. Participantes que não puderam ser adicionados aparecem na lista de participantes do grupo retornado. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.create[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"participants": {
"minItems": 1,
"maxItems": 1024,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"description": {
"type": "string",
"maxLength": 2048
},
"announce": {
"type": "boolean"
},
"locked": {
"type": "boolean"
},
"join_approval_required": {
"type": "boolean"
},
"member_add_mode": {
"type": "string",
"enum": [
"admin_add",
"all_member_add"
]
},
"ephemeral_seconds": {
"anyOf": [
{
"type": "number",
"enum": [
0
]
},
{
"type": "number",
"enum": [
86400
]
},
{
"type": "number",
"enum": [
604800
]
},
{
"type": "number",
"enum": [
7776000
]
}
]
}
},
"required": [
"name",
"participants"
]
},
"examples": {
"basico": {
"summary": "Grupo com dois participantes",
"value": {
"name": "Equipe Wabox",
"participants": [
"5511988887777",
"5511977776666"
],
"description": "Grupo de testes"
}
},
"somente_admins": {
"summary": "Só admins enviam mensagens e editam o grupo",
"value": {
"name": "Avisos",
"participants": [
"5511988887777"
],
"announce": true,
"locked": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Grupo criado (metadados + participantes).",
"content": {
"application/json": {
"example": {
"id": "120363012345678901-group",
"name": "Equipe Wabox",
"description": "Grupo de testes",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [
{
"phone": "5511999998888",
"lid": "123456789012345@lid",
"is_admin": true,
"is_super_admin": true
},
{
"phone": "5511988887777",
"is_admin": false,
"is_super_admin": false
}
],
"participant_count": 2,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "all_member_add",
"ephemeral_seconds": 0,
"is_community": false,
"suspended": false
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Criar grupo (compatibilidade z-api)",
"tags": [
"Groups"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/groups/invite-info": {
"get": {
"description": "`?invite=`. Não entra no grupo, só consulta. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.inviteInfo[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "invite",
"required": true,
"in": "query",
"description": "Código do convite ou link completo `https://chat.whatsapp.com/...`.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Metadados do grupo (sem participantes).",
"content": {
"application/json": {
"example": {
"id": "120363012345678901-group",
"name": "Equipe Wabox",
"description": "Grupo de testes",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [],
"participant_count": 2,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "all_member_add",
"ephemeral_seconds": 0,
"is_community": false,
"suspended": false
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Informações do grupo pelo link de convite",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/group-invitation-metadata": {
"get": {
"description": "`?invite=`. Não entra no grupo, só consulta. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.inviteInfo[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "invite",
"required": true,
"in": "query",
"description": "Código do convite ou link completo `https://chat.whatsapp.com/...`.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Metadados do grupo (sem participantes).",
"content": {
"application/json": {
"example": {
"id": "120363012345678901-group",
"name": "Equipe Wabox",
"description": "Grupo de testes",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [],
"participant_count": 2,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "all_member_add",
"ephemeral_seconds": 0,
"is_community": false,
"suspended": false
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Informações do grupo pelo link de convite (compatibilidade z-api)",
"tags": [
"Groups"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/groups/join": {
"post": {
"description": "Body `{ \"invite\": \"\" }`. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.join[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"invite": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"invite"
]
},
"examples": {
"basico": {
"summary": "Link completo",
"value": {
"invite": "https://chat.whatsapp.com/AbCdEfGhIjK123456789"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Id do grupo em que você entrou.",
"content": {
"application/json": {
"example": {
"group_id": "120363012345678901-group"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Entrar em um grupo pelo link de convite",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/accept-invite-group": {
"post": {
"description": "Body `{ \"invite\": \"\" }`. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.join[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"invite": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"invite"
]
},
"examples": {
"basico": {
"summary": "Link completo",
"value": {
"invite": "https://chat.whatsapp.com/AbCdEfGhIjK123456789"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Id do grupo em que você entrou.",
"content": {
"application/json": {
"example": {
"group_id": "120363012345678901-group"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Entrar em um grupo pelo link de convite (compatibilidade z-api)",
"tags": [
"Groups"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/groups/{id}": {
"get": {
"description": "Id do grupo como devolvido pela API / webhooks: `-group` (o JID bruto `@g.us` também é aceito). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.get",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Metadados do grupo com a lista de participantes.",
"content": {
"application/json": {
"example": {
"id": "120363012345678901-group",
"name": "Equipe Wabox",
"description": "Grupo de testes",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [
{
"phone": "5511999998888",
"lid": "123456789012345@lid",
"is_admin": true,
"is_super_admin": true
},
{
"phone": "5511988887777",
"is_admin": false,
"is_super_admin": false
}
],
"participant_count": 2,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "all_member_add",
"ephemeral_seconds": 0,
"is_community": false,
"suspended": false
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Metadados e participantes do grupo",
"tags": [
"Groups"
]
},
"put": {
"description": "Body parcial: envie só os campos que quer alterar. `remove_picture: true` remove a foto; `description: \"\"` limpa a descrição. Id do grupo como devolvido pela API / webhooks: `-group` (o JID bruto `@g.us` também é aceito). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.update",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 2048
},
"picture": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"picture_mime_type": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"remove_picture": {
"type": "boolean"
},
"announce": {
"type": "boolean"
},
"locked": {
"type": "boolean"
},
"join_approval_required": {
"type": "boolean"
},
"member_add_mode": {
"type": "string",
"enum": [
"admin_add",
"all_member_add"
]
},
"ephemeral_seconds": {
"anyOf": [
{
"type": "number",
"enum": [
0
]
},
{
"type": "number",
"enum": [
86400
]
},
{
"type": "number",
"enum": [
604800
]
},
{
"type": "number",
"enum": [
7776000
]
}
]
}
}
},
"examples": {
"basico": {
"summary": "Nome, descrição e configurações",
"value": {
"name": "Equipe Wabox",
"description": "Grupo de testes",
"announce": true,
"ephemeral_seconds": 604800
}
},
"foto": {
"summary": "Trocar a foto (URL ou base64)",
"value": {
"picture": "https://exemplo.com/foto.jpg",
"picture_mime_type": "image/jpeg"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Grupo atualizado.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Atualizar nome / descrição / foto / configurações",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/invite-link": {
"get": {
"description": "Somente admins. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.inviteLink",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Link e código do convite atual.",
"content": {
"application/json": {
"example": {
"url": "https://chat.whatsapp.com/AbCdEfGhIjK123456789",
"code": "AbCdEfGhIjK123456789"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Link de convite",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/invite-link/revoke": {
"post": {
"description": "O link anterior deixa de funcionar. Somente admins. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.revokeInviteLink",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Novo link e código do convite.",
"content": {
"application/json": {
"example": {
"url": "https://chat.whatsapp.com/AbCdEfGhIjK123456789",
"code": "AbCdEfGhIjK123456789"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Revogar o link de convite e gerar um novo",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/participants": {
"post": {
"description": "Body `{ \"action\": \"add\" | \"remove\" | \"promote\" | \"demote\" | \"approve\" | \"reject\", \"phones\": [...] }`. Cada telefone recebe seu próprio resultado (`error` é o status do WhatsApp: 403 não permitido, 408 saiu recentemente, 409 já é membro…). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.participants",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"add",
"remove",
"promote",
"demote",
"approve",
"reject"
]
},
"phones": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
}
},
"required": [
"action",
"phones"
]
},
"examples": {
"basico": {
"summary": "Adicionar participantes",
"value": {
"action": "add",
"phones": [
"5511977776666",
"5511900000000"
]
}
},
"promover": {
"summary": "Promover a admin",
"value": {
"action": "promote",
"phones": [
"5511977776666"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Um resultado por telefone em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511977776666",
"ok": true
},
{
"phone": "5511900000000",
"ok": false,
"error": "403"
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Adicionar / remover / promover / rebaixar / aprovar / rejeitar participantes",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/add-participant": {
"post": {
"description": "Equivale a `POST /groups/{id}/participants` com `action: \"add\"`. Cada telefone recebe seu próprio resultado (`error` é o status do WhatsApp: 403 não permitido, 408 saiu recentemente, 409 já é membro…). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.addParticipant",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phones": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
}
},
"required": [
"phones"
]
},
"examples": {
"basico": {
"summary": "Telefones a adicionar",
"value": {
"phones": [
"5511977776666",
"5511900000000"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Um resultado por telefone em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511977776666",
"ok": true
},
{
"phone": "5511900000000",
"ok": false,
"error": "403"
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Adicionar participantes (compat z-api)",
"tags": [
"Groups"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/remove-participant": {
"post": {
"description": "Equivale a `POST /groups/{id}/participants` com `action: \"remove\"`. Cada telefone recebe seu próprio resultado (`error` é o status do WhatsApp: 403 não permitido, 408 saiu recentemente, 409 já é membro…). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.removeParticipant",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phones": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
}
},
"required": [
"phones"
]
},
"examples": {
"basico": {
"summary": "Telefones a remover",
"value": {
"phones": [
"5511977776666"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Um resultado por telefone em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511977776666",
"ok": true
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Remover participantes (compat z-api)",
"tags": [
"Groups"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/add-admin": {
"post": {
"description": "Equivale a `POST /groups/{id}/participants` com `action: \"promote\"`. Cada telefone recebe seu próprio resultado (`error` é o status do WhatsApp: 403 não permitido, 408 saiu recentemente, 409 já é membro…). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.addAdmin",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phones": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
}
},
"required": [
"phones"
]
},
"examples": {
"basico": {
"summary": "Telefones a promover",
"value": {
"phones": [
"5511977776666"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Um resultado por telefone em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511977776666",
"ok": true
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Promover a admin (compat z-api)",
"tags": [
"Groups"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/remove-admin": {
"post": {
"description": "Equivale a `POST /groups/{id}/participants` com `action: \"demote\"`. Cada telefone recebe seu próprio resultado (`error` é o status do WhatsApp: 403 não permitido, 408 saiu recentemente, 409 já é membro…). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.removeAdmin",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phones": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
}
},
"required": [
"phones"
]
},
"examples": {
"basico": {
"summary": "Telefones a rebaixar",
"value": {
"phones": [
"5511977776666"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Um resultado por telefone em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511977776666",
"ok": true
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Rebaixar admin (compat z-api)",
"tags": [
"Groups"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/requests": {
"get": {
"description": "Para grupos com aprovação de entrada ativada (`join_approval_required`). Aprove ou rejeite com `POST /groups/{id}/participants` (`action: \"approve\" | \"reject\"`). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.requests",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Solicitações pendentes em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511966665555",
"requested_at": "2026-08-20T11:00:00.000Z"
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Solicitações de entrada pendentes",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/groups/{id}/leave": {
"post": {
"description": "Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "groups.leave",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do grupo (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Você saiu do grupo.",
"content": {
"application/json": {
"example": {
"left": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Sair do grupo",
"tags": [
"Groups"
]
}
},
"/instances/{instance_id}/token/{token}/chats": {
"get": {
"description": "O engine mantém, por instância, uma lista de conversas (só metadados — nunca o conteúdo das mensagens): iniciada com o histórico que o celular envia após o pareamento e depois atualizada pelo tráfego e pelas mudanças feitas no celular. Conversas fixadas vêm primeiro, depois as mais recentes. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "chats.list",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "q",
"required": false,
"in": "query",
"description": "Filtro por telefone / nome",
"schema": {}
},
{
"name": "archived",
"required": false,
"in": "query",
"description": "true = só arquivadas, false = só ativas, ausente = todas",
"schema": {}
},
{
"name": "page_size",
"required": false,
"in": "query",
"description": "1–500, padrão 100",
"schema": {}
},
{
"name": "page",
"required": false,
"in": "query",
"description": "Página (a partir de 1). Padrão 1.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Lista paginada de conversas.",
"content": {
"application/json": {
"example": {
"data": [
{
"phone": "5511988887777",
"name": "Maria Silva",
"is_group": false,
"last_message_at": "2026-08-20T11:30:00.000Z",
"unread_count": 2,
"marked_unread": false,
"archived": false,
"pinned": true,
"muted": true,
"muted_until": "2026-08-21T11:30:00.000Z",
"ephemeral_seconds": 0
}
],
"page": 1,
"page_size": 100,
"total": 1
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar conversas",
"tags": [
"Chats"
]
}
},
"/instances/{instance_id}/token/{token}/chats/{phone}": {
"get": {
"description": "Contagem de não lidas, flags de arquivada/fixada/silenciada e timer de mensagens temporárias. 404 `chat_not_found` quando o engine ainda não viu a conversa. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "chats.get",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"description": "Telefone do contato ou id do grupo",
"schema": {
"example": "5511988887777",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Dados da conversa.",
"content": {
"application/json": {
"example": {
"phone": "5511988887777",
"name": "Maria Silva",
"is_group": false,
"last_message_at": "2026-08-20T11:30:00.000Z",
"unread_count": 2,
"marked_unread": false,
"archived": false,
"pinned": true,
"muted": true,
"muted_until": "2026-08-21T11:30:00.000Z",
"ephemeral_seconds": 0
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"404": {
"description": "Conversa desconhecida para o engine.",
"content": {
"application/json": {
"example": {
"error": {
"code": "chat_not_found",
"message": "Chat not found"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Detalhes da conversa",
"tags": [
"Chats"
]
}
},
"/instances/{instance_id}/token/{token}/chats/{phone}/{action}": {
"post": {
"description": "`action` ∈ archive | unarchive | mute | unmute | pin | unpin | read | unread | delete. Para `mute`, body `{ \"mute_seconds\": 28800 }` (ausente = para sempre); nas demais ações o body é opcional. A mudança é refletida no celular via app state do WhatsApp. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "chats.action",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"description": "Telefone do contato ou id do grupo",
"schema": {
"example": "5511988887777",
"type": "string"
}
},
{
"name": "action",
"required": true,
"in": "path",
"schema": {
"enum": [
"archive",
"unarchive",
"mute",
"unmute",
"pin",
"unpin",
"read",
"unread",
"delete"
],
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"archive",
"unarchive",
"mute",
"unmute",
"pin",
"unpin",
"read",
"unread",
"delete"
]
},
"mute_seconds": {
"type": "integer",
"minimum": 0,
"maximum": 315360000
}
},
"required": [
"action"
]
},
"examples": {
"mute": {
"summary": "Silenciar por 8 horas (`action` = `mute`)",
"value": {
"mute_seconds": 28800
}
}
}
}
}
},
"responses": {
"200": {
"description": "Ação aplicada.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Arquivar / silenciar / fixar / ler / não lida / apagar conversa",
"tags": [
"Chats"
]
}
},
"/instances/{instance_id}/token/{token}/modify-chat": {
"post": {
"description": "Body `{ phone, action, mute_seconds? }` — igual a `POST /chats/{phone}/{action}`. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "chats.modifyChat",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"archive",
"unarchive",
"mute",
"unmute",
"pin",
"unpin",
"read",
"unread",
"delete"
]
},
"mute_seconds": {
"type": "integer",
"minimum": 0,
"maximum": 315360000
},
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"required": [
"action",
"phone"
]
},
"examples": {
"basico": {
"summary": "Arquivar",
"value": {
"phone": "5511988887777",
"action": "archive"
}
},
"mute": {
"summary": "Silenciar por 8 horas",
"value": {
"phone": "5511988887777",
"action": "mute",
"mute_seconds": 28800
}
}
}
}
}
},
"responses": {
"200": {
"description": "Ação aplicada.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Ação na conversa (compat z-api)",
"tags": [
"Chats"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/chats/{phone}/expiration": {
"put": {
"description": "Body `{ \"value\": 0 | 86400 | 604800 | 7776000 }` (segundos; 0 desativa). Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "chats.expiration",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"description": "Telefone do contato ou id do grupo",
"schema": {
"example": "5511988887777",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"anyOf": [
{
"type": "number",
"enum": [
0
]
},
{
"type": "number",
"enum": [
86400
]
},
{
"type": "number",
"enum": [
604800
]
},
{
"type": "number",
"enum": [
7776000
]
}
]
}
},
"required": [
"value"
]
},
"examples": {
"basico": {
"summary": "24 horas",
"value": {
"value": 86400
}
},
"desativar": {
"summary": "Desativar",
"value": {
"value": 0
}
}
}
}
}
},
"responses": {
"200": {
"description": "Timer atualizado.",
"content": {
"application/json": {
"example": {
"value": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Timer de mensagens temporárias",
"tags": [
"Chats"
]
}
},
"/instances/{instance_id}/token/{token}/send-button-list": {
"post": {
"description": "Até 10 botões em `buttons[]`, de quatro tipos: `{ type: \"reply\", id, label }` (resposta rápida — o `id` volta no webhook `buttons_response`), `{ type: \"url\", label, url }` (abre um link), `{ type: \"call\", label, phone }` (liga para o número) e `{ type: \"copy\", label, code }` (copia `code` para a área de transferência). `label` tem até 60 caracteres. Se `type` for omitido ele é inferido pelos outros campos (`url` → url, `phone` → call, `code` → copy, senão reply; um botão reply sem `id` usa o `label` como id) — compatível com o formato do z-api. Opcionais: `image` de cabeçalho (URL, data URL ou base64), `title` e `footer`. `send-button-actions` é um alias da mesma rota.\n\n**Best effort.** Mensagens interativas não são um recurso oficial para contas comuns do WhatsApp: elas são entregues como mensagens \"native flow\" e a renderização depende do app e da plataforma de quem recebe — celulares (Android/iOS) exibem normalmente, mas o **WhatsApp Web e o WhatsApp Desktop não exibem** botões, lista nem carrossel (mostram o placeholder \"mensagem de visualização única\" e a pessoa precisa abrir no celular; é o mesmo comportamento de outras APIs não-oficiais e não há contorno conhecido, já que o conteúdo é cifrado igual para todos os dispositivos). Em versões antigas do app a mensagem pode chegar como texto simples. Botões `reply` voltam como webhook `buttons_response`; a opção escolhida em uma lista, como `list_response`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendButtons[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"title": {
"type": "string",
"maxLength": 256
},
"footer": {
"type": "string",
"maxLength": 256
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
},
"image": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"buttons": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"reply"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"type",
"id",
"label"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"url"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"type",
"label",
"url"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"call"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"phone": {
"type": "string",
"pattern": "^\\d{5,20}$"
}
},
"required": [
"type",
"label",
"phone"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"copy"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"type",
"label",
"code"
]
}
]
}
}
},
"required": [
"phone",
"message",
"buttons"
]
},
"examples": {
"basico": {
"summary": "Quatro tipos de botão com imagem de cabeçalho",
"value": {
"phone": "5511988887777",
"title": "Pedido #4821",
"message": "Seu pedido saiu para entrega. O que deseja fazer?",
"footer": "Wabox Store",
"image": "https://example.com/pedidos/4821.jpg",
"buttons": [
{
"type": "reply",
"id": "confirmar_recebimento",
"label": "Confirmar recebimento"
},
{
"type": "url",
"label": "Rastrear entrega",
"url": "https://example.com/rastreio/4821"
},
{
"type": "call",
"label": "Falar com a loja",
"phone": "5511977776666"
},
{
"type": "copy",
"label": "Copiar cupom",
"code": "FRETE10"
}
]
}
},
"sem_type": {
"summary": "Botões de resposta rápida sem `type` (inferido, estilo z-api)",
"value": {
"phone": "5511988887777",
"message": "Podemos confirmar sua consulta de amanhã às 10h?",
"buttons": [
{
"label": "Sim, confirmo"
},
{
"id": "remarcar",
"label": "Preciso remarcar"
}
],
"delay_typing": 2
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Enviar mensagem com botões",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-button-actions": {
"post": {
"description": "Até 10 botões em `buttons[]`, de quatro tipos: `{ type: \"reply\", id, label }` (resposta rápida — o `id` volta no webhook `buttons_response`), `{ type: \"url\", label, url }` (abre um link), `{ type: \"call\", label, phone }` (liga para o número) e `{ type: \"copy\", label, code }` (copia `code` para a área de transferência). `label` tem até 60 caracteres. Se `type` for omitido ele é inferido pelos outros campos (`url` → url, `phone` → call, `code` → copy, senão reply; um botão reply sem `id` usa o `label` como id) — compatível com o formato do z-api. Opcionais: `image` de cabeçalho (URL, data URL ou base64), `title` e `footer`. `send-button-actions` é um alias da mesma rota.\n\n**Best effort.** Mensagens interativas não são um recurso oficial para contas comuns do WhatsApp: elas são entregues como mensagens \"native flow\" e a renderização depende do app e da plataforma de quem recebe — celulares (Android/iOS) exibem normalmente, mas o **WhatsApp Web e o WhatsApp Desktop não exibem** botões, lista nem carrossel (mostram o placeholder \"mensagem de visualização única\" e a pessoa precisa abrir no celular; é o mesmo comportamento de outras APIs não-oficiais e não há contorno conhecido, já que o conteúdo é cifrado igual para todos os dispositivos). Em versões antigas do app a mensagem pode chegar como texto simples. Botões `reply` voltam como webhook `buttons_response`; a opção escolhida em uma lista, como `list_response`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendButtons[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"title": {
"type": "string",
"maxLength": 256
},
"footer": {
"type": "string",
"maxLength": 256
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
},
"image": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"buttons": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"reply"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"type",
"id",
"label"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"url"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"type",
"label",
"url"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"call"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"phone": {
"type": "string",
"pattern": "^\\d{5,20}$"
}
},
"required": [
"type",
"label",
"phone"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"copy"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"type",
"label",
"code"
]
}
]
}
}
},
"required": [
"phone",
"message",
"buttons"
]
},
"examples": {
"basico": {
"summary": "Quatro tipos de botão com imagem de cabeçalho",
"value": {
"phone": "5511988887777",
"title": "Pedido #4821",
"message": "Seu pedido saiu para entrega. O que deseja fazer?",
"footer": "Wabox Store",
"image": "https://example.com/pedidos/4821.jpg",
"buttons": [
{
"type": "reply",
"id": "confirmar_recebimento",
"label": "Confirmar recebimento"
},
{
"type": "url",
"label": "Rastrear entrega",
"url": "https://example.com/rastreio/4821"
},
{
"type": "call",
"label": "Falar com a loja",
"phone": "5511977776666"
},
{
"type": "copy",
"label": "Copiar cupom",
"code": "FRETE10"
}
]
}
},
"sem_type": {
"summary": "Botões de resposta rápida sem `type` (inferido, estilo z-api)",
"value": {
"phone": "5511988887777",
"message": "Podemos confirmar sua consulta de amanhã às 10h?",
"buttons": [
{
"label": "Sim, confirmo"
},
{
"id": "remarcar",
"label": "Preciso remarcar"
}
],
"delay_typing": 2
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Enviar mensagem com botões (compatibilidade z-api)",
"tags": [
"Interactive"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/send-button-otp": {
"post": {
"description": "Atalho para uma mensagem com um único botão `copy` que coloca `code` na área de transferência do destinatário. `button_label` é o texto do botão (padrão `Copiar código`). Aceita `title`, `footer` e os campos de resposta/menção como `send-button-list`.\n\n**Best effort.** Mensagens interativas não são um recurso oficial para contas comuns do WhatsApp: elas são entregues como mensagens \"native flow\" e a renderização depende do app e da plataforma de quem recebe — celulares (Android/iOS) exibem normalmente, mas o **WhatsApp Web e o WhatsApp Desktop não exibem** botões, lista nem carrossel (mostram o placeholder \"mensagem de visualização única\" e a pessoa precisa abrir no celular; é o mesmo comportamento de outras APIs não-oficiais e não há contorno conhecido, já que o conteúdo é cifrado igual para todos os dispositivos). Em versões antigas do app a mensagem pode chegar como texto simples. Botões `reply` voltam como webhook `buttons_response`; a opção escolhida em uma lista, como `list_response`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendOtp",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"title": {
"type": "string",
"maxLength": 256
},
"footer": {
"type": "string",
"maxLength": 256
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"button_label": {
"default": "Copiar código",
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"phone",
"message",
"code"
]
},
"examples": {
"basico": {
"summary": "Código de verificação",
"value": {
"phone": "5511988887777",
"message": "Seu código de verificação é *482913*. Ele expira em 5 minutos.",
"code": "482913",
"button_label": "Copiar código"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Enviar código OTP com botão \"copiar\"",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-button-pix": {
"post": {
"description": "Envia um card \"copiar chave PIX\" com o `name` do recebedor, a chave (`key`) e o `key_type` (`cpf`, `cnpj`, `phone`, `email` ou `evp` — chave aleatória; aceita maiúsculas). `message` é um texto opcional acima do botão. É uma chave PIX estática: o valor não vai na mensagem, informe-o no texto.\n\n**Best effort.** Mensagens interativas não são um recurso oficial para contas comuns do WhatsApp: elas são entregues como mensagens \"native flow\" e a renderização depende do app e da plataforma de quem recebe — celulares (Android/iOS) exibem normalmente, mas o **WhatsApp Web e o WhatsApp Desktop não exibem** botões, lista nem carrossel (mostram o placeholder \"mensagem de visualização única\" e a pessoa precisa abrir no celular; é o mesmo comportamento de outras APIs não-oficiais e não há contorno conhecido, já que o conteúdo é cifrado igual para todos os dispositivos). Em versões antigas do app a mensagem pode chegar como texto simples. Botões `reply` voltam como webhook `buttons_response`; a opção escolhida em uma lista, como `list_response`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendPix",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"evp"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"message": {
"type": "string",
"maxLength": 4096
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"key",
"key_type",
"name"
]
},
"examples": {
"basico": {
"summary": "Chave PIX CNPJ",
"value": {
"phone": "5511988887777",
"name": "Wabox Store LTDA",
"key": "12345678000199",
"key_type": "cnpj",
"message": "Para concluir o pedido #4821, pague R$ 149,90 na chave PIX abaixo."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Enviar botão de pagamento PIX",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-option-list": {
"post": {
"description": "`button_label` (até 20 caracteres) é o texto do botão que abre o menu. As opções vão em `sections[].rows[]` (até 10 seções com `title` opcional, cada uma com até 10 linhas) ou no atalho `options[]` (até 10 linhas em uma única seção sem título) — envie um dos dois. Cada linha tem `id`, `title` (até 24 caracteres) e `description` opcional (até 72). A opção escolhida chega no webhook `list_response` com o `id` da linha.\n\n**Best effort.** Mensagens interativas não são um recurso oficial para contas comuns do WhatsApp: elas são entregues como mensagens \"native flow\" e a renderização depende do app e da plataforma de quem recebe — celulares (Android/iOS) exibem normalmente, mas o **WhatsApp Web e o WhatsApp Desktop não exibem** botões, lista nem carrossel (mostram o placeholder \"mensagem de visualização única\" e a pessoa precisa abrir no celular; é o mesmo comportamento de outras APIs não-oficiais e não há contorno conhecido, já que o conteúdo é cifrado igual para todos os dispositivos). Em versões antigas do app a mensagem pode chegar como texto simples. Botões `reply` voltam como webhook `buttons_response`; a opção escolhida em uma lista, como `list_response`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendOptionList",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"title": {
"type": "string",
"maxLength": 256
},
"footer": {
"type": "string",
"maxLength": 256
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
},
"button_label": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"sections": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 24
},
"rows": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 24
},
"description": {
"type": "string",
"maxLength": 72
}
},
"required": [
"id",
"title"
]
}
}
},
"required": [
"rows"
]
}
},
"options": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 24
},
"description": {
"type": "string",
"maxLength": 72
}
},
"required": [
"id",
"title"
]
}
}
},
"required": [
"phone",
"message",
"button_label"
]
},
"examples": {
"basico": {
"summary": "Menu com seções",
"value": {
"phone": "5511988887777",
"title": "Atendimento Wabox Store",
"message": "Escolha o setor com o qual você quer falar:",
"footer": "Seg. a sex., das 9h às 18h",
"button_label": "Ver opções",
"sections": [
{
"title": "Vendas",
"rows": [
{
"id": "vendas_novo_pedido",
"title": "Novo pedido",
"description": "Fazer um orçamento ou comprar"
},
{
"id": "vendas_status",
"title": "Status do pedido",
"description": "Acompanhar uma compra"
}
]
},
{
"title": "Suporte",
"rows": [
{
"id": "suporte_tecnico",
"title": "Suporte técnico",
"description": "Problemas com o produto"
},
{
"id": "suporte_financeiro",
"title": "Financeiro",
"description": "Boletos, notas fiscais e reembolsos"
}
]
}
]
}
},
"options": {
"summary": "Atalho `options[]` (uma seção sem título)",
"value": {
"phone": "5511988887777",
"message": "Qual horário prefere para a entrega?",
"button_label": "Escolher horário",
"options": [
{
"id": "manha",
"title": "Manhã",
"description": "8h às 12h"
},
{
"id": "tarde",
"title": "Tarde",
"description": "13h às 18h"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Enviar lista de opções (menu de seleção única)",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-carousel": {
"post": {
"description": "`message` é o texto que acompanha o carrossel e `cards[]` tem de 1 a 10 cards. Cada card tem `image` obrigatória (URL, data URL ou base64), `text`, `title`/`footer` opcionais e até 3 `buttons` nos mesmos formatos de `send-button-list` (reply, url, call, copy; `type` pode ser omitido). Botões `reply` voltam como `buttons_response`.\n\n**Best effort.** Mensagens interativas não são um recurso oficial para contas comuns do WhatsApp: elas são entregues como mensagens \"native flow\" e a renderização depende do app e da plataforma de quem recebe — celulares (Android/iOS) exibem normalmente, mas o **WhatsApp Web e o WhatsApp Desktop não exibem** botões, lista nem carrossel (mostram o placeholder \"mensagem de visualização única\" e a pessoa precisa abrir no celular; é o mesmo comportamento de outras APIs não-oficiais e não há contorno conhecido, já que o conteúdo é cifrado igual para todos os dispositivos). Em versões antigas do app a mensagem pode chegar como texto simples. Botões `reply` voltam como webhook `buttons_response`; a opção escolhida em uma lista, como `list_response`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendCarousel",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"cards": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"image": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"title": {
"type": "string",
"maxLength": 256
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"footer": {
"type": "string",
"maxLength": 256
},
"buttons": {
"maxItems": 3,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"reply"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"type",
"id",
"label"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"url"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"type",
"label",
"url"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"call"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"phone": {
"type": "string",
"pattern": "^\\d{5,20}$"
}
},
"required": [
"type",
"label",
"phone"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"copy"
]
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"code": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"type",
"label",
"code"
]
}
]
}
}
},
"required": [
"image",
"text"
]
}
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"message",
"cards"
]
},
"examples": {
"basico": {
"summary": "Dois cards de produto",
"value": {
"phone": "5511988887777",
"message": "Confira as ofertas da semana:",
"cards": [
{
"image": "https://example.com/produtos/tenis-runner.jpg",
"title": "Tênis Runner",
"text": "De R$ 399,90 por R$ 299,90 até domingo.",
"footer": "Frete grátis",
"buttons": [
{
"type": "reply",
"id": "quero_tenis_runner",
"label": "Quero este"
},
{
"type": "url",
"label": "Ver na loja",
"url": "https://example.com/p/tenis-runner"
}
]
},
{
"image": "https://example.com/produtos/mochila-urban.jpg",
"title": "Mochila Urban",
"text": "Compartimento para notebook de 15\". R$ 189,90.",
"buttons": [
{
"type": "reply",
"id": "quero_mochila_urban",
"label": "Quero este"
}
]
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Enviar carrossel de cards",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-event": {
"post": {
"description": "Cria um evento do WhatsApp no chat (`phone` costuma ser um grupo). `start_at`/`end_at` em ISO-8601 com fuso (ex.: `2026-09-15T14:00:00Z`); opcionais `description`, `location` (`name`, `latitude`, `longitude`), `join_link` (link de chamada/reunião) e `extra_guests_allowed`. Os convidados respondem pelo app ou por `send-event-response`; as confirmações chegam como webhook `event_response`. Guarde o `message_id` retornado: ele é necessário para editar ou cancelar o evento com `send-edit-event`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendEvent",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": {
"type": "string",
"maxLength": 2048
},
"start_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"end_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"location": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 256
},
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
},
"join_link": {
"type": "string",
"format": "uri"
},
"extra_guests_allowed": {
"type": "boolean"
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"name",
"start_at"
]
},
"examples": {
"basico": {
"summary": "Evento em grupo com local e link",
"value": {
"phone": "120363012345678901-group",
"name": "Reunião de planejamento",
"description": "Alinhamento das metas do próximo trimestre.",
"start_at": "2026-09-15T14:00:00Z",
"end_at": "2026-09-15T15:00:00Z",
"location": {
"name": "Escritório Wabox — sala 2",
"latitude": -23.55052,
"longitude": -46.633308
},
"join_link": "https://meet.example.com/wabox-planejamento",
"extra_guests_allowed": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento enfileirado.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Criar evento de calendário",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-edit-event": {
"post": {
"description": "Envie o evento completo novamente (todos os campos de `send-event`) com `edit_message_id` = `message_id` do evento original; `canceled: true` cancela o evento. A resposta devolve o mesmo `message_id` do evento editado.\n\n**Limitação:** só funciona para eventos que esta instância criou (ou recebeu) desde o último restart do engine — o segredo da mensagem fica em memória. Se o evento não for encontrado, o webhook `delivery` chega com `error_code: message_not_found`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.editEvent",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": {
"type": "string",
"maxLength": 2048
},
"start_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"end_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"location": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 256
},
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
},
"join_link": {
"type": "string",
"format": "uri"
},
"extra_guests_allowed": {
"type": "boolean"
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
},
"edit_message_id": {
"type": "string",
"minLength": 1
},
"canceled": {
"type": "boolean"
}
},
"required": [
"phone",
"name",
"start_at",
"edit_message_id"
]
},
"examples": {
"editar": {
"summary": "Adiar o evento em uma hora",
"value": {
"phone": "120363012345678901-group",
"edit_message_id": "3EB0A9C6D2F1E4B5A7C8",
"name": "Reunião de planejamento",
"description": "Alinhamento das metas do próximo trimestre. Novo horário!",
"start_at": "2026-09-15T15:00:00Z",
"end_at": "2026-09-15T16:00:00Z",
"location": {
"name": "Escritório Wabox — sala 2",
"latitude": -23.55052,
"longitude": -46.633308
},
"join_link": "https://meet.example.com/wabox-planejamento",
"extra_guests_allowed": true
}
},
"cancelar": {
"summary": "Cancelar o evento",
"value": {
"phone": "120363012345678901-group",
"edit_message_id": "3EB0A9C6D2F1E4B5A7C8",
"name": "Reunião de planejamento",
"start_at": "2026-09-15T14:00:00Z",
"end_at": "2026-09-15T15:00:00Z",
"canceled": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Edição enfileirada; `message_id` é o id do evento editado.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Editar ou cancelar um evento",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-event-response": {
"post": {
"description": "Confirma presença em um evento: `event_message_id` é o `message_id` do evento e `response` é `going`, `not_going` ou `maybe` (aceita maiúsculas). `extra_guests` (0–99) informa acompanhantes quando o evento permite. Em grupos, use `participant` (telefone de quem criou o evento) e `from_me` para ajudar o engine a localizar a mensagem. Não aceita `delay_message`/`delay_typing`. A resposta devolve um novo `message_id` (o da mensagem de RSVP), não o do evento.\n\n**Limitação:** só funciona para eventos que esta instância criou ou recebeu desde o último restart do engine — o segredo da mensagem fica em memória. Se o evento não for encontrado, o webhook `delivery` chega com `error_code: message_not_found`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; o resultado chega no webhook `delivery`.",
"operationId": "interactive.sendEventResponse",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"event_message_id": {
"type": "string",
"minLength": 1
},
"response": {
"type": "string",
"enum": [
"going",
"not_going",
"maybe"
]
},
"extra_guests": {
"type": "integer",
"minimum": 0,
"maximum": 99
},
"from_me": {
"description": "Se a mensagem referenciada foi enviada por esta instância. Padrão: o que o engine registrou, senão `false`.",
"type": "boolean"
},
"participant": {
"description": "Grupos: número do participante que enviou a mensagem referenciada.",
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"required": [
"phone",
"event_message_id",
"response"
]
},
"examples": {
"basico": {
"summary": "Confirmar presença com um acompanhante",
"value": {
"phone": "120363012345678901-group",
"event_message_id": "3EB0A9C6D2F1E4B5A7C8",
"response": "going",
"extra_guests": 1,
"from_me": false,
"participant": "5511977776666"
}
}
}
}
}
},
"responses": {
"200": {
"description": "RSVP enfileirado.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Responder a um evento (RSVP)",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-text-status": {
"post": {
"description": "Publica no seu status (stories). Quem vê segue a sua configuração de privacidade de status. Sempre endereçado a `status@broadcast` — não envie `phone`. Aceita apenas `delay_message` (não há `delay_typing`). Opcionais: `background_color` (`#RRGGBB`; padrão verde do WhatsApp) e `font` (índice da fonte do WhatsApp, 0–9).\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendTextStatus",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 65536
},
"background_color": {
"type": "string",
"pattern": "^#?[0-9a-fA-F]{6}$"
},
"font": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"message"
]
},
"examples": {
"basico": {
"summary": "Texto com cor de fundo e fonte",
"value": {
"message": "Promoção relâmpago: 20% off até as 18h de hoje!",
"background_color": "#075E54",
"font": 2
}
}
}
}
}
},
"responses": {
"200": {
"description": "Status enfileirado.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Publicar status de texto",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-image-status": {
"post": {
"description": "Publica no seu status (stories). Quem vê segue a sua configuração de privacidade de status. Sempre endereçado a `status@broadcast` — não envie `phone`. Aceita apenas `delay_message` (não há `delay_typing`). `image` aceita URL, data URL ou base64; `caption` é a legenda e `mime_type` sobrescreve o tipo detectado.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendImageStatus",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"image": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"caption": {
"type": "string",
"maxLength": 65536
},
"mime_type": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"image"
]
},
"examples": {
"basico": {
"summary": "Imagem por URL com legenda",
"value": {
"image": "https://example.com/status/lancamento.jpg",
"caption": "Novidades chegando na próxima semana"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Status enfileirado.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Publicar status de imagem",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-video-status": {
"post": {
"description": "Publica no seu status (stories). Quem vê segue a sua configuração de privacidade de status. Sempre endereçado a `status@broadcast` — não envie `phone`. Aceita apenas `delay_message` (não há `delay_typing`). `video` aceita URL, data URL ou base64 de um MP4; `caption` é a legenda e `mime_type` sobrescreve o tipo detectado.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendVideoStatus",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"video": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"caption": {
"type": "string",
"maxLength": 65536
},
"mime_type": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"video"
]
},
"examples": {
"basico": {
"summary": "Vídeo MP4 por URL",
"value": {
"video": "https://example.com/status/bastidores.mp4",
"caption": "Bastidores da nova coleção",
"mime_type": "video/mp4"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Status enfileirado.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Publicar status de vídeo",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/send-newsletter-admin-invite": {
"post": {
"description": "Envia para `phone` um card de convite para administrar o canal `newsletter_id` (formato `@newsletter`), com `caption` opcional. Para publicar em um canal, use qualquer endpoint `send-*` com `phone: \"@newsletter\"`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id definitivo no WhatsApp (`id` é um alias dele) e o resultado chega no webhook `delivery`. `delay_message` e `delay_typing` (segundos, 0–15) funcionam como nos demais envios: o primeiro substitui o intervalo aleatório da instância para esta mensagem, o segundo mostra \"digitando…\" antes de enviar.",
"operationId": "interactive.sendNewsletterInvite",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"description": "Token da instância. Trate como senha.",
"schema": {
"type": "string"
},
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"newsletter_id": {
"type": "string",
"pattern": "^\\d+@newsletter$"
},
"caption": {
"type": "string",
"maxLength": 1024
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"newsletter_id"
]
},
"examples": {
"basico": {
"summary": "Convite com texto",
"value": {
"phone": "5511988887777",
"newsletter_id": "120363012345678901@newsletter",
"caption": "Quer me ajudar a administrar o canal da Wabox Store?"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Convite enfileirado.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Assinatura da instância inativa (trial expirado ou pagamento pendente).",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Instance subscription is not active"
}
}
}
}
}
},
"summary": "Convidar alguém para administrar seu canal",
"tags": [
"Interactive"
]
}
},
"/instances/{instance_id}/token/{token}/privacy": {
"get": {
"description": "Quem pode ver seu \"visto por último\" / online / foto de perfil / recado, confirmações de leitura, quem pode adicionar você a grupos, ligar ou enviar mensagem. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "privacy.get",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Configurações atuais.",
"content": {
"application/json": {
"example": {
"last_seen": "contacts",
"online": "match_last_seen",
"profile_picture": "all",
"about": "contacts",
"read_receipts": "all",
"groups": "contacts",
"calls": "all",
"messages": "all",
"stickers": "contacts"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Configurações de privacidade atuais",
"tags": [
"Privacy"
]
}
},
"/instances/{instance_id}/token/{token}/privacy/{setting}": {
"put": {
"description": "Body `{ \"value\": ... }`. Valores permitidos — `last_seen`: `all` | `contacts` | `contact_blacklist` | `none`; `online`: `all` | `match_last_seen`; `profile_picture`: `all` | `contacts` | `contact_blacklist` | `none`; `about`: `all` | `contacts` | `contact_blacklist` | `none`; `read_receipts`: `all` | `none`; `groups`: `all` | `contacts` | `contact_blacklist` | `none`; `calls`: `all` | `known`; `messages`: `all` | `contacts`; `stickers`: `contacts` | `contact_allowlist` | `none`. Valor fora da lista responde 400 `invalid_request`. A resposta é o conjunto completo de configurações após a alteração. `disappearing` define o timer padrão de mensagens temporárias para novas conversas (`value` em segundos: 0, 86400, 604800 ou 7776000) e responde `{ \"updated\": true }`. Imediato: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "privacy.set",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "setting",
"required": true,
"in": "path",
"description": "Configuração a alterar, ou `disappearing` para o timer padrão de mensagens temporárias.",
"schema": {
"enum": [
"last_seen",
"online",
"profile_picture",
"about",
"read_receipts",
"groups",
"calls",
"messages",
"stickers",
"disappearing"
],
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"anyOf": [
{
"type": "string",
"enum": [
"all",
"contacts",
"contact_blacklist",
"contact_allowlist",
"match_last_seen",
"known",
"none",
"on_standard",
"off"
]
},
{
"anyOf": [
{
"type": "number",
"enum": [
0
]
},
{
"type": "number",
"enum": [
86400
]
},
{
"type": "number",
"enum": [
604800
]
},
{
"type": "number",
"enum": [
7776000
]
}
]
}
]
}
},
"required": [
"value"
]
},
"examples": {
"basico": {
"summary": "Visto por último só para contatos",
"value": {
"value": "contacts"
}
},
"disappearing": {
"summary": "Timer padrão de 24h (`setting` = `disappearing`)",
"value": {
"value": 86400
}
}
}
}
}
},
"responses": {
"200": {
"description": "Configurações após a alteração (ou `{ \"updated\": true }` para `disappearing`).",
"content": {
"application/json": {
"example": {
"last_seen": "contacts",
"online": "match_last_seen",
"profile_picture": "all",
"about": "contacts",
"read_receipts": "all",
"groups": "contacts",
"calls": "all",
"messages": "all",
"stickers": "contacts"
},
"examples": {
"configuracao": {
"summary": "Configuração de privacidade",
"value": {
"last_seen": "contacts",
"online": "match_last_seen",
"profile_picture": "all",
"about": "contacts",
"read_receipts": "all",
"groups": "contacts",
"calls": "all",
"messages": "all",
"stickers": "contacts"
}
},
"disappearing": {
"summary": "`disappearing`",
"value": {
"updated": true
}
}
}
}
}
},
"400": {
"description": "`value` inválido para a configuração.",
"content": {
"application/json": {
"example": {
"error": {
"code": "invalid_request",
"message": "value for last_seen must be one of: all, contacts, contact_blacklist, none"
}
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Workspace sem assinatura ativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Active subscription required"
}
}
}
}
},
"409": {
"description": "Instância não está conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Alterar uma configuração de privacidade",
"tags": [
"Privacy"
]
}
},
"/instances/{instance_id}/token/{token}/communities": {
"post": {
"description": "O WhatsApp cria o grupo de avisos automaticamente; `participants` são adicionados a ele. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.create",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 2048
},
"participants": {
"default": [],
"maxItems": 1024,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
}
},
"required": [
"name"
]
},
"examples": {
"basico": {
"summary": "Comunidade com um participante",
"value": {
"name": "Comunidade Wabox",
"description": "Nossa comunidade",
"participants": [
"5511988887777"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Comunidade criada; `groups[]` traz o grupo de avisos (`is_announcement: true`).",
"content": {
"application/json": {
"example": {
"id": "120363012345678901-group",
"name": "Comunidade Wabox",
"description": "Nossa comunidade",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [],
"participant_count": 1,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "admin_add",
"ephemeral_seconds": 0,
"is_community": true,
"suspended": false,
"groups": [
{
"id": "120363012345678902-group",
"name": "Comunidade Wabox",
"is_announcement": true
},
{
"id": "120363012345678903-group",
"name": "Suporte",
"is_announcement": false
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Criar comunidade",
"tags": [
"Communities"
]
},
"get": {
"description": "Comunidades das quais você participa. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.list",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Lista de comunidades em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "120363012345678901-group",
"name": "Comunidade Wabox",
"description": "Nossa comunidade",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [],
"participant_count": 1,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "admin_add",
"ephemeral_seconds": 0,
"is_community": true,
"suspended": false
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar comunidades",
"tags": [
"Communities"
]
}
},
"/instances/{instance_id}/token/{token}/communities/{id}": {
"get": {
"description": "Id da comunidade no formato de grupo: `-group`. `groups[]` lista os grupos vinculados (o grupo de avisos vem com `is_announcement: true`). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.get",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da comunidade (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Metadados da comunidade com os grupos vinculados.",
"content": {
"application/json": {
"example": {
"id": "120363012345678901-group",
"name": "Comunidade Wabox",
"description": "Nossa comunidade",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [],
"participant_count": 1,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "admin_add",
"ephemeral_seconds": 0,
"is_community": true,
"suspended": false,
"groups": [
{
"id": "120363012345678902-group",
"name": "Comunidade Wabox",
"is_announcement": true
},
{
"id": "120363012345678903-group",
"name": "Suporte",
"is_announcement": false
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Metadados e grupos vinculados",
"tags": [
"Communities"
]
},
"put": {
"description": "Mesmo body de `PUT /groups/{id}` (parcial; `remove_picture: true` remove a foto). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.update",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da comunidade (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 2048
},
"picture": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"picture_mime_type": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"remove_picture": {
"type": "boolean"
},
"announce": {
"type": "boolean"
},
"locked": {
"type": "boolean"
},
"join_approval_required": {
"type": "boolean"
},
"member_add_mode": {
"type": "string",
"enum": [
"admin_add",
"all_member_add"
]
},
"ephemeral_seconds": {
"anyOf": [
{
"type": "number",
"enum": [
0
]
},
{
"type": "number",
"enum": [
86400
]
},
{
"type": "number",
"enum": [
604800
]
},
{
"type": "number",
"enum": [
7776000
]
}
]
}
}
},
"examples": {
"basico": {
"summary": "Nome e descrição",
"value": {
"name": "Comunidade Wabox",
"description": "Nossa comunidade"
}
},
"foto": {
"summary": "Trocar a foto (URL ou base64)",
"value": {
"picture": "https://exemplo.com/foto.jpg",
"picture_mime_type": "image/jpeg"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Comunidade atualizada.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Atualizar nome / descrição / foto",
"tags": [
"Communities"
]
}
},
"/instances/{instance_id}/token/{token}/communities/{id}/participants": {
"get": {
"description": "Telefones dos membros de todos os grupos vinculados (sem repetição). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.participants",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da comunidade (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Telefones em `data`.",
"content": {
"application/json": {
"example": {
"data": [
"5511999998888",
"5511988887777"
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Todos os membros da comunidade",
"tags": [
"Communities"
]
}
},
"/instances/{instance_id}/token/{token}/communities/{id}/groups": {
"post": {
"description": "Body `{ \"group_ids\": [...] }` — você precisa ser admin da comunidade e dos grupos. Um resultado por grupo (`error` é o status do WhatsApp, ex.: 403 não permitido). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.link",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da comunidade (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"group_ids": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"pattern": "^(\\d+(-\\d+)?-group|\\d+(-\\d+)?@g\\.us)$"
}
}
},
"required": [
"group_ids"
]
},
"examples": {
"basico": {
"summary": "Dois grupos",
"value": {
"group_ids": [
"120363012345678903-group",
"120363012345678904-group"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Um resultado por grupo em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"group_id": "120363012345678903-group",
"ok": true
},
{
"group_id": "120363012345678904-group",
"ok": false,
"error": "403"
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Vincular grupos existentes à comunidade",
"tags": [
"Communities"
]
}
},
"/instances/{instance_id}/token/{token}/communities/{id}/groups/create": {
"post": {
"description": "Mesmo body de `POST /groups`. O grupo já nasce vinculado (`parent_id` = id da comunidade). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.createGroup",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da comunidade (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"participants": {
"minItems": 1,
"maxItems": 1024,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"description": {
"type": "string",
"maxLength": 2048
},
"announce": {
"type": "boolean"
},
"locked": {
"type": "boolean"
},
"join_approval_required": {
"type": "boolean"
},
"member_add_mode": {
"type": "string",
"enum": [
"admin_add",
"all_member_add"
]
},
"ephemeral_seconds": {
"anyOf": [
{
"type": "number",
"enum": [
0
]
},
{
"type": "number",
"enum": [
86400
]
},
{
"type": "number",
"enum": [
604800
]
},
{
"type": "number",
"enum": [
7776000
]
}
]
}
},
"required": [
"name",
"participants"
]
},
"examples": {
"basico": {
"summary": "Grupo com dois participantes",
"value": {
"name": "Suporte",
"participants": [
"5511988887777",
"5511977776666"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Grupo criado (metadados + participantes), vinculado à comunidade.",
"content": {
"application/json": {
"example": {
"id": "120363012345678903-group",
"name": "Suporte",
"description": "",
"owner": "5511999998888",
"created_at": "2026-08-01T10:00:00.000Z",
"participants": [
{
"phone": "5511999998888",
"lid": "123456789012345@lid",
"is_admin": true,
"is_super_admin": true
},
{
"phone": "5511988887777",
"is_admin": false,
"is_super_admin": false
}
],
"participant_count": 2,
"announce": false,
"locked": false,
"join_approval_required": false,
"member_add_mode": "all_member_add",
"ephemeral_seconds": 0,
"is_community": false,
"suspended": false,
"parent_id": "120363012345678901-group"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Criar grupo dentro da comunidade",
"tags": [
"Communities"
]
}
},
"/instances/{instance_id}/token/{token}/communities/{id}/groups/unlink": {
"post": {
"description": "Body `{ \"group_ids\": [...] }`. Os grupos continuam existindo, só deixam de fazer parte da comunidade. Um resultado por grupo. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.unlink",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da comunidade (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"group_ids": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"pattern": "^(\\d+(-\\d+)?-group|\\d+(-\\d+)?@g\\.us)$"
}
}
},
"required": [
"group_ids"
]
},
"examples": {
"basico": {
"summary": "Dois grupos",
"value": {
"group_ids": [
"120363012345678903-group",
"120363012345678904-group"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Um resultado por grupo em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"group_id": "120363012345678903-group",
"ok": true
},
{
"group_id": "120363012345678904-group",
"ok": false,
"error": "403"
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Desvincular grupos da comunidade",
"tags": [
"Communities"
]
}
},
"/instances/{instance_id}/token/{token}/communities/{id}/groups/{group_id}": {
"delete": {
"description": "Atalho para `POST /communities/{id}/groups/unlink` com um único grupo; devolve só o resultado dele. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.unlinkOne",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da comunidade (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
},
{
"name": "group_id",
"required": true,
"in": "path",
"description": "Id do grupo vinculado (`-group`).",
"schema": {
"example": "120363012345678902-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Resultado da desvinculação.",
"content": {
"application/json": {
"example": {
"group_id": "120363012345678902-group",
"ok": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Desvincular um grupo da comunidade",
"tags": [
"Communities"
]
}
},
"/instances/{instance_id}/token/{token}/communities/{id}/leave": {
"post": {
"description": "Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "communities.leave",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da comunidade (`-group`).",
"schema": {
"example": "120363012345678901-group",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Você saiu da comunidade.",
"content": {
"application/json": {
"example": {
"left": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Sair da comunidade",
"tags": [
"Communities"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters": {
"post": {
"description": "Você passa a ser o dono. `picture` opcional (JPEG/PNG, por URL ou base64). Para publicar em um canal seu, use qualquer endpoint `send-*` com `phone: \"@newsletter\"`. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.create",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 2048
},
"picture": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"picture_mime_type": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"name"
]
},
"examples": {
"basico": {
"summary": "Nome e descrição",
"value": {
"name": "Canal Wabox",
"description": "Novidades da API"
}
},
"com_foto": {
"summary": "Com foto por URL",
"value": {
"name": "Canal Wabox",
"description": "Novidades da API",
"picture": "https://exemplo.com/logo.png",
"picture_mime_type": "image/png"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Canal criado (`role: \"owner\"`).",
"content": {
"application/json": {
"example": {
"id": "120363999999999999@newsletter",
"name": "Canal Wabox",
"description": "Novidades da API",
"invite_code": "0029VaAbCdEfGhIjKlMn1o",
"invite_url": "https://whatsapp.com/channel/0029VaAbCdEfGhIjKlMn1o",
"subscriber_count": 1234,
"verified": false,
"state": "active",
"picture_url": "https://pps.whatsapp.net/v/t61.24694-24/abc.jpg",
"role": "owner",
"muted": false,
"created_at": "2026-06-01T10:00:00.000Z",
"reactions_mode": "all"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Criar canal",
"tags": [
"Newsletters"
]
},
"get": {
"description": "`role` indica sua relação com cada canal (`owner`, `admin`, `subscriber`). Para publicar em um canal seu, use qualquer endpoint `send-*` com `phone: \"@newsletter\"`. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.list",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Lista de canais em `data`.",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "120363999999999999@newsletter",
"name": "Canal Wabox",
"description": "Novidades da API",
"invite_code": "0029VaAbCdEfGhIjKlMn1o",
"invite_url": "https://whatsapp.com/channel/0029VaAbCdEfGhIjKlMn1o",
"subscriber_count": 1234,
"verified": false,
"state": "active",
"picture_url": "https://pps.whatsapp.net/v/t61.24694-24/abc.jpg",
"role": "owner",
"muted": false,
"created_at": "2026-06-01T10:00:00.000Z",
"reactions_mode": "all"
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Canais que você possui ou segue",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/invite-info": {
"get": {
"description": "`?invite=`. Não segue o canal, só consulta. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.inviteInfo",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "invite",
"required": true,
"in": "query",
"description": "Código do convite ou link completo `https://whatsapp.com/channel/`.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Metadados do canal (`role: \"guest\"` quando você não o segue).",
"content": {
"application/json": {
"example": {
"id": "120363999999999999@newsletter",
"name": "Canal Wabox",
"description": "Novidades da API",
"invite_code": "0029VaAbCdEfGhIjKlMn1o",
"invite_url": "https://whatsapp.com/channel/0029VaAbCdEfGhIjKlMn1o",
"subscriber_count": 1234,
"verified": false,
"state": "active",
"picture_url": "https://pps.whatsapp.net/v/t61.24694-24/abc.jpg",
"role": "guest",
"muted": false,
"created_at": "2026-06-01T10:00:00.000Z",
"reactions_mode": "all"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Informações do canal pelo link de convite",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/{id}": {
"get": {
"description": "Id do canal como devolvido pela API / webhooks: `@newsletter`. Para publicar em um canal seu, use qualquer endpoint `send-*` com `phone: \"@newsletter\"`. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.get",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do canal (`@newsletter`).",
"schema": {
"example": "120363999999999999@newsletter",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Metadados do canal.",
"content": {
"application/json": {
"example": {
"id": "120363999999999999@newsletter",
"name": "Canal Wabox",
"description": "Novidades da API",
"invite_code": "0029VaAbCdEfGhIjKlMn1o",
"invite_url": "https://whatsapp.com/channel/0029VaAbCdEfGhIjKlMn1o",
"subscriber_count": 1234,
"verified": false,
"state": "active",
"picture_url": "https://pps.whatsapp.net/v/t61.24694-24/abc.jpg",
"role": "owner",
"muted": false,
"created_at": "2026-06-01T10:00:00.000Z",
"reactions_mode": "all"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Metadados do canal",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/{id}/follow": {
"post": {
"description": "Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.follow",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do canal (`@newsletter`).",
"schema": {
"example": "120363999999999999@newsletter",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Agora você segue o canal.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Seguir canal",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/{id}/unfollow": {
"post": {
"description": "Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.unfollow",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do canal (`@newsletter`).",
"schema": {
"example": "120363999999999999@newsletter",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Você deixou de seguir o canal.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Deixar de seguir canal",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/{id}/mute": {
"post": {
"description": "Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.mute",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do canal (`@newsletter`).",
"schema": {
"example": "120363999999999999@newsletter",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Canal silenciado.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Silenciar canal",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/{id}/unmute": {
"post": {
"description": "Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.unmute",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do canal (`@newsletter`).",
"schema": {
"example": "120363999999999999@newsletter",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Canal com notificações reativadas.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Reativar notificações do canal",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/{id}/messages": {
"get": {
"description": "Metadados + texto das últimas publicações. A mídia não é baixada: para publicações de imagem/vídeo/documento você recebe só o `type` (e o `text`, se houver). `?count=` (≤ 100, padrão 50) e `?before=` paginam para trás. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.messages",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do canal (`@newsletter`).",
"schema": {
"example": "120363999999999999@newsletter",
"type": "string"
}
},
{
"name": "before",
"required": false,
"in": "query",
"description": "Retorna publicações anteriores a este `server_id` (paginação).",
"schema": {}
},
{
"name": "count",
"required": false,
"in": "query",
"description": "Quantidade de publicações (1–100, padrão 50).",
"schema": {}
}
],
"responses": {
"200": {
"description": "Publicações em `data`, da mais recente para a mais antiga.",
"content": {
"application/json": {
"example": {
"data": [
{
"server_id": 119,
"message_id": "3EB0A9C6D2F1E4B5A7F1",
"timestamp": "2026-08-19T10:00:00.000Z",
"type": "text",
"text": "Bem-vindos ao canal!",
"views_count": 980,
"reactions": {
"👍": 12,
"❤️": 3
}
},
{
"server_id": 118,
"message_id": "3EB0A9C6D2F1E4B5A7F0",
"timestamp": "2026-08-18T10:00:00.000Z",
"type": "image",
"views_count": 1500,
"reactions": {}
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Publicações recentes",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/{id}/reaction": {
"post": {
"description": "Body `{ \"server_id\": 119, \"reaction\": \"👍\" }`. `server_id` vem da listagem de publicações ou do webhook `received`. Reação vazia (`\"\"`) remove a sua. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.reaction",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do canal (`@newsletter`).",
"schema": {
"example": "120363999999999999@newsletter",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"server_id": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"reaction": {
"default": "",
"type": "string",
"maxLength": 16
}
},
"required": [
"server_id"
]
},
"examples": {
"basico": {
"summary": "Reagir com emoji",
"value": {
"server_id": 119,
"reaction": "👍"
}
},
"remover": {
"summary": "Remover a sua reação",
"value": {
"server_id": 119,
"reaction": ""
}
}
}
}
}
},
"responses": {
"200": {
"description": "Reação enviada.",
"content": {
"application/json": {
"example": {
"sent": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Reagir a uma publicação",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/newsletters/{id}/read": {
"post": {
"description": "Body `{ \"server_ids\": [118, 119] }` (até 100 por chamada). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "newsletters.read",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do canal (`@newsletter`).",
"schema": {
"example": "120363999999999999@newsletter",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"server_ids": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
},
"required": [
"server_ids"
]
},
"examples": {
"basico": {
"summary": "Duas publicações",
"value": {
"server_ids": [
118,
119
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Publicações marcadas como vistas.",
"content": {
"application/json": {
"example": {
"read": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Marcar publicações como vistas",
"tags": [
"Newsletters"
]
}
},
"/instances/{instance_id}/token/{token}/business/profile": {
"get": {
"description": "Descrição, endereço, e-mail, sites, categorias e horário de funcionamento de uma conta WhatsApp Business. `?phone=` lê o perfil de outro negócio; omitido = o seu. Contas comuns respondem `is_business: false` (os demais campos vêm vazios). Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.profile",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": false,
"in": "query",
"description": "Número do negócio a consultar. Omitido = o número desta instância.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Perfil comercial.",
"content": {
"application/json": {
"example": {
"phone": "5511966665555",
"is_business": true,
"name": "Loja Teste",
"verified_name": "Loja Teste LTDA",
"description": "Roupas e acessórios",
"address": "Rua A, 100 - São Paulo",
"email": "contato@loja.test",
"website": [
"https://loja.test"
],
"categories": [
{
"id": "133436743388217",
"name": "Vestuário"
}
],
"business_hours": {
"timezone": "America/Sao_Paulo",
"config": [
{
"day_of_week": "monday",
"mode": "specific_hours",
"open_time": "09:00",
"close_time": "18:00"
},
{
"day_of_week": "sunday",
"mode": "closed"
}
]
}
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Perfil comercial",
"tags": [
"Business"
]
},
"put": {
"description": "Atualização parcial: só os campos enviados mudam (`website: []` / `categories: []` limpam). `business_hours.config[].open_time/close_time` são `HH:MM` no `timezone` informado. Os ids de `categories` são os que aparecem em `categories[].id` de qualquer perfil comercial.\n\n**Best effort.** O WhatsApp não tem API pública de catálogo para dispositivos vinculados: o Wabox fala o mesmo protocolo que o WhatsApp Web usa, e ele pode mudar sem aviso. Escrever no catálogo exige uma conta **WhatsApp Business**.\n\nImediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.updateProfile",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"description": {
"type": "string",
"maxLength": 512
},
"address": {
"type": "string",
"maxLength": 256
},
"email": {
"type": "string",
"maxLength": 128
},
"website": {
"maxItems": 2,
"type": "array",
"items": {
"type": "string",
"maxLength": 256,
"format": "uri"
}
},
"categories": {
"maxItems": 3,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"business_hours": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"config": {
"maxItems": 7,
"type": "array",
"items": {
"type": "object",
"properties": {
"day_of_week": {
"type": "string",
"enum": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
]
},
"mode": {
"type": "string",
"enum": [
"open_24h",
"specific_hours",
"appointment_only",
"closed"
]
},
"open_time": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
"close_time": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
}
},
"required": [
"day_of_week",
"mode"
]
}
}
},
"required": [
"timezone",
"config"
]
}
}
},
"examples": {
"basico": {
"summary": "Descrição, site e horário",
"value": {
"description": "Roupas e acessórios",
"website": [
"https://loja.test"
],
"business_hours": {
"timezone": "America/Sao_Paulo",
"config": [
{
"day_of_week": "monday",
"mode": "specific_hours",
"open_time": "09:00",
"close_time": "18:00"
},
{
"day_of_week": "sunday",
"mode": "closed"
}
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Perfil atualizado.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Atualizar o perfil comercial",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/business/products": {
"get": {
"description": "Seu catálogo, ou o de outro negócio com `?phone=`. Pagine com `?limit=` (≤100, padrão 50) e `?cursor=`; quando `next_cursor` não vem na resposta, não há mais páginas. Preços são valores decimais na moeda de `currency` (`79.9` = R$ 79,90).\n\n**Best effort.** O WhatsApp não tem API pública de catálogo para dispositivos vinculados: o Wabox fala o mesmo protocolo que o WhatsApp Web usa, e ele pode mudar sem aviso. Escrever no catálogo exige uma conta **WhatsApp Business**.\n\nImediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.products",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "cursor",
"required": false,
"in": "query",
"description": "`next_cursor` da página anterior.",
"schema": {}
},
{
"name": "limit",
"required": false,
"in": "query",
"description": "Itens por página (1–100, padrão 50).",
"schema": {}
},
{
"name": "phone",
"required": false,
"in": "query",
"description": "Número do negócio cujo catálogo será lido. Omitido = o seu.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Página de produtos. `next_cursor` só aparece quando há mais páginas.",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "6543210987654321",
"name": "Camiseta Wabox",
"description": "100% algodão",
"price": 79.9,
"currency": "BRL",
"retailer_id": "SKU-001",
"url": "https://wabox.me/loja/camiseta",
"image_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc.jpg",
"thumbnail_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc_100.jpg",
"hidden": false,
"availability": "in stock",
"review_status": "approved"
}
],
"next_cursor": "eyJwYWdlIjoyfQ=="
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar produtos do catálogo",
"tags": [
"Business"
]
},
"post": {
"description": "Adiciona um produto ao seu catálogo. `images` são enviadas ao WhatsApp (JPEG/PNG, até 10; URL, data URL ou base64). Produtos novos passam pela revisão do WhatsApp (`review_status`). `price` é decimal na moeda de `currency` (ISO-4217).\n\n**Best effort.** O WhatsApp não tem API pública de catálogo para dispositivos vinculados: o Wabox fala o mesmo protocolo que o WhatsApp Web usa, e ele pode mudar sem aviso. Escrever no catálogo exige uma conta **WhatsApp Business**.\n\nImediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.createProduct",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"description": {
"type": "string",
"maxLength": 300
},
"price": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"retailer_id": {
"type": "string",
"maxLength": 60
},
"url": {
"type": "string",
"maxLength": 256,
"format": "uri"
},
"images": {
"default": [],
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
}
},
"hidden": {
"default": false,
"type": "boolean"
}
},
"required": [
"name",
"price",
"currency"
]
},
"examples": {
"basico": {
"summary": "Produto com imagem",
"value": {
"name": "Camiseta Wabox",
"description": "100% algodão",
"price": 79.9,
"currency": "BRL",
"retailer_id": "SKU-001",
"url": "https://wabox.me/loja/camiseta",
"images": [
"https://wabox.me/loja/camiseta.jpg"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Produto criado.",
"content": {
"application/json": {
"example": {
"id": "6543210987654321",
"name": "Camiseta Wabox",
"description": "100% algodão",
"price": 79.9,
"currency": "BRL",
"retailer_id": "SKU-001",
"url": "https://wabox.me/loja/camiseta",
"image_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc.jpg",
"thumbnail_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc_100.jpg",
"hidden": false,
"availability": "in stock",
"review_status": "approved"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Criar um produto",
"tags": [
"Business"
]
},
"delete": {
"description": "Body `{ \"product_ids\": [...] }` (1–50 ids). Responde 404 `product_not_found` se algum id não está no seu catálogo.\n\n**Best effort.** O WhatsApp não tem API pública de catálogo para dispositivos vinculados: o Wabox fala o mesmo protocolo que o WhatsApp Web usa, e ele pode mudar sem aviso. Escrever no catálogo exige uma conta **WhatsApp Business**.\n\nImediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.deleteProducts",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"product_ids": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
},
"required": [
"product_ids"
]
},
"examples": {
"basico": {
"summary": "Dois produtos",
"value": {
"product_ids": [
"6543210987654321",
"6543210987654322"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Quantidade de produtos apagados.",
"content": {
"application/json": {
"example": {
"deleted": 2
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Apagar vários produtos",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/business/products/{id}": {
"put": {
"description": "Atualização parcial; `images` (quando enviado) substitui todas as imagens (`[]` remove todas). Responde 404 `product_not_found` se o produto não está no seu catálogo.\n\n**Best effort.** O WhatsApp não tem API pública de catálogo para dispositivos vinculados: o Wabox fala o mesmo protocolo que o WhatsApp Web usa, e ele pode mudar sem aviso. Escrever no catálogo exige uma conta **WhatsApp Business**.\n\nImediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.updateProduct",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do produto no WhatsApp (o `id` da listagem).",
"schema": {
"example": "6543210987654321",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"description": {
"type": "string",
"maxLength": 300
},
"price": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"retailer_id": {
"type": "string",
"maxLength": 60
},
"url": {
"type": "string",
"maxLength": 256,
"format": "uri"
},
"images": {
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
}
},
"hidden": {
"type": "boolean"
}
}
},
"examples": {
"basico": {
"summary": "Mudar preço e ocultar",
"value": {
"price": 69.9,
"hidden": true
}
},
"imagens": {
"summary": "Substituir as imagens",
"value": {
"images": [
"https://wabox.me/loja/camiseta-frente.jpg",
"https://wabox.me/loja/camiseta-verso.jpg"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Produto atualizado.",
"content": {
"application/json": {
"example": {
"id": "6543210987654321",
"name": "Camiseta Wabox",
"description": "100% algodão",
"price": 69.9,
"currency": "BRL",
"retailer_id": "SKU-001",
"url": "https://wabox.me/loja/camiseta",
"image_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc.jpg",
"thumbnail_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc_100.jpg",
"hidden": true,
"availability": "in stock",
"review_status": "approved"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Editar um produto",
"tags": [
"Business"
]
},
"delete": {
"description": "Remove o produto do seu catálogo. Responde 404 `product_not_found` se ele não existe.\n\n**Best effort.** O WhatsApp não tem API pública de catálogo para dispositivos vinculados: o Wabox fala o mesmo protocolo que o WhatsApp Web usa, e ele pode mudar sem aviso. Escrever no catálogo exige uma conta **WhatsApp Business**.\n\nImediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.deleteProduct",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id do produto no WhatsApp (o `id` da listagem).",
"schema": {
"example": "6543210987654321",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Quantidade de produtos apagados.",
"content": {
"application/json": {
"example": {
"deleted": 1
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Apagar um produto",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/business/collections": {
"get": {
"description": "Coleções (com seus produtos) do seu catálogo ou do de outro negócio (`?phone=`).\n\n**Best effort.** O WhatsApp não tem API pública de catálogo para dispositivos vinculados: o Wabox fala o mesmo protocolo que o WhatsApp Web usa, e ele pode mudar sem aviso. Escrever no catálogo exige uma conta **WhatsApp Business**.\n\nImediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.collections",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "limit",
"required": false,
"in": "query",
"description": "Máximo de coleções (1–100, padrão 50).",
"schema": {}
},
{
"name": "phone",
"required": false,
"in": "query",
"description": "Número do negócio cujo catálogo será lido. Omitido = o seu.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Coleções com seus produtos.",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "1234567890",
"name": "Verão",
"review_status": "approved",
"products": [
{
"id": "6543210987654321",
"name": "Camiseta Wabox",
"description": "100% algodão",
"price": 79.9,
"currency": "BRL",
"retailer_id": "SKU-001",
"url": "https://wabox.me/loja/camiseta",
"image_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc.jpg",
"thumbnail_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc_100.jpg",
"hidden": false,
"availability": "in stock",
"review_status": "approved"
}
]
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar coleções do catálogo",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/business/orders/{id}": {
"get": {
"description": "Itens e totais de um pedido que um cliente fez a partir do seu catálogo. `id` e `?token=` vêm do bloco `order` do webhook `received`. Responde 404 `order_not_found` se o par id/token não bate.\n\n**Best effort.** O WhatsApp não tem API pública de catálogo para dispositivos vinculados: o Wabox fala o mesmo protocolo que o WhatsApp Web usa, e ele pode mudar sem aviso. Escrever no catálogo exige uma conta **WhatsApp Business**.\n\nImediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "business.order",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "`order.id` do webhook `received`.",
"schema": {
"example": "1234567890123456",
"type": "string"
}
},
{
"name": "token",
"required": true,
"in": "query",
"description": "`order.token` do webhook `received`.",
"schema": {}
}
],
"responses": {
"200": {
"description": "Pedido com itens e totais.",
"content": {
"application/json": {
"example": {
"id": "1234567890123456",
"created_at": "2026-08-20T11:58:00.000Z",
"catalog_id": "9876543210",
"total": 159.8,
"subtotal": 159.8,
"currency": "BRL",
"price_status": "confirmed",
"products": [
{
"id": "6543210987654321",
"name": "Camiseta Wabox",
"quantity": 2,
"price": 79.9,
"currency": "BRL",
"image_url": "https://mmg.whatsapp.net/v/t45.5328-4/abc.jpg",
"variant": "Tamanho: M"
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Detalhes de um pedido",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/send-product": {
"post": {
"description": "Card de um produto do seu catálogo (ou do catálogo de outro negócio, com `business_phone`), com `message` opcional abaixo. `product_id` pode ser o id do WhatsApp ou o seu `retailer_id`. O produto é lido do catálogo na hora do envio: se não existir, o `delivery` chega com erro.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id final no WhatsApp e o resultado chega no webhook `delivery`.",
"operationId": "business.sendProduct",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"product_id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"business_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"message": {
"type": "string",
"maxLength": 1024
},
"footer": {
"type": "string",
"maxLength": 60
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone",
"product_id"
]
},
"examples": {
"basico": {
"summary": "Produto do seu catálogo",
"value": {
"phone": "5511988887777",
"product_id": "6543210987654321",
"message": "Olha essa camiseta!",
"footer": "Loja Teste"
}
},
"outro_negocio": {
"summary": "Produto de outro negócio",
"value": {
"phone": "5511988887777",
"product_id": "SKU-001",
"business_phone": "5511977776666"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Enviar card de produto",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/send-catalog": {
"post": {
"description": "Envia `https://wa.me/c/` (seu próprio catálogo por padrão) com uma `message` opcional acima.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id final no WhatsApp e o resultado chega no webhook `delivery`.",
"operationId": "business.sendCatalog",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"business_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"message": {
"type": "string",
"maxLength": 4096
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
}
},
"required": [
"phone"
]
},
"examples": {
"basico": {
"summary": "Seu catálogo",
"value": {
"phone": "5511988887777",
"message": "Confira nosso catálogo"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Enviar link do catálogo",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/send-order": {
"post": {
"description": "Card com o resumo de um pedido (`title`, `item_count`, `total`). Os itens só existem em pedidos que o cliente fez a partir do catálogo: um card criado aqui sem `token` mostra apenas o resumo. `order_id` é a sua referência (gerada quando omitida); `status` padrão `inquiry`. Para responder a um pedido que o cliente fez, use `order-status-update`.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id final no WhatsApp e o resultado chega no webhook `delivery`.",
"operationId": "business.sendOrder",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"item_count": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 9999
},
"total": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"message": {
"type": "string",
"maxLength": 1024
},
"seller_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"thumbnail": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
},
"order_id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"status": {
"type": "string",
"enum": [
"inquiry",
"accepted",
"declined"
]
},
"token": {
"type": "string",
"maxLength": 512
},
"order_request_message_id": {
"type": "string",
"minLength": 1
}
},
"required": [
"phone",
"title",
"total",
"currency"
]
},
"examples": {
"basico": {
"summary": "Resumo de pedido",
"value": {
"phone": "5511988887777",
"order_id": "PED-42",
"title": "Pedido #42",
"item_count": 2,
"total": 159.8,
"currency": "BRL",
"message": "Seu pedido foi registrado."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Enviar card de pedido",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/order-status-update": {
"post": {
"description": "Responde a um pedido que o cliente fez: devolva o `order_id`, o `token` e o `message_id` da mensagem do pedido como `order_request_message_id` (tudo do bloco `order` do webhook `received`), com `status: accepted | declined`. Use `GET /business/orders/{id}` para ler os itens antes.\n\nA mensagem entra na fila e é enviada de forma assíncrona; `message_id` já é o id final no WhatsApp e o resultado chega no webhook `delivery`.",
"operationId": "business.orderStatusUpdate",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$",
"description": "Chat de destino: número só dígitos com DDI e DDD (`5511988887777`), grupo (`-group`), canal (`@newsletter`), LID (`@lid`) ou `status@broadcast`."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"item_count": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 9999
},
"total": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"message": {
"type": "string",
"maxLength": 1024
},
"seller_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"thumbnail": {
"type": "string",
"minLength": 1,
"maxLength": 94371840,
"description": "URL http(s) pública, `data:` URL ou base64 puro."
},
"reply_to_message_id": {
"description": "Id da mensagem a citar (responder), no mesmo chat.",
"type": "string",
"minLength": 1
},
"mentioned": {
"description": "Números a mencionar; cada um precisa aparecer no texto como `@`.",
"maxItems": 500,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"mention_all": {
"description": "Grupos: menciona todos os participantes.",
"type": "boolean"
},
"delay_message": {
"description": "Segundos (0–15) de espera antes de enviar, substituindo o intervalo aleatório da instância (`delay_message_min_ms`/`max_ms`).",
"type": "number",
"minimum": 0,
"maximum": 15
},
"delay_typing": {
"description": "Segundos (0–15) mostrando \"digitando…\" (ou \"gravando…\" em voice notes) antes de enviar. Padrão 0.",
"type": "number",
"minimum": 0,
"maximum": 15
},
"order_id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"token": {
"type": "string",
"maxLength": 512
},
"order_request_message_id": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"accepted",
"declined"
]
}
},
"required": [
"phone",
"title",
"total",
"currency",
"order_id",
"order_request_message_id",
"status"
]
},
"examples": {
"basico": {
"summary": "Aceitar o pedido",
"value": {
"phone": "5511988887777",
"order_id": "1234567890123456",
"token": "AbCdEf0123456789",
"order_request_message_id": "3EB0A9C6D2F1E4B5A7E2",
"status": "accepted",
"title": "Pedido #42",
"item_count": 2,
"total": 159.8,
"currency": "BRL",
"message": "Pedido confirmado!"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mensagem enfileirada.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"message_id": {
"type": "string"
},
"wabox_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued"
]
}
},
"required": [
"id",
"message_id",
"wabox_id",
"status"
]
},
"example": {
"id": "3EB0A9C6D2F1E4B5A7C8",
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"status": "queued"
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada (ações imediatas de perfil, catálogo e pedidos).",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Aceitar ou recusar um pedido",
"tags": [
"Business"
]
}
},
"/instances/{instance_id}/token/{token}/labels": {
"get": {
"description": "Todas as etiquetas com os chats (telefones / ids de grupo) que as carregam. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. A primeira chamada após a instância (re)iniciar dispara uma sincronização das etiquetas com o WhatsApp e pode responder 502 `action_failed` se ela ainda não terminou — repita em alguns segundos. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.list[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Etiquetas e os chats de cada uma.",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "1724155200000",
"name": "Novo cliente",
"color": 3,
"chats": [
"5511988887777",
"120363012345678901-group"
]
},
{
"id": "2",
"name": "Pagamento pendente",
"color": 7,
"chats": []
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar etiquetas",
"tags": [
"Labels"
]
},
"post": {
"description": "Body `{ \"name\", \"color\" }` (`color` = índice da paleta dos apps do WhatsApp, 0–19; padrão 0). Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.create[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"color": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 19
}
},
"required": [
"name"
]
},
"examples": {
"basico": {
"summary": "Etiqueta com cor",
"value": {
"name": "Novo cliente",
"color": 3
}
}
}
}
}
},
"responses": {
"200": {
"description": "Etiqueta criada (ainda sem chats).",
"content": {
"application/json": {
"example": {
"id": "1724155200000",
"name": "Novo cliente",
"color": 3,
"chats": []
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Criar uma etiqueta",
"tags": [
"Labels"
]
}
},
"/instances/{instance_id}/token/{token}/tags": {
"get": {
"description": "Todas as etiquetas com os chats (telefones / ids de grupo) que as carregam. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. A primeira chamada após a instância (re)iniciar dispara uma sincronização das etiquetas com o WhatsApp e pode responder 502 `action_failed` se ela ainda não terminou — repita em alguns segundos. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.list[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"responses": {
"200": {
"description": "Etiquetas e os chats de cada uma.",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "1724155200000",
"name": "Novo cliente",
"color": 3,
"chats": [
"5511988887777",
"120363012345678901-group"
]
},
{
"id": "2",
"name": "Pagamento pendente",
"color": 7,
"chats": []
}
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Listar etiquetas (compatibilidade z-api)",
"tags": [
"Labels"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
},
"post": {
"description": "Body `{ \"name\", \"color\" }` (`color` = índice da paleta dos apps do WhatsApp, 0–19; padrão 0). Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.create[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"color": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 19
}
},
"required": [
"name"
]
},
"examples": {
"basico": {
"summary": "Etiqueta com cor",
"value": {
"name": "Novo cliente",
"color": 3
}
}
}
}
}
},
"responses": {
"200": {
"description": "Etiqueta criada (ainda sem chats).",
"content": {
"application/json": {
"example": {
"id": "1724155200000",
"name": "Novo cliente",
"color": 3,
"chats": []
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Criar uma etiqueta (compatibilidade z-api)",
"tags": [
"Labels"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/labels/{id}": {
"put": {
"description": "Envie `name`, `color` ou ambos. Responde 404 `label_not_found` se a etiqueta não existe. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.update[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da etiqueta (o `id` da listagem).",
"schema": {
"example": "1724155200000",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"color": {
"type": "integer",
"minimum": 0,
"maximum": 19
}
}
},
"examples": {
"basico": {
"summary": "Renomear",
"value": {
"name": "Cliente novo"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Etiqueta atualizada.",
"content": {
"application/json": {
"example": {
"id": "1724155200000",
"name": "Cliente novo",
"color": 3,
"chats": [
"5511988887777",
"120363012345678901-group"
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Renomear / recolorir uma etiqueta",
"tags": [
"Labels"
]
},
"delete": {
"description": "Remove a etiqueta de todos os chats. Responde 404 `label_not_found` se ela não existe. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.remove[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da etiqueta (o `id` da listagem).",
"schema": {
"example": "1724155200000",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Etiqueta apagada.",
"content": {
"application/json": {
"example": {
"deleted": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Apagar uma etiqueta",
"tags": [
"Labels"
]
}
},
"/instances/{instance_id}/token/{token}/tags/{id}": {
"put": {
"description": "Envie `name`, `color` ou ambos. Responde 404 `label_not_found` se a etiqueta não existe. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.update[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da etiqueta (o `id` da listagem).",
"schema": {
"example": "1724155200000",
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"color": {
"type": "integer",
"minimum": 0,
"maximum": 19
}
}
},
"examples": {
"basico": {
"summary": "Renomear",
"value": {
"name": "Cliente novo"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Etiqueta atualizada.",
"content": {
"application/json": {
"example": {
"id": "1724155200000",
"name": "Cliente novo",
"color": 3,
"chats": [
"5511988887777",
"120363012345678901-group"
]
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Renomear / recolorir uma etiqueta (compatibilidade z-api)",
"tags": [
"Labels"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
},
"delete": {
"description": "Remove a etiqueta de todos os chats. Responde 404 `label_not_found` se ela não existe. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.remove[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da etiqueta (o `id` da listagem).",
"schema": {
"example": "1724155200000",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Etiqueta apagada.",
"content": {
"application/json": {
"example": {
"deleted": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Apagar uma etiqueta (compatibilidade z-api)",
"tags": [
"Labels"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/chats/{phone}/labels/{id}": {
"put": {
"description": "`phone` pode ser um usuário ou um id de grupo. Responde 404 `label_not_found` se a etiqueta não existe. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.addToChat[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"description": "Telefone ou id de grupo (`120363012345678901-group`).",
"schema": {
"example": "5511988887777",
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da etiqueta (o `id` da listagem).",
"schema": {
"example": "1724155200000",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Etiqueta aplicada ao chat.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Etiquetar um chat",
"tags": [
"Labels"
]
},
"delete": {
"description": "Responde 404 `label_not_found` se a etiqueta não existe. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.removeFromChat[0]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"description": "Telefone ou id de grupo (`120363012345678901-group`).",
"schema": {
"example": "5511988887777",
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da etiqueta (o `id` da listagem).",
"schema": {
"example": "1724155200000",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Etiqueta removida do chat.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Tirar a etiqueta de um chat",
"tags": [
"Labels"
]
}
},
"/instances/{instance_id}/token/{token}/chats/{phone}/tags/{id}/add": {
"put": {
"description": "`phone` pode ser um usuário ou um id de grupo. Responde 404 `label_not_found` se a etiqueta não existe. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.addToChat[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"description": "Telefone ou id de grupo (`120363012345678901-group`).",
"schema": {
"example": "5511988887777",
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da etiqueta (o `id` da listagem).",
"schema": {
"example": "1724155200000",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Etiqueta aplicada ao chat.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Etiquetar um chat (compatibilidade z-api)",
"tags": [
"Labels"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/instances/{instance_id}/token/{token}/chats/{phone}/tags/{id}/remove": {
"delete": {
"description": "Responde 404 `label_not_found` se a etiqueta não existe. Etiquetas só existem em contas **WhatsApp Business**. As mudanças são refletidas no celular. Imediata: exige a instância conectada (caso contrário, 409 `instance_not_connected`).",
"operationId": "labels.removeFromChat[1]",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Id da instância (dashboard › instância › Credenciais).",
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
},
{
"name": "token",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"description": "Token da instância. Trate como senha.",
"example": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E"
},
{
"name": "phone",
"required": true,
"in": "path",
"description": "Telefone ou id de grupo (`120363012345678901-group`).",
"schema": {
"example": "5511988887777",
"type": "string"
}
},
{
"name": "id",
"required": true,
"in": "path",
"description": "Id da etiqueta (o `id` da listagem).",
"schema": {
"example": "1724155200000",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Etiqueta removida do chat.",
"content": {
"application/json": {
"example": {
"updated": true
}
}
}
},
"401": {
"description": "Instância/token inválidos ou `Client-Token` ausente.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found or invalid token"
}
}
}
}
},
"402": {
"description": "Trial expirado ou assinatura inativa.",
"content": {
"application/json": {
"example": {
"error": {
"code": "subscription_required",
"message": "Trial expired or subscription inactive. Subscribe in the dashboard to keep sending."
}
}
}
}
},
"409": {
"description": "Instância não conectada.",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_connected",
"message": "Instance is not connected"
}
}
}
}
}
},
"summary": "Tirar a etiqueta de um chat (compatibilidade z-api)",
"tags": [
"Labels"
],
"x-hidden": true,
"x-wabox-compat": "z-api"
}
},
"/partner/instances": {
"post": {
"description": "Cria uma instância no workspace Partner e já inicia a sessão. A resposta traz `id`, `token` e `api_url`: use-os na API pública normal para obter o QR (`GET /qr-code`), status e enviar mensagens. `webhooks` e `settings` são opcionais e aceitam os mesmos campos de `PUT /webhooks` e `PUT /settings`. Instâncias Partner não têm trial nem `402`.",
"operationId": "partnerInstances.create",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "Nome da instância (rótulo interno)."
},
"webhooks": {
"description": "Webhooks e filtros, como em `PUT /webhooks`.",
"type": "object",
"properties": {
"received_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"delivery_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"message_status_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"connected_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"disconnected_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"chat_presence_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"notify_sent_by_me": {
"type": "boolean"
},
"ignore_groups": {
"type": "boolean"
},
"ignore_private": {
"type": "boolean"
},
"ignore_text": {
"type": "boolean"
},
"ignore_image": {
"type": "boolean"
},
"ignore_video": {
"type": "boolean"
},
"ignore_audio": {
"type": "boolean"
},
"ignore_document": {
"type": "boolean"
},
"ignore_received_callback": {
"type": "boolean"
},
"ignore_delivery_callback": {
"type": "boolean"
},
"ignore_message_status_callback": {
"type": "boolean"
},
"ignore_connected_callback": {
"type": "boolean"
},
"ignore_disconnected_callback": {
"type": "boolean"
},
"ignore_chat_presence_callback": {
"type": "boolean"
}
}
},
"settings": {
"description": "Configurações, como em `PUT /settings`.",
"type": "object",
"properties": {
"auto_read_message": {
"type": "boolean"
},
"auto_read_status": {
"type": "boolean"
},
"call_reject_auto": {
"type": "boolean"
},
"call_reject_message": {
"nullable": true,
"type": "string",
"maxLength": 1000
},
"disable_enqueue_when_disconnected": {
"type": "boolean"
},
"delay_message_min_ms": {
"type": "integer",
"minimum": 0,
"maximum": 15000
},
"delay_message_max_ms": {
"type": "integer",
"minimum": 0,
"maximum": 15000
},
"proxy_url": {
"nullable": true,
"type": "string",
"format": "uri"
}
}
}
},
"required": [
"name"
]
},
"examples": {
"basico": {
"summary": "Só o nome",
"value": {
"name": "Loja Centro"
}
},
"completo": {
"summary": "Com webhooks e configurações",
"value": {
"name": "Loja Centro",
"webhooks": {
"received_url": "https://kinbox.example/wabox/received",
"delivery_url": "https://kinbox.example/wabox/delivery",
"message_status_url": "https://kinbox.example/wabox/status",
"connected_url": "https://kinbox.example/wabox/connected",
"disconnected_url": "https://kinbox.example/wabox/disconnected",
"notify_sent_by_me": true
},
"settings": {
"call_reject_auto": true,
"call_reject_message": "Não atendemos chamadas."
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Instância criada.",
"content": {
"application/json": {
"example": {
"id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"name": "Loja Centro",
"token": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"status": "qr",
"status_reason": null,
"connected": false,
"phone": null,
"profile_name": null,
"platform": null,
"connected_at": null,
"disconnected_at": null,
"subscription_status": "partner",
"trial_ends_at": "2026-09-15T12:00:00.000Z",
"due_at": null,
"settings": {
"auto_read_message": false,
"auto_read_status": false,
"call_reject_auto": false,
"call_reject_message": null,
"disable_enqueue_when_disconnected": false,
"delay_message_min_ms": 1000,
"delay_message_max_ms": 3000,
"proxy_url": null
},
"webhooks": {
"received_url": "https://kinbox.example/wabox/received",
"delivery_url": "https://kinbox.example/wabox/delivery",
"message_status_url": "https://kinbox.example/wabox/status",
"connected_url": "https://kinbox.example/wabox/connected",
"disconnected_url": "https://kinbox.example/wabox/disconnected",
"chat_presence_url": null,
"notify_sent_by_me": true,
"ignore_groups": false,
"ignore_private": false,
"ignore_text": false,
"ignore_image": false,
"ignore_video": false,
"ignore_audio": false,
"ignore_document": false,
"ignore_received_callback": false,
"ignore_delivery_callback": false,
"ignore_message_status_callback": false,
"ignore_connected_callback": false,
"ignore_disconnected_callback": false,
"ignore_chat_presence_callback": false,
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
},
"api_url": "https://api.wabox.me/instances/8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b/token/3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"created_at": "2026-09-15T12:00:00.000Z",
"updated_at": "2026-09-15T12:00:00.000Z"
}
}
}
},
"401": {
"description": "`Partner-Token` ausente ou inválido.",
"content": {
"application/json": {
"example": {
"error": {
"code": "partner_token_required",
"message": "Invalid Partner-Token"
}
}
}
}
}
},
"security": [
{
"PartnerToken": []
}
],
"summary": "Criar instância",
"tags": [
"Partner"
]
},
"get": {
"description": "Instâncias do workspace Partner, da mais recente para a mais antiga, com `token` e webhooks. Filtre por `status` (`connected` / `disconnected`) ou `q` (nome, id ou número).",
"operationId": "partnerInstances.list",
"parameters": [
{
"name": "page_size",
"required": false,
"in": "query",
"description": "1–100. Padrão 20.",
"schema": {
"example": 20
}
},
{
"name": "page",
"required": false,
"in": "query",
"schema": {
"example": 1
}
},
{
"name": "q",
"required": false,
"in": "query",
"description": "Busca por nome, id ou número.",
"schema": {}
},
{
"name": "status",
"required": false,
"in": "query",
"schema": {
"enum": [
"connected",
"disconnected"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Página de instâncias.",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"name": "Loja Centro",
"token": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"status": "qr",
"status_reason": null,
"connected": false,
"phone": null,
"profile_name": null,
"platform": null,
"connected_at": null,
"disconnected_at": null,
"subscription_status": "partner",
"trial_ends_at": "2026-09-15T12:00:00.000Z",
"due_at": null,
"settings": {
"auto_read_message": false,
"auto_read_status": false,
"call_reject_auto": false,
"call_reject_message": null,
"disable_enqueue_when_disconnected": false,
"delay_message_min_ms": 1000,
"delay_message_max_ms": 3000,
"proxy_url": null
},
"webhooks": {
"received_url": "https://kinbox.example/wabox/received",
"delivery_url": "https://kinbox.example/wabox/delivery",
"message_status_url": "https://kinbox.example/wabox/status",
"connected_url": "https://kinbox.example/wabox/connected",
"disconnected_url": "https://kinbox.example/wabox/disconnected",
"chat_presence_url": null,
"notify_sent_by_me": true,
"ignore_groups": false,
"ignore_private": false,
"ignore_text": false,
"ignore_image": false,
"ignore_video": false,
"ignore_audio": false,
"ignore_document": false,
"ignore_received_callback": false,
"ignore_delivery_callback": false,
"ignore_message_status_callback": false,
"ignore_connected_callback": false,
"ignore_disconnected_callback": false,
"ignore_chat_presence_callback": false,
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
},
"api_url": "https://api.wabox.me/instances/8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b/token/3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"created_at": "2026-09-15T12:00:00.000Z",
"updated_at": "2026-09-15T12:00:00.000Z"
}
],
"page": 1,
"page_size": 20,
"total": 1
}
}
}
},
"401": {
"description": "`Partner-Token` ausente ou inválido.",
"content": {
"application/json": {
"example": {
"error": {
"code": "partner_token_required",
"message": "Invalid Partner-Token"
}
}
}
}
}
},
"security": [
{
"PartnerToken": []
}
],
"summary": "Listar instâncias",
"tags": [
"Partner"
]
}
},
"/partner/instances/{instance_id}": {
"get": {
"operationId": "partnerInstances.get",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"name": "Loja Centro",
"token": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"status": "qr",
"status_reason": null,
"connected": false,
"phone": null,
"profile_name": null,
"platform": null,
"connected_at": null,
"disconnected_at": null,
"subscription_status": "partner",
"trial_ends_at": "2026-09-15T12:00:00.000Z",
"due_at": null,
"settings": {
"auto_read_message": false,
"auto_read_status": false,
"call_reject_auto": false,
"call_reject_message": null,
"disable_enqueue_when_disconnected": false,
"delay_message_min_ms": 1000,
"delay_message_max_ms": 3000,
"proxy_url": null
},
"webhooks": {
"received_url": "https://kinbox.example/wabox/received",
"delivery_url": "https://kinbox.example/wabox/delivery",
"message_status_url": "https://kinbox.example/wabox/status",
"connected_url": "https://kinbox.example/wabox/connected",
"disconnected_url": "https://kinbox.example/wabox/disconnected",
"chat_presence_url": null,
"notify_sent_by_me": true,
"ignore_groups": false,
"ignore_private": false,
"ignore_text": false,
"ignore_image": false,
"ignore_video": false,
"ignore_audio": false,
"ignore_document": false,
"ignore_received_callback": false,
"ignore_delivery_callback": false,
"ignore_message_status_callback": false,
"ignore_connected_callback": false,
"ignore_disconnected_callback": false,
"ignore_chat_presence_callback": false,
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
},
"api_url": "https://api.wabox.me/instances/8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b/token/3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"created_at": "2026-09-15T12:00:00.000Z",
"updated_at": "2026-09-15T12:00:00.000Z"
}
}
}
},
"401": {
"description": "`Partner-Token` ausente ou inválido.",
"content": {
"application/json": {
"example": {
"error": {
"code": "partner_token_required",
"message": "Invalid Partner-Token"
}
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"example": {
"error": {
"code": "instance_not_found",
"message": "Instance not found"
}
}
}
}
}
},
"security": [
{
"PartnerToken": []
}
],
"summary": "Detalhes da instância",
"tags": [
"Partner"
]
},
"put": {
"description": "Atualização parcial de `name`, `webhooks` e/ou `settings`.",
"operationId": "partnerInstances.update",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "Nome da instância (rótulo interno)."
},
"webhooks": {
"type": "object",
"properties": {
"received_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"delivery_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"message_status_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"connected_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"disconnected_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"chat_presence_url": {
"nullable": true,
"type": "string",
"format": "uri"
},
"notify_sent_by_me": {
"type": "boolean"
},
"ignore_groups": {
"type": "boolean"
},
"ignore_private": {
"type": "boolean"
},
"ignore_text": {
"type": "boolean"
},
"ignore_image": {
"type": "boolean"
},
"ignore_video": {
"type": "boolean"
},
"ignore_audio": {
"type": "boolean"
},
"ignore_document": {
"type": "boolean"
},
"ignore_received_callback": {
"type": "boolean"
},
"ignore_delivery_callback": {
"type": "boolean"
},
"ignore_message_status_callback": {
"type": "boolean"
},
"ignore_connected_callback": {
"type": "boolean"
},
"ignore_disconnected_callback": {
"type": "boolean"
},
"ignore_chat_presence_callback": {
"type": "boolean"
}
}
},
"settings": {
"type": "object",
"properties": {
"auto_read_message": {
"type": "boolean"
},
"auto_read_status": {
"type": "boolean"
},
"call_reject_auto": {
"type": "boolean"
},
"call_reject_message": {
"nullable": true,
"type": "string",
"maxLength": 1000
},
"disable_enqueue_when_disconnected": {
"type": "boolean"
},
"delay_message_min_ms": {
"type": "integer",
"minimum": 0,
"maximum": 15000
},
"delay_message_max_ms": {
"type": "integer",
"minimum": 0,
"maximum": 15000
},
"proxy_url": {
"nullable": true,
"type": "string",
"format": "uri"
}
}
}
}
},
"examples": {
"webhooks": {
"summary": "Trocar a URL de recebimento",
"value": {
"webhooks": {
"received_url": "https://kinbox.example/v2/wabox/received"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"name": "Loja Centro",
"token": "3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"status": "qr",
"status_reason": null,
"connected": false,
"phone": null,
"profile_name": null,
"platform": null,
"connected_at": null,
"disconnected_at": null,
"subscription_status": "partner",
"trial_ends_at": "2026-09-15T12:00:00.000Z",
"due_at": null,
"settings": {
"auto_read_message": false,
"auto_read_status": false,
"call_reject_auto": false,
"call_reject_message": null,
"disable_enqueue_when_disconnected": false,
"delay_message_min_ms": 1000,
"delay_message_max_ms": 3000,
"proxy_url": null
},
"webhooks": {
"received_url": "https://kinbox.example/wabox/received",
"delivery_url": "https://kinbox.example/wabox/delivery",
"message_status_url": "https://kinbox.example/wabox/status",
"connected_url": "https://kinbox.example/wabox/connected",
"disconnected_url": "https://kinbox.example/wabox/disconnected",
"chat_presence_url": null,
"notify_sent_by_me": true,
"ignore_groups": false,
"ignore_private": false,
"ignore_text": false,
"ignore_image": false,
"ignore_video": false,
"ignore_audio": false,
"ignore_document": false,
"ignore_received_callback": false,
"ignore_delivery_callback": false,
"ignore_message_status_callback": false,
"ignore_connected_callback": false,
"ignore_disconnected_callback": false,
"ignore_chat_presence_callback": false,
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
},
"api_url": "https://api.wabox.me/instances/8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b/token/3A1F5C7E9B2D4F6A8C0E1B3D5F7A9C2E",
"created_at": "2026-09-15T12:00:00.000Z",
"updated_at": "2026-09-15T12:00:00.000Z"
}
}
}
},
"401": {
"description": "`Partner-Token` ausente ou inválido.",
"content": {
"application/json": {
"example": {
"error": {
"code": "partner_token_required",
"message": "Invalid Partner-Token"
}
}
}
}
}
},
"security": [
{
"PartnerToken": []
}
],
"summary": "Atualizar instância",
"tags": [
"Partner"
]
},
"delete": {
"description": "Desconecta o número (o aparelho vinculado some do celular), para a sessão e remove a instância. Mensagens na fila são descartadas.",
"operationId": "partnerInstances.remove",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
}
],
"responses": {
"204": {
"description": "Removida."
},
"401": {
"description": "`Partner-Token` ausente ou inválido.",
"content": {
"application/json": {
"example": {
"error": {
"code": "partner_token_required",
"message": "Invalid Partner-Token"
}
}
}
}
}
},
"security": [
{
"PartnerToken": []
}
],
"summary": "Excluir instância",
"tags": [
"Partner"
]
}
},
"/partner/instances/{instance_id}/rotate-token": {
"post": {
"description": "O token atual deixa de valer imediatamente.",
"operationId": "partnerInstances.rotateToken",
"parameters": [
{
"name": "instance_id",
"required": true,
"in": "path",
"description": "Id da instância (dashboard › instância › Credenciais).",
"schema": {
"type": "string"
},
"example": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b"
}
],
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"example": {
"token": "7C2E3A1F5C7E9B2D4F6A8C0E1B3D5F7A"
}
}
}
},
"401": {
"description": "`Partner-Token` ausente ou inválido.",
"content": {
"application/json": {
"example": {
"error": {
"code": "partner_token_required",
"message": "Invalid Partner-Token"
}
}
}
}
}
},
"security": [
{
"PartnerToken": []
}
],
"summary": "Gerar novo token da instância",
"tags": [
"Partner"
]
}
}
},
"info": {
"title": "Wabox API",
"description": "API pública do Wabox — WhatsApp via REST + webhooks.\n\nBase: `{server}/instances/{instance_id}/token/{token}`. Header `Client-Token` obrigatório quando ativado em Segurança.\n\nTudo em `snake_case`. Datas ISO-8601 (UTC). Erros: `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`.\n\nEnvios respondem `{ id, message_id, wabox_id, status: \"queued\" }` na hora; o resultado chega no webhook `delivery`. `message_id` já é o id definitivo do WhatsApp.",
"version": "1.0",
"contact": {}
},
"tags": [
{
"name": "Instance",
"description": "Conexão (QR code / código de pareamento), status, webhooks e configurações da instância.",
"x-group": "Instância"
},
{
"name": "Messages",
"description": "Envio de texto, mídia, localização, contatos, reações, enquetes e ações sobre mensagens. Tudo passa pela fila; o resultado chega no webhook `delivery`.",
"x-group": "Mensagens"
},
{
"name": "Interactive",
"description": "Botões, listas, carrossel, PIX, eventos de calendário, status (stories) e convite de canal. Best effort: renderizam no celular; o WhatsApp Web/Desktop não exibe botões, listas nem carrossel.",
"x-group": "Interativos"
},
{
"name": "Queue",
"description": "Mensagens aguardando envio (pacing anti-ban ou instância desconectada).",
"x-group": "Fila"
},
{
"name": "Chats",
"description": "Lista de conversas, ações (arquivar, silenciar, fixar, ler) e mensagens temporárias.",
"x-group": "Chats"
},
{
"name": "Contacts",
"description": "Contatos, foto de perfil, verificação de números e bloqueio.",
"x-group": "Contatos"
},
{
"name": "Profile",
"description": "Nome, recado e foto do número conectado.",
"x-group": "Perfil"
},
{
"name": "Groups",
"description": "Criar, listar, administrar participantes, links de convite e configurações.",
"x-group": "Grupos"
},
{
"name": "Communities",
"description": "Comunidades e vínculo de grupos.",
"x-group": "Comunidades"
},
{
"name": "Newsletters",
"description": "Canais (newsletters): criar, seguir, ler e reagir a posts. Para publicar, use qualquer `send-*` com `phone: @newsletter`.",
"x-group": "Canais"
},
{
"name": "Privacy",
"description": "Configurações de privacidade da conta.",
"x-group": "Privacidade"
},
{
"name": "Business",
"description": "Perfil comercial, catálogo de produtos, pedidos e envio de produto/catálogo/pedido. Best effort: depende do protocolo do WhatsApp Web.",
"x-group": "Business e catálogo"
},
{
"name": "Labels",
"description": "Etiquetas (labels) de conversas — só em contas WhatsApp Business.",
"x-group": "Etiquetas"
},
{
"name": "Partner",
"description": "Para integradores: criar e administrar instâncias do próprio workspace Partner com o header `Partner-Token` (base `/partner`, sem `instance_id`/`token` na URL). As instâncias criadas aqui são operadas pela API pública normal e não têm trial nem `402`.",
"x-group": "Partner"
},
{
"name": "Webhooks",
"description": "Eventos entregues por `POST` na URL configurada em cada instância.",
"x-group": "Webhooks"
}
],
"servers": [
{
"url": "https://api.wabox.me"
}
],
"components": {
"securitySchemes": {
"ClientToken": {
"type": "apiKey",
"in": "header",
"name": "Client-Token",
"description": "Segundo fator opcional (workspace › Segurança). Quando ativado, obrigatório em todas as instâncias do workspace."
},
"PartnerToken": {
"type": "apiKey",
"in": "header",
"name": "Partner-Token",
"description": "Credencial da Partner API (workspace › Segurança › Partner API). Só nas rotas `/partner/*`."
}
},
"schemas": {}
},
"webhooks": {
"received": {
"post": {
"operationId": "webhook.received",
"tags": [
"Webhooks"
],
"summary": "Mensagem recebida",
"description": "Disparado para cada mensagem que chega ao número conectado (e para as enviadas pelo próprio celular ou pela API quando `notify_sent_by_me` está ligado — nesse caso `from_me: true`; `from_api` diz se saiu pela API). O conteúdo vem em **um** bloco opcional conforme o tipo: `text`, `image`, `audio`, `video`, `document`, `sticker`, `location`, `contact`/`contacts`, `reaction`, `poll`, `poll_vote`, `buttons_response`, `list_response`, `buttons`, `list`, `event`, `event_response`, `newsletter_invite`, `product`, `order` — ou `notification` para eventos de chat (grupo alterado, mensagem apagada, chamada perdida…). URLs de mídia são assinadas e expiram: copie o arquivo para o seu storage. `waiting_message: true` é um placeholder enquanto a mensagem real ainda está sendo decifrada.\n\nHeaders de toda entrega: `Content-Type: application/json`, `User-Agent: Wabox-Webhook/1.0`, `X-Wabox-Event: `, `X-Wabox-Event-Id: `, `X-Wabox-Instance-Id: ` e `X-Wabox-Signature: t=,v1=` (HMAC-SHA256 do corpo cru com o `secret` da instância). Responda 2xx em até 10 s; caso contrário o Wabox tenta de novo em 10 s, 1 min, 10 min, 1 h e 6 h. Entregas são ordenadas por instância e podem repetir (`event_id` é a chave de idempotência).",
"parameters": [
{
"name": "X-Wabox-Event",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"received"
]
},
"description": "Tipo do evento."
},
{
"name": "X-Wabox-Event-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Id único do evento (ULID). Use para deduplicar."
},
{
"name": "X-Wabox-Instance-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Instância que gerou o evento."
},
{
"name": "X-Wabox-Signature",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "`t=,v1=` — `v1 = HMAC-SHA256(secret, \".\")`. Ausente quando a instância não tem segredo."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"received"
]
},
"event_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"instance_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"momment": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"message_id": {
"type": "string",
"minLength": 1
},
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"chat_lid": {
"type": "string"
},
"sender_lid": {
"type": "string"
},
"from_me": {
"type": "boolean"
},
"from_api": {
"type": "boolean"
},
"is_group": {
"type": "boolean"
},
"is_newsletter": {
"type": "boolean"
},
"is_edit": {
"type": "boolean"
},
"forwarded": {
"type": "boolean"
},
"broadcast": {
"type": "boolean"
},
"waiting_message": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"SENT",
"RECEIVED",
"READ",
"READ_BY_ME",
"PLAYED"
]
},
"chat_name": {
"type": "string"
},
"sender_name": {
"type": "string"
},
"sender_photo": {
"type": "string"
},
"participant_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"participant_lid": {
"type": "string"
},
"reference_message_id": {
"type": "string",
"minLength": 1
},
"message_expiration_seconds": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"expires_at": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"text": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"url": {
"type": "string"
},
"thumbnail_url": {
"type": "string"
}
},
"required": [
"message"
]
},
"image": {
"type": "object",
"properties": {
"mime_type": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"download_error": {
"type": "string"
},
"view_once": {
"type": "boolean"
},
"file_size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string"
},
"caption": {
"type": "string"
},
"thumbnail_url": {
"type": "string"
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"mime_type"
]
},
"audio": {
"type": "object",
"properties": {
"mime_type": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"download_error": {
"type": "string"
},
"view_once": {
"type": "boolean"
},
"file_size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string"
},
"ptt": {
"type": "boolean"
},
"seconds": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"mime_type",
"ptt"
]
},
"video": {
"type": "object",
"properties": {
"mime_type": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"download_error": {
"type": "string"
},
"view_once": {
"type": "boolean"
},
"file_size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string"
},
"caption": {
"type": "string"
},
"thumbnail_url": {
"type": "string"
},
"seconds": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"is_gif": {
"type": "boolean"
}
},
"required": [
"mime_type"
]
},
"document": {
"type": "object",
"properties": {
"mime_type": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"download_error": {
"type": "string"
},
"view_once": {
"type": "boolean"
},
"file_size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string"
},
"file_name": {
"type": "string"
},
"title": {
"type": "string"
},
"caption": {
"type": "string"
},
"page_count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"mime_type"
]
},
"sticker": {
"type": "object",
"properties": {
"mime_type": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"download_error": {
"type": "string"
},
"view_once": {
"type": "boolean"
},
"file_size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sha256": {
"type": "string"
},
"animated": {
"type": "boolean"
}
},
"required": [
"mime_type"
]
},
"location": {
"type": "object",
"properties": {
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"latitude",
"longitude"
]
},
"contact": {
"type": "object",
"properties": {
"display_name": {
"type": "string"
},
"vcard": {
"type": "string"
},
"phones": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"display_name",
"vcard",
"phones"
]
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"display_name": {
"type": "string"
},
"vcard": {
"type": "string"
},
"phones": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"display_name",
"vcard",
"phones"
]
}
},
"reaction": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"time": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"reaction_by": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"referenced_message": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"minLength": 1
},
"from_me": {
"type": "boolean"
},
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"participant": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"required": [
"message_id",
"from_me",
"phone"
]
}
},
"required": [
"value",
"time",
"reaction_by",
"referenced_message"
]
},
"poll": {
"type": "object",
"properties": {
"question": {
"type": "string"
},
"poll_max_options": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
}
}
},
"required": [
"question",
"poll_max_options",
"options"
]
},
"poll_vote": {
"type": "object",
"properties": {
"poll_message_id": {
"type": "string",
"minLength": 1
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
}
}
},
"required": [
"poll_message_id",
"options"
]
},
"buttons_response": {
"type": "object",
"properties": {
"button_id": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"button_id",
"message"
]
},
"list_response": {
"type": "object",
"properties": {
"selected_row_id": {
"type": "string"
},
"title": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"selected_row_id"
]
},
"buttons": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"title": {
"type": "string"
},
"footer": {
"type": "string"
},
"buttons": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"reply",
"url",
"call",
"copy",
"other"
]
},
"url": {
"type": "string"
},
"phone": {
"type": "string"
}
},
"required": [
"label",
"type"
]
}
}
},
"required": [
"message",
"buttons"
]
},
"list": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"title": {
"type": "string"
},
"footer": {
"type": "string"
},
"button_label": {
"type": "string"
},
"sections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title"
]
}
}
},
"required": [
"rows"
]
}
}
},
"required": [
"message",
"sections"
]
},
"event": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"start_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"end_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"location": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
}
}
},
"join_link": {
"type": "string"
},
"canceled": {
"type": "boolean"
},
"extra_guests_allowed": {
"type": "boolean"
}
},
"required": [
"name",
"start_at",
"canceled"
]
},
"event_response": {
"type": "object",
"properties": {
"event_message_id": {
"type": "string",
"minLength": 1
},
"response": {
"type": "string",
"enum": [
"going",
"not_going",
"maybe",
"unknown"
]
},
"extra_guests": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"event_message_id",
"response"
]
},
"newsletter_invite": {
"type": "object",
"properties": {
"newsletter_id": {
"type": "string"
},
"name": {
"type": "string"
},
"caption": {
"type": "string"
}
},
"required": [
"newsletter_id"
]
},
"product": {
"type": "object",
"properties": {
"product_id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"currency": {
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
},
"sale_price": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
},
"retailer_id": {
"type": "string"
},
"url": {
"type": "string"
},
"business_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"image_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"body": {
"type": "string"
},
"footer": {
"type": "string"
}
},
"required": [
"product_id",
"title"
]
},
"order": {
"type": "object",
"properties": {
"order_id": {
"type": "string"
},
"token": {
"type": "string"
},
"item_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"status": {
"type": "string",
"enum": [
"inquiry",
"accepted",
"declined",
"unknown"
]
},
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"seller_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"total": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
},
"currency": {
"type": "string"
},
"order_request_message_id": {
"type": "string",
"minLength": 1
}
},
"required": [
"order_id",
"item_count",
"status"
]
},
"notification": {
"type": "string",
"enum": [
"REVOKE",
"GROUP_CREATE",
"GROUP_CHANGE_SUBJECT",
"GROUP_CHANGE_DESCRIPTION",
"GROUP_CHANGE_ICON",
"GROUP_PARTICIPANT_ADD",
"GROUP_PARTICIPANT_REMOVE",
"GROUP_PARTICIPANT_PROMOTE",
"GROUP_PARTICIPANT_DEMOTE",
"GROUP_PARTICIPANT_LEAVE",
"GROUP_PARTICIPANT_INVITE",
"MEMBERSHIP_APPROVAL_REQUEST",
"CALL_RECEIVED",
"CALL_MISSED",
"CALL_MISSED_VOICE",
"CALL_MISSED_VIDEO",
"E2E_ENCRYPTED",
"CIPHERTEXT",
"PROFILE_NAME_UPDATED",
"PROFILE_PICTURE_UPDATED"
]
},
"notification_parameters": {
"type": "array",
"items": {
"type": "string"
}
},
"unsupported": {
"type": "object",
"properties": {
"wa_type": {
"type": "string"
}
},
"required": [
"wa_type"
]
}
},
"required": [
"type",
"event_id",
"instance_id",
"momment",
"message_id",
"phone",
"from_me",
"from_api",
"is_group",
"is_newsletter",
"is_edit",
"forwarded",
"broadcast",
"waiting_message",
"status"
]
},
"example": {
"type": "received",
"event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X",
"instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"momment": 1786968300000,
"message_id": "3EB0A9C6D2F1E4B5A7C8",
"phone": "5511988887777",
"chat_lid": "98765432109876@lid",
"sender_lid": "98765432109876@lid",
"from_me": false,
"from_api": false,
"is_group": false,
"is_newsletter": false,
"is_edit": false,
"forwarded": false,
"broadcast": false,
"waiting_message": false,
"status": "RECEIVED",
"chat_name": "Maria",
"sender_name": "Maria",
"text": {
"message": "Olá! Tudo bem?"
}
}
}
}
},
"responses": {
"2XX": {
"description": "Qualquer 2xx confirma o recebimento. Outros códigos (ou timeout de 10 s) agendam nova tentativa."
}
}
}
},
"delivery": {
"post": {
"operationId": "webhook.delivery",
"tags": [
"Webhooks"
],
"summary": "Resultado de um envio",
"description": "Fecha o ciclo de cada `POST /send-*`: `wabox_id` é o id devolvido pelo endpoint e `message_id` o id do WhatsApp (o mesmo da resposta). Quando o envio falha, `error_code` traz o motivo (`phone_not_on_whatsapp`, `media_invalid`, `message_not_found`, `send_timeout`…) e `message_id` pode vir ausente.\n\nHeaders de toda entrega: `Content-Type: application/json`, `User-Agent: Wabox-Webhook/1.0`, `X-Wabox-Event: `, `X-Wabox-Event-Id: `, `X-Wabox-Instance-Id: ` e `X-Wabox-Signature: t=,v1=` (HMAC-SHA256 do corpo cru com o `secret` da instância). Responda 2xx em até 10 s; caso contrário o Wabox tenta de novo em 10 s, 1 min, 10 min, 1 h e 6 h. Entregas são ordenadas por instância e podem repetir (`event_id` é a chave de idempotência).",
"parameters": [
{
"name": "X-Wabox-Event",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"delivery"
]
},
"description": "Tipo do evento."
},
{
"name": "X-Wabox-Event-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Id único do evento (ULID). Use para deduplicar."
},
{
"name": "X-Wabox-Instance-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Instância que gerou o evento."
},
{
"name": "X-Wabox-Signature",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "`t=,v1=` — `v1 = HMAC-SHA256(secret, \".\")`. Ausente quando a instância não tem segredo."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"delivery"
]
},
"event_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"instance_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"momment": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"wabox_id": {
"type": "string"
},
"message_id": {
"type": "string",
"minLength": 1
},
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string",
"enum": [
"instance_not_found",
"instance_not_connected",
"instance_already_connected",
"instance_starting",
"invalid_phone",
"phone_not_on_whatsapp",
"invalid_request",
"send_failed",
"send_timeout",
"not_allowed",
"shadow_ban",
"group_suspended",
"media_download_failed",
"media_invalid",
"message_not_found",
"group_not_found",
"chat_not_found",
"invite_link_invalid",
"newsletter_not_found",
"product_not_found",
"label_not_found",
"order_not_found",
"action_failed",
"engine_unavailable",
"internal"
]
}
},
"required": [
"type",
"event_id",
"instance_id",
"momment",
"wabox_id",
"phone"
]
},
"example": {
"type": "delivery",
"event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X",
"instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"momment": 1786968420000,
"wabox_id": "wbx_01J5Q8ZK3M4N5P6Q7R8S9T0M01",
"message_id": "3EB0A9C6D2F1E4B5A7D0",
"phone": "5511988887777"
}
}
}
},
"responses": {
"2XX": {
"description": "Qualquer 2xx confirma o recebimento. Outros códigos (ou timeout de 10 s) agendam nova tentativa."
}
}
}
},
"message_status": {
"post": {
"operationId": "webhook.message_status",
"tags": [
"Webhooks"
],
"summary": "Recibo de mensagem (entregue / lida / reproduzida)",
"description": "Ticks das mensagens que **você** enviou: `SENT` (um tick), `RECEIVED` (dois), `READ` (azul), `PLAYED` (áudio ouvido). Pode agrupar vários `ids` do mesmo chat. Em grupos, `participant_phone` indica quem produziu o recibo.\n\nHeaders de toda entrega: `Content-Type: application/json`, `User-Agent: Wabox-Webhook/1.0`, `X-Wabox-Event: `, `X-Wabox-Event-Id: `, `X-Wabox-Instance-Id: ` e `X-Wabox-Signature: t=,v1=` (HMAC-SHA256 do corpo cru com o `secret` da instância). Responda 2xx em até 10 s; caso contrário o Wabox tenta de novo em 10 s, 1 min, 10 min, 1 h e 6 h. Entregas são ordenadas por instância e podem repetir (`event_id` é a chave de idempotência).",
"parameters": [
{
"name": "X-Wabox-Event",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"message_status"
]
},
"description": "Tipo do evento."
},
{
"name": "X-Wabox-Event-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Id único do evento (ULID). Use para deduplicar."
},
{
"name": "X-Wabox-Instance-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Instância que gerou o evento."
},
{
"name": "X-Wabox-Signature",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "`t=,v1=` — `v1 = HMAC-SHA256(secret, \".\")`. Ausente quando a instância não tem segredo."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"message_status"
]
},
"event_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"instance_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"momment": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"ids": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"SENT",
"RECEIVED",
"READ",
"READ_BY_ME",
"PLAYED"
]
},
"is_group": {
"type": "boolean"
},
"participant_phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"phone_device": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"type",
"event_id",
"instance_id",
"momment",
"ids",
"phone",
"status",
"is_group",
"phone_device"
]
},
"example": {
"type": "message_status",
"event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1Y",
"instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"momment": 1786968480000,
"ids": [
"3EB0A9C6D2F1E4B5A7D0"
],
"phone": "5511988887777",
"status": "READ",
"is_group": false,
"phone_device": 0
}
}
}
},
"responses": {
"2XX": {
"description": "Qualquer 2xx confirma o recebimento. Outros códigos (ou timeout de 10 s) agendam nova tentativa."
}
}
}
},
"connected": {
"post": {
"operationId": "webhook.connected",
"tags": [
"Webhooks"
],
"summary": "Instância conectada",
"description": "O número leu o QR code / código de pareamento ou reconectou. `phone` é o número conectado.\n\nHeaders de toda entrega: `Content-Type: application/json`, `User-Agent: Wabox-Webhook/1.0`, `X-Wabox-Event: `, `X-Wabox-Event-Id: `, `X-Wabox-Instance-Id: ` e `X-Wabox-Signature: t=,v1=` (HMAC-SHA256 do corpo cru com o `secret` da instância). Responda 2xx em até 10 s; caso contrário o Wabox tenta de novo em 10 s, 1 min, 10 min, 1 h e 6 h. Entregas são ordenadas por instância e podem repetir (`event_id` é a chave de idempotência).",
"parameters": [
{
"name": "X-Wabox-Event",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"connected"
]
},
"description": "Tipo do evento."
},
{
"name": "X-Wabox-Event-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Id único do evento (ULID). Use para deduplicar."
},
{
"name": "X-Wabox-Instance-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Instância que gerou o evento."
},
{
"name": "X-Wabox-Signature",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "`t=,v1=` — `v1 = HMAC-SHA256(secret, \".\")`. Ausente quando a instância não tem segredo."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"connected"
]
},
"event_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"instance_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"momment": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"connected": {
"type": "boolean",
"enum": [
true
]
},
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
}
},
"required": [
"type",
"event_id",
"instance_id",
"momment",
"connected",
"phone"
]
},
"example": {
"type": "connected",
"event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1W",
"instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"momment": 1786968030000,
"connected": true,
"phone": "5511999998888"
}
}
}
},
"responses": {
"2XX": {
"description": "Qualquer 2xx confirma o recebimento. Outros códigos (ou timeout de 10 s) agendam nova tentativa."
}
}
}
},
"disconnected": {
"post": {
"operationId": "webhook.disconnected",
"tags": [
"Webhooks"
],
"summary": "Instância desconectada",
"description": "`reason` diz o que aconteceu: `network` e `stream_replaced` são temporários (o engine reconecta sozinho); `logged_out` (dispositivo removido no celular) e `banned` exigem novo QR code; `stopped` é uma parada pela API/assinatura.\n\nHeaders de toda entrega: `Content-Type: application/json`, `User-Agent: Wabox-Webhook/1.0`, `X-Wabox-Event: `, `X-Wabox-Event-Id: `, `X-Wabox-Instance-Id: ` e `X-Wabox-Signature: t=,v1=` (HMAC-SHA256 do corpo cru com o `secret` da instância). Responda 2xx em até 10 s; caso contrário o Wabox tenta de novo em 10 s, 1 min, 10 min, 1 h e 6 h. Entregas são ordenadas por instância e podem repetir (`event_id` é a chave de idempotência).",
"parameters": [
{
"name": "X-Wabox-Event",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"disconnected"
]
},
"description": "Tipo do evento."
},
{
"name": "X-Wabox-Event-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Id único do evento (ULID). Use para deduplicar."
},
{
"name": "X-Wabox-Instance-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Instância que gerou o evento."
},
{
"name": "X-Wabox-Signature",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "`t=,v1=` — `v1 = HMAC-SHA256(secret, \".\")`. Ausente quando a instância não tem segredo."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"disconnected"
]
},
"event_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"instance_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"momment": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"disconnected": {
"type": "boolean",
"enum": [
true
]
},
"reason": {
"type": "string",
"enum": [
"network",
"stream_replaced",
"logged_out",
"banned",
"stopped",
"engine_shutdown",
"unknown"
]
},
"error": {
"type": "string"
}
},
"required": [
"type",
"event_id",
"instance_id",
"momment",
"disconnected",
"reason",
"error"
]
},
"example": {
"type": "disconnected",
"event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X",
"instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"momment": 1786971600000,
"disconnected": true,
"reason": "logged_out",
"error": "Device has been disconnected"
}
}
}
},
"responses": {
"2XX": {
"description": "Qualquer 2xx confirma o recebimento. Outros códigos (ou timeout de 10 s) agendam nova tentativa."
}
}
}
},
"chat_presence": {
"post": {
"operationId": "webhook.chat_presence",
"tags": [
"Webhooks"
],
"summary": "Presença no chat (digitando / gravando / online)",
"description": "`COMPOSING`, `RECORDING`, `PAUSED`, `AVAILABLE`, `UNAVAILABLE`. `last_seen` só quando o contato compartilha o \"visto por último\".\n\nHeaders de toda entrega: `Content-Type: application/json`, `User-Agent: Wabox-Webhook/1.0`, `X-Wabox-Event: `, `X-Wabox-Event-Id: `, `X-Wabox-Instance-Id: ` e `X-Wabox-Signature: t=,v1=` (HMAC-SHA256 do corpo cru com o `secret` da instância). Responda 2xx em até 10 s; caso contrário o Wabox tenta de novo em 10 s, 1 min, 10 min, 1 h e 6 h. Entregas são ordenadas por instância e podem repetir (`event_id` é a chave de idempotência).",
"parameters": [
{
"name": "X-Wabox-Event",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"chat_presence"
]
},
"description": "Tipo do evento."
},
{
"name": "X-Wabox-Event-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Id único do evento (ULID). Use para deduplicar."
},
{
"name": "X-Wabox-Instance-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Instância que gerou o evento."
},
{
"name": "X-Wabox-Signature",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "`t=,v1=` — `v1 = HMAC-SHA256(secret, \".\")`. Ausente quando a instância não tem segredo."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"chat_presence"
]
},
"event_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"instance_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"momment": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"phone": {
"type": "string",
"minLength": 1,
"pattern": "^(\\d{5,20}|\\d+@lid|\\d+(-\\d+)?-group|\\d+@g\\.us|\\d+@newsletter|\\d+@broadcast|status@broadcast)$"
},
"status": {
"type": "string",
"enum": [
"AVAILABLE",
"UNAVAILABLE",
"COMPOSING",
"PAUSED",
"RECORDING"
]
},
"last_seen": {
"nullable": true,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"type",
"event_id",
"instance_id",
"momment",
"phone",
"status",
"last_seen"
]
},
"example": {
"type": "chat_presence",
"event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1Y",
"instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
"momment": 1786968540000,
"phone": "5511988887777",
"status": "COMPOSING",
"last_seen": null
}
}
}
},
"responses": {
"2XX": {
"description": "Qualquer 2xx confirma o recebimento. Outros códigos (ou timeout de 10 s) agendam nova tentativa."
}
}
}
}
}
}