Referência da API
Gerada da especificação OpenAPI da API. Os exemplos usam $API_URL e $API_KEY: veja o guia Começar.
Versão 2.0 · A mesma especificação, em OpenAPI 3.1, é servida aberta pela sua API em $API_URL/openapi.json.
As descrições das rotas vêm da especificação da API.
Autenticação
- chave de API (wck_...)
- A chave de API (wck_...) que você cria no painel, em API. Ela abre só as áreas (números, Marketing e Fluxos) e os números que você escolher; não abre CRM, IA nem a caixa de entrada.
- chave do número
- A chave de um número: abre só as rotas daquele número (/api/v1/instances/{id}/...).
- chave do cluster
- A chave de um cluster: abre só as rotas daquele cluster (/api/v1/clusters/{cid}/...).
- chave da plataforma
- A chave da plataforma: é a que o painel usa por dentro e não é entregue ao cliente. As rotas que só ela abre vêm marcadas, e o filtro acima as esconde.
224 rotas
Números
Números de WhatsApp: criar, conectar por QR code, estado, chave própria, pausa e limites de contato frio.
get/api/v1/instancesLista as instânciasChave de API
Todas as instâncias ativas da sua API, da mais recente para a mais antiga (por created_at). Cada item traz a api_key da instância (mascarada com chave de cliente, que só vê os números dela). Um número removido não aparece aqui. Com removed=only, lista só os números removidos (RemovedInstance, o removido mais recente primeiro), cujo histórico continua na caixa de entrada; só com a chave global (chave de cliente: 403 CLIENT_KEY_SCOPE).
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
removedopcional | query | "only" | only lista só os números removidos (só a chave global). |
Respostas
200Lista de instâncias (ou de números removidos, comremoved=only).json[ { "api_key": "inst_k3y_exemplo", "created_at": "2026-01-10T12:00:00Z", "id": "3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c01", "name": "Atendimento", "phone": "5511999990000", "reachout_locked_until": "0001-01-01T00:00:00Z", "status": "online", "updated_at": "2026-01-10T12:05:00Z" } ]401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403removed=onlycom chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }503removed=only: não foi possível ler os números removidos; tente de novo.json{ "error": "removed numbers unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/instances" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instancesCria uma instânciaSó a chave da plataforma
Cria a instância com status connecting, gera a api_key dela e já inicia a sessão do WhatsApp (o QR fica disponível em GET /api/v1/instances/{id}/qr). Sujeito ao limite do plano max_instances (403 plan_limit). Um número removido não conta no limite. Com o armazenamento da API no teto (max_storage_mb) também 403 plan_limit; se o armazenamento não pode ser medido, 503 usage_unavailable. O número só existe depois que o banco o grava: se o banco recusa, 500 INSTANCE_NOT_STORED e nada é criado.
Com provider: cloud, o número oficial: a API confere o token e o número na Graph API da Meta (v27.0), registra o número com o pin (quando vem), assina os webhooks da WABA e guarda o token cifrado. O número nasce com o status da Meta (online quando CONNECTED, senão restricted), nunca awaiting_qr. Precisa do plano com cloud_numbers_enabled, conta em max_instances e só existe numa instalação que oferece cloud. Ele envia por /send, /send-media e /send-reply (pela Graph API, dentro da janela de 24 h) e recebe pelo webhook da Meta (/webhooks/meta), com o mesmo evento message de hoje.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
access_tokenopcional | string | provider: cloud: o token do usuário de sistema. Fica cifrado e nunca volta. |
nameobrigatório | string | |
phone_number_idopcional | string | provider: cloud: o id do número na API oficial da Meta. |
pinopcional | string | provider: cloud, opcional: o PIN de 6 dígitos para registrar o número na Meta. Sem ele, o número não é registrado de novo (já registrado). |
provideropcional | "whatsmeow" | "cloud" | O tipo do número; o padrão é whatsmeow. Só os tipos que a instalação oferece (GET /api/v1/settings/providers). |
waba_idopcional | string | provider: cloud: o id da conta do WhatsApp Business. |
{
"name": "Atendimento"
}Respostas
201Instância criada. Um número oficial pode vir comwarnings, o que falta na instalação para ele funcionar, sem impedir o cadastro:meta_webhook_unconfigured: …quando faltam a configuração do servidor ou a configuração do servidor (o/webhooks/metadá 503, e o número não recebe mensagens nem abre a janela de 24 h até elas existirem).json{ "api_key": "inst_k3y_exemplo", "created_at": "2026-01-10T12:00:00Z", "id": "3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c01", "name": "Atendimento", "phone": "5511999990000", "reachout_locked_until": "0001-01-01T00:00:00Z", "status": "online", "updated_at": "2026-01-10T12:05:00Z", "warnings": [ "string" ] }400nameausente ou corpo inválido;invalid_provider(tipo desconhecido);invalid_cloud_number(um campo do número oficial inválido).json{ "error": "name required" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Sem vaga emmax_instancesou armazenamento no teto (max_storage_mb) (plan_limit), ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED). Um número oficial semcloud_numbers_enabledno plano:plan_feature_disabled.json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }409provider_disabled: a instalação não oferece esse tipo.cloud_register_limited: a Meta bloqueou novos registros do número por 72 h (erro 133016).cloud_number_exists: ophone_number_idjá é um número ativo aqui.json{ "code": "cloud_register_limited", "error": "Meta blocked new registrations of this number for 72 hours (more than 10 in 72 hours)" }422A Meta recusou:cloud_auth_invalid(token inválido, expirado ou revogado; erro 190),cloud_number_invalid(o número ou a WABA não existe, ou o token não tem permissão),cloud_request_refused(outra recusa: o código do erro da Meta e um texto nosso; a mensagem da Meta vai só ao log).json{ "code": "cloud_auth_invalid", "error": "the access token was refused by Meta (invalid, expired or revoked)" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança do número (INSTANCE_NOT_STORED; nada mudou), ou falhou a preparação da sessão local do WhatsApp (semcode).json{ "code": "INSTANCE_NOT_STORED", "error": "could not store the change; nothing changed" }502A Graph API da Meta não respondeu ou falhou (cloud_unavailable); nada foi criado.json{ "code": "cloud_unavailable", "error": "the Meta Graph API did not answer; try again" }503Não foi possível ler o uso do plano (usage_unavailable); tente de novo. Um número oficial sem a chave de cifra do servidor (secrets_key_missing).json{ "code": "usage_unavailable", "error": "Could not check the plan usage. Try again later." }
Exemplo
curl -X POST "$API_URL/api/v1/instances" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Atendimento"}'get/api/v1/instances/healthSaúde de todos os númerosChave de API
Resumo da saúde de cada número que a chave vê (a chave de cliente vê só os números dela), ordenado por instanceId. Não é o GET /api/v1/health, que é o health check aberto. As regras estão na operação instanceGetHealth.
Chave: chave da plataforma, chave de API (wck_...)
Respostas
200Resumo por número.json{ "instances": [ { "instanceId": "string", "level": "good", "reasons": [ "string" ], "suggestedDailyLimit": 0 } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Não foi possível calcular a saúde (HEALTH_UNAVAILABLE); tente de novo.json{ "code": "HEALTH_UNAVAILABLE", "error": "health not available" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/health" \
-H "Authorization: Bearer $API_KEY"delete/api/v1/instances/{id}Remove um número (o histórico fica)Chave do número ou do cluster
Tira o número da conta sem apagar o histórico. Faz logout do WhatsApp, apaga o armazenamento local do dispositivo, tira o número da memória e de GET /instances, anula a api_key dele (a chave passa a dar 401), apaga webhooks, Chatwoot e a participação em clusters e aquecimentos, tira o número das chaves de cliente (uma lista que fica vazia continua vazia) e zera as não lidas. Mensagens, conversas e notas ficam: a caixa de entrada continua lendo, com instance_removed: true, e as mensagens do mês continuam contando no uso. O número removido deixa de contar em max_instances, não volta ao reiniciar e /instances/{id}/* passa a dar 410 INSTANCE_REMOVED. É idempotente com a chave global: repetir devolve o mesmo removed_at (a chave do número já não vale, então repetir com ela dá 401). Para apagar o histórico de vez, DELETE /api/v1/instances/{id}/history. Conectar o mesmo telefone de novo cria um número novo, com histórico separado.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Número removido (ou já removido antes).json{ "removed_at": "2026-10-31T12:00:00Z", "status": "removed" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança do número; nada mudou, nem na memória nem depois de reiniciar (INSTANCE_NOT_STORED).json{ "code": "INSTANCE_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X DELETE "$API_URL/api/v1/instances/<id>" \
-H "Authorization: Bearer $API_KEY"put/api/v1/instances/{id}/cloud/credentialsTroca o token de acesso do número oficialChave de API
Um token novo de usuário de sistema para um número oficial. A API confere na Graph API que ele abre a conta (WABA) e o phone_number_id do número, grava-o cifrado (como no cadastro) e relê o status. A resposta é a instância, com o token só pelos 4 últimos caracteres (cloud.token_last4); o token nunca volta numa resposta nem num log. Um token recusado não muda nada. Num número por QR: 409 provider_unsupported.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
access_tokenobrigatório | string | O token de usuário de sistema da Meta (de 20 a 1000 caracteres, sem espaços). |
{
"access_token": "string"
}Respostas
200O token foi trocado.json{ "api_key": "inst_k3y_exemplo", "created_at": "2026-01-10T12:00:00Z", "id": "3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c01", "name": "Atendimento", "phone": "5511999990000", "reachout_locked_until": "0001-01-01T00:00:00Z", "status": "online", "updated_at": "2026-01-10T12:05:00Z" }400Token ausente ou fora do formato (invalid_cloud_number).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Uma chave de cliente sem este número (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }422A Meta recusou o token (cloud_auth_invalid) ou ele não abre este número ou esta conta (cloud_number_invalid).json{ "error": "invalid request" }502A Graph API não respondeu (cloud_unavailable).json{ "error": "invalid request" }503sem a chave de cifra do servidor (secrets_key_missing).json{ "error": "invalid request" }
Exemplo
curl -X PUT "$API_URL/api/v1/instances/<id>/cloud/credentials" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"access_token":"string"}'get/api/v1/instances/{id}/cluster-audit-logsTrilha de auditoria de cluster da instânciaChave do número ou do cluster
Eventos de auditoria dos clusters envolvendo esta instância, do mais novo para o mais antigo. URLs de webhook no payload (webhook_url, error_notification_url) vêm mascaradas (scheme://host), inclusive em linhas antigas. Sem banco, responde {"audit_logs": [], "total": 0}.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
limitopcional | query | integer | Página (padrão 50; inválido ou <= 0 vira 50). |
offsetopcional | query | integer | Deslocamento (padrão 0). |
event_typeopcional | query | string | Tipo de evento exato. |
searchopcional | query | string | Busca (sem diferenciar maiúsculas) no tipo e no payload. |
Respostas
200Página da trilha.json{ "audit_logs": [ { "cluster_id": "string", "created_at": "2026-01-01T12:00:00Z", "event_type": "string", "id": "string", "instance_id": "string", "instance_name": "string", "instance_phone": "string", "payload": null } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/cluster-audit-logs" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/cluster-errorsErros de cluster da instânciaChave do número ou do cluster
Erros registrados pelos clusters envolvendo esta instância, do mais novo para o mais antigo, com o desfecho do job relacionado (job_*) quando existe. Sem banco, responde {"errors": [], "total": 0}.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
limitopcional | query | integer | Página (padrão 50; inválido ou <= 0 vira 50). |
offsetopcional | query | integer | Deslocamento (padrão 0). |
categoryopcional | query | string | Categoria exata. |
severityopcional | query | string | Severidade exata. |
searchopcional | query | string | Busca (sem diferenciar maiúsculas) em tipo, mensagem, categoria e payload. |
Respostas
200Página de erros.json{ "errors": [ { "category": "string", "cluster_id": "string", "created_at": "2026-01-01T12:00:00Z", "event_type": "string", "id": "string", "instance_id": "string", "instance_name": "string", "instance_phone": "string", "job_attempts": [ { "attempted_at": null, "category": null, "consecutive_failures": null, "instance_id": null, "instance_name": null, "instance_phone": null, "is_healthy": null, "last_failure_category": null, "message": null, "throttled_until": null } ], "job_completed_at": "2026-01-01T12:00:00Z", "job_completed_instance_id": "string", "job_completed_instance_name": "string", "job_completed_instance_phone": "string", "job_failed_at": "2026-01-01T12:00:00Z", "job_last_error": "string", "job_last_error_category": "string", "job_outcome": "string", "job_status": "string", "message": "string", "payload": null, "severity": "string" } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/cluster-errors" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/disconnectDesconecta o dispositivo (logout)Chave do número ou do cluster
Faz logout do WhatsApp Web e volta a instância para awaiting_qr, limpando o telefone. Se o logout falha (conta banida ou já desconectada), o armazenamento do dispositivo é limpo à mão para que um novo QR possa ser gerado.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Dispositivo desconectado.json{ "status": "disconnected" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/disconnect" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/healthSaúde do númeroChave de API
Nível (good, attention, critical), motivos, limite diário sugerido, janelas de 24 h e 7 dias e os últimos eventos do número. Calculado com os sinais da API (banimento, logout, falhas, recibos, opt-outs, idade e volume); não existe nota de qualidade da Meta sem a API oficial. Só observa, não freia envio. critical: banimento ativo ou nas últimas 72 h, número deslogado, falha > 20 % ou entrega < 60 % em 24 h (50+ envios). attention: banimento em 7 dias, sessão substituída em 24 h, falha > 5 %, entrega < 85 %, opt-out > 2 % ou bloqueios > 0,5 % (HIGH_BLOCK_RATE) (20+ envios), volume acima do limite, número com menos de 7 dias. Limite sugerido: 50 para número com menos de 7 dias ou sem envios em 7 dias; senão 50, dobrando a cada 7 dias completos desde a criação ou o último banimento/logout, até 1.000. Qualquer motivo de atenção de risco (todos menos NEW_NUMBER e VOLUME_ABOVE_LIMIT) corta o limite pela metade, e VOLUME_ABOVE_LIMIT compara os envios de 24 h com esse limite já cortado; 0 em critical. Um número oficial é medido pela régua da Meta, sem a régua de 50 a 1.000, sem VOLUME_ABOVE_LIMIT e sem NEW_NUMBER: as mesmas taxas de falha, entrega e opt-out, mais QUALITY_RED (critical), QUALITY_FLAGGED (attention), AUTH_INVALID (critical: a Meta recusou o token) e TOKEN_EXPIRING (attention: vence em menos de 7 dias); o limite sugerido é o da Meta, e a resposta traz quality e messagingLimit.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Saúde do número.json{ "computedAt": "2026-01-01T12:00:00Z", "events": [ { "at": "2026-01-01T12:00:00Z", "detail": "string", "type": "temp_ban" } ], "instanceId": "string", "level": "good", "messagingLimit": "string", "quality": "string", "reasons": [ { "code": "TEMP_BAN", "detail": "string", "since": "2026-01-01T12:00:00Z" } ], "suggestedDailyLimit": 0, "window": { "blocks": 0, "delivered": 0, "failed": 0, "hours": 24, "optOuts": 0, "read": 0, "sent": 0 }, "window7d": { "blocks": 0, "delivered": 0, "failed": 0, "hours": 24, "optOuts": 0, "read": 0, "sent": 0 } }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Não foi possível calcular a saúde (HEALTH_UNAVAILABLE); tente de novo.json{ "code": "HEALTH_UNAVAILABLE", "error": "health not available" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/health" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/health-historyHistórico de saúde da instânciaChave do número ou do cluster
Últimos retratos de saúde da instância, em ordem cronológica (o mais antigo primeiro, bom para sparklines). Sem banco, responde {"history": [], "total": 0}.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
limitopcional | query | integer | Quantos retratos (padrão 200; máximo 1000, acima disso vira 1000). |
Respostas
200Histórico.json{ "history": [ { "consecutive_failures": 0, "id": "string", "instance_id": "string", "last_failure_category": "string", "recorded_at": "2026-01-01T12:00:00Z", "status": "string", "throttled_until": "2026-01-01T12:00:00Z" } ], "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/health-history" \
-H "Authorization: Bearer $API_KEY"delete/api/v1/instances/{id}/historyApaga o histórico de um número removidoSó a chave da plataforma
Só a chave global. Apaga de vez o número removido e, com ele, as mensagens, conversas, notas e a saúde dele (LGPD). Não dá para desfazer. Antes de apagar, guarda as mensagens do mês desse número, enviadas e recebidas, sem as de aquecimento: o uso do mês e o limite de mensagens do plano não baixam. Ficam, porque são da conta: os contatos do Marketing, destinatários e recibos de campanha e execuções de fluxo. Um número ativo dá 409 INSTANCE_NOT_REMOVED: remova antes com DELETE /api/v1/instances/{id}.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID do número removido (UUID). |
Respostas
204Histórico apagado.401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }409O número está ativo (INSTANCE_NOT_REMOVED).json{ "code": "INSTANCE_NOT_REMOVED", "error": "number is not removed: remove it first" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O histórico não foi apagado; nada mudou (HISTORY_NOT_DELETED).json{ "error": "invalid request" }
Exemplo
curl -X DELETE "$API_URL/api/v1/instances/<id>/history" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/mcpFluxo do servidor MCP (não suportado)Chave do número ou do cluster
Sem sessão, não há fluxo do servidor para o cliente. Responde 405, como o transporte espera.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
405Método não suportado no modo sem sessão.
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/mcp" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/mcpServidor MCP do número (ferramentas para uma IA de fora)Chave de API
Servidor MCP no transporte Streamable HTTP, sem sessão: cada POST leva uma mensagem JSON-RPC (initialize, tools/list, tools/call…) e a resposta vem em JSON. As ferramentas send_text, send_media, list_chats, get_messages, list_contacts, get_contact, get_number_status, list_templates e send_template (as duas últimas num número oficial: fora da janela de 24 h só um template vai) chamam por dentro as rotas REST deste número com a mesma chave, então valem os mesmos limites do plano, a mesma contagem do mês e o mesmo bloqueio de conta suspensa. Um erro da rota volta como resultado de ferramenta com isError: true e a mensagem da API. A chave do número só abre o MCP dele; a chave global abre o de qualquer número; uma chave de cliente com o escopo numbers abre o dos números da lista dela (fora dela, 403 CLIENT_KEY_SCOPE), e as regras dela valem em cada ferramenta.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
idopcional | string | integer | |
jsonrpcobrigatório | string | |
methodobrigatório | string | |
paramsopcional | object |
{
"id": "string",
"jsonrpc": "string",
"method": "tools/list",
"params": {}
}Respostas
200Resposta JSON-RPC.json{}202Notificação aceita (sem resposta).400Mensagem JSON-RPC inválida.401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Chave de cliente sem o escoponumbersou com o número fora da lista dela (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/mcp" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"string","jsonrpc":"string","method":"tools/list","params":{}}'delete/api/v1/instances/{id}/mcpEncerrar sessão MCP (não suportado)Chave do número ou do cluster
Sem sessão, não há o que encerrar. Responde 405.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
405Método não suportado no modo sem sessão.
Exemplo
curl -X DELETE "$API_URL/api/v1/instances/<id>/mcp" \
-H "Authorization: Bearer $API_KEY"put/api/v1/instances/{id}/pausePausa ou retoma os envios da instânciaChave do número ou do cluster
Com paused: true todo envio pela instância (direto, cluster, Chatwoot etc.) é recusado com 429. paused ausente vale false.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
pausedopcional | boolean |
{
"paused": true
}Respostas
200Atualizado.json{ "paused": false, "status": "string" }400Corpo JSON inválido.json{ "error": "paused required" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ao retomar (paused: falseou ausente); pausar continua liberado.json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança do número; nada mudou, nem na memória nem depois de reiniciar (INSTANCE_NOT_STORED).json{ "code": "INSTANCE_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/instances/<id>/pause" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"paused":true}'get/api/v1/instances/{id}/qrObtém o QR de pareamentoChave do número ou do cluster
Responde sempre 200 com um status:
ready:qr_imagetraz o QR atual (imagem em data URL).paired: o dispositivo já está ligado a uma conta; usereconnectem vez de parear de novo.generating: o QR ainda não existe. Se não há sessão de pareamento rodando (parada por desconexão, expirada ou nunca iniciada), a rota inicia uma; no máximo uma a cada 20 s, para que o polling não derrube a sessão que ainda está conectando. Tente de novo em alguns segundos.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Estado do QR.json{ "message": "QR not ready, try again", "status": "generating" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/qr" \
-H "Authorization: Bearer $API_KEY"put/api/v1/instances/{id}/reachout-cooldownDefine o cooldown após erro de primeiro contatoChave do número ou do cluster
Segundos que a instância fica travada para envios depois que o WhatsApp recusa um contato frio (erro de reachout). 0 desliga. Valor negativo: 400 {"error":"seconds must be >= 0"}.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
secondsopcional | integer |
{
"seconds": 3600
}Respostas
200Atualizado.json{ "reachout_cooldown_seconds": 0, "status": "string" }400Corpo JSON inválido ousecondsnegativo.json{ "error": "seconds required" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Instância inexistente.json{ "error": "not found" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança do número; nada mudou, nem na memória nem depois de reiniciar (INSTANCE_NOT_STORED).json{ "code": "INSTANCE_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/instances/<id>/reachout-cooldown" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"seconds":3600}'post/api/v1/instances/{id}/reconnectReconecta a instânciaChave do número ou do cluster
Derruba a conexão atual e inicia uma nova em segundo plano (status connecting). Não desfaz o pareamento.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Reconexão iniciada.json{ "status": "reconnecting" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/reconnect" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/refreshRecarrega contatos, conversas e mapa de LIDsChave do número ou do cluster
Num número por QR, dispara em segundo plano a recarga dos contatos, das conversas e do mapa LID↔telefone da instância; sem cliente ativo, não faz nada e responde igual (status: refreshing). Num número oficial (provider: cloud), relê agora na Graph API o status, o telefone, a qualidade e o limite, o nome verificado e a validade do token, e responde a instância; um token recusado deixa o número restricted (cloud_auth_invalid), e a Graph API fora do ar dá 502 cloud_unavailable. A qualidade RED ou FLAGGED deixa o número online. No máximo um /refresh por minuto por número oficial (429 refresh_too_soon, com Retry-After); a API também relê cada número oficial uma vez por dia. Se a API não consegue abrir o token guardado (a chave de cifra do servidor ou o banco), é 503 cloud_credentials_unavailable, e o número não muda.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Recarga iniciada.json{ "status": "refreshing" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Um número oficial atualizado há menos de um minuto (refresh_too_soon); tente depois doRetry-After.json{ "error": "invalid request" }502Número oficial com a Graph API sem responder (cloud_unavailable).json{ "error": "invalid request" }503Número oficial cujo token guardado a API não conseguiu abrir (cloud_credentials_unavailable); o número não muda.json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/refresh" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/restoreRestaura um número removido, com o históricoSó a chave da plataforma
Só a chave global. Traz de volta um número removido com o mesmo id: ele volta para a lista desconectado, com uma chave nova (a antiga continua sem valer) e sem sessão, então pede QR de novo (GET /api/v1/instances/{id}/qr). As mensagens, conversas, notas e a saúde dele continuam ligadas ao mesmo id e deixam de ser marcadas instance_removed na Caixa. O que a remoção desfez não volta: webhooks, Chatwoot, participação em clusters e aquecimentos, e o número nas chaves de cliente que o listavam. Ocupa uma vaga de max_instances, como criar (403 plan_limit). Com a conta suspensa ou cancelada, 403 ACCOUNT_SUSPENDED. Um número ativo dá 409 INSTANCE_NOT_REMOVED; um id desconhecido, ou um número cujo histórico já foi apagado, dá 404.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID do número removido (UUID). |
Respostas
200Número restaurado (com a chave nova emapi_key).json{ "api_key": "inst_k3y_exemplo", "created_at": "2026-01-10T12:00:00Z", "id": "3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c01", "name": "Atendimento", "phone": "5511999990000", "reachout_locked_until": "0001-01-01T00:00:00Z", "status": "online", "updated_at": "2026-01-10T12:05:00Z" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Sem vaga emmax_instances(plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "plan_limit", "error": "Plan limit reached: max_instances.", "limit": "max_instances" }404Recurso inexistente.json{ "error": "invalid request" }409O número está ativo (INSTANCE_NOT_REMOVED).json{ "code": "INSTANCE_NOT_REMOVED", "error": "number is not removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança do número (INSTANCE_NOT_STORED; nada mudou), ou falhou a preparação da sessão local do WhatsApp (semcode).json{ "code": "INSTANCE_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/restore" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/rotate-api-keyGera uma nova chave da instânciaChave do número ou do cluster
Substitui a api_key da instância por uma nova; a anterior deixa de valer imediatamente.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Nova chave.json{ "api_key": "string" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não gravou a chave nova (api_key_rotation_failed): a chave atual continua valendo.json{ "code": "api_key_rotation_failed", "error": "could not store the new api key; the current key still works" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/rotate-api-key" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/statsMétricas da instânciaChave de API
Dados da instância mais contagens de mensagens (no banco, sem as do aquecimento), contatos e conversas em memória, e se o Chatwoot está ativo.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Métricas.json{ "api_key": "string", "chat_count": 0, "chatwoot_enabled": false, "contact_count": 0, "created_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "message_count": 0, "name": "string", "paused": false, "phone": "string", "proxy_country": "string", "reachout_cooldown_seconds": 0, "reachout_locked_reason": "string", "reachout_locked_until": "2026-01-01T12:00:00Z", "status": "connecting" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/stats" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/statusConsulta a instânciaChave de API
Devolve a instância (mesmo formato da listagem), incluindo status e a api_key (mascarada com chave de cliente).
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Instância.json{ "api_key": "inst_k3y_exemplo", "created_at": "2026-01-10T12:00:00Z", "id": "3f2b8c1e-9a4d-4e7b-8c21-5d6f7a8b9c01", "name": "Atendimento", "phone": "5511999990000", "reachout_locked_until": "0001-01-01T00:00:00Z", "status": "online", "updated_at": "2026-01-10T12:05:00Z" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/status" \
-H "Authorization: Bearer $API_KEY"Envio
Enviar texto, mídia e resposta citada por um número.
post/api/v1/instances/{id}/sendEnvia uma mensagem de textoChave de API
Envio direto e síncrono de texto pela instância. to aceita telefone (dígitos, com ou sem +, espaços e traços) ou um JID completo (...@s.whatsapp.net, ...@g.us).
Ordem das recusas: conta suspensa/cancelada (403 ACCOUNT_SUSPENDED), instância inexistente (404), cota mensal do plano (max_messages_per_month: 403 plan_limit, ou 503 usage_unavailable quando o uso do mês não pode ser lido), corpo inválido (400), instância sem cliente (503), conversa nova além de max_chats_per_instance (403 plan_limit, ou 503 usage_unavailable quando as conversas não podem ser contadas), instância pausada ou travada por reachout (429 com Retry-After), e por fim o resultado do WhatsApp.
Destinatário sem WhatsApp: 400 {"error":"recipient is not on WhatsApp","code":"RECIPIENT_NOT_ON_WHATSAPP"}; não conta como falha da instância nem cria cooldown.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
bodyobrigatório | string | |
toobrigatório | string | Telefone ou JID do destinatário. |
{
"body": "Olá!",
"to": "5511999990000"
}Respostas
200Mensagem aceita pelo WhatsApp.json{ "id": "3EB0A1B2C3D4E5F60718" }400to/bodyausentes, telefone inválido ou destinatário sem WhatsApp. Num número oficial:recipient_invalid(um grupo ou um LID não é destinatário) ecloud_send_refused(a Meta recusou a mensagem; vem o código do erro dela e um texto nosso, nunca o texto da Meta).json{ "error": "to and body required" }401Chave ausente ou inválida, ou a sessão do WhatsApp foi deslogada/banida (categoriaauth).json{ "error": "invalid request" }403Cota mensal do plano esgotada (plan_limit,max_messages_per_month), conversa nova num número já no teto de conversas (plan_limit,max_chats_per_instance; responder a uma conversa existente passa) ou conta suspensa/cancelada (ACCOUNT_SUSPENDED; se o bloqueio chega já no envio, o corpo vem só comerror).json{ "code": "plan_limit", "error": "Plan limit reached: max_messages_per_month.", "limit": "max_messages_per_month" }404Recurso inexistente.json{ "error": "invalid request" }409Número oficial (provider: cloud): a janela de 24 h com o contato está fechada (window_closed: ele não escreveu nas últimas 24 h; só um modelo aprovado vai, e a API recusa antes de chamar a Meta), o tipo de mensagem não existe num número oficial (provider_unsupported), ou o número oficial não estáonline(number_restricted: qualidade pausada, número sinalizado ou removido na Meta;statusestatus_reasondizem o motivo, a Meta não é chamada, ePOST /instances/{id}/refreshrelê o status).json{ "code": "number_restricted", "error": "this official number cannot send now (status restricted); POST /instances/:id/refresh reads its status from Meta again", "status": "restricted", "status_reason": "quality_red" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }422Número oficial, a Meta recusou o token (cloud_auth_invalid, o mesmo status do cadastro); o número ficarestricted, e o próximo envio já recebe o mesmo 422 sem a Meta ser chamada, até trocar o token (PUT /instances/{id}/cloud/credentials).json{ "error": "invalid request" }429Instância pausada, travada por reachout (Retry-After3600), limite de taxa do WhatsApp (Retry-After300) ou limite de taxa global da API (Retry-After1).json{ "error": "instance is temporarily locked after a reachout error" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }502Erro do servidor do WhatsApp.json{ "error": "invalid request" }503Instância sem cliente (instance not ready), falha de rede/conexão com o WhatsApp, ou uso do mês ilegível (usage_unavailable).json{ "error": "instance not ready" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/send" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"Olá!","to":"5511999990000"}'post/api/v1/instances/{id}/send-mediaEnvia uma mídiaChave de API
Corpo em formulário (não JSON): multipart/form-data com o arquivo em file, ou file_url com uma URL http(s) pública (endereços privados/loopback são recusados; até 64 MB; timeout de 30 s). Se os dois vêm, vale file_url. type força o tipo (image, video, audio, document); sem ele, o tipo sai do MIME. Áudio audio/ogg é enviado como nota de voz. Mesmas recusas do envio de texto (403 ACCOUNT_SUSPENDED/plan_limit, 503 usage_unavailable/ instance not ready, 429 pausa/reachout, 400 RECIPIENT_NOT_ON_WHATSAPP). Falhas ao preparar a mídia: entrada do cliente (sem file nem file_url, to inválido, arquivo ilegível) = 400 MEDIA_INVALID_INPUT; a URL do cliente não pôde ser baixada (recusada, fora do ar, status de erro, grande demais) = 422 MEDIA_DOWNLOAD_FAILED; falha nossa (upload ao WhatsApp, disco) = 500 MEDIA_PREPARE_FAILED.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/x-www-form-urlencoded)
| Campo | Tipo | Descrição |
|---|---|---|
captionopcional | string | |
file_urlobrigatório | string (uri) | |
toobrigatório | string | |
typeopcional | "image" | "video" | "audio" | "document" |
{
"caption": "Nosso catálogo",
"file_url": "https://cdn.example.com/catalogo.pdf",
"to": "5511999990000",
"type": "document"
}Respostas
200Mídia aceita pelo WhatsApp.json{ "caption": "string", "file_name": "string", "id": "string", "mime_type": "string", "timestamp": "2026-01-01T12:00:00Z", "to": "string", "type": "image" }400toausente, entrada de mídia inválida (MEDIA_INVALID_INPUT) ou destinatário sem WhatsApp. Num número oficial:recipient_invalid(um grupo ou um LID não é destinatário) ecloud_send_refused(a Meta recusou a mensagem; vem o código do erro dela e um texto nosso, nunca o texto da Meta). Também, antes do upload para a Meta:media_too_large(acima do teto da Meta para o tipo: imagem 5 MB, vídeo e áudio 16 MB, documento 100 MB) emedia_type_unsupported(um tipo que a Meta não aceita naquele tipo de mídia; mande como documento).json{ "error": "to required" }401Chave ausente ou inválida, ou a sessão do WhatsApp foi deslogada/banida (categoriaauth).json{ "error": "invalid request" }403Cota mensal do plano esgotada (plan_limit,max_messages_per_month), conversa nova num número já no teto de conversas (plan_limit,max_chats_per_instance; responder a uma conversa existente passa) ou conta suspensa/cancelada (ACCOUNT_SUSPENDED).json{ "code": "plan_limit", "error": "Plan limit reached: max_instances.", "limit": "max_instances" }404Recurso inexistente.json{ "error": "invalid request" }409Número oficial (provider: cloud): a janela de 24 h com o contato está fechada (window_closed: ele não escreveu nas últimas 24 h; só um modelo aprovado vai, e a API recusa antes de chamar a Meta), o tipo de mensagem não existe num número oficial (provider_unsupported), ou o número oficial não estáonline(number_restricted: qualidade pausada, número sinalizado ou removido na Meta;statusestatus_reasondizem o motivo, a Meta não é chamada, ePOST /instances/{id}/refreshrelê o status).json{ "code": "number_restricted", "error": "this official number cannot send now (status restricted); POST /instances/:id/refresh reads its status from Meta again", "status": "restricted", "status_reason": "quality_red" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }413Arquivo acima de 64 MB, ou corpo acima de 65 MB (MEDIA_TOO_LARGE). Um corpo declarado maior é recusado sem ser lido.json{ "code": "MEDIA_TOO_LARGE", "error": "media too large: the limit is 64 MB" }422A URL de mídia do cliente não pôde ser baixada (MEDIA_DOWNLOAD_FAILED). Num número oficial, tambémcloud_auth_invalid(a Meta recusou o token; o número ficarestricted, e o próximo envio já recebe o mesmo 422 sem a Meta ser chamada, até trocar o token).json{ "code": "MEDIA_DOWNLOAD_FAILED", "error": "media download failed: download failed with status 404" }429Instância pausada, travada por reachout, limite de taxa do WhatsApp ou da API.json{ "error": "invalid request" }500Falha nossa ao preparar a mídia (MEDIA_PREPARE_FAILED) ou erro desconhecido no envio.json{ "error": "invalid request" }502Erro do servidor do WhatsApp.json{ "error": "invalid request" }503Instância sem cliente, falha de rede com o WhatsApp, ou uso do mês ilegível (usage_unavailable).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/send-media" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d '{"caption":"Nosso catálogo","file_url":"https://cdn.example.com/catalogo.pdf","to":"5511999990000","type":"document"}'post/api/v1/instances/{id}/send-replyResponde citando uma mensagemChave de API
Envia texto citando a mensagem quoted_message_id enviada por quoted_sender. Devolve a mensagem gravada. Mesmas recusas do envio de texto (403 ACCOUNT_SUSPENDED/plan_limit, 503 usage_unavailable/instance not ready, 429 pausa/reachout, 400 telefone inválido ou RECIPIENT_NOT_ON_WHATSAPP).
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
bodyobrigatório | string | |
quoted_message_idobrigatório | string | ID no WhatsApp da mensagem citada. |
quoted_senderobrigatório | string | Telefone ou JID de quem enviou a mensagem citada. |
toobrigatório | string |
{
"body": "Perfeito, combinado.",
"quoted_message_id": "3EB0FFEEDDCCBBAA0011",
"quoted_sender": "5511999990000",
"to": "5511999990000"
}Respostas
200Resposta aceita pelo WhatsApp.json{ "body": "string", "conversation_key": "string", "direction": "inbound", "from": "string", "id": "string", "instance_id": "string", "is_group": false, "media": { "file_name": "string", "mime_type": "string" }, "media_caption": "string", "recipient": "string", "sender": "string", "source": "string", "timestamp": "2026-01-01T12:00:00Z" }400Campos ausentes,to/quoted_senderinválidos, ou destinatário sem WhatsApp. Num número oficial:recipient_invalid(um grupo ou um LID não é destinatário) ecloud_send_refused(a Meta recusou a mensagem; vem o código do erro dela e um texto nosso, nunca o texto da Meta).json{ "error": "to, body, quoted_message_id and quoted_sender required" }401Chave ausente ou inválida, ou a sessão do WhatsApp foi deslogada/banida (categoriaauth).json{ "error": "invalid request" }403Cota mensal do plano esgotada (plan_limit,max_messages_per_month), conversa nova num número já no teto de conversas (plan_limit,max_chats_per_instance; responder a uma conversa existente passa) ou conta suspensa/cancelada (ACCOUNT_SUSPENDED).json{ "code": "plan_limit", "error": "Plan limit reached: max_instances.", "limit": "max_instances" }404Recurso inexistente.json{ "error": "invalid request" }409Número oficial (provider: cloud): a janela de 24 h com o contato está fechada (window_closed: ele não escreveu nas últimas 24 h; só um modelo aprovado vai, e a API recusa antes de chamar a Meta), o tipo de mensagem não existe num número oficial (provider_unsupported), ou o número oficial não estáonline(number_restricted: qualidade pausada, número sinalizado ou removido na Meta;statusestatus_reasondizem o motivo, a Meta não é chamada, ePOST /instances/{id}/refreshrelê o status).json{ "code": "number_restricted", "error": "this official number cannot send now (status restricted); POST /instances/:id/refresh reads its status from Meta again", "status": "restricted", "status_reason": "quality_red" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }422Número oficial, a Meta recusou o token (cloud_auth_invalid, o mesmo status do cadastro); o número ficarestricted, e o próximo envio já recebe o mesmo 422 sem a Meta ser chamada, até trocar o token (PUT /instances/{id}/cloud/credentials).json{ "error": "invalid request" }429Instância pausada, travada por reachout, limite de taxa do WhatsApp ou da API.json{ "error": "invalid request" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }502Erro do servidor do WhatsApp.json{ "error": "invalid request" }503Instância sem cliente, falha de rede com o WhatsApp, ou uso do mês ilegível (usage_unavailable).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/send-reply" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"Perfeito, combinado.","quoted_message_id":"3EB0FFEEDDCCBBAA0011","quoted_sender":"5511999990000","to":"5511999990000"}'Mensagens e conversas
Mensagens gravadas (com status de entregue e lida nas enviadas), grupos, contatos e conversas.
get/api/v1/instances/{id}/chatsLista as conversas da instânciaChave de API
Conversas em memória (carregadas na conexão e em refresh). Num número oficial, as conversas que a API guarda das mensagens dele, a da última mensagem primeiro, com unread_count, pinned e o nome do contato do Marketing (até 5000).
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Conversas.json{ "chats": [ { "archived": false, "jid": "string", "last_message_time": "2026-01-01T12:00:00Z", "muted": false, "name": "string", "pinned": false, "unread_count": 0 } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/chats" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/contactsLista os contatos da instânciaChave de API
Contatos em memória (carregados na conexão e em refresh), sem ordem garantida. Num número oficial, quem conversou com ele, pelas mensagens que a API guarda: o JID (telefone ou BSUID), conversation_key e o nome do contato do Marketing (até 5000).
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Contatos.json{ "contacts": [ { "conversation_key": "string", "jid": "string", "name": "string", "push_name": "string" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/contacts" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/groupsLista os grupos da contaChave de API
Consulta ao vivo, no WhatsApp, os grupos de que a conta participa.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Grupos.json{ "groups": [ { "announce_only": false, "is_community": false, "jid": "string", "locked": false, "member_count": 0, "name": "string", "owner_jid": "string", "participants": [ "string" ] } ] }401Chave ausente ou inválida, ou a instância não está logada no WhatsApp (not logged in).json{ "error": "not logged in" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Instância sem cliente.json{ "error": "not ready" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/groups" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/messagesLista as mensagens da instânciaChave de API
Mensagens recebidas e enviadas, da mais nova para a mais antiga. Sem filtros e com offset + limit <= 500, vem do buffer em memória (últimas 500); com filtros ou além disso, do banco (as 2.000 mais novas que passam nos filtros). total conta só o que essa fonte leu (até 500 ou até 2.000). Mensagens outbound trazem status (sent → delivered → read, pelos recibos do destinatário) e os horários delivered_at/read_at; as recebidas não trazem esses campos.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
limitopcional | query | integer | Tamanho da página; valores ≤ 0 ou inválidos voltam ao padrão. |
offsetopcional | query | integer | Deslocamento; valores negativos ou inválidos viram 0. |
directionopcional | query | "inbound" | "outbound" | Filtra pela direção. |
sourceopcional | query | string | Filtra pela origem exata (instance, cluster, chatwoot, campaign, flow, warmer…). |
searchopcional | query | string | Busca sem diferenciar maiúsculas em body, from, sender, source e conversation_key. |
Respostas
200Página de mensagens.json{ "limit": 50, "messages": [ { "body": "Olá!", "conversation_key": "5511999990000", "delivered_at": "2026-01-10T12:00:02Z", "direction": "outbound", "from": "5511999990000@s.whatsapp.net", "id": "3EB0A1B2C3D4E5F60718", "is_group": false, "read_at": "2026-01-10T12:01:00Z", "recipient": "5511999990000", "sender": "5581999990000@s.whatsapp.net", "source": "instance", "status": "read", "timestamp": "2026-01-10T12:00:00Z" } ], "offset": 0, "total": 1 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/messages" \
-H "Authorization: Bearer $API_KEY"Caixa de entrada
O atendimento de cada conversa (status, responsável, fixada, etiquetas, não lidas, janela de 24 h) e as notas internas. Só a chave da plataforma.
get/api/v1/inbox/conversationsLista as conversasSó a chave da plataforma
Conversas de todos os números, fixadas primeiro e depois pela última mensagem. Os filtros se combinam (E). Paginação por cursor: a página seguinte custa o mesmo que a primeira, e uma conversa que muda de posição durante a leitura não se repete. Grupos e o aquecimento ficam fora. Uma conversa entra na caixa com a primeira mensagem do contato ou com um envio manual (envio direto, Chatwoot ou o celular do número); envios de campanha, fluxo e cluster só atualizam uma conversa que já existe.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
instanceIdsopcional | query | string | Ids de instância separados por vírgula: só as conversas desses números (o SaaS manda os que a pessoa pode ver). Ausente = todos. |
statusopcional | query | "open" | "resolved" | Abertas ou resolvidas; ausente = as duas. |
assigneeopcional | query | string | Só as atribuídas a este id. |
unassignedopcional | query | "true" | "false" | true = sem responsável; false = com responsável. |
unreadopcional | query | "true" | "false" | true = com não lidas; false = sem. |
pinnedopcional | query | "true" | "false" | true = só fixadas; false = só não fixadas. |
labelopcional | query | string | Só as que têm esta etiqueta: tag do contato ou etiqueta da conversa. |
qopcional | query | string | Busca sem caixa e sem acento no telefone, no nome do contato e no texto das mensagens. |
cursoropcional | query | string | O next_cursor da página anterior. |
limitopcional | query | integer | Itens por página. |
Respostas
200Uma página de conversas.json{ "conversations": [ { "agent_paused_at": "2026-01-01T12:00:00Z", "agent_paused_reason": "transfer", "assignee": "string", "contact": { "fields": null, "id": null, "name": null, "optedOut": null, "tags": null, "tags_detail": null }, "conversation_key": "string", "created_at": "2026-01-01T12:00:00Z", "handled_by": "agent", "instance_id": "00000000-0000-4000-8000-000000000000", "instance_removed": false, "labels": [ "string" ], "labels_detail": [ { "color": "gray", "name": null } ], "last_inbound_at": "2026-01-01T12:00:00Z", "last_message": { "at": "2026-01-01T12:00:00Z", "direction": "inbound", "id": "string", "preview": "string" }, "last_read_at": "2026-01-01T12:00:00Z", "name": "string", "pinned": false, "resolved_at": "2026-01-01T12:00:00Z", "status": "open", "unread_count": 0, "updated_at": "2026-01-01T12:00:00Z", "window_expires_at": "2026-01-01T12:00:00Z" } ], "next_cursor": "string" }400Pedido inválido (codeINBOX_INVALID_REQUEST).json{ "code": "INBOX_INVALID_REQUEST", "error": "status must be open or resolved" }401Sem a chave global (a chave de instância não vale aqui).json{ "error": "unauthorized: missing or invalid API key" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "inbox operation failed" }503Banco indisponível.json{ "error": "inbox storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/inbox/conversations" \
-H "Authorization: Bearer $API_KEY"get/api/v1/inbox/conversations/{instanceId}/{key}Abre uma conversaSó a chave da plataforma
Estado da conversa, mensagens (mais recente primeiro, paginadas com before, com status entregue/lida nas enviadas) e as notas internas.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
instanceIdobrigatório | path | string (uuid) | Número (instância) da conversa. |
keyobrigatório | path | string | conversation_key da conversa. |
beforeopcional | query | string | O next_before da página anterior. |
limitopcional | query | integer | Mensagens por página. |
Respostas
200A conversa.json{ "conversation": { "agent_paused_at": "2026-01-01T12:00:00Z", "agent_paused_reason": "transfer", "assignee": "string", "contact": { "fields": {}, "id": "00000000-0000-4000-8000-000000000000", "name": "string", "optedOut": false, "tags": [ null ], "tags_detail": [ null ] }, "conversation_key": "string", "created_at": "2026-01-01T12:00:00Z", "handled_by": "agent", "instance_id": "00000000-0000-4000-8000-000000000000", "instance_removed": false, "labels": [ "string" ], "labels_detail": [ { "color": "gray", "name": "string" } ], "last_inbound_at": "2026-01-01T12:00:00Z", "last_message": { "at": "2026-01-01T12:00:00Z", "direction": "inbound", "id": "string", "preview": "string" }, "last_read_at": "2026-01-01T12:00:00Z", "name": "string", "pinned": false, "resolved_at": "2026-01-01T12:00:00Z", "status": "open", "unread_count": 0, "updated_at": "2026-01-01T12:00:00Z", "window_expires_at": "2026-01-01T12:00:00Z" }, "messages": [ { "body": "string", "conversation_key": "string", "direction": "inbound", "from": "string", "id": "string", "instance_id": "string", "is_group": false, "media": { "file_name": null, "mime_type": null }, "media_caption": "string", "recipient": "string", "sender": "string", "source": "string", "timestamp": "2026-01-01T12:00:00Z", "delivered_at": "2026-01-01T12:00:00Z", "read_at": "2026-01-01T12:00:00Z", "status": "sent", "template": null } ], "next_before": "string", "notes": [ { "author": "string", "body": "string", "conversation_key": "string", "created_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "instance_id": "00000000-0000-4000-8000-000000000000" } ] }400Pedido inválido (codeINBOX_INVALID_REQUEST).json{ "code": "INBOX_INVALID_REQUEST", "error": "status must be open or resolved" }401Sem a chave global (a chave de instância não vale aqui).json{ "error": "unauthorized: missing or invalid API key" }404A conversa não existe (CONVERSATION_NOT_FOUND): só existe depois da primeira mensagem do contato ou de um envio manual.json{ "code": "CONVERSATION_NOT_FOUND", "error": "conversation not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "inbox operation failed" }503Banco indisponível.json{ "error": "inbox storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/inbox/conversations/<instanceId>/<key>" \
-H "Authorization: Bearer $API_KEY"patch/api/v1/inbox/conversations/{instanceId}/{key}Atribui, fixa, resolve, etiqueta ou marca como lidaSó a chave da plataforma
Muda numa só operação o que vier no corpo e devolve a conversa atualizada.
Agente de IA: atribuir um assignee pausa o agente na conversa; agent_paused: true pausa sem atribuir; agent_paused: false devolve a conversa ao agente e tira o responsável (com um assignee não nulo no mesmo corpo: 400 INBOX_INVALID_REQUEST).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
instanceIdobrigatório | path | string (uuid) | Número (instância) da conversa. |
keyobrigatório | path | string | conversation_key da conversa. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
agent_pausedopcional | boolean | true pausa o agente de IA na conversa (mantém o agent_paused_at se já estava pausado). false devolve a conversa ao agente: limpa o agent_paused_at e também tira o responsável (assignee vira null). false com um assignee não nulo no mesmo corpo é 400 INBOX_INVALID_REQUEST; com assignee null ou "" é aceito. |
assigneeopcional | string | null | Atribui a um id opaco do SaaS; null ou "" tira o responsável; ausente mantém. Atribuir alguém também pausa o agente de IA na conversa (agent_paused_at); tirar o responsável não o devolve ao agente (para isso, agent_paused: false). |
labelsopcional | array<string> | Substitui o conjunto (sem repetição; [] tira todas). Até 100 etiquetas de até 100 caracteres, com ou sem contato (o limite das tags do Marketing). Com contato, grava nas tags dele e vale em toda conversa desse telefone; sem contato, fica na conversa. |
pinnedopcional | boolean | |
readopcional | boolean | Marca como lida: zera unread_count e grava last_read_at. |
statusopcional | "open" | "resolved" |
{
"assignee": "person-123"
}Respostas
200A conversa atualizada.json{ "agent_paused_at": "2026-01-01T12:00:00Z", "agent_paused_reason": "transfer", "assignee": "string", "contact": { "fields": {}, "id": "00000000-0000-4000-8000-000000000000", "name": "string", "optedOut": false, "tags": [ "string" ], "tags_detail": [ { "color": "gray", "name": null } ] }, "conversation_key": "string", "created_at": "2026-01-01T12:00:00Z", "handled_by": "agent", "instance_id": "00000000-0000-4000-8000-000000000000", "instance_removed": false, "labels": [ "string" ], "labels_detail": [ { "color": "gray", "name": "string" } ], "last_inbound_at": "2026-01-01T12:00:00Z", "last_message": { "at": "2026-01-01T12:00:00Z", "direction": "inbound", "id": "string", "preview": "string" }, "last_read_at": "2026-01-01T12:00:00Z", "name": "string", "pinned": false, "resolved_at": "2026-01-01T12:00:00Z", "status": "open", "unread_count": 0, "updated_at": "2026-01-01T12:00:00Z", "window_expires_at": "2026-01-01T12:00:00Z" }400Pedido inválido (codeINBOX_INVALID_REQUEST).json{ "code": "INBOX_INVALID_REQUEST", "error": "status must be open or resolved" }401Sem a chave global (a chave de instância não vale aqui).json{ "error": "unauthorized: missing or invalid API key" }404A conversa não existe (CONVERSATION_NOT_FOUND): só existe depois da primeira mensagem do contato ou de um envio manual.json{ "code": "CONVERSATION_NOT_FOUND", "error": "conversation not found" }409O número da conversa foi removido da conta: o histórico é só leitura (INSTANCE_REMOVED).json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "inbox operation failed" }503Banco indisponível.json{ "error": "inbox storage unavailable" }
Exemplo
curl -X PATCH "$API_URL/api/v1/inbox/conversations/<instanceId>/<key>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"assignee":"person-123"}'post/api/v1/inbox/conversations/{instanceId}/{key}/contactCria o contato do Marketing com o telefone da conversaSó a chave da plataforma
A única forma de uma conversa virar contato: contato entra em campanha, então é sempre escolha de alguém (ler ou etiquetar nunca cria). O contato nasce com o telefone da conversa e, como tags, as etiquetas das conversas desse telefone em todos os números, que saem das conversas. Uma linha guardada só para registrar opt-out vira o contato e mantém o opt-out. Vale o plano: Marketing ligado e o limite de contatos.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
instanceIdobrigatório | path | string (uuid) | Número (instância) da conversa. |
keyobrigatório | path | string | conversation_key da conversa. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
nameopcional | string |
{
"name": "Ana Cliente"
}Respostas
201A conversa, com o contato.json{ "agent_paused_at": "2026-01-01T12:00:00Z", "agent_paused_reason": "transfer", "assignee": "string", "contact": { "fields": {}, "id": "00000000-0000-4000-8000-000000000000", "name": "string", "optedOut": false, "tags": [ "string" ], "tags_detail": [ { "color": "gray", "name": null } ] }, "conversation_key": "string", "created_at": "2026-01-01T12:00:00Z", "handled_by": "agent", "instance_id": "00000000-0000-4000-8000-000000000000", "instance_removed": false, "labels": [ "string" ], "labels_detail": [ { "color": "gray", "name": "string" } ], "last_inbound_at": "2026-01-01T12:00:00Z", "last_message": { "at": "2026-01-01T12:00:00Z", "direction": "inbound", "id": "string", "preview": "string" }, "last_read_at": "2026-01-01T12:00:00Z", "name": "string", "pinned": false, "resolved_at": "2026-01-01T12:00:00Z", "status": "open", "unread_count": 0, "updated_at": "2026-01-01T12:00:00Z", "window_expires_at": "2026-01-01T12:00:00Z" }400Pedido inválido (INBOX_INVALID_REQUEST), inclusive a chave da conversa não ser telefone (LID).json{ "code": "INBOX_INVALID_REQUEST", "error": "status must be open or resolved" }401Sem a chave global (a chave de instância não vale aqui).json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled) ou limite de contatos (plan_limit,max_contacts).json{ "code": "plan_limit", "error": "Plan limit reached: max_instances.", "limit": "max_instances" }404A conversa não existe (CONVERSATION_NOT_FOUND): só existe depois da primeira mensagem do contato ou de um envio manual.json{ "code": "CONVERSATION_NOT_FOUND", "error": "conversation not found" }409O contato já existe (CONTACT_EXISTS), ou o número da conversa foi removido (INSTANCE_REMOVED).json{ "code": "CONTACT_EXISTS", "error": "contact already exists" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "inbox operation failed" }503Banco indisponível.json{ "error": "inbox storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/inbox/conversations/<instanceId>/<key>/contact" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Ana Cliente"}'post/api/v1/inbox/conversations/{instanceId}/{key}/notesEscreve uma nota internaSó a chave da plataforma
A nota fica só na caixa de entrada: nunca vai para o WhatsApp, para o webhook ou para o Chatwoot, e nunca aparece na prévia da lista.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
instanceIdobrigatório | path | string (uuid) | Número (instância) da conversa. |
keyobrigatório | path | string | conversation_key da conversa. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
authorobrigatório | string | Id opaco de quem escreveu. |
bodyobrigatório | string |
{
"author": "person-123",
"body": "Cliente pediu retorno amanhã cedo."
}Respostas
201A nota gravada.json{ "author": "string", "body": "string", "conversation_key": "string", "created_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "instance_id": "00000000-0000-4000-8000-000000000000" }400Pedido inválido (codeINBOX_INVALID_REQUEST).json{ "code": "INBOX_INVALID_REQUEST", "error": "status must be open or resolved" }401Sem a chave global (a chave de instância não vale aqui).json{ "error": "unauthorized: missing or invalid API key" }404A conversa não existe (CONVERSATION_NOT_FOUND): só existe depois da primeira mensagem do contato ou de um envio manual.json{ "code": "CONVERSATION_NOT_FOUND", "error": "conversation not found" }409O número da conversa foi removido da conta: o histórico é só leitura (INSTANCE_REMOVED).json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "inbox operation failed" }503Banco indisponível.json{ "error": "inbox storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/inbox/conversations/<instanceId>/<key>/notes" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"author":"person-123","body":"Cliente pediu retorno amanhã cedo."}'get/api/v1/inbox/countsTodos os contadores numa chamadaSó a chave da plataforma
Os números dos filtros e do menu da caixa de entrada numa chamada só (a chave global é compartilhada pela equipe e /api/v1 tem limite de taxa). Tudo conta conversas abertas, menos resolved; cada número é o tamanho da lista com o mesmo filtro e status=open, lidos no mesmo instante.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
instanceIdsopcional | query | string | Ids de instância separados por vírgula: só as conversas desses números (o SaaS manda os que a pessoa pode ver). Ausente = todos. |
assigneeopcional | query | string | Quem está olhando: conta as abertas dele em mine. |
Respostas
200Os contadores.json{ "by_instance": [ { "instance_id": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b", "open": 30, "unread": 6 } ], "by_label": [ { "label": "vip", "open": 4 } ], "mine": 7, "open": 45, "pinned": 3, "resolved": 120, "unassigned": 12, "unread": 9, "unread_messages": 23 }400Pedido inválido (codeINBOX_INVALID_REQUEST).json{ "code": "INBOX_INVALID_REQUEST", "error": "instanceIds must be instance ids separated by commas" }401Sem a chave global (a chave de instância não vale aqui).json{ "error": "unauthorized: missing or invalid API key" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "inbox operation failed" }503Banco indisponível.json{ "error": "inbox storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/inbox/counts" \
-H "Authorization: Bearer $API_KEY"CRM
Funis, etapas e negócios (kanban), com o histórico de cada negócio. Só a chave da plataforma.
get/api/v1/crm/contacts/{contactID}/dealsNegócios de um contatoSó a chave da plataforma
Os negócios do contato, do mais novo para o mais antigo, até 200 (o painel do contato na caixa de entrada). Contato sem negócios, ou inexistente, = lista vazia.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
contactIDobrigatório | path | string (uuid) | Id do contato. |
Respostas
200Os negócios do contato.json{ "deals": [ { "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 } ] }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Id que não é UUID (not_found).json{ "code": "not_found", "error": "contact not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/contacts/<contactID>/deals" \
-H "Authorization: Bearer $API_KEY"get/api/v1/crm/dealsLista os negóciosSó a chave da plataforma
Negócios do mais novo para o mais antigo (created_at), por cursor. Os filtros se combinam (E). O kanban ordena cada coluna por position.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
pipeline_idopcional | query | string (uuid) | Só deste funil. |
stage_idopcional | query | string (uuid) | Só desta etapa. |
owneropcional | query | string | Só deste responsável. |
statusopcional | query | "open" | "won" | "lost" | Abertos, ganhos ou perdidos; ausente = todos. |
tagopcional | query | string | Só os de contato com esta tag. |
qopcional | query | string | Busca no título e no nome do contato (sem caixa) e no telefone do contato. |
instance_idopcional | query | array<string (uuid)> | Só os negócios cujo contato tem conversa em algum destes números (inbox_conversations, pelo telefone do contato; repetível: instance_id=a&instance_id=b, até 100). Negócio sem contato fica fora. É o alcance "numbers" do SaaS. |
cursoropcional | query | string | O next_cursor da página anterior. |
limitopcional | query | integer | Itens por página. |
Respostas
200Uma página de negócios.json{ "deals": [ { "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 } ], "next_cursor": "string" }400Filtro inválido:status(invalid_status),instance_id(invalid_instance: não é UUID ou mais de 100),limit(invalid_limit) oucursor(invalid_cursor).json{ "code": "invalid_cursor", "error": "invalid cursor" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/deals" \
-H "Authorization: Bearer $API_KEY"post/api/v1/crm/dealsCria um negócioSó a chave da plataforma
Cria o negócio numa etapa aberta do funil (stage_id; ausente = a primeira aberta), no fim da coluna, com um evento created. currency padrão USD; source padrão manual.
Contato. contact_id aponta um contato existente; phone usa o contato desse telefone e, se não houver, cria o contato, como o "Salvar como contato" da caixa de entrada: dentro de max_contacts, uma linha que só tinha o opt-out vira o contato mantendo o consentimento, e as etiquetas das conversas desse telefone viram tags do contato. O funil e a etapa são conferidos antes: um 404 ou 409 não cria contato. Sem os dois, o negócio fica sem contato.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
contact_idopcional | string (uuid) | Contato existente. Não envie junto com phone. |
currencyopcional | string | |
expected_close_atopcional | string | null (date-time) | |
fieldsopcional | object | Os campos personalizados: só as chaves do esquema ativo, cada uma pelo tipo; os obrigatórios precisam vir. Fora disso, 400 field_invalid com field. |
owneropcional | string | null | |
phoneopcional | string | Telefone E.164 (+, espaços, -, (, ) e . são ignorados). Sem contato com ele, o contato é criado. Não envie junto com contact_id. |
pipeline_idobrigatório | string (uuid) | |
sourceopcional | "manual" | "inbox" | "flow" | "import" | |
stage_idopcional | string (uuid) | Etapa aberta do funil; ausente = a primeira aberta. |
titleobrigatório | string | |
value_centsopcional | integer | null (int64) |
{
"currency": "BRL",
"phone": "+5511987654321",
"pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f",
"title": "Plano anual",
"value_cents": 120000
}Respostas
201O negócio criado.json{ "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 }400Corpo inválido (invalid_body, inclusive data fora do ISO 8601) ou campo inválido:invalid_pipeline,invalid_title,invalid_value,invalid_currency,invalid_source,invalid_contact(os dois enviados, ou contato inexistente),invalid_owner,invalid_phoneouinvalid_stage(etapa de ganho ou de perda).json{ "code": "invalid_contact", "error": "send contact_id or phone, not both" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Limitemax_contactsdo plano ao criar o contato pelo telefone (plan_limit), funçãocrm_enabledfora do plano (plan_feature_disabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Funil inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "pipeline not found" }409A etapa não é do funil (stage_not_in_pipeline).json{ "code": "stage_not_in_pipeline", "error": "the stage is not in this pipeline" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/deals" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"currency":"BRL","phone":"+5511987654321","pipeline_id":"3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f","title":"Plano anual","value_cents":120000}'get/api/v1/crm/deals/exportExporta os negócios em JSON, por cursorSó a chave da plataforma
A exportação dos negócios para outra API, a que o job de cópia do SaaS lê. Usa os filtros da lista e do CSV (pipeline_id, stage_id, status, owner, tag, q, instance_id, field.<chave>) ou ids, para exportar um a um; os mais novos primeiro. Cada negócio leva o funil e a etapa (pelo id e pelo nome), os campos pela chave, o responsável, o contato (telefone e nome), o valor, o status, as datas, as tarefas e as notas. Importe com POST /crm/deals/import. Só a chave global.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
pipeline_idopcional | query | string (uuid) | |
statusopcional | query | "open" | "won" | "lost" | |
owneropcional | query | string | |
instance_idopcional | query | array<string (uuid)> | Só os negócios cujo contato tem conversa em algum destes números (inbox_conversations, pelo telefone do contato; repetível: instance_id=a&instance_id=b, até 100). Negócio sem contato fica fora. É o alcance "numbers" do SaaS. |
idsopcional | query | string | Ids de negócio, separados por vírgula ou repetidos (até 500). |
cursoropcional | query | string | O next_cursor da página anterior. |
limitopcional | query | integer |
Respostas
200Uma página de negócios;next_cursornull na última.json{ "deals": [ { "closed_at": "2026-01-01T12:00:00Z", "contact": { "id": "string", "name": "string", "phone": "string" }, "created_at": "2026-01-01T12:00:00Z", "currency": "string", "expected_close_at": "2026-01-01T12:00:00Z", "fields": {}, "id": "00000000-0000-4000-8000-000000000000", "lost_reason": "string", "notes": [ { "actor": null, "at": null, "text": null } ], "owner": "string", "pipeline": { "id": "string", "name": "string" }, "source": "string", "stage": { "id": "string", "kind": "open", "name": "string" }, "stage_entered_at": "2026-01-01T12:00:00Z", "status": "open", "tasks": [ { "created_at": null, "done_at": null, "due_at": null, "owner": null, "title": null } ], "title": "string", "updated_at": "2026-01-01T12:00:00Z", "value_cents": 0 } ], "next_cursor": "string" }400Filtro,idsou cursor inválido.json{ "error": "invalid request" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }422limitacima de 500 (limit_too_large) ou mais de 500ids(too_many_ids).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/deals/export" \
-H "Authorization: Bearer $API_KEY"get/api/v1/crm/deals/export.csvExporta os negócios em CSVSó a chave da plataforma
Os negócios com os filtros da lista (pipeline_id, stage_id, status, owner, tag, q, instance_id, field.<chave>), em CSV pela RFC 4180 (CRLF, UTF-8), em streaming: as colunas fixas e uma coluna por campo ativo do negócio. Um texto que começa com =, +, -, @, tab ou CR sai com uma aspa simples na frente, para a planilha não o rodar como fórmula. No máximo 50.000 linhas; acima disso, 400 export_too_large.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
pipeline_idopcional | query | string (uuid) | |
statusopcional | query | "open" | "won" | "lost" | |
owneropcional | query | string | |
instance_idopcional | query | array<string (uuid)> | Só os negócios cujo contato tem conversa em algum destes números (inbox_conversations, pelo telefone do contato; repetível: instance_id=a&instance_id=b, até 100). Negócio sem contato fica fora. É o alcance "numbers" do SaaS. |
Respostas
200O CSV.jsonstring400Acima de 50.000 linhas (export_too_large) ou filtro inválido.json{ "error": "invalid request" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/deals/export.csv" \
-H "Authorization: Bearer $API_KEY"post/api/v1/crm/deals/importImporta negócios em lote, idempotente pela origemSó a chave da plataforma
A importação de negócios de outra API, até 500 por chamada. Cada negócio é o da exportação com a origin (a API de origem e o id do negócio lá): repetir o lote não duplica nada, e a linha diz already_imported com o negócio que ficou. O funil e a etapa vêm pelo mapping (o id de origem para o id de destino) ou, sem entrada nele, pelo nome; o que não casa volta como refused (pipeline_not_mapped, stage_not_mapped, pipeline_mapping_invalid, stage_mapping_invalid), e nada é criado. O status segue a etapa (um status diferente do tipo da etapa é status_stage_mismatch). Os campos vão pela chave: um campo que o destino não tem, ou com valor que não serve, volta em warnings (field_unknown:<chave>, field_invalid:<chave>); um obrigatório ausente recusa a linha (field_required:<chave>). O responsável só vai quando a linha o traz. O contato é achado pelo telefone ou criado (no limite do plano: plan_limit), mantendo o opt-out. As datas de criação, de entrada na etapa e de fechamento da origem ficam; as tarefas e as notas também. Um negócio importado não dispara os fluxos de negócio criado. Só a chave global.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
dealsobrigatório | array<any> | |
deals[].closed_atopcional | string | null (date-time) | |
deals[].contactopcional | object | null | |
deals[].contact.idopcional | string | |
deals[].contact.nameopcional | string | |
deals[].contact.phoneopcional | string | |
deals[].created_atopcional | string (date-time) | |
deals[].currencyopcional | string | |
deals[].expected_close_atopcional | string | null (date-time) | |
deals[].fieldsopcional | object | |
deals[].idopcional | string (uuid) | |
deals[].lost_reasonopcional | string | null | |
deals[].notesopcional | array<object> | |
deals[].notes[].actoropcional | string | |
deals[].notes[].atopcional | string (date-time) | |
deals[].notes[].textopcional | string | |
deals[].owneropcional | string | null | |
deals[].pipelineopcional | object | |
deals[].pipeline.idopcional | string | |
deals[].pipeline.nameopcional | string | |
deals[].sourceopcional | string | |
deals[].stageopcional | object | |
deals[].stage.idopcional | string | |
deals[].stage.kindopcional | "open" | "won" | "lost" | |
deals[].stage.nameopcional | string | |
deals[].stage_entered_atopcional | string (date-time) | |
deals[].statusopcional | "open" | "won" | "lost" | |
deals[].tasksopcional | array<object> | |
deals[].tasks[].created_atopcional | string (date-time) | |
deals[].tasks[].done_atopcional | string | null (date-time) | |
deals[].tasks[].due_atopcional | string | null (date-time) | |
deals[].tasks[].owneropcional | string | null | |
deals[].tasks[].titleopcional | string | |
deals[].titleopcional | string | |
deals[].updated_atopcional | string (date-time) | |
deals[].value_centsopcional | integer | null | |
deals[].originobrigatório | object | |
deals[].origin.apiobrigatório | string | A API de origem (o SaaS dá o nome). |
deals[].origin.idobrigatório | string | O id do negócio na origem. |
mappingopcional | object | |
mapping.pipelinesopcional | object | Id do funil de origem para o id do funil de destino. |
mapping.stagesopcional | object | Id da etapa de origem para o id da etapa de destino (do funil de destino). |
{
"deals": [
{
"closed_at": "2026-01-01T12:00:00Z",
"contact": {
"id": null,
"name": null,
"phone": null
},
"created_at": "2026-01-01T12:00:00Z",
"currency": "string",
"expected_close_at": "2026-01-01T12:00:00Z",
"fields": {},
"id": "00000000-0000-4000-8000-000000000000",
"lost_reason": "string",
"notes": [
null
],
"owner": "string",
"pipeline": {
"id": null,
"name": null
},
"source": "string",
"stage": {
"id": null,
"kind": "open",
"name": null
},
"stage_entered_at": "2026-01-01T12:00:00Z",
"status": "open",
"tasks": [
null
],
"title": "string",
"updated_at": "2026-01-01T12:00:00Z",
"value_cents": 0,
"origin": {
"api": null,
"id": null
}
}
],
"mapping": {
"pipelines": {},
"stages": {}
}
}Respostas
200O relatório, uma linha por negócio, na ordem do lote.json{ "already_imported": 0, "created": 0, "refused": 0, "results": [ { "deal_id": "string", "index": 0, "origin_id": "string", "reason": "string", "result": "created", "warnings": [ "string" ] } ] }400Corpo inválido (invalid_body).json{ "error": "invalid request" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }413Mais de 500 negócios ou mais de 16 MB (batch_too_large).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/deals/import" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"deals":[{"closed_at":"2026-01-01T12:00:00Z","contact":{"id":null,"name":null,"phone":null},"created_at":"2026-01-01T12:00:00Z","currency":"string","expected_close_at":"2026-01-01T12:00:00Z","fields":{},"id":"00000000-0000-4000-8000-000000000000","lost_reason":"string","notes":[null],"owner":"string","pipeline":{"id":null,"name":null},"source":"string","stage":{"id":null,"kind":"open","name":null},"stage_entered_at":"2026-01-01T12:00:00Z","status":"open","tasks":[null],"title":"string","updated_at":"2026-01-01T12:00:00Z","value_cents":0,"origin":{"api":null,"id":null}}],"mapping":{"pipelines":{},"stages":{}}}'get/api/v1/crm/deals/{id}Lê um negócioSó a chave da plataforma
O negócio, com o contato.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
Respostas
200O negócio.json{ "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/deals/<id>" \
-H "Authorization: Bearer $API_KEY"patch/api/v1/crm/deals/{id}Edita um negócioSó a chave da plataforma
Edita título, valor, moeda, responsável e previsão de fechamento. Um campo enviado como null limpa (value_cents, owner, expected_close_at). Mudança de valor e de responsável grava um evento (value, owner). A etapa muda por /move, /won, /lost e /reopen.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
currencyopcional | string | |
expected_close_atopcional | string | null (date-time) | |
fieldsopcional | object | Junta aos campos salvos; null apaga a chave (menos num obrigatório). Cada valor pelo tipo do esquema; fora disso, 400 field_invalid com field. |
owneropcional | string | null | |
titleopcional | string | |
value_centsopcional | integer | null (int64) |
{
"currency": "string",
"expected_close_at": "2026-01-01T12:00:00Z",
"fields": {},
"owner": "string",
"title": "string",
"value_cents": 0
}Respostas
200O negócio.json{ "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 }400Corpo inválido ou campo desconhecido (invalid_body), ou campo inválido:invalid_title,invalid_value,invalid_currency,invalid_owner,invalid_date.json{ "code": "invalid_body", "error": "unknown field stage_id" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X PATCH "$API_URL/api/v1/crm/deals/<id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"currency":"string","expected_close_at":"2026-01-01T12:00:00Z","fields":{},"owner":"string","title":"string","value_cents":0}'get/api/v1/crm/deals/{id}/eventsHistórico do negócioSó a chave da plataforma
Os eventos do negócio, do mais antigo para o mais novo: criação, mudanças de etapa, de status, de valor e de responsável, e as notas.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
Respostas
200O histórico.json{ "events": [ { "actor": "pessoa-1", "at": "2026-11-02T09:30:00Z", "from": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "id": 42, "kind": "stage", "to": "7a2d3c9f-3e5c-4b62-8b8f-1d2e3f4a5b6c" } ] }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/deals/<id>/events" \
-H "Authorization: Bearer $API_KEY"post/api/v1/crm/deals/{id}/lostMarca como perdidoSó a chave da plataforma
Leva o negócio para a etapa de perda do funil, no fim da coluna, e o fecha (status: lost, closed_at, lost_reason). Perder exige reason. Cada mudança de etapa grava um evento stage; cada mudança de status, um won, lost ou reopen.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
reasonobrigatório | string |
{
"reason": "string"
}Respostas
200O negócio.json{ "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 }400Corpo inválido (invalid_body) ou motivo vazio ou acima de 500 caracteres (invalid_reason).json{ "code": "invalid_body", "error": "invalid JSON body" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }409O funil não tem etapa de perda (stage_not_in_pipeline).json{ "code": "stage_not_in_pipeline", "error": "the stage is not in the deal's pipeline" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/deals/<id>/lost" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"string"}'post/api/v1/crm/deals/{id}/moveMove um negócioSó a chave da plataforma
Põe o negócio na etapa stage_id (do mesmo funil) na posição position da coluna e renumera a coluna de destino. Entrar na etapa de ganho ou de perda fecha o negócio (status, closed_at); entrar numa etapa aberta reabre (status: open, closed_at e lost_reason limpos). Entrar na etapa de perda exige reason, como em /lost. Cada mudança de etapa grava um evento stage; cada mudança de status, um won, lost ou reopen.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
positionopcional | integer | null | Posição na coluna de destino; ausente ou além do fim = o fim. |
reasonopcional | string | Motivo da perda; obrigatório quando o destino é a etapa de perda e o negócio ainda não está perdido. |
stage_idobrigatório | string (uuid) | Etapa do mesmo funil (aberta, de ganho ou de perda). |
{
"position": 0,
"reason": "string",
"stage_id": "00000000-0000-4000-8000-000000000000"
}Respostas
200O negócio.json{ "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 }400Corpo inválido (invalid_body), posição negativa (invalid_position),stage_idausente ou que não é UUID (invalid_stage), ou etapa de perda semreasonou com mais de 500 caracteres (invalid_reason).json{ "code": "invalid_body", "error": "invalid JSON body" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }409A etapa não é do funil do negócio (stage_not_in_pipeline).json{ "code": "stage_not_in_pipeline", "error": "the stage is not in the deal's pipeline" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/deals/<id>/move" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"position":0,"reason":"string","stage_id":"00000000-0000-4000-8000-000000000000"}'post/api/v1/crm/deals/{id}/notesAdiciona uma notaSó a chave da plataforma
Grava uma nota no histórico do negócio (evento note, com o texto em to).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
textobrigatório | string |
{
"text": "string"
}Respostas
201O evento da nota.json{ "actor": "pessoa-1", "at": "2026-11-02T09:30:00Z", "from": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "id": 42, "kind": "stage", "to": "7a2d3c9f-3e5c-4b62-8b8f-1d2e3f4a5b6c" }400Corpo inválido (invalid_body) ou texto vazio ou acima de 5000 caracteres (invalid_text).json{ "code": "invalid_body", "error": "invalid JSON body" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/deals/<id>/notes" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"string"}'post/api/v1/crm/deals/{id}/reopenReabre um negócioSó a chave da plataforma
Leva um negócio ganho ou perdido para a etapa aberta stage_id, no fim da coluna, e o reabre (status: open, closed_at e lost_reason limpos); num negócio aberto, 409 deal_not_closed. Cada mudança de etapa grava um evento stage; cada mudança de status, um won, lost ou reopen.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
stage_idobrigatório | string (uuid) | Etapa aberta do mesmo funil. |
{
"stage_id": "00000000-0000-4000-8000-000000000000"
}Respostas
200O negócio.json{ "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 }400Corpo inválido (invalid_body) oustage_idausente, que não é UUID ou que não é etapa aberta (invalid_stage).json{ "code": "invalid_body", "error": "invalid JSON body" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }409A etapa não é do funil do negócio (stage_not_in_pipeline) ou o negócio está aberto (deal_not_closed).json{ "code": "deal_not_closed", "error": "only a won or lost deal can be reopened" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/deals/<id>/reopen" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage_id":"00000000-0000-4000-8000-000000000000"}'get/api/v1/crm/deals/{id}/tasksTarefas de um negócioSó a chave da plataforma
As abertas primeiro, pelo prazo (sem prazo por último); depois as concluídas, a mais recente primeiro.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
Respostas
200As tarefas.json{ "next_cursor": "string", "tasks": [ { "created_at": "2026-01-01T12:00:00Z", "deal_id": "00000000-0000-4000-8000-000000000000", "deal_title": "string", "done": false, "done_at": "2026-01-01T12:00:00Z", "due_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "overdue": false, "owner": "string", "title": "string", "updated_at": "2026-01-01T12:00:00Z" } ] }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/deals/<id>/tasks" \
-H "Authorization: Bearer $API_KEY"post/api/v1/crm/deals/{id}/tasksCria uma tarefa no negócioSó a chave da plataforma
No máximo 50 tarefas abertas por negócio (contadas sob a trava da linha do negócio). Grava o evento task_created (com o título) no histórico do negócio, com o actor de X-WAAPI-Actor.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
due_atopcional | string | null (date-time) | RFC 3339; null ou ausente = sem prazo. |
owneropcional | string | null | |
titleobrigatório | string | Uma linha. |
{
"due_at": "2026-01-01T12:00:00Z",
"owner": "string",
"title": "string"
}Respostas
201A tarefa criada.json{ "created_at": "2026-01-01T12:00:00Z", "deal_id": "00000000-0000-4000-8000-000000000000", "deal_title": "string", "done": false, "done_at": "2026-01-01T12:00:00Z", "due_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "overdue": false, "owner": "string", "title": "string", "updated_at": "2026-01-01T12:00:00Z" }400Corpo inválido (invalid_body), título fora de 1 a 200 caracteres numa linha (invalid_title), prazo que não é RFC 3339 (invalid_due_at) ou responsável acima de 200 caracteres (invalid_owner).json{ "code": "invalid_due_at", "error": "due_at must be an RFC 3339 date and time, or null" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }409O negócio já tem 50 tarefas abertas (too_many_tasks).json{ "code": "too_many_tasks", "error": "a deal has at most 50 open tasks" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/deals/<id>/tasks" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"due_at":"2026-01-01T12:00:00Z","owner":"string","title":"string"}'post/api/v1/crm/deals/{id}/wonMarca como ganhoSó a chave da plataforma
Leva o negócio para a etapa de ganho do funil, no fim da coluna, e o fecha (status: won, closed_at). Num negócio que já está nela, não muda nada. Sem corpo. Cada mudança de etapa grava um evento stage; cada mudança de status, um won, lost ou reopen.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do negócio. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Respostas
200O negócio.json{ "closed_at": null, "contact": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Maria", "phone": "5511987654321" }, "created_at": "2026-11-01T12:00:00Z", "currency": "BRL", "expected_close_at": null, "id": "0b7e7f3c-5a7d-4a8e-9f60-2b1c3d4e5f60", "lost_reason": null, "next_task": { "due_at": "2026-11-07T14:00:00Z", "id": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6", "overdue": true, "title": "Ligar" }, "owner": "pessoa-1", "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f", "position": 0, "source": "manual", "stage_entered_at": "2026-11-01T12:00:00Z", "stage_id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "status": "open", "title": "Plano anual", "updated_at": "2026-11-01T12:00:00Z", "value_cents": 120000 }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Negócio inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "deal not found" }409O funil não tem etapa de ganho (stage_not_in_pipeline).json{ "code": "stage_not_in_pipeline", "error": "the stage is not in the deal's pipeline" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/deals/<id>/won" \
-H "Authorization: Bearer $API_KEY"get/api/v1/crm/fieldsCampos personalizados de uma entidadeSó a chave da plataforma
Os campos de deal ou contact, na ordem; com archived=true, também os arquivados.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
entityobrigatório | query | "deal" | "contact" | |
archivedopcional | query | boolean |
Respostas
200Os campos.json{ "fields": [ { "archived_at": "2026-01-01T12:00:00Z", "entity": "deal", "id": "00000000-0000-4000-8000-000000000000", "key": "string", "label": "string", "options": [ "string" ], "position": 0, "required": false, "type": "text" } ] }400entityinválida (invalid_entity).json{ "error": "invalid request" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/fields?entity=<entity>" \
-H "Authorization: Bearer $API_KEY"post/api/v1/crm/fieldsCria um campo personalizadoSó a chave da plataforma
A key em snake_case, única por entidade (contando as arquivadas: 409 field_key_taken); no máximo 50 campos ativos por entidade (409 too_many_fields); options só no select (1 a 100, distintas).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
entityobrigatório | "deal" | "contact" | |
keyobrigatório | string | |
labelobrigatório | string | |
optionsopcional | array<string> | |
positionopcional | integer | |
requiredopcional | boolean | |
typeobrigatório | "text" | "number" | "date" | "select" | "bool" |
{
"entity": "deal",
"key": "string",
"label": "string",
"options": [
"string"
],
"position": 0,
"required": false,
"type": "text"
}Respostas
201Criado.json{ "archived_at": "2026-01-01T12:00:00Z", "entity": "deal", "id": "00000000-0000-4000-8000-000000000000", "key": "string", "label": "string", "options": [ "string" ], "position": 0, "required": false, "type": "text" }400Corpo inválido (invalid_key,invalid_type,invalid_label,invalid_options,invalid_entity).json{ "error": "invalid request" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }409Chave já usada (field_key_taken) ou 50 campos (too_many_fields).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/fields" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"entity":"deal","key":"string","label":"string","options":["string"],"position":0,"required":false,"type":"text"}'patch/api/v1/crm/fields/{id}Muda um campo personalizadoSó a chave da plataforma
label, options, required e position; a entity, a key e o type não mudam (400 field_immutable).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
labelopcional | string | |
optionsopcional | array<string> | |
positionopcional | integer | |
requiredopcional | boolean |
{
"label": "string",
"options": [
"string"
],
"position": 0,
"required": false
}Respostas
200O campo.json{ "archived_at": "2026-01-01T12:00:00Z", "entity": "deal", "id": "00000000-0000-4000-8000-000000000000", "key": "string", "label": "string", "options": [ "string" ], "position": 0, "required": false, "type": "text" }400Corpo inválido.json{ "error": "invalid request" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Campo inexistente ou arquivado (not_found).json{ "error": "invalid request" }
Exemplo
curl -X PATCH "$API_URL/api/v1/crm/fields/<id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"label":"string","options":["string"],"position":0,"required":false}'delete/api/v1/crm/fields/{id}Arquiva um campo personalizadoSó a chave da plataforma
O valor salvo nos negócios fica; a chave não pode ser gravada de novo.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) |
Respostas
204Arquivado.401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Campo inexistente ou já arquivado (not_found).json{ "error": "invalid request" }
Exemplo
curl -X DELETE "$API_URL/api/v1/crm/fields/<id>" \
-H "Authorization: Bearer $API_KEY"get/api/v1/crm/pipelinesLista os funisSó a chave da plataforma
Os funis não arquivados, por position, cada um com as etapas: as abertas por position, depois a de ganho e a de perda. Um funil arquivado sai da lista; os negócios dele ficam e continuam acessíveis pelo id.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Respostas
200Os funis.json{ "pipelines": [ { "archived_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "name": "string", "position": 0, "stages": [ { "color": "", "id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "kind": "open", "name": "Proposta", "position": 2 } ] } ] }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/pipelines" \
-H "Authorization: Bearer $API_KEY"post/api/v1/crm/pipelinesCria um funilSó a chave da plataforma
O funil nasce com as etapas Novo, Qualificado, Proposta, Negociação (abertas), Ganho e Perdido; ganho e perdido ficam sempre no fim e não podem ser removidas. Entra no fim da lista.
Plano. max_pipelines conta os funis não arquivados: ausente = sem limite; 0 = nenhum funil. No limite: 403 plan_limit.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
nameobrigatório | string | Sem espaços nas pontas. |
{
"name": "string"
}Respostas
201O funil criado, com as etapas.json{ "archived_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "name": "string", "position": 0, "stages": [ { "color": "", "id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "kind": "open", "name": "Proposta", "position": 2 } ] }400Corpo inválido (invalid_body: JSON malformado ou campo desconhecido) ou nome vazio ou acima de 200 caracteres (invalid_name).json{ "code": "invalid_body", "error": "invalid JSON body" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Limitemax_pipelinesdo plano (plan_limit), funçãocrm_enabledfora do plano (plan_feature_disabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/pipelines" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"string"}'patch/api/v1/crm/pipelines/{id}Edita um funilSó a chave da plataforma
Renomeia, muda a posição ou arquiva (archived: true) e desarquiva (archived: false) o funil. Arquivado, ele sai da lista; os negócios dele ficam. Desarquivar volta a contar no max_pipelines, sob a mesma trava da criação. A resposta traz o funil mesmo arquivado.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do funil. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
archivedopcional | boolean | null | true arquiva (sai da lista; os negócios ficam); false desarquiva. |
nameopcional | string | null | |
positionopcional | integer | null |
{
"archived": false,
"name": "string",
"position": 0
}Respostas
200O funil.json{ "archived_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "name": "string", "position": 0, "stages": [ { "color": "", "id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "kind": "open", "name": "Proposta", "position": 2 } ] }400Corpo inválido (invalid_body), nome inválido (invalid_name) ou posição negativa (invalid_position).json{ "code": "invalid_body", "error": "invalid JSON body" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Desarquivar acima do limitemax_pipelinesdo plano (plan_limit; o funil continua arquivado), funçãocrm_enabledfora do plano (plan_feature_disabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Funil inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "pipeline not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X PATCH "$API_URL/api/v1/crm/pipelines/<id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"archived":false,"name":"string","position":0}'get/api/v1/crm/pipelines/{id}/reportRelatórios do funilSó a chave da plataforma
Os relatórios do funil num período, cada bloco numa consulta agregada, a partir do histórico dos negócios: a conversão por etapa, o tempo em cada etapa (as estadas que terminaram no período: mediana e média, em dias), os ganhos e as perdas (contagem e valor por moeda, os motivos das perdas) e o valor ganho por período (group) e por responsável. Os valores nunca somam moedas diferentes. Os períodos e as datas são em UTC. Aceita os filtros owner e instance_id (como o resumo), e também tag e q.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do funil. |
fromopcional | query | string | Início, RFC 3339 ou YYYY-MM-DD (UTC). Ausente = 30 dias antes de to. |
toopcional | query | string | Fim (exclusivo), RFC 3339 ou YYYY-MM-DD (o fim desse dia, UTC). Ausente = agora. No máximo 366 dias depois de from. |
groupopcional | query | "day" | "week" | "month" | Os períodos do valor ganho (a semana começa na segunda). |
owneropcional | query | string | Só deste responsável. |
instance_idopcional | query | array<string (uuid)> | Só os negócios cujo contato tem conversa em algum destes números (inbox_conversations, pelo telefone do contato; repetível: instance_id=a&instance_id=b, até 100). Negócio sem contato fica fora. É o alcance "numbers" do SaaS. |
Respostas
200Os relatórios.json{ "conversion": [ { "advanced": 0, "entered": 0, "kind": "open", "name": "string", "rate": 0, "stage_id": "00000000-0000-4000-8000-000000000000" } ], "from": "2026-01-01T12:00:00Z", "group": "day", "outcomes": { "lost": { "count": 0, "value_cents_by_currency": {} }, "lost_reasons": [ { "count": 0, "reason": "string" } ], "won": { "count": 0, "value_cents_by_currency": {} } }, "pipeline_id": "00000000-0000-4000-8000-000000000000", "time_in_stage": [ { "avg_days": 0, "kind": "string", "median_days": 0, "name": "string", "stage_id": "00000000-0000-4000-8000-000000000000", "stays": 0 } ], "to": "2026-01-01T12:00:00Z", "won_by_owner": [ { "count": 0, "value_cents_by_currency": {}, "owner": "string" } ], "won_by_period": [ { "count": 0, "value_cents_by_currency": {}, "period": "string" } ] }400Período inválido (invalid_period),groupinválido (invalid_group) ouinstance_idinválido (invalid_instance).json{ "error": "invalid request" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Funil inexistente, ou id que não é UUID (not_found).json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/pipelines/<id>/report" \
-H "Authorization: Bearer $API_KEY"post/api/v1/crm/pipelines/{id}/stagesCria uma etapaSó a chave da plataforma
Adiciona uma etapa aberta no fim das abertas (ganho e perdido continuam no fim). Só etapas abertas podem ser criadas: cada funil tem uma etapa de ganho e uma de perda.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do funil. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
coloropcional | string | |
kindopcional | "" | "open" | Só open (ou ausente): cada funil tem uma etapa de ganho e uma de perda. |
nameobrigatório | string |
{
"color": "string",
"kind": "",
"name": "string"
}Respostas
201A etapa criada.json{ "color": "", "id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "kind": "open", "name": "Proposta", "position": 2 }400Corpo inválido (invalid_body), nome inválido (invalid_name),kinddiferente deopen(invalid_kind) ou cor acima de 32 caracteres (invalid_color).json{ "code": "invalid_color", "error": "color is limited to 32 characters" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Funil inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "pipeline not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/crm/pipelines/<id>/stages" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"color":"string","kind":"","name":"string"}'put/api/v1/crm/pipelines/{id}/stages/orderReordena as etapas abertasSó a chave da plataforma
Define a ordem das etapas abertas. stage_ids tem de ser exatamente as etapas abertas do funil, cada uma uma vez; ganho e perdido não entram e ficam no fim.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do funil. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
stage_idsobrigatório | array<string (uuid)> | Todas as etapas abertas do funil, cada uma uma vez, na ordem nova. |
{
"stage_ids": [
"00000000-0000-4000-8000-000000000000"
]
}Respostas
200O funil, com as etapas na ordem nova.json{ "archived_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "name": "string", "position": 0, "stages": [ { "color": "", "id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "kind": "open", "name": "Proposta", "position": 2 } ] }400Corpo inválido (invalid_body) oustage_idsque não é exatamente o conjunto das etapas abertas (invalid_stage_ids).json{ "code": "invalid_body", "error": "invalid JSON body" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Funil inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "pipeline not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X PUT "$API_URL/api/v1/crm/pipelines/<id>/stages/order" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage_ids":["00000000-0000-4000-8000-000000000000"]}'get/api/v1/crm/pipelines/{id}/summaryResumo do funil por etapaSó a chave da plataforma
Cada etapa do funil, na ordem do kanban (abertas, ganho, perdido), com a quantidade de negócios e a soma dos valores por moeda, numa consulta agregada só. É o total real de cada coluna: a lista é paginada. Aceita os filtros da lista (owner, status, tag, q, instance_id); pipeline_id e stage_id não se aplicam aqui. Um negócio sem valor conta em count e não soma nada; uma etapa sem negócios vem com count: 0 e value_cents_by_currency vazio.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id do funil. |
owneropcional | query | string | Só deste responsável. |
statusopcional | query | "open" | "won" | "lost" | Abertos, ganhos ou perdidos; ausente = todos. |
tagopcional | query | string | Só os de contato com esta tag. |
qopcional | query | string | Busca no título e no nome do contato (sem caixa) e no telefone do contato. |
instance_idopcional | query | array<string (uuid)> | Só os negócios cujo contato tem conversa em algum destes números (inbox_conversations, pelo telefone do contato; repetível: instance_id=a&instance_id=b, até 100). Negócio sem contato fica fora. É o alcance "numbers" do SaaS. |
Respostas
200As etapas do funil com as contas.json{ "stages": [ { "count": 3, "stage_id": "8a1c1f6e-6f0e-4c0e-9d5b-1d2a3b4c5d6e", "value_cents_by_currency": { "BRL": 5000, "USD": 10000 } }, { "count": 0, "stage_id": "9b2d2a7f-7a1f-4d1f-8e6c-2e3b4c5d6e7f", "value_cents_by_currency": {} } ] }400Filtro inválido:status(invalid_status) ouinstance_id(invalid_instance).json{ "code": "invalid_instance", "error": "instance_id must be a number's id" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Funil inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "pipeline not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/pipelines/<id>/summary" \
-H "Authorization: Bearer $API_KEY"patch/api/v1/crm/stages/{id}Edita uma etapaSó a chave da plataforma
Renomeia ou muda a cor de uma etapa (inclusive a de ganho e a de perda). A ordem muda por PUT /api/v1/crm/pipelines/{id}/stages/order.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id da etapa. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
coloropcional | string | null | |
nameopcional | string | null |
{
"color": "string",
"name": "string"
}Respostas
200A etapa.json{ "color": "", "id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b", "kind": "open", "name": "Proposta", "position": 2 }400Corpo inválido (invalid_body), nome inválido (invalid_name) ou cor acima de 32 caracteres (invalid_color).json{ "code": "invalid_color", "error": "color is limited to 32 characters" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Etapa inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "stage not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X PATCH "$API_URL/api/v1/crm/stages/<id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"color":"string","name":"string"}'delete/api/v1/crm/stages/{id}Remove uma etapaSó a chave da plataforma
Remove uma etapa aberta; a de ganho e a de perda não são removidas. Se a etapa tem negócios, move_to é obrigatório: eles vão para o fim da coluna dessa etapa aberta do mesmo funil, na ordem em que estavam, cada um com um evento stage (o actor vem do X-WAAPI-Actor).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id da etapa. |
move_toopcional | query | string (uuid) | Etapa aberta do mesmo funil que recebe os negócios. Obrigatório quando a etapa tem negócios. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Respostas
204Etapa removida.400Etapa de ganho ou de perda (invalid_stage), oumove_toque não é etapa aberta (invalid_stage).json{ "code": "invalid_stage", "error": "move_to must be an open stage" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Etapa inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "stage not found" }409A etapa tem negócios e faltamove_to(stage_has_deals), oumove_tonão é outra etapa do mesmo funil (stage_not_in_pipeline).json{ "code": "stage_not_in_pipeline", "error": "move_to must be another stage of the same pipeline" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X DELETE "$API_URL/api/v1/crm/stages/<id>" \
-H "Authorization: Bearer $API_KEY"get/api/v1/crm/tasksMinhas tarefasSó a chave da plataforma
As tarefas de todos os negócios, por responsável e estado. Sem status: as abertas. overdue: abertas com o prazo antes de agora; today: abertas com o prazo de agora até o fim de hoje no fuso tz; upcoming: abertas com o prazo depois de hoje ou sem prazo; done: as concluídas, a mais recente primeiro. As abertas vêm pelo prazo (sem prazo por último). Paginada por cursor.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
owneropcional | query | string | Só deste responsável. |
statusopcional | query | "overdue" | "today" | "upcoming" | "done" | |
tzopcional | query | string | Fuso IANA do "hoje" (por exemplo America/Sao_Paulo). |
limitopcional | query | integer | |
cursoropcional | query | string | O next_cursor da página anterior. |
Respostas
200Uma página de tarefas.json{ "next_cursor": "string", "tasks": [ { "created_at": "2026-01-01T12:00:00Z", "deal_id": "00000000-0000-4000-8000-000000000000", "deal_title": "string", "done": false, "done_at": "2026-01-01T12:00:00Z", "due_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "overdue": false, "owner": "string", "title": "string", "updated_at": "2026-01-01T12:00:00Z" } ] }400status(invalid_status),tz(invalid_tz),limit(invalid_limit) oucursor(invalid_cursor) inválido.json{ "code": "invalid_status", "error": "status must be overdue, today, upcoming or done" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/crm/tasks" \
-H "Authorization: Bearer $API_KEY"patch/api/v1/crm/tasks/{id}Edita, conclui ou reabre uma tarefaSó a chave da plataforma
done: true conclui (evento task_done); false reabre (evento task_reopened), dentro do limite de 50 abertas. Concluir uma tarefa já concluída não grava evento.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id da tarefa. |
X-WAAPI-Actoropcional | header | string | Quem fez a mudança: texto opaco de até 200 caracteres (o SaaS manda o id da pessoa). Vira o actor do histórico. Ausente, vazio, mais longo ou com NUL = api. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
doneopcional | boolean | true conclui (evento task_done), false reabre (task_reopened, dentro do limite de 50 abertas). |
due_atopcional | string | RFC 3339; "" tira o prazo. |
owneropcional | string | "" tira o responsável. |
titleopcional | string |
{
"done": false,
"due_at": "string",
"owner": "string",
"title": "string"
}Respostas
200A tarefa.json{ "created_at": "2026-01-01T12:00:00Z", "deal_id": "00000000-0000-4000-8000-000000000000", "deal_title": "string", "done": false, "done_at": "2026-01-01T12:00:00Z", "due_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "overdue": false, "owner": "string", "title": "string", "updated_at": "2026-01-01T12:00:00Z" }400Corpo inválido ou vazio (invalid_body),invalid_title,invalid_due_atouinvalid_owner.json{ "code": "invalid_body", "error": "nothing to change" }401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Tarefa inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "task not found" }409Reabrir passaria de 50 tarefas abertas (too_many_tasks).json{ "code": "too_many_tasks", "error": "a deal has at most 50 open tasks" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X PATCH "$API_URL/api/v1/crm/tasks/<id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"done":false,"due_at":"string","owner":"string","title":"string"}'delete/api/v1/crm/tasks/{id}Apaga uma tarefaSó a chave da plataforma
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | Id da tarefa. |
Respostas
204Apagada.401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Tarefa inexistente, ou id que não é UUID (not_found).json{ "code": "not_found", "error": "task not found" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (crm_unavailable, sem detalhes do banco).json{ "code": "crm_unavailable", "error": "crm operation failed" }503Banco indisponível.json{ "error": "crm storage unavailable" }
Exemplo
curl -X DELETE "$API_URL/api/v1/crm/tasks/<id>" \
-H "Authorization: Bearer $API_KEY"get/api/v1/events/streamEventos em tempo real (SSE)Chave de API
Um fluxo text/event-stream de eventos pequenos, com o tipo e os ids: inbox.message, inbox.conversation, crm.deal e crm.task. Cada evento vem como id: <n>, event: <tipo> e data: {"type","instance_id","data"}, e um comentário : ping sai a cada 25 s. Os eventos saem por LISTEN/NOTIFY do Postgres, depois do commit de quem gravou, em qualquer processo. Com Last-Event-ID, o fluxo retoma pelos eventos que chegaram depois daquele id (os últimos 500 ou 5 min; os ids podem chegar fora de ordem, então a retomada é pela ordem de chegada); se o id já não está guardado, vem event: reset. Um fluxo que não acompanha (256 eventos sem ler) é fechado, e o cliente reconecta com Last-Event-ID. A chave global recebe tudo; a chave de cliente com o escopo numbers recebe só inbox.message dos números dela. No máximo 10 fluxos por chave de cliente e 50 para a chave global.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
Last-Event-IDopcional | header | string | O id do último evento recebido, para retomar. |
Respostas
200O fluxo de eventos.jsonid: 42 event: crm.deal data: {"type":"crm.deal","instance_id":"","data":{"deal_id":"…","pipeline_id":"…","stage_id":"…","change":"stage"}}401Sem a chave global (a chave de instância e a de cluster não valem aqui).json{ "error": "unauthorized: missing or invalid API key" }403Funçãocrm_enabledfora do plano (plan_feature_disabled), chave de cliente (CLIENT_KEY_SCOPE): o CRM é só da chave global, ou, numa escrita (POST,PUT,PATCH,DELETE), a conta suspensa ou cancelada (ACCOUNT_SUSPENDED); as leituras seguem abertas.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }429Mais de 10 fluxos abertos com a mesma chave (too_many_streams), ou o limite de requisições.json{ "error": "invalid request" }503O tempo real não está disponível (sem banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/events/stream" \
-H "Authorization: Bearer $API_KEY"Proxy
O proxy de saída do número: consultar, trocar o endereço e escolher o país.
get/api/v1/instances/{id}/proxyVer o proxy da instânciaChave de API
Mostra o proxy atual da instância e os países disponíveis no provedor (webshare.io). Liberada mesmo com proxy_enabled=false no plano. enabled = a API tem a chave do provedor e o plano inclui proxy_enabled. countries só vem com enabled e quando o provedor respondeu; caso contrário é null. current vem sem usuário/senha (http://•••@host:porta) e vazio quando enabled é false ou o número não tem proxy (com o plano sem proxy, o número conecta sem proxy). Também com a chave de cliente com numbers e o número na lista dela.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Proxy da instância.json{ "countries": { "BR": 120, "US": 900 }, "country": "BR", "current": "http://•••@203.0.113.10:8080", "enabled": true, "provider": "webshare.io" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/proxy" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/proxy/countryDefinir o país do proxyChave do número ou do cluster
Grava o país do proxy e tenta buscar um proxy desse país para a sessão. Se o provedor falhar, o país fica gravado e a resposta é 200 sem proxy. Barrada com 403 plan_feature_disabled sem proxy_enabled; 400 proxy not configured sem chave do provedor; 400 country required sem country. Mudar o país conta como uma troca do mês (max_proxy_rotations_per_month, reservada antes; acima do teto 403 plan_limit, uso ilegível 503 usage_unavailable) e reconecta o número.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
countryobrigatório | string |
{
"country": "BR"
}Respostas
200País gravado.json{ "country": "string", "proxy": "string", "status": "string" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Proxy fora do plano (plan_feature_disabled), trocas do mês esgotadas (plan_limit,max_proxy_rotations_per_month) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }503Não foi possível ler o uso do plano (usage_unavailable); tente de novo.json{ "code": "usage_unavailable", "error": "Could not check the plan usage. Try again later." }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/proxy/country" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"country":"BR"}'put/api/v1/instances/{id}/proxy/customUsar o proxy próprio no númeroChave de API
O número passa a conectar pelo proxy do cliente (http://, https:// ou socks5://, com usuário e senha opcionais). Exige custom_proxy_enabled no plano (ausente = não incluído; 403 plan_feature_disabled). O host passa pela mesma guarda de endereço público da base_url das chaves de IA (sem loopback, rede privada, link-local, metadados de nuvem, CGNAT, IPv6 interno nem nome interno); sem caminho, query ou fragmento: 400 invalid_proxy_url com o motivo. Antes de trocar, a API abre um túnel até o WhatsApp pelo proxy: se falhar, 400 proxy_unreachable com o motivo e nada muda. Aceito, é cifrado com a configuração do servidor (sem ela, 503 secrets_key_missing), conta como uma troca do mês (max_proxy_rotations_per_month) e reconecta o número. O provedor nunca recebe o proxy próprio. A resposta e os logs nunca trazem o usuário nem a senha. Também com a chave de cliente com numbers e o número na lista dela.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
urlobrigatório | string |
{
"url": "http://usuario:senha@proxy.example.com:8080"
}Respostas
200Em uso; o proxy do número.json{ "countries": { "BR": 120, "US": 900 }, "country": "BR", "current": "http://•••@203.0.113.10:8080", "enabled": true, "provider": "webshare.io" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Proxy próprio fora do plano (plan_feature_disabled), trocas do mês esgotadas (plan_limit) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "plan_limit", "error": "Plan limit reached: max_instances.", "limit": "max_instances" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }503sem a chave de cifra do servidor (secrets_key_missing) ou uso do plano ilegível (usage_unavailable).json{ "error": "invalid request" }
Exemplo
curl -X PUT "$API_URL/api/v1/instances/<id>/proxy/custom" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"http://usuario:senha@proxy.example.com:8080"}'delete/api/v1/instances/{id}/proxy/customVoltar ao proxy do provedorChave de API
Apaga o proxy próprio do número e o reconecta pelo proxy do provedor (ou sem proxy). Também com a chave de cliente com numbers e o número na lista dela.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200O proxy do número depois de apagar.json{ "countries": { "BR": 120, "US": 900 }, "country": "BR", "current": "http://•••@203.0.113.10:8080", "enabled": true, "provider": "webshare.io" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }
Exemplo
curl -X DELETE "$API_URL/api/v1/instances/<id>/proxy/custom" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/proxy/rotateTrocar o proxy da instânciaChave do número ou do cluster
Busca um novo proxy no provedor (sticky por instância: um número, um IP) e o aplica à sessão. O país vem do campo de formulário country ou, na falta dele, da query country; vazio = qualquer país. Barrada com 403 plan_feature_disabled quando o plano não inclui proxy_enabled. Responde 400 proxy not configured quando a sua API não tem chave do provedor e 500 com a mensagem do provedor quando ele falha. Troca o IP de verdade: vai para o próximo proxy válido do pool, com outro endereço, grava e reconecta o número; sem outro IP no pool, 409 NO_OTHER_PROXY. Cada troca reserva uma unidade de max_proxy_rotations_per_month (mês UTC) antes; acima do teto 403 plan_limit, uso ilegível 503 usage_unavailable; uma troca que falha não conta.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
countryopcional | query | string | Código do país (alternativa ao campo de formulário). |
Corpo (application/x-www-form-urlencoded)
| Campo | Tipo | Descrição |
|---|---|---|
countryopcional | string | Código do país do proxy. |
{
"country": "BR"
}Respostas
200Proxy trocado.json{ "country": "string", "current": "string", "enabled": false, "provider": "string" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Proxy fora do plano (plan_feature_disabled), trocas do mês esgotadas (plan_limit,max_proxy_rotations_per_month) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409Não há outro IP no pool do provedor (NO_OTHER_PROXY); o proxy atual fica. Tambémprovider_disabledsem o número por QR na instalação, ouprovider_unsupportednum número oficial.json{ "code": "NO_OTHER_PROXY", "error": "no other valid proxy in the pool to rotate to" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Não foi possível ler o uso do plano (usage_unavailable); tente de novo.json{ "code": "usage_unavailable", "error": "Could not check the plan usage. Try again later." }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/proxy/rotate" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d '{"country":"BR"}'get/api/v1/settings/proxyVer o provedor de proxy configuradoSó a chave da plataforma
O provedor em uso: o salvo por esta rota (source settings) vence o das variáveis de ambiente (source env); sem nenhum, provider e source são null. A chave nunca volta inteira: só os 4 últimos caracteres. Só a chave global.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Respostas
200O provedor em uso.json{ "api_key_last4": "9f3a", "plan_id": "12345", "provider": "webshare", "source": "settings", "updated_at": "2026-11-07T10:00:00Z" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }
Exemplo
curl -X GET "$API_URL/api/v1/settings/proxy" \
-H "Authorization: Bearer $API_KEY"put/api/v1/settings/proxyConfigurar o provedor de proxySó a chave da plataforma
Salva o provedor (webshare), a chave e o plano. A chave é cifrada com a configuração do servidor; sem ela, 503 secrets_key_missing e nada é gravado. Mandar a chave mascarada (como a leitura devolve) ou omiti-la mantém a salva, só para o mesmo provedor (senão 400 MASKED_SECRET_NEW_DESTINATION ou api_key_required). Os números conectados mantêm o proxy atual: a chave nova vale na próxima troca de IP. Só a chave global.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
api_keyopcional | string | |
plan_idopcional | string | |
providerobrigatório | string |
{
"api_key": "string",
"plan_id": "string",
"provider": "string"
}Respostas
200Salvo; o provedor em uso.json{ "api_key_last4": "9f3a", "plan_id": "12345", "provider": "webshare", "source": "settings", "updated_at": "2026-11-07T10:00:00Z" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }503sem a chave de cifra do servidor (secrets_key_missing) ou o banco indisponível.json{ "error": "invalid request" }
Exemplo
curl -X PUT "$API_URL/api/v1/settings/proxy" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"api_key":"string","plan_id":"string","provider":"string"}'delete/api/v1/settings/proxyVoltar ao provedor das variáveis de ambienteSó a chave da plataforma
Apaga o provedor salvo; vale de novo o das variáveis de ambiente (ou nenhum). Só a chave global.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Respostas
200O provedor em uso depois de apagar.json{ "api_key_last4": "9f3a", "plan_id": "12345", "provider": "webshare", "source": "settings", "updated_at": "2026-11-07T10:00:00Z" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }
Exemplo
curl -X DELETE "$API_URL/api/v1/settings/proxy" \
-H "Authorization: Bearer $API_KEY"Webhook do número
Os destinos que recebem os eventos de mensagem do número.
get/api/v1/instances/{id}/webhookVer os destinos de webhookChave do número ou do cluster
Destinos de webhook deste número (targets), com a URL mascarada e o tipo de assinatura (signing), sem o segredo; e, só para leitura, os destinos globais da sua API (global_targets, configurados no servidor) com a URL reduzida a esquema e host.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Destinos do número e globais.json{ "global_targets": [ { "events": [ "message" ], "url": "https://hooks.example.com" } ], "targets": [ { "events": [ "*" ], "signing": "own", "url": "https://hooks.example.com/services/T0…CD/B0…GH/abcd…uvwx" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/webhook" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/webhookSubstituir os destinos de webhookChave do número ou do cluster
Substitui a lista de destinos deste número: só os eventos dele vão para lá. Fica gravada (volta depois de reiniciar); falha ao gravar = 500 WEBHOOK_NOT_STORED e nada muda. events vazio ou omitido = todos (*). targets: [] limpa. Os destinos globais (variáveis de ambiente) não mudam por aqui; uma URL nas duas listas recebe o evento uma vez.
Limite do plano. max_webhooks é o total de destinos somando todos os números da API. Só um salvamento que aumenta os destinos deste número é barrado acima do teto (403 plan_limit, max_webhooks); manter, editar ou remover sempre passa. Com a conta suspensa ou cancelada, o mesmo salvamento que aumenta os destinos dá 403 ACCOUNT_SUSPENDED.
Segredo por destino. Um destino novo ganha um segredo de assinatura próprio (whsec_…), devolvido só nesta resposta (secret). Um destino que já estava gravado (mesma URL, ou a URL mascarada como veio do GET, literal ou percent-codificada como %E2%80%A6/%E2%80%A2) mantém o segredo e não o mostra de novo. Uma URL mascarada que não corresponde a nenhum destino gravado: 400 masked webhook url does not match a saved destination. Uma URL mascarada que corresponde a mais de um destino gravado (URLs diferentes com a mesma máscara, como ?client=1 e ?client=2, que leem ?client=••••): 400 AMBIGUOUS_MASKED_TARGET e nada é gravado; mande a URL inteira desses destinos. Destino gravado antes desta versão continua assinado com o segredo comum do servidor (signing: deployment) até ter o segredo girado em POST /api/v1/instances/{id}/webhook/rotate-secret. Uma URL nas duas listas (número e global) recebe o evento uma vez, assinada como a do número.
Cada url é validada e normalizada (esquema e host em minúsculas) antes de gravar; se uma falhar, responde 400 com a mensagem estável e nada é salvo:
| Regra | Mensagem |
|---|---|
| URL ausente ou em branco | webhook url is required |
| URL que não parseia | webhook url is invalid |
Esquema diferente de https (http só em desenvolvimento) | webhook url must be https |
user:pass@ na URL | webhook url must not include credentials |
| Host vazio | webhook url host is required |
| Porta abaixo de 1024 que não seja a padrão do esquema | webhook url port is not allowed |
IP literal interno (loopback, RFC 1918, ULA, link-local/metadados, CGNAT, multicast, não especificado, IPv4 embutido em IPv6) ou nome interno (localhost, *.localhost, *.local, *.internal, *.intranet, *.lan, *.home.arpa) | webhook url must not point to a private address |
Na entrega as mesmas regras são refeitas, mais DNS no envio, checagem no dialer (rebinding) e até 2 redirects. events filtra os eventos (* = todos; hoje o evento emitido é message); events vazio ou ausente é gravado como * (todos). Para parar de receber, tire o destino da lista. Corpo: event, timestamp, instance_id, data; header X-WAAPI-Event e X-WAAPI-Signature (HMAC-SHA256 do corpo com o segredo do destino; ver signing).
Conferir a assinatura. X-WAAPI-Signature = HMAC-SHA256 do corpo bruto, em hexadecimal, com o segredo do destino. Calcule sobre os bytes recebidos (antes de interpretar o JSON) e compare em tempo constante. Node: crypto.timingSafeEqual(Buffer.from(sig,'hex'), crypto.createHmac('sha256', secret).update(rawBody).digest()). Python: hmac.compare_digest(sig, hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()).
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
targetsobrigatório | array<object> | Lista nova completa; [] remove todos os destinos. Ausente ou null = 400 invalid targets. |
targets[].eventsopcional | array | null | Eventos enviados a este destino; * = todos. Vazio, null ou ausente = todos (gravado como *). |
targets[].urlopcional | string (uri) | Destino http(s) público: sem usuário/senha na URL, sem host interno (localhost, *.local, *.internal…) nem IP privado, loopback, link-local ou CGNAT, porta padrão ou >= 1024. Conferido de novo após o DNS e a cada redirect. |
{
"targets": [
{
"events": [
"*"
],
"url": "https://hooks.example.com/waapi"
}
]
}Respostas
200Destinos gravados (URL mascarada);secretsó nos destinos criados agora.json{ "status": "updated", "targets": [ { "events": [ "*" ], "secret": "whsec_0000000000000000000000000000000000000000000000000000000000000000", "signing": "own", "url": "https://hooks.example.com/services/T0…CD/B0…GH/abcd…uvwx" } ] }400Corpo inválido (invalid targets), URL recusada (mensagens da tabela), URL mascarada que não corresponde a um destino gravado ou que corresponde a mais de um (AMBIGUOUS_MASKED_TARGET).json{ "code": "AMBIGUOUS_MASKED_TARGET", "error": "masked webhook url matches more than one saved destination; send the full url" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit,max_webhooks) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED) num salvamento com mais destinos que os gravados.json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Falha ao gravar (WEBHOOK_NOT_STORED): nada muda.json{ "code": "WEBHOOK_NOT_STORED", "error": "webhook not updated: could not store it" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/webhook" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"targets":[{"events":["*"],"url":"https://hooks.example.com/waapi"}]}'post/api/v1/instances/{id}/webhook/rotate-secretGirar o segredo de assinaturaChave do número ou do cluster
Dá um segredo novo a um destino deste número (url, como gravada ou mascarada como veio do GET) ou, sem url (corpo vazio), a todos os destinos dele. Uma URL mascarada que corresponde a mais de um destino é 400 AMBIGUOUS_MASKED_TARGET (mande a URL inteira ou gire todos). O segredo novo vem só nesta resposta e vale na hora: o anterior deixa de assinar. Gravado antes de valer; falha ao gravar = 500 WEBHOOK_NOT_STORED e nada muda. É também como um destino antigo (signing: deployment) passa a ter segredo próprio.
Conferir a assinatura. X-WAAPI-Signature = HMAC-SHA256 do corpo bruto, em hexadecimal, com o segredo do destino. Calcule sobre os bytes recebidos (antes de interpretar o JSON) e compare em tempo constante. Node: crypto.timingSafeEqual(Buffer.from(sig,'hex'), crypto.createHmac('sha256', secret).update(rawBody).digest()). Python: hmac.compare_digest(sig, hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()).
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
urlopcional | string | Destino a girar; ausente ou vazio = todos. |
{}Respostas
200Todos os destinos do número;secretsó nos girados agora.json{ "status": "rotated", "targets": [ { "events": [ "*" ], "secret": "whsec_1111111111111111111111111111111111111111111111111111111111111111", "signing": "own", "url": "https://hooks.example.com/services/T0…CD/B0…GH/abcd…uvwx" } ] }400Corpo ilegível (invalid body) ou URL mascarada que corresponde a mais de um destino (AMBIGUOUS_MASKED_TARGET).json{ "code": "AMBIGUOUS_MASKED_TARGET", "error": "masked webhook url matches more than one saved destination; send the full url" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Número inexistente, ou nenhum destino com essaurl(ou nenhum destino) (WEBHOOK_NOT_FOUND).json{ "code": "WEBHOOK_NOT_FOUND", "error": "webhook destination not found" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Falha ao gravar (WEBHOOK_NOT_STORED): nada muda.json{ "code": "WEBHOOK_NOT_STORED", "error": "webhook not updated: could not store it" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/webhook/rotate-secret" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{}'post/api/v1/instances/{id}/webhook/testTestar um destino gravadoChave do número ou do cluster
Manda um evento de teste a um destino já gravado deste número. A url é a gravada ou a mascarada como veio do GET (literal ou percent-codificada, %E2%80%A6/%E2%80%A2), resolvida como na edição.
O evento vai para a URL real gravada, assinado com o segredo daquele destino (ou com o segredo comum do servidor, se ele não tem segredo próprio), pela mesma entrega e proteção de rede dos eventos normais. O filtro events não vale para o teste. Corpo entregue: {"event":"webhook.test","timestamp","instance_id","data":{"test":true}}, com X-WAAPI-Event: webhook.test e X-WAAPI-Signature.
O receptor falhar não é erro da rota: 200 com ok: false. A resposta nunca traz a URL real nem o segredo. Só destinos gravados são testados: uma URL que não está gravada é 404, sem nenhuma chamada. A chave de cliente é negada.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
urlobrigatório | string | Destino gravado, como gravado ou mascarado como veio do GET. |
{
"url": "https://hooks.example.com/w?client=%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2"
}Respostas
200O teste foi feito.oksó com resposta 2xx do receptor;status= código HTTP do receptor ou0quando nada respondeu;errorvazio no sucesso, senão um texto curto (receiver answered 500, a regra que recusou o destino,webhook target could not be resolved,webhook redirect refused,webhook stopped after too many redirects,webhook target timed out,webhook target could not be reached).json{ "duration_ms": 182, "error": "", "ok": true, "status": 200 }400Corpo ilegível ou semurl(INVALID_BODY), ou URL mascarada que corresponde a mais de um destino (AMBIGUOUS_MASKED_TARGET).json{ "code": "AMBIGUOUS_MASKED_TARGET", "error": "masked webhook url matches more than one saved destination; send the full url" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Número inexistente (not found), ou nenhum destino gravado com essaurl(WEBHOOK_TARGET_NOT_FOUND).json{ "code": "WEBHOOK_TARGET_NOT_FOUND", "error": "webhook destination not found" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite próprio do teste: no máximo 6 testes por número em qualquer minuto (WEBHOOK_TEST_RATE_LIMITED, comRetry-Afterem segundos até o mais antigo sair do minuto), sem nenhuma chamada ao destino. Só conta o teste que ia enviar: um 400 ou 404 não conta. O limite comum da API continua valendo (rate limit exceeded).json{ "code": "WEBHOOK_TEST_RATE_LIMITED", "error": "too many webhook tests for this number, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/webhook/test" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.example.com/w?client=%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2"}'Chatwoot
A integração com o Chatwoot: configuração, caixa de entrada, registros e o recebedor de eventos.
get/api/v1/instances/{id}/chatwootVer a integração ChatwootChave do número ou do cluster
Devolve a configuração Chatwoot da instância. Sem configuração, responde só {"enabled": false}. api_token e webhook_token vêm mascarado (primeiros e últimos 4 caracteres com …, ou ••••); mandar de volta o valor mascarado mantém o salvo.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Configuração (ou{"enabled": false}quando não há).json{ "account_id": "string", "api_token": "string", "base_url": "string", "created_at": "2026-01-01T12:00:00Z", "enabled": false, "inbox_id": "string", "inbox_name": "string", "instance_id": "string", "source_name": "string", "updated_at": "2026-01-01T12:00:00Z", "webhook_token": "string" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/chatwoot" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/chatwootLigar ou editar a integração ChatwootChave do número ou do cluster
Grava a integração. Sem webhook_token, a API gera um. A caixa (inbox) de API no Chatwoot é: a de inbox_id quando informada; senão a já gravada; senão uma nova criada agora (falha na criação = 400 failed to create inbox: …). Nos dois primeiros casos nome e URL de webhook da caixa são sincronizados no Chatwoot (falha só vai ao log). A URL de webhook registrada é <esquema>://<host da requisição>/webhooks/chatwoot?token=<webhook_token> (esquema de X-Forwarded-Proto quando presente). inbox_name padrão = primeiro bloco do ID da instância; source_name padrão = whatsapp. Barrada com 403 plan_feature_disabled sem chatwoot_enabled no plano. Com a conta suspensa ou cancelada, criar a integração ou ligá-la (enabled: true) dá 403 ACCOUNT_SUSPENDED; desligar a existente (enabled: false) e o DELETE continuam. Um número ainda sem integração acima de max_chatwoot_integrations (contam as configuradas, ligadas ou não) recebe 403 plan_limit antes de qualquer chamada ao Chatwoot; editar ou desligar a de um número que já tem não pede vaga. api_token e webhook_token enviados mascarados (como o GET devolve) mantêm os valores gravados só se o destino não muda: com outra base_url (comparada sem a barra final e sem diferença de maiúsculas no host) ou outra account_id, 400 MASKED_SECRET_NEW_DESTINATION, e é preciso mandar o token de novo (o token gravado iria para o servidor novo). Sem configuração gravada, 400. A resposta devolve os dois mascarados.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
account_idobrigatório | string | |
api_tokenobrigatório | string | Token de acesso de um usuário/agente do Chatwoot. Valor mascarado (como veio do GET) mantém o gravado. |
base_urlobrigatório | string | URL do Chatwoot (a barra final é removida). |
enabledopcional | boolean | |
inbox_idopcional | string | Caixa existente a usar; vazio reaproveita a gravada ou cria uma nova. |
inbox_nameopcional | string | |
source_nameopcional | string | |
webhook_tokenopcional | string | Credencial de /webhooks/chatwoot; vazio = gerado pela API. Valor mascarado mantém o gravado. |
{
"account_id": "1",
"api_token": "string",
"base_url": "https://chatwoot.example.com",
"enabled": false,
"inbox_id": "string",
"inbox_name": "string",
"source_name": "whatsapp",
"webhook_token": "string"
}Respostas
200Configuração gravada.json{ "account_id": "string", "api_token": "string", "base_url": "string", "enabled": false, "inbox_id": "string", "inbox_name": "string", "source_name": "string", "webhook_token": "string" }400Faltambase_url,account_idouapi_token, a caixa não pôde ser criada, um token mascarado (como o GET o devolve) foi enviado sem configuração gravada, ou com outrabase_urlouaccount_id(MASKED_SECRET_NEW_DESTINATION; nada muda).json{ "error": "base_url, account_id and api_token required" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite ou função do plano (plan_limit/plan_feature_disabled), ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ao criar a integração ou ligá-la (enabled: true).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Não foi possível contar as integrações do plano (max_chatwoot_integrations), num número que ainda não tem integração (usage_unavailable); nada é criado no Chatwoot. Tente de novo.json{ "code": "usage_unavailable", "error": "Could not check the plan usage. Try again later." }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/chatwoot" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"account_id":"1","api_token":"string","base_url":"https://chatwoot.example.com","enabled":false,"inbox_id":"string","inbox_name":"string","source_name":"whatsapp","webhook_token":"string"}'delete/api/v1/instances/{id}/chatwootRemover a integração ChatwootChave do número ou do cluster
Apaga a configuração local. Não apaga a caixa no Chatwoot (use DELETE …/chatwoot/inbox antes).
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Removida.json{ "status": "string" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X DELETE "$API_URL/api/v1/instances/<id>/chatwoot" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/chatwoot/dispatch-logsRegistro de espelhamento para o ChatwootChave do número ou do cluster
Mensagens que a API tentou espelhar no Chatwoot, da mais nova para a mais antiga.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
limitopcional | query | integer | Máximo de linhas (padrão 50; valor inválido ou <= 0 vira 50). |
statusopcional | query | string | Filtra por status exato (ex. success, error, skipped). |
Respostas
200Linhas do registro.json{ "logs": [ { "chatwoot_response_status": 0, "contact_id": "string", "conversation_id": "string", "created_at": "2026-01-01T12:00:00Z", "direction": "inbound", "error_message": "string", "from_jid": "string", "id": "string", "instance_id": "string", "message_id": "string", "phone": "5511999990000", "sender": "string", "skip_reason": "string", "source": "string", "status": "success" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/chatwoot/dispatch-logs" \
-H "Authorization: Bearer $API_KEY"delete/api/v1/instances/{id}/chatwoot/inboxApagar a caixa no ChatwootChave do número ou do cluster
Apaga a caixa (inbox) no Chatwoot e limpa o inbox_id da configuração local, que continua existindo. 400 no inbox to delete quando não há caixa; 400 failed to delete inbox: … quando o Chatwoot recusa.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Caixa apagada.json{ "status": "string" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X DELETE "$API_URL/api/v1/instances/<id>/chatwoot/inbox" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/chatwoot/webhook-logsRegistro de eventos recebidos do ChatwootChave do número ou do cluster
Eventos que o Chatwoot mandou a /webhooks/chatwoot para esta instância, do mais novo para o mais antigo.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
limitopcional | query | integer | Máximo de linhas (padrão 50; valor inválido ou <= 0 vira 50). |
statusopcional | query | string | Filtra por status exato (sent, scheduled, ignored, blocked, error). |
Respostas
200Linhas do registro.json{ "logs": [ { "content": "string", "created_at": "2026-01-01T12:00:00Z", "error_message": "string", "event": "message_created", "id": "string", "inbox_id": "string", "instance_id": "string", "message_type": "outgoing", "phone": "5511999990000", "status": "sent" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/chatwoot/webhook-logs" \
-H "Authorization: Bearer $API_KEY"post/webhooks/chatwootReceber eventos do ChatwootSem chave
Endereço que a API registra na caixa do Chatwoot. Não usa chave de API: a credencial é o webhook_token da integração, na query token (como a API registra) ou no header X-Chatwoot-Token. Tem limite de taxa.
A rota aceita qualquer método: HEAD e OPTIONS (verificações do Chatwoot) respondem 200 sem corpo; os demais métodos seguem o mesmo tratamento do POST.
Só event=message_created com message_type=outgoing (resposta de agente) é enviado ao WhatsApp; o resto, e os ecos da própria API, respondem {"status":"ignored"}. A caixa (conversation.inbox_id) identifica a instância; a integração precisa estar ligada e o token conferir. O telefone vem, nesta ordem, de conversation.meta.sender.phone_number, …identifier, sender.phone_number, sender.identifier ou contact_inbox.source_id. Uma nota privada do agente (private: true, ou um valor que a API não entende) também responde {"status":"ignored"} e não vai ao cliente. Com anexos, o envio é agendado em segundo plano (scheduled). Plano sem chatwoot_enabled, conta suspensa/cancelada, número pausado ou travado por reachout, cota max_messages_per_month esgotada ou uso do mês ilegível respondem 200 {"status":"blocked"} com o motivo em error (para o Chatwoot não reenviar) e nada vai ao WhatsApp.
O token é conferido antes de ler o corpo; o corpo vai até 1 MiB (acima, 413 body too large).
Chave: nenhuma (o token do caminho é a credencial)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
tokenopcional | query | string | webhook_token da integração (ou use o header X-Chatwoot-Token). |
X-Chatwoot-Tokenopcional | header | string | Alternativa à query token. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
attachmentsopcional | array | null | |
attachments[].data_urlopcional | string | |
attachments[].file_nameopcional | string | |
attachments[].file_typeopcional | string | |
attachments[].idopcional | integer | |
attachments[].thumb_urlopcional | string | |
contentopcional | string | null | |
content_attributesopcional | object | null | |
conversationopcional | object | |
conversation.contact_inboxopcional | object | |
conversation.contact_inbox.source_idopcional | string | |
conversation.idopcional | integer | |
conversation.inbox_idopcional | integer | |
conversation.metaopcional | object | |
conversation.meta.senderopcional | object | |
conversation.meta.sender.emailopcional | string | |
conversation.meta.sender.identifieropcional | string | |
conversation.meta.sender.nameopcional | string | |
conversation.meta.sender.phone_numberopcional | string | |
conversation.statusopcional | string | |
eventopcional | string | |
message_typeopcional | string | |
senderopcional | object | |
sender.emailopcional | string | |
sender.identifieropcional | string | |
sender.nameopcional | string | |
sender.phone_numberopcional | string |
{
"content": "Olá, como posso ajudar?",
"conversation": {
"id": 42,
"inbox_id": 7,
"meta": {
"sender": {
"phone_number": "+5511999990000"
}
}
},
"event": "message_created",
"message_type": "outgoing"
}Respostas
200Evento tratado.json{ "error": "Tenant suspended. Contact support.", "status": "blocked" }400Corpo ilegível (invalid body), JSON inválido (invalid json) ou sem telefone (missing source_id).json{ "error": "invalid request" }401Token ausente (missing token), integração inexistente ou desligada, ou token errado (unauthorized).json{ "error": "invalid request" }404Caixa sem instância (inbox not mapped).json{ "error": "invalid request" }413Corpo acima de 1 MiB (body too large); um tamanho declarado maior é recusado sem ler.json{ "error": "body too large" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Não foi possível conferir o token; tente de novo.json{ "error": "token check unavailable" }
Exemplo
curl -X POST "$API_URL/webhooks/chatwoot" \
-H "Content-Type: application/json" \
-d '{"content":"Olá, como posso ajudar?","conversation":{"id":42,"inbox_id":7,"meta":{"sender":{"phone_number":"+5511999990000"}}},"event":"message_created","message_type":"outgoing"}'Fila do número
Os envios de cluster na fila de um número: listar, repetir e cancelar.
get/api/v1/instances/{id}/queueListar a fila de envio da instânciaChave do número ou do cluster
Jobs da fila durável de envio (fila do cluster) pedidos para esta instância ou que ela tentou, do mais novo para o mais antigo. Liberada mesmo com queue_enabled=false. Em jobs pending vêm os campos next_instance_* (próxima instância que vai tentar).
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
statusopcional | query | "pending" | "sending" | "completed" | "failed" | "cancelled" | |
limitopcional | query | integer | Página (1–200; fora disso vira 50). |
offsetopcional | query | integer | Deslocamento (negativo vira 0). |
Respostas
200Página de jobs.json{ "jobs": [ { "attempts": [ { "attempted_at": null, "category": null, "consecutive_failures": null, "instance_id": null, "instance_name": null, "instance_phone": null, "is_healthy": null, "last_failure_category": null, "message": null, "throttled_until": null } ], "attempts_count": 0, "body": "string", "cluster_id": "string", "completed_at": "2026-01-01T12:00:00Z", "completed_instance_id": "string", "created_at": "2026-01-01T12:00:00Z", "failed_at": "2026-01-01T12:00:00Z", "id": "string", "kind": "text", "last_error": "string", "last_error_category": "string", "media": {}, "message_id": "string", "next_attempt_at": "2026-01-01T12:00:00Z", "next_instance_consecutive_failures": 0, "next_instance_healthy": false, "next_instance_id": "string", "next_instance_last_failure_category": "string", "next_instance_name": "string", "next_instance_phone": "string", "next_instance_throttled_until": "2026-01-01T12:00:00Z", "payload": {}, "recipient": "5511999990000", "reply": {}, "requested_instance_id": "string", "status": "pending", "updated_at": "2026-01-01T12:00:00Z" } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/queue" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/queue/retry-allReenviar todos os jobs da instânciaChave do número ou do cluster
Volta para pending os jobs da instância nos status pedidos (padrão failed,cancelled). Jobs cancelados por bloqueio de cobrança ficam de fora (só o reenvio individual os traz de volta). Corpo opcional, em JSON ou formulário. Barrada com 403 plan_feature_disabled sem queue_enabled e com 403 ACCOUNT_SUSPENDED com a conta suspensa ou cancelada.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID da instância (UUID; outro formato = 400 invalid UUID filter). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
statusopcional | string | Status separados por vírgula; vazio = failed,cancelled. |
{
"status": "failed,cancelled"
}Respostas
200Quantidade de jobs devolvidos à fila.json{ "retried": 0 }400ID que não é UUID (invalid UUID filter) ou JSON inválido (invalid retry-all request).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled) ou conta suspensa/cancelada (ACCOUNT_SUSPENDED).json{ "code": "string", "error": "string", "feature": "string" }404Recurso inexistente.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/queue/retry-all" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"failed,cancelled"}'post/api/v1/instances/{id}/queue/{job_id}/cancelCancelar um jobChave do número ou do cluster
Cancela um job pending ou failed (outro status = 409). O job precisa ter sido pedido para esta instância ou tentado por ela (senão 404). Liberada com queue_enabled=false; barrada com 403 ACCOUNT_SUSPENDED com a conta suspensa ou cancelada.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
job_idobrigatório | path | string | ID do job. |
Respostas
200Job cancelado.json{ "job_id": "string", "status": "string" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ou limite do plano. Na suspensão a API barra o que envia, cria ou volta a trabalhar: envios e reenvios das filas, criar número, cluster, membro, aquecimento, regra e chave de cliente, girar chave, trocar proxy ou país, ativar aquecimento, editar regra sem desligá-la, salvar webhook do número com mais destinos que os gravados, criar ou ligar o Chatwoot, retomar a pausa (paused:falseou ausente) de número, membro de cluster e membro de aquecimento e, no Marketing, criar e iniciar campanha e fluxo, importar contatos, aplicar e criar tags. O corpo vale como a rota o lê (a chave sem diferenciar maiúsculas). Ler, pausar, cancelar (inclusive jobs das filas), apagar, desligar, tirar ou editar destinos de webhook, reconectar e as notas e o contato da Caixa continuam.json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/queue/<job_id>/cancel" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/queue/{job_id}/retryReenviar um jobChave do número ou do cluster
Volta um job failed ou cancelled para pending (zera as tentativas) ou adianta um pending. O job precisa ter sido pedido para esta instância ou tentado por ela (senão 404). Outro status = 409. Barrada com 403 plan_feature_disabled sem queue_enabled e com 403 ACCOUNT_SUSPENDED com a conta suspensa ou cancelada.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
job_idobrigatório | path | string | ID do job. |
Respostas
200Job de volta à fila.json{ "job_id": "string", "status": "string" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled) ou conta suspensa/cancelada (ACCOUNT_SUSPENDED).json{ "code": "string", "error": "string", "feature": "string" }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }410O número foi removido da conta: o histórico dele fica só para leitura na caixa de entrada.json{ "code": "INSTANCE_REMOVED", "error": "number was removed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/queue/<job_id>/retry" \
-H "Authorization: Bearer $API_KEY"Clusters
Grupos de números com um endereço só: membros, modo de escolha, fila e envio.
get/api/v1/clustersLista os clustersSó a chave da plataforma
Devolve todos os clusters da sua API, com a api_key mascarada (abcd…wxyz). Só a chave global tem acesso a esta rota.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Respostas
200Clusters (array simples, sem paginação).json[ { "api_key": "3f1c…9d7c", "created_at": "2026-10-01T12:00:00Z", "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "mode": "random", "name": "Atendimento", "reachout_cooldown_seconds": 3600, "updated_at": "2026-10-02T09:30:00Z", "webhook_url": "https://hooks.example.com/waapi/cluster" } ]401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters" \
-H "Authorization: Bearer $API_KEY"post/api/v1/clustersCria um clusterSó a chave da plataforma
Cria o cluster com modo random e uma chave própria gerada pelo servidor. A resposta traz a api_key completa (única vez, além de GET /clusters/{cid}?reveal=1 e da rotação). Sujeito ao limite do plano max_clusters.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
nameobrigatório | string |
{
"name": "Atendimento"
}Respostas
201Cluster criado.json{ "api_key": "3f1c…9d7c", "created_at": "2026-10-01T12:00:00Z", "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "mode": "random", "name": "Atendimento", "reachout_cooldown_seconds": 3600, "updated_at": "2026-10-02T09:30:00Z", "webhook_url": "https://hooks.example.com/waapi/cluster" }400nameausente ({"error":"name required"}).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do planomax_clustersatingido (plan_limit) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Atendimento"}'get/api/v1/clusters/{cid}Detalha um clusterChave do número ou do cluster
A api_key vem mascarada, salvo com ?reveal=1.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
revealopcional | query | "1" | 1 devolve a api_key completa. |
Respostas
200O cluster.json{ "api_key": "3f1c…9d7c", "created_at": "2026-10-01T12:00:00Z", "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "mode": "random", "name": "Atendimento", "reachout_cooldown_seconds": 3600, "updated_at": "2026-10-02T09:30:00Z", "webhook_url": "https://hooks.example.com/waapi/cluster" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>" \
-H "Authorization: Bearer $API_KEY"delete/api/v1/clusters/{cid}Apaga um clusterChave do número ou do cluster
Apaga o cluster e, em cascata no banco, membros, middlewares, filas e rotas. As instâncias não são apagadas.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Respostas
200Apagado.json{ "status": "deleted" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (CLUSTER_NOT_STORED): nada muda; tente de novo.json{ "code": "CLUSTER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X DELETE "$API_URL/api/v1/clusters/<cid>" \
-H "Authorization: Bearer $API_KEY"get/api/v1/clusters/{cid}/audit-logsLista a trilha de auditoria do clusterChave do número ou do cluster
Ações do cluster (membros, configuração, middlewares, rotação de chave, mensagens enviadas e recebidas), do mais novo ao mais antigo. URLs de webhook e de notificação aparecem só como scheme://host.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
event_typeopcional | query | string | Filtro exato, ex. cluster.member.added. |
searchopcional | query | string | Busca (ILIKE) no evento e no payload. |
limitopcional | query | integer | Itens por página (inteiro > 0; inválido vale 50). |
offsetopcional | query | integer |
Respostas
200Página da auditoria.json{ "audit_logs": [ { "cluster_id": "00000000-0000-4000-8000-000000000000", "created_at": "2026-01-01T12:00:00Z", "event_type": "string", "id": "string", "instance_id": "00000000-0000-4000-8000-000000000000", "instance_name": "string", "instance_phone": "string", "payload": {} } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>/audit-logs" \
-H "Authorization: Bearer $API_KEY"put/api/v1/clusters/{cid}/dashboard-urlDefine a URL do painel usada nos alertasChave do número ou do cluster
Base usada para montar o link dos alertas de erro (<dashboard_url>/clusters/<cid>?job=<job_id>). Vazio remove o link.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
dashboard_urlopcional | string |
{
"dashboard_url": "https://painel.example.com"
}Respostas
200Atualizado.json{ "status": "updated" }400Corpo que não é o JSON esperado (INVALID_BODY): nada muda. Corpo vazio também éINVALID_BODY; para limpar, envie{}.json{ "code": "INVALID_BODY", "error": "invalid JSON body" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (CLUSTER_NOT_STORED): nada muda; tente de novo.json{ "code": "CLUSTER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/clusters/<cid>/dashboard-url" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"dashboard_url":"https://painel.example.com"}'put/api/v1/clusters/{cid}/error-notificationConfigura os alertas de erro do clusterChave do número ou do cluster
Alertas operacionais (falha final de envio, nenhuma instância disponível, instância com autenticação restrita…) vão para a URL (POST JSON) e/ou para o e-mail (via Resend, se configurado na sua API). Campos vazios desligam o canal. A URL passa pela validação de destino.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
error_notification_emailopcional | string | Vazio desliga o canal. |
error_notification_urlopcional | string | Vazio desliga o canal. |
{
"error_notification_email": "ops@example.com",
"error_notification_url": "https://hooks.example.com/waapi/alerts"
}Respostas
200Atualizado.json{ "status": "updated" }400URL de notificação inválida ou não permitida, ou corpo que não é o JSON esperado (INVALID_BODY): nada muda. Corpo vazio também éINVALID_BODY; para limpar, envie{}.json{ "code": "INVALID_BODY", "error": "invalid JSON body" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (CLUSTER_NOT_STORED): nada muda; tente de novo.json{ "code": "CLUSTER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/clusters/<cid>/error-notification" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"error_notification_email":"ops@example.com","error_notification_url":"https://hooks.example.com/waapi/alerts"}'get/api/v1/clusters/{cid}/errorsLista os erros do clusterChave do número ou do cluster
Eventos cluster.error.* gravados, do mais novo ao mais antigo, enriquecidos com o desfecho do job de envio quando o payload tem job_id. Inclui as falhas finais SENDER_IS_RECIPIENT (veja POST /clusters/{cid}/send).
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
instance_idopcional | query | string (uuid) | Filtra por instância. |
categoryopcional | query | "client" | "rate_limit" | "reachout" | "auth" | "network" | "server" | "unknown" | "billing" | |
severityopcional | query | "critical" | "error" | "warning" | |
searchopcional | query | string | Busca (ILIKE) em evento, mensagem, categoria e payload. |
limitopcional | query | integer | Itens por página (inteiro > 0; inválido vale 50). |
offsetopcional | query | integer |
Respostas
200Página de erros.json{ "errors": [ { "category": "string", "cluster_id": "00000000-0000-4000-8000-000000000000", "created_at": "2026-01-01T12:00:00Z", "event_type": "string", "id": "string", "instance_id": "00000000-0000-4000-8000-000000000000", "instance_name": "string", "instance_phone": "string", "job_attempts": [ { "attempted_at": null, "category": null, "consecutive_failures": null, "instance_id": null, "instance_name": null, "instance_phone": null, "is_healthy": null, "last_failure_category": null, "message": null, "throttled_until": null } ], "job_completed_at": "2026-01-01T12:00:00Z", "job_completed_instance_id": "00000000-0000-4000-8000-000000000000", "job_completed_instance_name": "string", "job_completed_instance_phone": "string", "job_failed_at": "2026-01-01T12:00:00Z", "job_last_error": "string", "job_last_error_category": "string", "job_outcome": "string", "job_status": "pending", "message": "SENDER_IS_RECIPIENT: no sender other than the recipient's own number", "payload": {}, "severity": "critical" } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>/errors" \
-H "Authorization: Bearer $API_KEY"get/api/v1/clusters/{cid}/membersLista os membrosChave do número ou do cluster
Instâncias do cluster com estado ao vivo, saúde e contagem de tentativas falhas.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Respostas
200Membros, em ordem de inclusão.json{ "members": [ { "added_at": "2026-01-01T12:00:00Z", "consecutive_failures": 0, "instance_id": "00000000-0000-4000-8000-000000000000", "last_failure_at": "2026-01-01T12:00:00Z", "last_failure_category": "client", "name": "string", "paused": false, "paused_by_plan": false, "paused_by_plan_at": "2026-01-01T12:00:00Z", "phone": "string", "reachout_cooldown_seconds": 0, "reachout_locked_reason": "string", "reachout_locked_until": "2026-01-01T12:00:00Z", "send_attempt_failed_count": 0, "send_attempt_failed_resolved_count": 0, "status": "string", "throttled_until": "2026-01-01T12:00:00Z" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Falha ao ler a pausa do plano dos membros.json{ "error": "could not read the members" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>/members" \
-H "Authorization: Bearer $API_KEY"post/api/v1/clusters/{cid}/membersAdiciona uma instância ao clusterChave do número ou do cluster
Idempotente: incluir uma instância que já é membro devolve 200 e não conta no limite. Uma instância nova no cluster está sujeita ao limite do plano max_cluster_members. Uma instância pode estar em vários clusters.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
instance_idobrigatório | string (uuid) |
{
"instance_id": "9b2f4c1e-3a5d-4e7f-8a1b-2c3d4e5f6a7b"
}Respostas
200Incluído.json{ "status": "added" }400instance_idausente (instance_id required) ou instância inexistente (instance not found).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do planomax_cluster_membersatingido (plan_limit) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/members" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"instance_id":"9b2f4c1e-3a5d-4e7f-8a1b-2c3d4e5f6a7b"}'delete/api/v1/clusters/{cid}/members/{id}Remove uma instância do clusterChave do número ou do cluster
A instância continua existindo. Quem não é membro: 404.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
idobrigatório | path | string (uuid) | ID da instância membro. |
Respostas
200Removido.json{ "status": "removed" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Só a chave global ou a do cluster abre esta rota; dá 403 com a chave do número membro (INSTANCE_KEY_SCOPE): ela só abre as rotas/api/v1/instances/{id}/…do próprio número.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key only opens the routes of that number (/api/v1/instances/{id})" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X DELETE "$API_URL/api/v1/clusters/<cid>/members/<id>" \
-H "Authorization: Bearer $API_KEY"put/api/v1/clusters/{cid}/members/{id}/pausePausa ou retoma um membroChave do número ou do cluster
Um membro pausado sai da escolha de remetente e da listagem de mensagens do cluster, sem sair do cluster. A escolha do cliente substitui a pausa do plano: paused_by_plan volta a false e um membro pausado pelo plano não volta mais sozinho quando o plano sobe.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
idobrigatório | path | string (uuid) | ID da instância membro. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
pausedopcional | boolean |
{
"paused": true
}Respostas
200Atualizado.json{ "paused": false, "status": "string" }400Corpo inválido (paused required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ao retomar (paused: falseou ausente); pausar continua liberado. Também a chave do número membro (INSTANCE_KEY_SCOPE): ela só abre as rotas/api/v1/instances/{id}/…do próprio número.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key only opens the routes of that number (/api/v1/instances/{id})" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (CLUSTER_NOT_STORED): nada muda; tente de novo.json{ "code": "CLUSTER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/clusters/<cid>/members/<id>/pause" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"paused":true}'put/api/v1/clusters/{cid}/members/{id}/reachout-cooldownDefine o intervalo de contato frio de um membroChave do número ou do cluster
Sobrepõe o valor do cluster para este membro (0 = usa o do cluster). O valor configurado na própria instância, se maior que 0, vale acima deste. Negativo vira 0.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
idobrigatório | path | string (uuid) | ID da instância membro. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
secondsopcional | integer | Segundos; negativo vira 0. |
{
"seconds": 3600
}Respostas
200Atualizado.reachout_cooldown_secondsecoa o valor enviado.json{ "reachout_cooldown_seconds": 0, "status": "string" }400Corpo inválido (seconds required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Só a chave global ou a do cluster abre esta rota; dá 403 com a chave do número membro (INSTANCE_KEY_SCOPE): ela só abre as rotas/api/v1/instances/{id}/…do próprio número.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key only opens the routes of that number (/api/v1/instances/{id})" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (CLUSTER_NOT_STORED): nada muda; tente de novo.json{ "code": "CLUSTER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/clusters/<cid>/members/<id>/reachout-cooldown" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"seconds":3600}'get/api/v1/clusters/{cid}/messagesLista as mensagens dos membrosChave de API
Junta as mensagens em memória de todos os membros ativos (não pausados), da mais nova à mais antiga, com instance_id em cada uma. Sem membros, devolve só {"messages": []}.
Chave: chave da plataforma, chave do cluster, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
instance_idopcional | query | string (uuid) | Só as de um membro. |
directionopcional | query | "inbound" | "outbound" | |
sourceopcional | query | string | Origem, ex. cluster, api, whatsapp. |
searchopcional | query | string | Busca (sem diferenciar maiúsculas) em corpo, remetente, origem e conversa. |
limitopcional | query | integer | Itens por página (inteiro > 0; inválido vale 50). |
offsetopcional | query | integer |
Respostas
200Página de mensagens.json{ "limit": 0, "messages": [ { "body": "string", "conversation_key": "string", "direction": "inbound", "from": "string", "id": "string", "instance_id": "00000000-0000-4000-8000-000000000000", "is_group": false, "media": { "file_name": "string", "mime_type": "string" }, "media_caption": "string", "recipient": "string", "sender": "string", "source": "string", "timestamp": "2026-01-01T12:00:00Z" } ], "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403instance_idnão é membro ativo do cluster (instance not in cluster), ou chave de cliente sem o escoponumbersou com membro do cluster fora da lista dela (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }503Não foi possível conferir a chave de cliente; tente de novo.json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>/messages" \
-H "Authorization: Bearer $API_KEY"get/api/v1/clusters/{cid}/middlewaresLista os middlewares do clusterChave do número ou do cluster
Estágios do pipeline em ordem de position. A api_key do provedor de LLM vem mascarada.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Respostas
200Middlewares.json{ "middlewares": [ { "cluster_id": "00000000-0000-4000-8000-000000000000", "config": { "api_key": "sk-exemplo", "apply_on_inbound": false, "apply_on_outbound": true, "model": "openai/gpt-4o-mini", "on_failure": "passthrough", "prompt": "Reescreva a mensagem com outras palavras, mantendo o sentido.", "provider": "openrouter" }, "created_at": "2026-01-01T12:00:00Z", "enabled": false, "id": "00000000-0000-4000-8000-000000000000", "position": 0, "type": "string", "updated_at": "2026-01-01T12:00:00Z" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>/middlewares" \
-H "Authorization: Bearer $API_KEY"post/api/v1/clusters/{cid}/middlewaresAdiciona um middleware ao clusterChave do número ou do cluster
Tipos que o pipeline executa: ai_rewrite (reescreve o texto por LLM, na ida e/ou na volta) e warmer_ai. Os dois exigem a função do plano ai_rewrite_enabled. Um tipo desconhecido ou uma configuração sem model é gravado, mas ignorado no envio.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
configopcional | object | object | Padrão {}. |
enabledopcional | boolean | |
positionopcional | integer | Negativo vira 0. |
typeobrigatório | string |
{
"config": {
"api_key": "sk-exemplo",
"apply_on_inbound": false,
"apply_on_outbound": true,
"model": "openai/gpt-4o-mini",
"on_failure": "passthrough",
"prompt": "Reescreva a mensagem com outras palavras, mantendo o sentido.",
"provider": "openrouter"
},
"enabled": true,
"position": 0,
"type": "ai_rewrite"
}Respostas
201Middleware criado (aapi_keydaconfigvolta mascarada, como em toda leitura).json{ "cluster_id": "00000000-0000-4000-8000-000000000000", "config": { "api_key": "sk-exemplo", "apply_on_inbound": false, "apply_on_outbound": true, "model": "openai/gpt-4o-mini", "on_failure": "passthrough", "prompt": "Reescreva a mensagem com outras palavras, mantendo o sentido.", "provider": "openrouter" }, "created_at": "2026-01-01T12:00:00Z", "enabled": false, "id": "00000000-0000-4000-8000-000000000000", "position": 0, "type": "string", "updated_at": "2026-01-01T12:00:00Z" }400typeausente (type required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função do planoai_rewrite_enableddesligada (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/middlewares" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"config":{"api_key":"sk-exemplo","apply_on_inbound":false,"apply_on_outbound":true,"model":"openai/gpt-4o-mini","on_failure":"passthrough","prompt":"Reescreva a mensagem com outras palavras, mantendo o sentido.","provider":"openrouter"},"enabled":true,"position":0,"type":"ai_rewrite"}'put/api/v1/clusters/{cid}/middlewares/{mid}Atualiza um middlewareChave do número ou do cluster
Atualização parcial: só os campos enviados mudam. config é mesclada à atual (uma api_key mascarada ou ausente mantém a gravada só no mesmo destino; com outra base_url, provider ou format, mascarada ou ausente, é 400 MASKED_SECRET_NEW_DESTINATION, porque a chave gravada iria para o provedor novo: mande a chave de novo). Desligar (enabled: false) é sempre permitido; qualquer outra alteração de um ai_rewrite/warmer_ai exige ai_rewrite_enabled. Um mid inexistente: 404.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
midobrigatório | path | string (uuid) | ID do middleware. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
configopcional | object | Mesclada à configuração atual. |
enabledopcional | boolean | |
positionopcional | integer |
{
"enabled": false
}Respostas
200Atualizado.json{ "status": "updated" }400Corpo inválido (invalid body), ou outrabase_url,providerouformatcom aapi_keymascarada ou ausente (MASKED_SECRET_NEW_DESTINATION; nada muda).json{ "code": "MASKED_SECRET_NEW_DESTINATION", "error": "Send the key again when the URL, provider or format changes." }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função do planoai_rewrite_enableddesligada (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED) numa alteração que não desliga o middleware (enabled: falsepassa).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X PUT "$API_URL/api/v1/clusters/<cid>/middlewares/<mid>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled":false}'delete/api/v1/clusters/{cid}/middlewares/{mid}Remove um middlewareChave do número ou do cluster
Um mid inexistente: 404.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
midobrigatório | path | string (uuid) | ID do middleware. |
Respostas
200Removido.json{ "status": "deleted" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X DELETE "$API_URL/api/v1/clusters/<cid>/middlewares/<mid>" \
-H "Authorization: Bearer $API_KEY"put/api/v1/clusters/{cid}/modeDefine o modo de seleção do remetenteChave do número ou do cluster
Modos registrados: random (um membro disponível sorteado a cada envio) e warmer_pairs (hoje equivale a random). O valor é gravado como enviado; um nome desconhecido é tratado como random na escolha.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
modeobrigatório | string | random ou warmer_pairs; outro valor é gravado e tratado como random. |
{
"mode": "random"
}Respostas
200Atualizado.json{ "mode": "random", "status": "updated" }400modeausente (mode required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (CLUSTER_NOT_STORED): nada muda; tente de novo.json{ "code": "CLUSTER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/clusters/<cid>/mode" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode":"random"}'get/api/v1/clusters/{cid}/queueLista os jobs de envio do clusterChave do número ou do cluster
Jobs do mais novo ao mais antigo. Nos pendentes, next_instance_* mostra o membro que seria escolhido agora.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
statusopcional | query | "pending" | "sending" | "completed" | "failed" | "cancelled" | |
limitopcional | query | integer | 1–200; fora disso vale 50. |
offsetopcional | query | integer |
Respostas
200Página de jobs.json{ "jobs": [ { "attempts_count": 0, "body": "Olá!", "cluster_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "created_at": "2026-10-02T09:30:00Z", "failed_at": "2026-10-02T09:30:01Z", "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "kind": "text", "last_error": "SENDER_IS_RECIPIENT: no sender other than the recipient's own number", "last_error_category": "client", "next_attempt_at": "2026-10-02T09:30:00Z", "recipient": "5511999990000", "status": "failed", "updated_at": "2026-10-02T09:30:01Z" } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>/queue" \
-H "Authorization: Bearer $API_KEY"post/api/v1/clusters/{cid}/queue/retry-allReenfileira jobs em loteChave do número ou do cluster
Reenfileira os jobs do cluster nos estados pedidos (padrão: failed e cancelled), opcionalmente só os que pediram ou tentaram uma instância. Jobs descartados porque a conta foi cancelada (cancelled com categoria billing) ficam de fora. Aceita JSON ou formulário; corpo vazio vale o padrão. Exige queue_enabled. Bloqueado com a conta suspensa ou cancelada.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
instance_idopcional | string (uuid) | Só jobs que pediram ou já tentaram esta instância. |
statusopcional | string | Estados separados por vírgula; padrão failed,cancelled. |
{
"instance_id": "00000000-0000-4000-8000-000000000000",
"status": "failed,cancelled"
}Respostas
200Quantidade reenfileirada.json{ "retried": 3 }400JSON inválido (invalid retry-all request) ouinstance_idnão é UUID (invalid UUID filter).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Funçãoqueue_enabledfora do plano ou conta suspensa (ACCOUNT_SUSPENDED).json{ "code": "string", "error": "string", "feature": "string" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/queue/retry-all" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"instance_id":"00000000-0000-4000-8000-000000000000","status":"failed,cancelled"}'get/api/v1/clusters/{cid}/queue/{job_id}Detalha um job de envioChave do número ou do cluster
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
job_idobrigatório | path | string (uuid) | ID do job de envio. |
Respostas
200O job (comattempts,last_erroremessage_idquando concluído).json{ "attempts_count": 0, "body": "Olá!", "cluster_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "created_at": "2026-10-02T09:30:00Z", "failed_at": "2026-10-02T09:30:01Z", "id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "kind": "text", "last_error": "SENDER_IS_RECIPIENT: no sender other than the recipient's own number", "last_error_category": "client", "next_attempt_at": "2026-10-02T09:30:00Z", "recipient": "5511999990000", "status": "failed", "updated_at": "2026-10-02T09:30:01Z" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>/queue/<job_id>" \
-H "Authorization: Bearer $API_KEY"post/api/v1/clusters/{cid}/queue/{job_id}/cancelCancela um jobChave do número ou do cluster
Só jobs pending ou failed podem ser cancelados. Liberado com a conta suspensa ou cancelada.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
job_idobrigatório | path | string (uuid) | ID do job de envio. |
Respostas
200Cancelado.json{ "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "status": "cancelled" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409Job em estado que não permite cancelar (job not found or cannot be cancelled). Tambémprovider_disabledsem o número por QR na instalação, ouprovider_unsupportednum número oficial.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/queue/<job_id>/cancel" \
-H "Authorization: Bearer $API_KEY"post/api/v1/clusters/{cid}/queue/{job_id}/retryReenfileira um jobChave do número ou do cluster
Um job failed ou cancelled volta a pending com as tentativas zeradas (todos os membros podem ser tentados de novo); um pending só é adiantado. Exige a função do plano queue_enabled. Bloqueado com a conta suspensa ou cancelada.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
job_idobrigatório | path | string (uuid) | ID do job de envio. |
Respostas
200Reenfileirado.json{ "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "status": "retrying" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Funçãoqueue_enabledfora do plano ou conta suspensa (ACCOUNT_SUSPENDED).json{ "code": "string", "error": "string", "feature": "string" }404Recurso inexistente.json{ "error": "invalid request" }409Job em estado que não permite reenvio (job not found or cannot be retried). Tambémprovider_disabledsem o número por QR na instalação, ouprovider_unsupportednum número oficial.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/queue/<job_id>/retry" \
-H "Authorization: Bearer $API_KEY"put/api/v1/clusters/{cid}/reachout-cooldownDefine o intervalo de contato frio do clusterChave do número ou do cluster
Tempo, em segundos, que um membro fica fora da escolha depois de um bloqueio de contato frio do WhatsApp (erro 463). Precedência: valor da instância > valor do membro neste cluster > valor do cluster. Negativo vira 0.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
secondsopcional | integer | Segundos; negativo vira 0. |
{
"seconds": 3600
}Respostas
200Atualizado.reachout_cooldown_secondsecoa o valor enviado.json{ "reachout_cooldown_seconds": 0, "status": "string" }400Corpo inválido (seconds required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (CLUSTER_NOT_STORED): nada muda; tente de novo.json{ "code": "CLUSTER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/clusters/<cid>/reachout-cooldown" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"seconds":3600}'post/api/v1/clusters/{cid}/receiveInjeta uma mensagem recebida no clusterChave do número ou do cluster
Registra uma mensagem de entrada sem passar pelo WhatsApp: roda os middlewares de entrada, atribui a mensagem a um membro (o instance_id pedido ou o modo do cluster) e esse membro a ingere como uma mensagem real (buffer, banco, Chatwoot, webhook da instância), além do webhook do cluster (cluster.message.received) e da auditoria. Útil para testar o pipeline de entrada ou trazer mensagens de outro canal. Mensagens reais do WhatsApp chegam sozinhas às instâncias; não use esta rota para elas.
Se nenhum membro está disponível, o cluster fica degradado por 5 minutos (respostas 503 nesse período) e o erro cluster.error.no_instance_available é emitido.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
bodyobrigatório | string | |
fromobrigatório | string | Telefone ou JID do remetente. |
instance_idopcional | string (uuid) | Membro que deve receber; sem ele, o modo do cluster escolhe. |
{
"body": "Oi, quero saber do meu pedido.",
"from": "5511999990000"
}Respostas
200Mensagem ingerida.json{ "instance_id": "9b2f4c1e-3a5d-4e7f-8a1b-2c3d4e5f6a7b", "message_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "status": "received" }400fromoubodyausente (from and body required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403instance_idpedido não é membro ativo do cluster (instance not in cluster).json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }422Um middleware bloqueou a mensagem (blocked by middleware), ex.ai_rewritecomon_failure=block.json{ "error": "blocked by middleware" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }503Nenhum membro disponível (no available instance in cluster) ou cluster degradado (cluster is temporarily degraded, try again later).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/receive" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"Oi, quero saber do meu pedido.","from":"5511999990000"}'get/api/v1/clusters/{cid}/recipient-routesLista as rotas fixas por destinatárioChave do número ou do cluster
Membro que atende cada destinatário (gravado a cada envio com sucesso), do uso mais recente ao mais antigo. Rotas antigas que apontam para o próprio número do destinatário ainda aparecem até o próximo envio com sucesso, mas a escolha as ignora.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
searchopcional | query | string | Busca (ILIKE) no destinatário. |
limitopcional | query | integer | 1–200; fora disso vale 50. |
offsetopcional | query | integer |
Respostas
200Página de rotas.json{ "limit": 0, "offset": 0, "routes": [ { "cluster_id": "00000000-0000-4000-8000-000000000000", "created_at": "2026-01-01T12:00:00Z", "instance_id": "string", "last_used_at": "2026-01-01T12:00:00Z", "recipient": "string", "updated_at": "2026-01-01T12:00:00Z", "use_count": 0 } ], "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/clusters/<cid>/recipient-routes" \
-H "Authorization: Bearer $API_KEY"post/api/v1/clusters/{cid}/rotate-api-keyGira a chave do clusterChave do número ou do cluster
Gera uma chave nova; a anterior deixa de valer na hora. Registra cluster.key.rotated na auditoria.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Respostas
200Nova chave (completa).json{ "api_key": "3f1c0a9e7b2d4c6f8a1e5d7c9b3a2f4e6d8c0b1a3e5f7d9c" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não gravou a chave nova (api_key_rotation_failed): a chave atual continua valendo.json{ "code": "api_key_rotation_failed", "error": "could not store the new api key; the current key still works" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/rotate-api-key" \
-H "Authorization: Bearer $API_KEY"post/api/v1/clusters/{cid}/sendEnvia texto pelo cluster (enfileirado)Chave de API
Passa o texto pelos middlewares de saída e cria um job na fila durável do cluster; responde 202 com o job_id. O envio real é assíncrono: acompanhe em GET /clusters/{cid}/queue/{job_id} ou pelo webhook do cluster (cluster.message.sent).
Escolha do remetente, entre os membros disponíveis (online, logados, saudáveis, sem bloqueio de contato frio, não pausados) e ainda não tentados neste job:
instance_idpedido, se houver; 2. a rota fixa do destinatário (gravada a cada
envio com sucesso); 3. o modo do cluster. Se um membro falha, o job tenta o próximo.
Nunca para o próprio número: o membro cujo telefone é o do destinatário nunca é escolhido. Se não houver outro membro, o job termina failed com last_error = SENDER_IS_RECIPIENT: no sender other than the recipient's own number e last_error_category = client (sai em /errors e no webhook cluster.error.send_failed). Se houver outro, mas indisponível, o job volta a esperar.
Plano: o limite mensal max_messages_per_month conta as mensagens já enviadas mais os jobs ainda pendentes; max_cluster_send_jobs limita os jobs na fila (pendentes + enviando). Middlewares de LLM exigem ai_rewrite_enabled.
Chave: chave da plataforma, chave do cluster, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
bodyobrigatório | string | |
instance_idopcional | string (uuid) | Membro preferido; se indisponível ou falhar, outro membro é tentado. |
toobrigatório | string | Telefone (com DDI) ou JID do destinatário. |
{
"body": "Olá! Seu pedido foi enviado.",
"to": "5511999990000"
}Respostas
202Job criado na fila do cluster.json{ "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "status": "pending" }400tooubodyausente (to and body required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (max_messages_per_monthoumax_cluster_send_jobs;max_clustersnum cluster além do teto do plano, em que os mais antigos continuam e os mais novos recusam envios), middleware de LLM fora do plano (plan_feature_disabled,ai_rewrite_enabled), conta suspensa/cancelada (ACCOUNT_SUSPENDED) ou chave de cliente sem o escoponumbersou com membro do cluster fora da lista dela (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }422Um middleware bloqueou a mensagem (blocked by middleware), ex.ai_rewritecomon_failure=block.json{ "error": "blocked by middleware" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Não foi possível ler o uso do plano (usage_unavailable) ou conferir a chave de cliente (client key check unavailable); tente de novo.json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/send" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"Olá! Seu pedido foi enviado.","to":"5511999990000"}'post/api/v1/clusters/{cid}/send-mediaEnvia mídia pelo cluster (enfileirado)Chave de API
multipart/form-data com o arquivo (file) ou uma URL pública (file_url, baixada na hora pelo servidor). A legenda passa pelos middlewares de saída. Mesma fila, mesma escolha de remetente (inclusive SENDER_IS_RECIPIENT) e mesmos limites do plano que POST /clusters/{cid}/send. O limite do plano é conferido antes do download.
Chave: chave da plataforma, chave do cluster, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (multipart/form-data)
| Campo | Tipo | Descrição |
|---|---|---|
captionopcional | string | |
fileopcional | string | Arquivo enviado. Use este ou file_url. |
file_urlopcional | string (uri) | URL pública baixada pelo servidor (validada contra destinos internos). |
instance_idopcional | string (uuid) | |
toobrigatório | string | |
typeopcional | "image" | "video" | "audio" | "document" | Padrão deduzido do MIME do arquivo. |
{
"caption": "string",
"file": "string",
"file_url": "https://example.com",
"instance_id": "00000000-0000-4000-8000-000000000000",
"to": "string",
"type": "image"
}Respostas
202Job criado na fila do cluster.json{ "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "status": "pending" }400toausente, ou semfilenemfile_url(MEDIA_INVALID_INPUT).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (max_messages_per_month,max_cluster_send_jobsou, só na mídia,max_storage_mb;max_clustersnum cluster além do teto do plano, em que os mais antigos continuam e os mais novos recusam envios), middleware de LLM fora do plano (plan_feature_disabled,ai_rewrite_enabled), conta suspensa/cancelada (ACCOUNT_SUSPENDED) ou chave de cliente sem o escoponumbersou com membro do cluster fora da lista dela (CLIENT_KEY_SCOPE).json{ "code": "plan_limit", "error": "Plan limit reached: max_storage_mb.", "limit": "max_storage_mb" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }413Arquivo acima de 64 MB, ou corpo acima de 65 MB (MEDIA_TOO_LARGE). Um corpo declarado maior é recusado sem ser lido.json{ "code": "MEDIA_TOO_LARGE", "error": "media too large: the limit is 64 MB" }422Um middleware bloqueou a mensagem (blocked by middleware), ou a URL de mídia do cliente não pôde ser baixada (MEDIA_DOWNLOAD_FAILED,download media: …).json{ "error": "blocked by middleware" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Falha nossa ao guardar a mídia (MEDIA_PREPARE_FAILED) ou ao criar o job.json{ "error": "invalid request" }503Não foi possível ler o uso do plano (usage_unavailable, também ao medir o armazenamento) ou conferir a chave de cliente (client key check unavailable); tente de novo.json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/send-media" \
-H "Authorization: Bearer $API_KEY" \
-F "to=5511999990000" \
-F "file=@arquivo.jpg"post/api/v1/clusters/{cid}/send-replyResponde citando uma mensagem (enfileirado)Chave de API
Envia texto como resposta citada. Mesma fila, escolha de remetente (inclusive SENDER_IS_RECIPIENT), middlewares e limites do plano que POST /clusters/{cid}/send. Para a citação aparecer, o ideal é pedir em instance_id o membro que recebeu a mensagem.
Chave: chave da plataforma, chave do cluster, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
bodyobrigatório | string | |
instance_idopcional | string (uuid) | |
quoted_message_idobrigatório | string | ID da mensagem citada no WhatsApp. |
quoted_senderobrigatório | string | Remetente da mensagem citada. |
toobrigatório | string |
{
"body": "Combinado, obrigado!",
"instance_id": "9b2f4c1e-3a5d-4e7f-8a1b-2c3d4e5f6a7b",
"quoted_message_id": "3EB0A1B2C3D4E5F6A7B8",
"quoted_sender": "5581988887777",
"to": "5581988887777"
}Respostas
202Job criado na fila do cluster.json{ "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9", "status": "pending" }400Campo obrigatório ausente (to, body, quoted_message_id and quoted_sender required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (max_messages_per_monthoumax_cluster_send_jobs;max_clustersnum cluster além do teto do plano, em que os mais antigos continuam e os mais novos recusam envios), middleware de LLM fora do plano (plan_feature_disabled,ai_rewrite_enabled), conta suspensa/cancelada (ACCOUNT_SUSPENDED) ou chave de cliente sem o escoponumbersou com membro do cluster fora da lista dela (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }422Um middleware bloqueou a mensagem (blocked by middleware), ex.ai_rewritecomon_failure=block.json{ "error": "blocked by middleware" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Não foi possível ler o uso do plano (usage_unavailable) ou conferir a chave de cliente (client key check unavailable); tente de novo.json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/clusters/<cid>/send-reply" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"Combinado, obrigado!","instance_id":"9b2f4c1e-3a5d-4e7f-8a1b-2c3d4e5f6a7b","quoted_message_id":"3EB0A1B2C3D4E5F6A7B8","quoted_sender":"5581988887777","to":"5581988887777"}'put/api/v1/clusters/{cid}/webhookConfigura o webhook do clusterChave do número ou do cluster
Recebe os eventos do cluster (cluster.message.sent, cluster.message.received e os cluster.error.*). webhook_url vazio desliga o webhook. A URL passa pela validação de destino (HTTPS e endereço público, salvo configuração da sua API). A auditoria guarda só scheme://host da URL.
Chave: chave da plataforma, chave do cluster
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cidobrigatório | path | string (uuid) | ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
webhook_tokenopcional | string | Valor mascarado (como veio da leitura) mantém o token atual. |
webhook_urlopcional | string | Vazio desliga o webhook. |
{
"webhook_token": "segredo-exemplo",
"webhook_url": "https://hooks.example.com/waapi/cluster"
}Respostas
200Atualizado.json{ "status": "updated" }400URL do webhook inválida ou não permitida, corpo que não é o JSON esperado (INVALID_BODY), ouwebhook_tokenmascarado (como a leitura o devolve) com outrawebhook_url(MASKED_SECRET_NEW_DESTINATION: a URL nova receberia o token gravado; mande o token de novo). Nada muda. O token mascarado com a mesma URL mantém o gravado. Corpo vazio também éINVALID_BODY; para limpar, envie{}.json{ "code": "INVALID_BODY", "error": "invalid JSON body" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (CLUSTER_NOT_STORED): nada muda; tente de novo.json{ "code": "CLUSTER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/clusters/<cid>/webhook" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"webhook_token":"segredo-exemplo","webhook_url":"https://hooks.example.com/waapi/cluster"}'Aquecimento
Conversas automáticas entre os seus números para aquecê-los.
get/api/v1/warmersLista os aquecimentosSó a chave da plataforma
Devolve todos os aquecimentos da sua API (array puro, sem envelope). Leitura livre mesmo sem warmup_enabled no plano.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Respostas
200Aquecimentos.json[ { "continuous": true, "created_at": "2026-10-01T12:00:00Z", "id": "7a6b5c4d-1111-4222-8333-944455556666", "max_messages": 0, "messages_per_hour": 60, "mode": "warmer_pairs", "name": "Aquecimento chips novos", "paused_by_plan": false, "paused_by_plan_at": null, "reachout_cooldown_seconds": 0, "status": "stopped", "updated_at": "2026-10-01T12:00:00Z" } ]401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers" \
-H "Authorization: Bearer $API_KEY"post/api/v1/warmersCria um aquecimentoSó a chave da plataforma
Cria um aquecimento em status=stopped, mode=warmer_pairs, messages_per_hour=60, max_messages=0 e continuous=true. Exige warmup_enabled no plano (403 plan_feature_disabled). O limite max_warmer_jobs conta só os aquecimentos rodando (active) e é checado ao ligar (PUT /warmers/{wid}/status): o novo nasce parado e não ocupa vaga, então só um plano com teto 0 recusa a criação (403 plan_limit com limit=max_warmer_jobs). As duas checagens vêm antes da validação do corpo.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
nameobrigatório | string |
{
"name": "Aquecimento chips novos"
}Respostas
201Aquecimento criado.json{ "continuous": true, "created_at": "2026-10-01T12:00:00Z", "id": "7a6b5c4d-1111-4222-8333-944455556666", "max_messages": 0, "messages_per_hour": 60, "mode": "warmer_pairs", "name": "Aquecimento chips novos", "paused_by_plan": false, "paused_by_plan_at": null, "reachout_cooldown_seconds": 0, "status": "stopped", "updated_at": "2026-10-01T12:00:00Z" }400nameausente ({"error":"name required"}).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Funçãowarmup_enabledfora do plano (plan_feature_disabled), plano com tetomax_warmer_jobs0 (plan_limit) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/warmers" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Aquecimento chips novos"}'get/api/v1/warmers/{wid}Detalha um aquecimentoSó a chave da plataforma
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Respostas
200Aquecimento.json{ "continuous": true, "created_at": "2026-10-01T12:00:00Z", "id": "7a6b5c4d-1111-4222-8333-944455556666", "max_messages": 0, "messages_per_hour": 60, "mode": "warmer_pairs", "name": "Aquecimento chips novos", "paused_by_plan": false, "paused_by_plan_at": null, "reachout_cooldown_seconds": 0, "status": "stopped", "updated_at": "2026-10-01T12:00:00Z" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>" \
-H "Authorization: Bearer $API_KEY"delete/api/v1/warmers/{wid}Exclui um aquecimentoSó a chave da plataforma
Livre mesmo sem warmup_enabled (o cliente sempre pode apagar o que criou); libera a vaga de max_warmer_jobs.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Respostas
200Excluído.json{ "status": "deleted" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (WARMER_NOT_STORED): nada muda; tente de novo.json{ "code": "WARMER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X DELETE "$API_URL/api/v1/warmers/<wid>" \
-H "Authorization: Bearer $API_KEY"get/api/v1/warmers/{wid}/audit-logsLista a trilha de auditoria do aquecimentoSó a chave da plataforma
Ações sobre o aquecimento (ex.: warmer.status.changed, warmer.schedule.updated, warmer.member.added, warmer.middleware.updated), mais recentes primeiro.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
event_typeopcional | query | string | Tipo exato do evento. |
searchopcional | query | string | Busca em tipo e payload. |
limitopcional | query | integer | Tamanho da página; inválido ou ≤ 0 vale 50 (sem teto). |
offsetopcional | query | integer |
Respostas
200Página de registros.json{ "audit_logs": [ { "created_at": "2026-10-01T12:10:00Z", "event_type": "warmer.status.changed", "id": "101", "payload": { "status": "active" }, "warmer_id": "7a6b5c4d-1111-4222-8333-944455556666" } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Aquecimento inexistente (também usado quando a consulta ao banco falha).json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/audit-logs" \
-H "Authorization: Bearer $API_KEY"get/api/v1/warmers/{wid}/errorsLista os erros do aquecimentoSó a chave da plataforma
Mais recentes primeiro. search busca (sem diferenciar maiúsculas) em tipo, mensagem, categoria e payload.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
instance_idopcional | query | string (uuid) | |
categoryopcional | query | string | Ex.: rate_limit, reachout, auth. |
severityopcional | query | "critical" | "error" | "warning" | |
searchopcional | query | string | |
limitopcional | query | integer | Tamanho da página; inválido ou ≤ 0 vale 50 (sem teto). |
offsetopcional | query | integer |
Respostas
200Página de erros.json{ "errors": [ { "category": "string", "created_at": "2026-01-01T12:00:00Z", "event_type": "string", "id": "string", "instance_id": "00000000-0000-4000-8000-000000000000", "instance_name": "string", "instance_phone": "string", "job_outcome": "string", "job_status": "string", "message": "string", "payload": {}, "severity": "critical", "warmer_id": "00000000-0000-4000-8000-000000000000" } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Aquecimento inexistente (também usado quando a consulta ao banco falha).json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/errors" \
-H "Authorization: Bearer $API_KEY"get/api/v1/warmers/{wid}/heatmapMapa de calor por hora do dia (7 dias)Só a chave da plataforma
Mensagens dos últimos 7 dias agrupadas por hora do dia (0–23). Com membros, o array tem sempre 24 posições (horas sem mensagens com zero); sem membros, vem vazio.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Respostas
200Horas do dia.json{ "heatmap": [ { "hour": 0, "received": 0, "sent": 0, "total": 0 } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Aquecimento inexistente (também usado quando a consulta ao banco falha).json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/heatmap" \
-H "Authorization: Bearer $API_KEY"get/api/v1/warmers/{wid}/membersLista os membros do aquecimentoSó a chave da plataforma
Membros em ordem de entrada, com nome, status, telefone e saúde copiados da instância viva.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Respostas
200Membros.json{ "members": [ { "added_at": "2026-10-01T12:05:00Z", "instance_id": "0d1e2f3a-4b5c-4d6e-8f70-819203a4b5c6", "name": "Chip 01", "phone": "5511999990000", "status": "online", "throttled_until": "0001-01-01T00:00:00Z" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/members" \
-H "Authorization: Bearer $API_KEY"post/api/v1/warmers/{wid}/membersAdiciona uma instância ao aquecimentoSó a chave da plataforma
Idempotente (uma instância que já é membro não gera erro). Exige warmup_enabled (403 plan_feature_disabled).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
instance_idobrigatório | string (uuid) |
{
"instance_id": "0d1e2f3a-4b5c-4d6e-8f70-819203a4b5c6"
}Respostas
200Adicionado.json{ "status": "added" }400instance_idausente, instância inexistente (instance not found) ou falha ao gravar.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit), função fora do plano (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/warmers/<wid>/members" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"instance_id":"0d1e2f3a-4b5c-4d6e-8f70-819203a4b5c6"}'delete/api/v1/warmers/{wid}/members/{id}Remove uma instância do aquecimentoSó a chave da plataforma
Livre mesmo sem warmup_enabled. Quem não é membro: 404.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
idobrigatório | path | string (uuid) | ID da instância membro. |
Respostas
200Removido.json{ "status": "removed" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Só a chave global abre esta rota; dá 403 com a chave do número membro (INSTANCE_KEY_SCOPE): ela só abre as rotas/api/v1/instances/{id}/…do próprio número.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key only opens the routes of that number (/api/v1/instances/{id})" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X DELETE "$API_URL/api/v1/warmers/<wid>/members/<id>" \
-H "Authorization: Bearer $API_KEY"put/api/v1/warmers/{wid}/members/{id}/pausePausa ou retoma um membroSó a chave da plataforma
Um membro pausado sai da escolha de pares do agendador. Livre mesmo sem warmup_enabled. Quem não é membro: 404 (nada muda).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
idobrigatório | path | string (uuid) | ID da instância membro. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
pausedopcional | boolean |
{
"paused": true
}Respostas
200Atualizado.json{ "paused": true, "status": "updated" }400Corpo inválido ({"error":"paused required"}).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ao retomar (paused: falseou ausente); pausar continua liberado. Também a chave do número membro (INSTANCE_KEY_SCOPE): ela só abre as rotas/api/v1/instances/{id}/…do próprio número.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key only opens the routes of that number (/api/v1/instances/{id})" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco falhou ao gravar a pausa: nada muda; tente de novo.json{ "error": "invalid request" }
Exemplo
curl -X PUT "$API_URL/api/v1/warmers/<wid>/members/<id>/pause" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"paused":true}'put/api/v1/warmers/{wid}/members/{id}/reachout-cooldownDefine o intervalo de reachout de um membroSó a chave da plataforma
Sobrepõe o intervalo do aquecimento para este membro (0 = usar o do aquecimento). O valor da própria instância, se > 0, ainda tem precedência. Negativo vira 0. Exige warmup_enabled (403 plan_feature_disabled).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
idobrigatório | path | string (uuid) | ID da instância membro. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
secondsopcional | integer | Segundos; negativo vira 0. |
{
"seconds": 900
}Respostas
200Atualizado.json{ "reachout_cooldown_seconds": 900, "status": "updated" }400Corpo inválido ({"error":"seconds required"}).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit) ou função fora do plano (plan_feature_disabled), ou a chave do número membro (INSTANCE_KEY_SCOPE): ela só abre as rotas/api/v1/instances/{id}/…do próprio número.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key only opens the routes of that number (/api/v1/instances/{id})" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (WARMER_NOT_STORED): nada muda; tente de novo.json{ "code": "WARMER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/warmers/<wid>/members/<id>/reachout-cooldown" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"seconds":900}'get/api/v1/warmers/{wid}/messagesLista as mensagens dos membros do aquecimentoSó a chave da plataforma
Lê do PostgreSQL as mensagens de todas as instâncias membro (todas as origens, não só source=warmer, a menos que filtrado), mais recentes primeiro. search busca (sem diferenciar maiúsculas) em corpo, remetente, origem e conversa.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
instance_idopcional | query | string (uuid) | Restringe a um membro; uma instância fora do aquecimento responde 404. |
directionopcional | query | "inbound" | "outbound" | |
sourceopcional | query | string | Ex.: warmer. |
searchopcional | query | string | |
limitopcional | query | integer | Tamanho da página; inválido ou ≤ 0 vale 50 (sem teto). |
offsetopcional | query | integer |
Respostas
200Página de mensagens.json{ "limit": 0, "messages": [ { "body": "Oi, tudo bem?", "direction": "inbound", "from": "5581999990000@s.whatsapp.net", "id": "3EB0A1B2C3D4E5F60718", "instance_id": "0d1e2f3a-4b5c-4d6e-8f70-819203a4b5c6", "is_group": false, "recipient": "5511999990000", "sender": "5581999990000@s.whatsapp.net", "source": "warmer", "timestamp": "2026-10-01T14:03:00Z" } ], "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Aquecimento inexistente,instance_idfora do aquecimento (instance not in warmer) ou falha na consulta.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/messages" \
-H "Authorization: Bearer $API_KEY"get/api/v1/warmers/{wid}/middlewaresLista as etapas (middlewares) do aquecimentoSó a chave da plataforma
Etapas em ordem de position. O api_key dentro de config vem mascarado.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Respostas
200Etapas.json{ "middlewares": [ { "config": { "api_key": "sk-or-exemplo", "model": "openai/gpt-4o-mini", "prompt": "Converse de forma natural e curta, em português.", "provider": "openrouter" }, "created_at": "2026-01-01T12:00:00Z", "enabled": false, "id": "00000000-0000-4000-8000-000000000000", "position": 0, "type": "warmer_ai", "updated_at": "2026-01-01T12:00:00Z", "warmer_id": "00000000-0000-4000-8000-000000000000" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/middlewares" \
-H "Authorization: Bearer $API_KEY"post/api/v1/warmers/{wid}/middlewaresAdiciona uma etapa ao aquecimentoSó a chave da plataforma
Exige warmup_enabled (403 plan_feature_disabled). Os tipos que chamam um LLM (ai_rewrite, warmer_ai) exigem também ai_rewrite_enabled. type não é validado na criação: um tipo desconhecido ou uma config sem model é ignorado ao montar o pipeline.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
configopcional | object | Configuração da etapa (objeto livre; vazio = {}). Para warmer_ai/ai_rewrite:
provider (openrouter|custom), base_url (obrigatório com custom), api_key
(mascarado na leitura), model (obrigatório para a etapa rodar), prompt,
temperature, max_tokens, on_failure (passthrough padrão | block); ai_rewrite
tem ainda apply_on_outbound e apply_on_inbound. |
config.api_keyopcional | string | |
config.apply_on_inboundopcional | boolean | |
config.apply_on_outboundopcional | boolean | |
config.base_urlopcional | string (uri) | |
config.max_tokensopcional | integer | |
config.modelopcional | string | |
config.on_failureopcional | "passthrough" | "block" | |
config.promptopcional | string | |
config.provideropcional | "openrouter" | "custom" | |
config.temperatureopcional | number | |
enabledopcional | boolean | |
positionopcional | integer | Negativo vira 0. |
typeobrigatório | string | Tipo da etapa. Tipos com efeito: ai_rewrite (reescreve o texto) e warmer_ai (gera o
próximo turno da conversa); ambos chamam um LLM e exigem ai_rewrite_enabled. Outros
valores são aceitos e gravados, mas ignorados no pipeline. |
{
"config": {
"api_key": "sk-or-exemplo",
"model": "openai/gpt-4o-mini",
"prompt": "Converse de forma natural e curta, em português.",
"provider": "openrouter"
},
"enabled": true,
"position": 0,
"type": "warmer_ai"
}Respostas
201Etapa criada.json{ "config": { "api_key": "sk-or-exemplo", "model": "openai/gpt-4o-mini", "prompt": "Converse de forma natural e curta, em português.", "provider": "openrouter" }, "created_at": "2026-01-01T12:00:00Z", "enabled": false, "id": "00000000-0000-4000-8000-000000000000", "position": 0, "type": "warmer_ai", "updated_at": "2026-01-01T12:00:00Z", "warmer_id": "00000000-0000-4000-8000-000000000000" }400typeausente ({"error":"type required"}).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit), função fora do plano (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/warmers/<wid>/middlewares" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"config":{"api_key":"sk-or-exemplo","model":"openai/gpt-4o-mini","prompt":"Converse de forma natural e curta, em português.","provider":"openrouter"},"enabled":true,"position":0,"type":"warmer_ai"}'put/api/v1/warmers/{wid}/middlewares/{mid}Atualiza uma etapa do aquecimentoSó a chave da plataforma
Atualização parcial: campo omitido mantém o valor gravado; um config objeto é mesclado sobre o gravado (chaves não enviadas, como api_key, são mantidas; uma api_key mascarada ou ausente mantém a gravada, a não ser com outra base_url, provider ou format: 400 MASKED_SECRET_NEW_DESTINATION, e é preciso mandar a chave de novo). Um corpo com "enabled":false (desligar = pausar), com ou sem outros campos, é sempre permitido, inclusive com a conta suspensa; qualquer outra edição exige warmup_enabled e, se a etapa é ai_rewrite/warmer_ai, também ai_rewrite_enabled (403 plan_feature_disabled) e, com a conta suspensa ou cancelada, dá 403 ACCOUNT_SUSPENDED. Um mid que não existe neste aquecimento: 404.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
midobrigatório | path | string (uuid) | ID da etapa (middleware). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
configopcional | object | Configuração da etapa (objeto livre; vazio = {}). Para warmer_ai/ai_rewrite:
provider (openrouter|custom), base_url (obrigatório com custom), api_key
(mascarado na leitura), model (obrigatório para a etapa rodar), prompt,
temperature, max_tokens, on_failure (passthrough padrão | block); ai_rewrite
tem ainda apply_on_outbound e apply_on_inbound. |
config.api_keyopcional | string | |
config.apply_on_inboundopcional | boolean | |
config.apply_on_outboundopcional | boolean | |
config.base_urlopcional | string (uri) | |
config.max_tokensopcional | integer | |
config.modelopcional | string | |
config.on_failureopcional | "passthrough" | "block" | |
config.promptopcional | string | |
config.provideropcional | "openrouter" | "custom" | |
config.temperatureopcional | number | |
enabledopcional | boolean | |
positionopcional | integer |
{
"enabled": false
}Respostas
200Atualizada.json{ "status": "updated" }400Corpo inválido ({"error":"invalid body"}), ou outrabase_url,providerouformatcom aapi_keymascarada ou ausente (MASKED_SECRET_NEW_DESTINATION; nada muda).json{ "code": "MASKED_SECRET_NEW_DESTINATION", "error": "Send the key again when the URL, provider or format changes." }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit), função fora do plano (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED) numa edição que não desliga a etapa.json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X PUT "$API_URL/api/v1/warmers/<wid>/middlewares/<mid>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled":false}'delete/api/v1/warmers/{wid}/middlewares/{mid}Exclui uma etapa do aquecimentoSó a chave da plataforma
Livre mesmo sem warmup_enabled/ai_rewrite_enabled. Uma etapa inexistente: 404.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
midobrigatório | path | string (uuid) | ID da etapa (middleware). |
Respostas
200Excluída.json{ "status": "deleted" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X DELETE "$API_URL/api/v1/warmers/<wid>/middlewares/<mid>" \
-H "Authorization: Bearer $API_KEY"get/api/v1/warmers/{wid}/queueLista os jobs de envio do aquecimentoSó a chave da plataforma
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
statusopcional | query | "pending" | "sending" | "completed" | "failed" | "cancelled" | Filtra por um status. |
limitopcional | query | integer | 1–200; fora disso vale 50. |
offsetopcional | query | integer |
Respostas
200Página de jobs.json{ "jobs": [ { "attempts": [ { "attempted_at": null, "category": null, "consecutive_failures": null, "instance_id": null, "instance_name": null, "instance_phone": null, "is_healthy": null, "last_failure_category": null, "message": null, "throttled_until": null } ], "attempts_count": 0, "body": "string", "completed_at": "2026-01-01T12:00:00Z", "completed_instance_id": "00000000-0000-4000-8000-000000000000", "conversation_id": "00000000-0000-4000-8000-000000000000", "created_at": "2026-01-01T12:00:00Z", "failed_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "kind": "text", "last_error": "string", "last_error_category": "string", "message_id": "string", "next_attempt_at": "2026-01-01T12:00:00Z", "payload": {}, "receiver_instance_id": "00000000-0000-4000-8000-000000000000", "recipient": "5581999990000", "sender_instance_id": "00000000-0000-4000-8000-000000000000", "status": "pending", "updated_at": "2026-01-01T12:00:00Z", "warmer_id": "00000000-0000-4000-8000-000000000000" } ], "limit": 0, "offset": 0, "total": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/queue" \
-H "Authorization: Bearer $API_KEY"post/api/v1/warmers/{wid}/queue/retry-allReenfileira em lote os jobs do aquecimentoSó a chave da plataforma
Volta a pending (tentativas zeradas) os jobs do aquecimento nos status pedidos (padrão failed,cancelled), opcionalmente só os que envolvem uma instância (remetente, destinatário ou alguma tentativa). Jobs cancelados por cobrança (last_error_category=billing) ficam de fora. Corpo opcional, em JSON ou formulário. Exige warmup_enabled (403 plan_feature_disabled).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
instance_idopcional | string (uuid) | Só jobs em que esta instância é remetente, destinatária ou aparece numa tentativa. |
statusopcional | string | Status separados por vírgula; padrão failed,cancelled. |
{
"instance_id": "00000000-0000-4000-8000-000000000000",
"status": "failed,cancelled"
}Respostas
200Quantidade reenfileirada.json{ "retried": 4 }400JSON inválido (invalid retry-all request) ouinstance_idque não é UUID (invalid UUID filter).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit), função fora do plano (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/warmers/<wid>/queue/retry-all" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"instance_id":"00000000-0000-4000-8000-000000000000","status":"failed,cancelled"}'get/api/v1/warmers/{wid}/queue/{job_id}Detalha um job de envioSó a chave da plataforma
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
job_idobrigatório | path | string (uuid) | ID do job de envio. |
Respostas
200Job.json{ "attempts": [ { "attempted_at": "2026-01-01T12:00:00Z", "category": "string", "consecutive_failures": 0, "instance_id": "00000000-0000-4000-8000-000000000000", "instance_name": "string", "instance_phone": "string", "is_healthy": false, "last_failure_category": "string", "message": "string", "throttled_until": "2026-01-01T12:00:00Z" } ], "attempts_count": 0, "body": "string", "completed_at": "2026-01-01T12:00:00Z", "completed_instance_id": "00000000-0000-4000-8000-000000000000", "conversation_id": "00000000-0000-4000-8000-000000000000", "created_at": "2026-01-01T12:00:00Z", "failed_at": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "kind": "text", "last_error": "string", "last_error_category": "string", "message_id": "string", "next_attempt_at": "2026-01-01T12:00:00Z", "payload": {}, "receiver_instance_id": "00000000-0000-4000-8000-000000000000", "recipient": "5581999990000", "sender_instance_id": "00000000-0000-4000-8000-000000000000", "status": "pending", "updated_at": "2026-01-01T12:00:00Z", "warmer_id": "00000000-0000-4000-8000-000000000000" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Aquecimento inexistente ou job que não pertence a ele.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/queue/<job_id>" \
-H "Authorization: Bearer $API_KEY"post/api/v1/warmers/{wid}/queue/{job_id}/cancelCancela um jobSó a chave da plataforma
Só cancela jobs pending ou failed (outros: 409). Livre mesmo sem warmup_enabled.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
job_idobrigatório | path | string (uuid) | ID do job de envio. |
Respostas
200Cancelado.json{ "job_id": "3f1c2b9a-6d1e-4a0b-9c55-0a1b2c3d4e5f", "status": "cancelled" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/warmers/<wid>/queue/<job_id>/cancel" \
-H "Authorization: Bearer $API_KEY"post/api/v1/warmers/{wid}/queue/{job_id}/retryReenfileira um jobSó a chave da plataforma
Um job failed ou cancelled volta a pending com as tentativas zeradas; um pending é antecipado para agora. Outros status: 409. Exige warmup_enabled (403 plan_feature_disabled).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
job_idobrigatório | path | string (uuid) | ID do job de envio. |
Respostas
200Reenfileirado.json{ "job_id": "3f1c2b9a-6d1e-4a0b-9c55-0a1b2c3d4e5f", "status": "retrying" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit), função fora do plano (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X POST "$API_URL/api/v1/warmers/<wid>/queue/<job_id>/retry" \
-H "Authorization: Bearer $API_KEY"put/api/v1/warmers/{wid}/reachout-cooldownDefine o intervalo de reachout do aquecimentoSó a chave da plataforma
Intervalo padrão (segundos) entre turnos de um membro neste aquecimento. Negativo vira 0. O valor da instância (se > 0) e o do membro (se > 0) têm precedência sobre este. Exige warmup_enabled (403 plan_feature_disabled).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
secondsopcional | integer | Segundos; negativo vira 0. |
{
"seconds": 900
}Respostas
200Atualizado.json{ "reachout_cooldown_seconds": 900, "status": "updated" }400Corpo inválido ({"error":"seconds required"}).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit) ou função fora do plano (plan_feature_disabled).json{ "code": "plan_limit", "error": "Plan limit reached: max_instances.", "limit": "max_instances" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (WARMER_NOT_STORED): nada muda; tente de novo.json{ "code": "WARMER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/warmers/<wid>/reachout-cooldown" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"seconds":900}'put/api/v1/warmers/{wid}/scheduleDefine ritmo, teto e janela do aquecimentoSó a chave da plataforma
Substitui todos os campos do agendamento (campo omitido vira zero/vazio/false). Valores negativos viram 0. max_messages só vale com continuous=false. Exige warmup_enabled (403 plan_feature_disabled).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
active_window_endopcional | string | HH:MM; vazio = sem janela. |
active_window_startopcional | string | HH:MM; vazio = sem janela. |
continuousopcional | boolean | |
max_messagesopcional | integer | Negativo vira 0; 0 = sem teto. |
messages_per_houropcional | integer | Negativo vira 0. |
{
"active_window_end": "20:00",
"active_window_start": "08:00",
"continuous": false,
"max_messages": 500,
"messages_per_hour": 30
}Respostas
200Atualizado.json{ "status": "updated" }400Corpo inválido ({"error":"invalid body"}).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Limite do plano (plan_limit) ou função fora do plano (plan_feature_disabled).json{ "code": "plan_limit", "error": "Plan limit reached: max_instances.", "limit": "max_instances" }404Aquecimento inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (WARMER_NOT_STORED): nada muda; tente de novo.json{ "code": "WARMER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/warmers/<wid>/schedule" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"active_window_end":"20:00","active_window_start":"08:00","continuous":false,"max_messages":500,"messages_per_hour":30}'get/api/v1/warmers/{wid}/statsEstatísticas do aquecimentoSó a chave da plataforma
Contadores agregados e por membro: mensagens com source='warmer' enviadas e recebidas, erros registrados, jobs da fila e hours_warming (intervalo entre a primeira e a última mensagem). Sem membros, os totais vêm zerados e members vazio.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Respostas
200Estatísticas.json{ "failed_jobs": 0, "hours_warming": 0, "last_error_at": "2026-01-01T12:00:00Z", "last_received_at": "2026-01-01T12:00:00Z", "last_sent_at": "2026-01-01T12:00:00Z", "members": [ { "attempts_count": 0, "error_count": 0, "failed_attempts_count": 0, "instance_id": "00000000-0000-4000-8000-000000000000", "last_error_at": "2026-01-01T12:00:00Z", "last_received_at": "2026-01-01T12:00:00Z", "last_sent_at": "2026-01-01T12:00:00Z", "name": "string", "phone": "string", "received_count": 0, "sent_count": 0 } ], "pending_jobs": 0, "total_errors": 0, "total_jobs": 0, "total_received": 0, "total_sent": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Aquecimento inexistente (também usado quando a consulta ao banco falha).json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/stats" \
-H "Authorization: Bearer $API_KEY"put/api/v1/warmers/{wid}/statusLiga, pausa ou para o aquecimentoSó a chave da plataforma
paused e stopped são sempre permitidos. Pedir active exige warmup_enabled (403 plan_feature_disabled) e respeita max_warmer_jobs contando só os aquecimentos rodando (sem contar este; religar um que já roda é idempotente): no teto, 403 plan_limit; com a conta suspensa ou cancelada, 403 ACCOUNT_SUSPENDED. Um valor fora de active|paused|stopped: 400 {"error":"invalid status"}. O status escolhido aqui substitui a pausa do plano: paused_by_plan volta a false e um aquecimento pausado pelo plano não volta mais sozinho quando o plano sobe.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
statusobrigatório | "active" | "paused" | "stopped" |
{
"status": "active"
}Respostas
200Status trocado.json{ "status": "updated", "warmer_status": "active" }400statusausente (status required) ou inválido (invalid status).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Pedido deactivecomwarmup_enabledfora do plano (plan_feature_disabled), no tetomax_warmer_jobs(plan_limit) ou com a conta suspensa ou cancelada (ACCOUNT_SUSPENDED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500O banco não aceitou a mudança (WARMER_NOT_STORED): nada muda; tente de novo.json{ "code": "WARMER_NOT_STORED", "error": "could not store the change; nothing changed" }
Exemplo
curl -X PUT "$API_URL/api/v1/warmers/<wid>/status" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"active"}'get/api/v1/warmers/{wid}/timelineLinha do tempo das últimas 24 horasSó a chave da plataforma
Mensagens do aquecimento por hora (UTC) nas últimas 24 horas; só horas com atividade aparecem, em ordem crescente.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
widobrigatório | path | string (uuid) | ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo). |
Respostas
200Baldes por hora.json{ "timeline": [ { "bucket": "2026-01-01T12:00:00Z", "bucket_text": "14:00", "received": 0, "sent": 0, "total": 0 } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }404Aquecimento inexistente (também usado quando a consulta ao banco falha).json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/warmers/<wid>/timeline" \
-H "Authorization: Bearer $API_KEY"Campanhas
Disparos para um público por tags, com janela de horário, ritmo, relatório e recibos.
get/api/v1/marketing/campaignsLista campanhasChave de API
Com chave de cliente restrita a alguns números, só as campanhas e os fluxos cujo remetente está todo na lista.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
cursoropcional | query | string (uuid) | Cursor opaco: o nextCursor da página anterior. |
limitopcional | query | integer | Itens por página. |
Respostas
200Página (ordem por ID).json{ "campaigns": [ { "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" } ], "nextCursor": "string" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível.json{ "error": "marketing storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/campaigns" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/campaignsCria uma campanha (rascunho)Chave de API
Aplica padrões (fuso America/Sao_Paulo, janela 08:00–20:00, 6/min). 403 plan_limit max_campaign_rate_per_minute se ratePerMinute passa do plano.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}.
Chave: chave da plataforma, chave de API (wck_...)
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
audienceobrigatório | object | tags e/ou crmStages (pelo menos um). Com os dois, a união: cada contato entra uma vez. |
audience.crmStagesopcional | object | Os contatos dos negócios abertos nestas etapas do funil. As etapas precisam ser do funil (400 crm_stage_not_found); sem crm_enabled no plano, 403 plan_feature_disabled. |
audience.crmStages.pipelineIdobrigatório | string (uuid) | |
audience.crmStages.stageIdsobrigatório | array<string (uuid)> | |
audience.tagsopcional | array<string> | Contatos com qualquer uma destas tags. Pode ser vazio quando há crmStages. |
defaultsopcional | object | Valor por variável quando o contato não tem o campo. |
messageobrigatório | object | |
message.mediaUrlopcional | string (uri) | URL http(s) obrigatória em image/video/document. |
message.templateopcional | CampaignTemplate | O template de uma campanha, com o cabeçalho de mídia e os botões dinâmicos, como o POST /instances/{id}/send-template os recebe. Os valores do corpo, do cabeçalho de texto e dos botões aceitam {{nome}} e {{<campo>}}; o link da mídia não. Na criação e no PATCH, com o template na lista sincronizada da conta do remetente: o que falta ou sobra é 400 template_parameters; um template de autenticação (ou um code) é 400 template_authentication_campaign, porque o código vai só no envio direto. Um link de mídia para endereço privado, de loopback ou link-local é recusado. |
message.template.header_parametersopcional | array<string> | Os valores das variáveis de um cabeçalho de texto. |
message.template.languageobrigatório | string | O código do idioma do template (pt_BR, en_US). |
message.template.nameobrigatório | string | |
message.template.namedopcional | object | Os valores por nome, num template named ({"first_name":"Ana"}). |
message.template.parametersopcional | array<string> | Os valores do corpo por posição: o 1º preenche {{1}}, e assim por diante. |
message.template.buttonsopcional | array<object> | Os valores dos botões dinâmicos, pela posição do botão no template (de 0). |
message.template.buttons[].indexobrigatório | integer | |
message.template.buttons[].textobrigatório | string | |
message.template.codeopcional | string | Recusado (400 template_authentication_campaign); o código de autenticação vai só no envio direto. |
message.template.header_mediaopcional | object | link (https público) ou id (uma mídia já enviada à Meta), um dos dois; filename só num documento. |
message.template.header_media.filenameopcional | string | |
message.template.header_media.idopcional | string | |
message.template.header_media.linkopcional | string (uri) | |
message.textopcional | string | Obrigatório em text; legenda nas mídias. Variáveis {{nome}} e {{<campo>}} dos fields do contato. |
message.typeobrigatório | "text" | "image" | "video" | "document" | "template" | template: um template aprovado de número oficial, o único tipo que um remetente oficial aceita (senão 400 needs_template); só com remetentes oficiais (senão 400 provider_unsupported). Remetentes que misturam números oficiais e QR → 400 sender_mixed. Na campanha, o código da falha da Meta depois do aceite é META_<n> (last_error_code). O template é conferido com o aprovado (400 template_parameters, template_authentication_campaign). |
nameobrigatório | string | Não pode ser só espaços. |
ratePerMinuteopcional | integer | Envios por minuto; acima de max_campaign_rate_per_minute dá 403 plan_limit. |
scheduledAtopcional | string | null (date-time) | Início futuro: ao dar start a campanha fica scheduled até esta hora. |
senderobrigatório | object | Exatamente um entre instanceIds (1–100, rodízio) e clusterId. As instâncias (ou os membros do cluster) precisam existir ao congelar o público. |
sender.clusterIdopcional | string (uuid) | |
sender.instanceIdsopcional | array<string (uuid)> | |
timezoneopcional | string | Fuso IANA da janela. |
windowopcional | object | Janela diária de envio (HH:MM); início e fim diferentes. |
window.endopcional | string | |
window.startopcional | string |
{
"audience": {
"tags": [
"clientes"
]
},
"defaults": {
"cidade": "sua cidade"
},
"message": {
"text": "Olá {{nome}}, oferta em {{cidade}}!",
"type": "text"
},
"name": "Black Friday",
"ratePerMinute": 6,
"scheduledAt": null,
"sender": {
"instanceIds": [
"3f2a9c10-2222-4d44-8b55-000000000020"
]
},
"timezone": "America/Sao_Paulo",
"window": {
"end": "20:00",
"start": "08:00"
}
}Respostas
201Campanha criada emdraft.json{ "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido), ou remetente que lista um número removido da conta (UNKNOWN_INSTANCE).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled), limite do plano (plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ou remetente fora da lista da chave de cliente (SENDER_NOT_ALLOWED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/campaigns" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"audience":{"tags":["clientes"]},"defaults":{"cidade":"sua cidade"},"message":{"text":"Olá {{nome}}, oferta em {{cidade}}!","type":"text"},"name":"Black Friday","ratePerMinute":6,"scheduledAt":null,"sender":{"instanceIds":["3f2a9c10-2222-4d44-8b55-000000000020"]},"timezone":"America/Sao_Paulo","window":{"end":"20:00","start":"08:00"}}'get/api/v1/marketing/campaigns/{id}Mostra uma campanhaChave de API
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
Respostas
200Campanha.json{ "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/campaigns/<id>" \
-H "Authorization: Bearer $API_KEY"patch/api/v1/marketing/campaigns/{id}Substitui a configuração da campanhaChave de API
Envie a configuração inteira. Só em draft ou scheduled (senão 409). Em scheduled o público é recongelado na mesma transação, sem consumir outra campanha do mês; remetente inexistente dá 400.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
audienceobrigatório | object | tags e/ou crmStages (pelo menos um). Com os dois, a união: cada contato entra uma vez. |
audience.crmStagesopcional | object | Os contatos dos negócios abertos nestas etapas do funil. As etapas precisam ser do funil (400 crm_stage_not_found); sem crm_enabled no plano, 403 plan_feature_disabled. |
audience.crmStages.pipelineIdobrigatório | string (uuid) | |
audience.crmStages.stageIdsobrigatório | array<string (uuid)> | |
audience.tagsopcional | array<string> | Contatos com qualquer uma destas tags. Pode ser vazio quando há crmStages. |
defaultsopcional | object | Valor por variável quando o contato não tem o campo. |
messageobrigatório | object | |
message.mediaUrlopcional | string (uri) | URL http(s) obrigatória em image/video/document. |
message.templateopcional | CampaignTemplate | O template de uma campanha, com o cabeçalho de mídia e os botões dinâmicos, como o POST /instances/{id}/send-template os recebe. Os valores do corpo, do cabeçalho de texto e dos botões aceitam {{nome}} e {{<campo>}}; o link da mídia não. Na criação e no PATCH, com o template na lista sincronizada da conta do remetente: o que falta ou sobra é 400 template_parameters; um template de autenticação (ou um code) é 400 template_authentication_campaign, porque o código vai só no envio direto. Um link de mídia para endereço privado, de loopback ou link-local é recusado. |
message.template.header_parametersopcional | array<string> | Os valores das variáveis de um cabeçalho de texto. |
message.template.languageobrigatório | string | O código do idioma do template (pt_BR, en_US). |
message.template.nameobrigatório | string | |
message.template.namedopcional | object | Os valores por nome, num template named ({"first_name":"Ana"}). |
message.template.parametersopcional | array<string> | Os valores do corpo por posição: o 1º preenche {{1}}, e assim por diante. |
message.template.buttonsopcional | array<object> | Os valores dos botões dinâmicos, pela posição do botão no template (de 0). |
message.template.buttons[].indexobrigatório | integer | |
message.template.buttons[].textobrigatório | string | |
message.template.codeopcional | string | Recusado (400 template_authentication_campaign); o código de autenticação vai só no envio direto. |
message.template.header_mediaopcional | object | link (https público) ou id (uma mídia já enviada à Meta), um dos dois; filename só num documento. |
message.template.header_media.filenameopcional | string | |
message.template.header_media.idopcional | string | |
message.template.header_media.linkopcional | string (uri) | |
message.textopcional | string | Obrigatório em text; legenda nas mídias. Variáveis {{nome}} e {{<campo>}} dos fields do contato. |
message.typeobrigatório | "text" | "image" | "video" | "document" | "template" | template: um template aprovado de número oficial, o único tipo que um remetente oficial aceita (senão 400 needs_template); só com remetentes oficiais (senão 400 provider_unsupported). Remetentes que misturam números oficiais e QR → 400 sender_mixed. Na campanha, o código da falha da Meta depois do aceite é META_<n> (last_error_code). O template é conferido com o aprovado (400 template_parameters, template_authentication_campaign). |
nameobrigatório | string | Não pode ser só espaços. |
ratePerMinuteopcional | integer | Envios por minuto; acima de max_campaign_rate_per_minute dá 403 plan_limit. |
scheduledAtopcional | string | null (date-time) | Início futuro: ao dar start a campanha fica scheduled até esta hora. |
senderobrigatório | object | Exatamente um entre instanceIds (1–100, rodízio) e clusterId. As instâncias (ou os membros do cluster) precisam existir ao congelar o público. |
sender.clusterIdopcional | string (uuid) | |
sender.instanceIdsopcional | array<string (uuid)> | |
timezoneopcional | string | Fuso IANA da janela. |
windowopcional | object | Janela diária de envio (HH:MM); início e fim diferentes. |
window.endopcional | string | |
window.startopcional | string |
{
"audience": {
"tags": [
"clientes"
]
},
"defaults": {
"cidade": "sua cidade"
},
"message": {
"text": "Olá {{nome}}, oferta em {{cidade}}!",
"type": "text"
},
"name": "Black Friday",
"ratePerMinute": 6,
"scheduledAt": null,
"sender": {
"instanceIds": [
"3f2a9c10-2222-4d44-8b55-000000000020"
]
},
"timezone": "America/Sao_Paulo",
"window": {
"end": "20:00",
"start": "08:00"
}
}Respostas
200Campanha atualizada.json{ "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido), remetente que lista um número removido da conta (UNKNOWN_INSTANCE) ou, numa campanhascheduled(o público é refeito), remetente sem número existente (invalid campaign sender).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled), limite do plano (plan_limit) ou remetente fora da lista da chave de cliente (SENDER_NOT_ALLOWED).json{ "code": "SENDER_NOT_ALLOWED", "error": "sender not allowed for this key" }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X PATCH "$API_URL/api/v1/marketing/campaigns/<id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"audience":{"tags":["clientes"]},"defaults":{"cidade":"sua cidade"},"message":{"text":"Olá {{nome}}, oferta em {{cidade}}!","type":"text"},"name":"Black Friday","ratePerMinute":6,"scheduledAt":null,"sender":{"instanceIds":["3f2a9c10-2222-4d44-8b55-000000000020"]},"timezone":"America/Sao_Paulo","window":{"end":"20:00","start":"08:00"}}'post/api/v1/marketing/campaigns/{id}/cancelCancela a campanhaChave de API
Qualquer estado exceto completed (409) vai para cancelled e marca finishedAt. Sem corpo. A ação do cliente substitui a pausa do plano: a espera plan_downgrade some e a campanha não volta mais sozinha quando o plano sobe.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
Respostas
200Campanha no novo estado.json{ "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/campaigns/<id>/cancel" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/campaigns/{id}/pausePausa a campanhaChave de API
De running, scheduled ou paused (idempotente) para paused; senão 409. Sem corpo. A ação do cliente substitui a pausa do plano: a espera plan_downgrade some e a campanha não volta mais sozinha quando o plano sobe.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
Respostas
200Campanha no novo estado.json{ "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/campaigns/<id>/pause" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/campaigns/{id}/previewPrévia do público e do textoChave de API
Corpo JSON obrigatório (pode ser {}). 404 se a campanha ou o contato não existem.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
contactIdopcional | string (uuid) | Opcional: renderiza o texto para este contato (após o start, com o snapshot congelado). |
{
"contactId": "c0a8012e-0000-4000-8000-000000000001"
}Respostas
200Prévia.json{ "audience": { "eligible": 115, "skippedOptOut": 5, "total": 120 }, "text": "Olá Maria, oferta em Recife!" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/campaigns/<id>/preview" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"contactId":"c0a8012e-0000-4000-8000-000000000001"}'get/api/v1/marketing/campaigns/{id}/recipientsLista destinatários da campanhaChave de API
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
statusopcional | query | "pending" | "sent" | "delivered" | "read" | "failed" | "skipped_optout" | "skipped_duplicate" | Filtra por status. |
cursoropcional | query | string (uuid) | Cursor opaco: o nextCursor da página anterior. |
limitopcional | query | integer | Itens por página. |
Respostas
200Página de destinatários (ordem por ID).json{ "nextCursor": "string", "recipients": [ { "attempts": 0, "contactId": "00000000-0000-4000-8000-000000000000", "createdAt": "2026-01-01T12:00:00Z", "deliveredAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "instanceId": "string", "lastErrorCode": "string", "messageId": "string", "phone": "string", "readAt": "2026-01-01T12:00:00Z", "sentAt": "2026-01-01T12:00:00Z", "status": "pending", "updatedAt": "2026-01-01T12:00:00Z" } ] }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/campaigns/<id>/recipients" \
-H "Authorization: Bearer $API_KEY"get/api/v1/marketing/campaigns/{id}/reportRelatório da campanhaChave de API
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
cursoropcional | query | string (uuid) | Cursor opaco: o nextCursor da página anterior. |
limitopcional | query | integer | Itens por página. |
Respostas
200Relatório com as falhas paginadas.json{ "campaign": { "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" }, "failures": [ { "attempts": 0, "contactId": "00000000-0000-4000-8000-000000000000", "createdAt": "2026-01-01T12:00:00Z", "deliveredAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "instanceId": "string", "lastErrorCode": "string", "messageId": "string", "phone": "string", "readAt": "2026-01-01T12:00:00Z", "sentAt": "2026-01-01T12:00:00Z", "status": "pending", "updatedAt": "2026-01-01T12:00:00Z" } ], "limit": 0, "nextCursor": "string", "period": { "end": "2026-01-01T12:00:00Z", "start": "2026-01-01T12:00:00Z" }, "stats": { "delivered": 0, "failed": 1, "pending": 1, "perInstance": [ { "connected": true, "delivered": 0, "failed": 1, "instanceId": "3f2a9c10-2222-4d44-8b55-000000000020", "pending": 1, "read": 0, "sent": 1, "skippedDuplicate": 0, "skippedOptOut": 0, "total": 3 } ], "read": 0, "sent": 1, "skippedDuplicate": 0, "skippedOptOut": 0, "total": 3, "waiting": { "instanceIds": [], "reason": "outside_window", "since": "2026-10-01T23:00:00Z" } } }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/campaigns/<id>/report" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/campaigns/{id}/resumeRetoma a campanhaChave de API
Só de paused, para running (ou scheduled se scheduledAt é futuro); senão 409. Sem corpo. Uma campanha pausada pelo plano só retoma se ainda couber em max_campaigns_per_month do mês em que começou (403 plan_limit); retomada, deixa de ser pausa do plano (a espera plan_downgrade some).
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
Respostas
200Campanha no novo estado.json{ "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido), ou remetente com número removido enquanto a campanha estava pausada (UNKNOWN_INSTANCE).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled), campanha pausada pelo plano que não cabe mais emmax_campaigns_per_month(plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ou remetente fora da lista da chave de cliente (SENDER_NOT_ALLOWED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/campaigns/<id>/resume" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/campaigns/{id}/startInicia a campanhaChave de API
Só em draft (409 nos demais; repetir após o start devolve 200 sem recriar o lote). Congela o público (opt-outs viram skipped_optout) e vai para running, ou scheduled se scheduledAt é futuro. 403 plan_limit com max_campaigns_per_month (campanhas iniciadas no mês UTC) ou max_campaign_rate_per_minute; 400 se um remetente não existe ou o cluster está vazio. Sem corpo.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
Respostas
200Campanha no novo estado.json{ "audience": { "tags": [ "clientes" ] }, "defaults": { "cidade": "sua cidade" }, "message": { "text": "Olá {{nome}}, oferta em {{cidade}}!", "type": "text" }, "name": "Black Friday", "ratePerMinute": 6, "scheduledAt": null, "sender": { "instanceIds": [ "3f2a9c10-2222-4d44-8b55-000000000020" ] }, "timezone": "America/Sao_Paulo", "window": { "end": "20:00", "start": "08:00" }, "createdAt": "2026-01-01T12:00:00Z", "createdBy": "api", "finishedAt": "2026-01-01T12:00:00Z", "id": "00000000-0000-4000-8000-000000000000", "startedAt": "2026-01-01T12:00:00Z", "status": "draft", "updatedAt": "2026-01-01T12:00:00Z" }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido), remetente que lista um número removido da conta (UNKNOWN_INSTANCE) ou sem número existente (invalid campaign sender; também cluster sem membros).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled), limite do plano (plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ou remetente fora da lista da chave de cliente (SENDER_NOT_ALLOWED).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409Conflito com o estado atual.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/campaigns/<id>/start" \
-H "Authorization: Bearer $API_KEY"get/api/v1/marketing/campaigns/{id}/statsEstatísticas da campanhaChave de API
Contadores por status, por remetente e a espera atual observada pelo worker. Leitura pura.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) da campanha. |
Respostas
200Estatísticas.json{ "delivered": 0, "failed": 1, "pending": 1, "perInstance": [ { "connected": true, "delivered": 0, "failed": 1, "instanceId": "3f2a9c10-2222-4d44-8b55-000000000020", "pending": 1, "read": 0, "sent": 1, "skippedDuplicate": 0, "skippedOptOut": 0, "total": 3 } ], "read": 0, "sent": 1, "skippedDuplicate": 0, "skippedOptOut": 0, "total": 3, "waiting": { "instanceIds": [], "reason": "outside_window", "since": "2026-10-01T23:00:00Z" } }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/campaigns/<id>/stats" \
-H "Authorization: Bearer $API_KEY"get/api/v1/marketing/overviewResumo do marketing no mêsChave de API
Contadores de envio da coorte de campanhas iniciadas no mês (UTC).
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
monthopcional | query | string | Mês AAAA-MM (UTC); padrão: mês atual. |
Respostas
200Resumo.json{ "campaignsThisMonth": 0, "contacts": 0, "month": "string", "recentCampaigns": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "string", "stats": { "delivered": 0, "failed": 0, "pending": 0, "read": 0, "sent": 0, "skippedDuplicate": 0, "skippedOptOut": 0, "total": 0 }, "status": "draft" } ], "stats": { "delivered": 0, "failed": 0, "pending": 0, "read": 0, "sent": 0, "skippedDuplicate": 0, "skippedOptOut": 0, "total": 0 }, "totalCampaigns": 0 }400Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Marketing fora do plano (plan_feature_disabled, featuremarketing_enabled).json{ "code": "plan_feature_disabled", "error": "Feature not included in your plan: marketing_enabled.", "feature": "marketing_enabled" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/overview" \
-H "Authorization: Bearer $API_KEY"Fluxos
O construtor de fluxos de conversa: rascunho, validação, publicação e webhook de entrada.
get/api/v1/marketing/flowsLista os fluxosChave de API
Lista sem graph nem published, ordenada por id, paginada por cursor (nextCursor vazio = fim). Rotas de fluxo aceitam a chave global ou uma chave de cliente com o escopo flows e exigem marketing_enabled e flows_enabled no plano (403 plan_feature_disabled), inclusive as leituras. Resposta com Cache-Control: no-store.
Com chave de cliente restrita a alguns números, só as campanhas e os fluxos cujo remetente está todo na lista.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
statusopcional | query | "draft" | "active" | "paused" | |
cursoropcional | query | string (uuid) | nextCursor da página anterior (UUID). |
limitopcional | query | integer |
Respostas
200Página de fluxos.json{ "flows": [ { "createdAt": "2026-10-29T16:00:00Z", "graph": { "edges": [], "nodes": [] }, "hasUnpublishedChanges": true, "id": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "name": "Boas-vindas", "pausedByPlan": false, "pausedByPlanAt": null, "publishedAt": "2026-10-29T18:00:00Z", "publishedVersion": 2, "ratePerMinute": 30, "revision": 3, "runs": { "active": 4, "completed": 120, "failed": 2, "lastRunAt": "2026-10-29T19:00:00Z" }, "sender": { "instanceIds": [ "9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31" ] }, "status": "active", "trigger": { "config": { "keywords": [ "oi" ], "match": "exact" }, "type": "keyword" }, "updatedAt": "2026-10-29T18:30:00Z", "webhook": { "rotatedAt": "2026-10-29T17:00:00Z" } } ], "nextCursor": "string" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível.json{ "error": "marketing storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/flows" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/flowsCria um fluxo (rascunho)Chave de API
Cria um rascunho. Padrões: trigger = {"type":"manual","config":{}}, sender = {}, graph = {"nodes":[],"edges":[]}, ratePerMinute = 30. No salvamento só a forma e o tamanho do grafo são conferidos (tipos de bloco, ligações e configuração só no publish). revision não é aceito aqui. A resposta traz webhook.token e webhook.path — a única vez em que o token aparece. ratePerMinute acima do max_campaign_rate_per_minute do plano → 403 plan_limit.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}.
Um fluxo só aponta para o que a chave de cliente restrita enxerga: goto_flow para fluxo visível e campaign_reply com campanhas visíveis; senão 403 SENDER_NOT_ALLOWED.
Chave: chave da plataforma, chave de API (wck_...)
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
graphopcional | object | Grafo do editor, guardado como enviado (JSONB). Até 500 nós e 2.000 arestas; listas vazias valem. |
graph.edgesobrigatório | array<object> | |
graph.edges[].idobrigatório | string | |
graph.edges[].sourceobrigatório | string | |
graph.edges[].sourceHandleopcional | string | null | |
graph.edges[].targetobrigatório | string | |
graph.nodesobrigatório | array<object> | |
graph.nodes[].dataopcional | object | null | |
graph.nodes[].idobrigatório | string | |
graph.nodes[].positionopcional | object | |
graph.nodes[].position.xopcional | number | |
graph.nodes[].position.yopcional | number | |
graph.nodes[].typeobrigatório | "trigger" | "send_text" | "send_media" | "menu" | "wait_reply" | "delay" | "condition" | "split" | "tag" | "optout" | "set_field" | "http_request" | "goto_flow" | "end" | "crm_deal" | "crm_stage" | string | Um dos tipos de FlowNodeType; outro valor é aceito no salvamento e recusado no publish (unknown_node_type). |
nameobrigatório | string | 1–200 caracteres após aparar espaços. |
ratePerMinuteopcional | integer | Envios por minuto, por remetente. Teto: max_campaign_rate_per_minute do plano. |
senderopcional | object | Remetente: instanceIds (até 100) ou clusterId, nunca os dois. {} vale no rascunho; o publish
exige um remetente e confere que as instâncias (todas) ou o cluster existem. |
sender.clusterIdopcional | string (uuid) | |
sender.instanceIdsopcional | array<string (uuid)> | |
triggeropcional | object | Gatilho. config (omitido = {}) só é conferido no publish; chave desconhecida ou valor fora da
faixa → invalid_trigger_config. Por tipo:
- message: {"cooldownHours": 0–720} (padrão 24) — qualquer mensagem recebida pelos remetentes.
- keyword: {"keywords": [1–50 palavras de até 100 bytes], "match": "exact"|"contains"} (padrão exact).
- campaign_reply: {"campaignIds": [uuid…], "withinHours": 1–720, "cooldownHours": 0–720};
campaignIds vazio = qualquer campanha; withinHours padrão 72; cooldownHours padrão 24.
- webhook: {}; o corpo da chamada vira {{webhook.*}}.
- deal_stage_changed: {"pipelineId": uuid, "stageIds": [1–50 uuid], "fromStageIds": [0–50 uuid]};
começa o fluxo para o contato do negócio que entra numa das etapas (depois do commit; no máximo uma
execução por fluxo, negócio e etapa por minuto); {{negocio.*}}.
- manual: {}; início por POST /flows/{id}/start. |
trigger.configopcional | object | |
trigger.config.campaignIdsopcional | array<string (uuid)> | |
trigger.config.cooldownHoursopcional | integer | |
trigger.config.fromStageIdsopcional | array<string (uuid)> | |
trigger.config.keywordsopcional | array<string> | |
trigger.config.matchopcional | "exact" | "contains" | |
trigger.config.pipelineIdopcional | string (uuid) | |
trigger.config.stageIdsopcional | array<string (uuid)> | |
trigger.config.withinHoursopcional | integer | |
trigger.typeobrigatório | "message" | "keyword" | "campaign_reply" | "webhook" | "deal_stage_changed" | "manual" |
{
"graph": {
"edges": [
{
"id": "e1",
"source": "n0",
"sourceHandle": "out",
"target": "n1"
}
],
"nodes": [
{
"data": {},
"id": "n0",
"position": {
"x": 0,
"y": 0
},
"type": "trigger"
},
{
"data": {
"text": "Oi {{nome}}!"
},
"id": "n1",
"position": {
"x": 120,
"y": 80
},
"type": "send_text"
}
]
},
"name": "Boas-vindas",
"ratePerMinute": 30,
"sender": {
"instanceIds": [
"9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31"
]
},
"trigger": {
"config": {
"keywords": [
"oi",
"olá"
],
"match": "exact"
},
"type": "keyword"
}
}Respostas
201Rascunho criado, com o token do webhook de entrada.json{ "createdAt": "2026-10-29T16:00:00Z", "graph": { "edges": [], "nodes": [] }, "hasUnpublishedChanges": true, "id": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "name": "Boas-vindas", "pausedByPlan": false, "pausedByPlanAt": null, "publishedAt": "2026-10-29T18:00:00Z", "publishedVersion": 2, "ratePerMinute": 30, "revision": 3, "runs": { "active": 4, "completed": 120, "failed": 2, "lastRunAt": "2026-10-29T19:00:00Z" }, "sender": { "instanceIds": [ "9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31" ] }, "status": "active", "trigger": { "config": { "keywords": [ "oi" ], "match": "exact" }, "type": "keyword" }, "updatedAt": "2026-10-29T18:30:00Z", "webhook": { "rotatedAt": "2026-10-29T17:00:00Z" } }400Pedido inválido ou remetente que lista um número removido da conta (UNKNOWN_INSTANCE; um número que nunca existiu é gravado e só barra a publicação).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED), remetente ou alvo fora da lista da chave de cliente (SENDER_NOT_ALLOWED) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/flows" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"graph":{"edges":[{"id":"e1","source":"n0","sourceHandle":"out","target":"n1"}],"nodes":[{"data":{},"id":"n0","position":{"x":0,"y":0},"type":"trigger"},{"data":{"text":"Oi {{nome}}!"},"id":"n1","position":{"x":120,"y":80},"type":"send_text"}]},"name":"Boas-vindas","ratePerMinute":30,"sender":{"instanceIds":["9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31"]},"trigger":{"config":{"keywords":["oi","olá"],"match":"exact"},"type":"keyword"}}'get/api/v1/marketing/flows/{id}Obtém um fluxoChave de API
Fluxo com o rascunho (graph) e a versão publicada em vigor (published, ausente sem publicação).
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Respostas
200Fluxo.json{ "createdAt": "2026-10-29T16:00:00Z", "graph": { "edges": [], "nodes": [] }, "hasUnpublishedChanges": true, "id": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "name": "Boas-vindas", "pausedByPlan": false, "pausedByPlanAt": null, "publishedAt": "2026-10-29T18:00:00Z", "publishedVersion": 2, "ratePerMinute": 30, "revision": 3, "runs": { "active": 4, "completed": 120, "failed": 2, "lastRunAt": "2026-10-29T19:00:00Z" }, "sender": { "instanceIds": [ "9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31" ] }, "status": "active", "trigger": { "config": { "keywords": [ "oi" ], "match": "exact" }, "type": "keyword" }, "updatedAt": "2026-10-29T18:30:00Z", "webhook": { "rotatedAt": "2026-10-29T17:00:00Z" } }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/flows/<id>" \
-H "Authorization: Bearer $API_KEY"patch/api/v1/marketing/flows/{id}Altera o rascunhoChave de API
Troca, inteiro, cada campo enviado do rascunho; nunca toca a versão publicada. Pelo menos um de name, trigger, sender, graph, ratePerMinute. Campo desconhecido ou forma inválida → 400. revision (opcional) dá trava otimista: diferente da atual → 409 revision_conflict com a revisão atual, e nada muda. Cada PATCH sobe revision.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Um fluxo só aponta para o que a chave de cliente restrita enxerga: goto_flow para fluxo visível e campaign_reply com campanhas visíveis; senão 403 SENDER_NOT_ALLOWED.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
graphopcional | object | Grafo do editor, guardado como enviado (JSONB). Até 500 nós e 2.000 arestas; listas vazias valem. |
graph.edgesobrigatório | array<object> | |
graph.edges[].idobrigatório | string | |
graph.edges[].sourceobrigatório | string | |
graph.edges[].sourceHandleopcional | string | null | |
graph.edges[].targetobrigatório | string | |
graph.nodesobrigatório | array<object> | |
graph.nodes[].dataopcional | object | null | |
graph.nodes[].idobrigatório | string | |
graph.nodes[].positionopcional | object | |
graph.nodes[].position.xopcional | number | |
graph.nodes[].position.yopcional | number | |
graph.nodes[].typeobrigatório | "trigger" | "send_text" | "send_media" | "menu" | "wait_reply" | "delay" | "condition" | "split" | "tag" | "optout" | "set_field" | "http_request" | "goto_flow" | "end" | "crm_deal" | "crm_stage" | string | Um dos tipos de FlowNodeType; outro valor é aceito no salvamento e recusado no publish (unknown_node_type). |
nameopcional | string | |
ratePerMinuteopcional | integer | |
revisionopcional | integer | Revisão esperada (trava otimista). |
senderopcional | object | Remetente: instanceIds (até 100) ou clusterId, nunca os dois. {} vale no rascunho; o publish
exige um remetente e confere que as instâncias (todas) ou o cluster existem. |
sender.clusterIdopcional | string (uuid) | |
sender.instanceIdsopcional | array<string (uuid)> | |
triggeropcional | object | Gatilho. config (omitido = {}) só é conferido no publish; chave desconhecida ou valor fora da
faixa → invalid_trigger_config. Por tipo:
- message: {"cooldownHours": 0–720} (padrão 24) — qualquer mensagem recebida pelos remetentes.
- keyword: {"keywords": [1–50 palavras de até 100 bytes], "match": "exact"|"contains"} (padrão exact).
- campaign_reply: {"campaignIds": [uuid…], "withinHours": 1–720, "cooldownHours": 0–720};
campaignIds vazio = qualquer campanha; withinHours padrão 72; cooldownHours padrão 24.
- webhook: {}; o corpo da chamada vira {{webhook.*}}.
- deal_stage_changed: {"pipelineId": uuid, "stageIds": [1–50 uuid], "fromStageIds": [0–50 uuid]};
começa o fluxo para o contato do negócio que entra numa das etapas (depois do commit; no máximo uma
execução por fluxo, negócio e etapa por minuto); {{negocio.*}}.
- manual: {}; início por POST /flows/{id}/start. |
trigger.configopcional | object | |
trigger.config.campaignIdsopcional | array<string (uuid)> | |
trigger.config.cooldownHoursopcional | integer | |
trigger.config.fromStageIdsopcional | array<string (uuid)> | |
trigger.config.keywordsopcional | array<string> | |
trigger.config.matchopcional | "exact" | "contains" | |
trigger.config.pipelineIdopcional | string (uuid) | |
trigger.config.stageIdsopcional | array<string (uuid)> | |
trigger.config.withinHoursopcional | integer | |
trigger.typeobrigatório | "message" | "keyword" | "campaign_reply" | "webhook" | "deal_stage_changed" | "manual" |
{
"graph": {
"edges": [
{
"id": "string",
"source": "string",
"sourceHandle": "string",
"target": "string"
}
],
"nodes": [
{
"data": {
"text": "Oi {{nome}}",
"ui": {
"color": "teal"
}
},
"id": "n1",
"position": {
"x": 120,
"y": 80
},
"type": "send_text"
}
]
},
"name": "string",
"ratePerMinute": 0,
"revision": 0,
"sender": {
"instanceIds": [
"9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31"
]
},
"trigger": {
"config": {
"keywords": [
"oi"
],
"match": "exact"
},
"type": "keyword"
}
}Respostas
200Fluxo atualizado.json{ "createdAt": "2026-10-29T16:00:00Z", "graph": { "edges": [], "nodes": [] }, "hasUnpublishedChanges": true, "id": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "name": "Boas-vindas", "pausedByPlan": false, "pausedByPlanAt": null, "publishedAt": "2026-10-29T18:00:00Z", "publishedVersion": 2, "ratePerMinute": 30, "revision": 3, "runs": { "active": 4, "completed": 120, "failed": 2, "lastRunAt": "2026-10-29T19:00:00Z" }, "sender": { "instanceIds": [ "9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31" ] }, "status": "active", "trigger": { "config": { "keywords": [ "oi" ], "match": "exact" }, "type": "keyword" }, "updatedAt": "2026-10-29T18:30:00Z", "webhook": { "rotatedAt": "2026-10-29T17:00:00Z" } }400Pedido inválido ou remetente que lista um número removido da conta (UNKNOWN_INSTANCE; um número que nunca existiu é gravado e só barra a publicação).json{ "error": "invalid marketing request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit), remetente ou alvo fora da lista da chave de cliente (SENDER_NOT_ALLOWED) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }409A revisão enviada não é a atual (revision_conflict).json{ "code": "revision_conflict", "error": "flow revision changed", "revision": 4 }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X PATCH "$API_URL/api/v1/marketing/flows/<id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"graph":{"edges":[{"id":"string","source":"string","sourceHandle":"string","target":"string"}],"nodes":[{"data":{"text":"Oi {{nome}}","ui":{"color":"teal"}},"id":"n1","position":{"x":120,"y":80},"type":"send_text"}]},"name":"string","ratePerMinute":0,"revision":0,"sender":{"instanceIds":["9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31"]},"trigger":{"config":{"keywords":["oi"],"match":"exact"},"type":"keyword"}}'delete/api/v1/marketing/flows/{id}Apaga um fluxoChave de API
Apaga o fluxo, as versões e o histórico de execuções. Com execução running/waiting → 409 flow_has_active_runs, salvo force=true, que cancela as execuções e apaga.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
forceopcional | query | "true" | "false" |
Respostas
204Apagado.400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }409O fluxo tem execuções ativas (flow_has_active_runs).json{ "activeRuns": 3, "code": "flow_has_active_runs", "error": "flow has active runs" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X DELETE "$API_URL/api/v1/marketing/flows/<id>" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/flows/{id}/duplicateDuplica um fluxoChave de API
Novo rascunho com o rascunho de origem (trigger, sender, graph, ratePerMinute), token de webhook novo (mostrado na resposta), sem versões nem execuções. Corpo opcional; nome padrão "<nome> (cópia)".
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}. Conta o remetente deste fluxo (rascunho e versão publicada) e o de todo fluxo que ele alcança por goto_flow, em qualquer profundidade.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
nameopcional | string | Padrão "<nome> (cópia)". |
{
"name": "string"
}Respostas
201Rascunho criado, com o token do webhook de entrada.json{ "createdAt": "2026-10-29T16:00:00Z", "graph": { "edges": [], "nodes": [] }, "hasUnpublishedChanges": true, "id": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "name": "Boas-vindas", "pausedByPlan": false, "pausedByPlanAt": null, "publishedAt": "2026-10-29T18:00:00Z", "publishedVersion": 2, "ratePerMinute": 30, "revision": 3, "runs": { "active": 4, "completed": 120, "failed": 2, "lastRunAt": "2026-10-29T19:00:00Z" }, "sender": { "instanceIds": [ "9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31" ] }, "status": "active", "trigger": { "config": { "keywords": [ "oi" ], "match": "exact" }, "type": "keyword" }, "updatedAt": "2026-10-29T18:30:00Z", "webhook": { "rotatedAt": "2026-10-29T17:00:00Z" } }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED), remetente ou alvo fora da lista da chave de cliente (SENDER_NOT_ALLOWED) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/flows/<id>/duplicate" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"string"}'post/api/v1/marketing/flows/{id}/pausePausa um fluxoChave de API
active → paused (já pausado pelo cliente: 200 sem mudança). Não interrompe execuções em andamento; impede novas (início manual, goto_flow, gatilhos). Rascunho → 409 flow_not_published. Sem corpo. Um fluxo pausado pelo plano passa a ser pausa do cliente: pausedByPlan volta a false e ele não volta mais sozinho quando o plano sobe.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Respostas
200Fluxo.json{ "createdAt": "2026-10-29T16:00:00Z", "graph": { "edges": [], "nodes": [] }, "hasUnpublishedChanges": true, "id": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "name": "Boas-vindas", "pausedByPlan": false, "pausedByPlanAt": null, "publishedAt": "2026-10-29T18:00:00Z", "publishedVersion": 2, "ratePerMinute": 30, "revision": 3, "runs": { "active": 4, "completed": 120, "failed": 2, "lastRunAt": "2026-10-29T19:00:00Z" }, "sender": { "instanceIds": [ "9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31" ] }, "status": "active", "trigger": { "config": { "keywords": [ "oi" ], "match": "exact" }, "type": "keyword" }, "updatedAt": "2026-10-29T18:30:00Z", "webhook": { "rotatedAt": "2026-10-29T17:00:00Z" } }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }409O fluxo nunca foi publicado (flow_not_published).json{ "code": "flow_not_published", "error": "flow is not published" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/flows/<id>/pause" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/flows/{id}/publishValida e publica o rascunhoChave de API
Valida o rascunho; válido, cria a versão publishedVersion+1 (a primeira é 1) com cópia congelada de trigger, sender, graph e ratePerMinute, e deixa o fluxo active. Um fluxo com send_template cujos remetentes misturam números oficiais e QR → 400 sender_mixed. Inválido → 422 flow_invalid com a lista de erros, e nada muda. Ativar um rascunho ou pausado conta em max_flows (403 plan_limit); republicar um ativo não. ratePerMinute acima do plano → 403 plan_limit (max_campaign_rate_per_minute). Sem corpo.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}. Conta o remetente deste fluxo (rascunho e versão publicada) e o de todo fluxo que ele alcança por goto_flow, em qualquer profundidade.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Um fluxo só aponta para o que a chave de cliente restrita enxerga: goto_flow para fluxo visível e campaign_reply com campanhas visíveis; senão 403 SENDER_NOT_ALLOWED.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Respostas
200Fluxo publicado.json{ "createdAt": "2026-10-29T16:00:00Z", "graph": { "edges": [], "nodes": [] }, "hasUnpublishedChanges": true, "id": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "name": "Boas-vindas", "pausedByPlan": false, "pausedByPlanAt": null, "publishedAt": "2026-10-29T18:00:00Z", "publishedVersion": 2, "ratePerMinute": 30, "revision": 3, "runs": { "active": 4, "completed": 120, "failed": 2, "lastRunAt": "2026-10-29T19:00:00Z" }, "sender": { "instanceIds": [ "9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31" ] }, "status": "active", "trigger": { "config": { "keywords": [ "oi" ], "match": "exact" }, "type": "keyword" }, "updatedAt": "2026-10-29T18:30:00Z", "webhook": { "rotatedAt": "2026-10-29T17:00:00Z" } }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED), remetente ou alvo fora da lista da chave de cliente (SENDER_NOT_ALLOWED) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }422O rascunho não passou na validação (flow_invalid).json{ "code": "flow_invalid", "error": "flow validation failed", "errors": [ { "code": "sender_required", "field": "sender", "nodeId": null }, { "code": "missing_field", "field": "data.text", "nodeId": "n3" }, { "code": "invalid_edge", "edgeId": "e7", "nodeId": "n2" } ] }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/flows/<id>/publish" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/flows/{id}/resumeRetoma um fluxo pausadoChave de API
paused → active, contando em max_flows (403 plan_limit); já ativo: 200 sem mudança. Rascunho → 409 flow_not_published. Sem corpo.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}. Conta o remetente deste fluxo (rascunho e versão publicada) e o de todo fluxo que ele alcança por goto_flow, em qualquer profundidade.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Respostas
200Fluxo.json{ "createdAt": "2026-10-29T16:00:00Z", "graph": { "edges": [], "nodes": [] }, "hasUnpublishedChanges": true, "id": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "name": "Boas-vindas", "pausedByPlan": false, "pausedByPlanAt": null, "publishedAt": "2026-10-29T18:00:00Z", "publishedVersion": 2, "ratePerMinute": 30, "revision": 3, "runs": { "active": 4, "completed": 120, "failed": 2, "lastRunAt": "2026-10-29T19:00:00Z" }, "sender": { "instanceIds": [ "9a0f2c1e-4b7d-4e3a-9c11-2f6b8d0e5a31" ] }, "status": "active", "trigger": { "config": { "keywords": [ "oi" ], "match": "exact" }, "type": "keyword" }, "updatedAt": "2026-10-29T18:30:00Z", "webhook": { "rotatedAt": "2026-10-29T17:00:00Z" } }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED), remetente ou alvo fora da lista da chave de cliente (SENDER_NOT_ALLOWED) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O fluxo nunca foi publicado (flow_not_published).json{ "code": "flow_not_published", "error": "flow is not published" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/flows/<id>/resume" \
-H "Authorization: Bearer $API_KEY"get/api/v1/marketing/flows/{id}/webhook/logsChamadas recentes do webhook de entradaChave de API
As 100 chamadas mais recentes a um token válido do fluxo, da mais recente para a mais antiga, inclusive as recusadas por plano ou cobrança (exceto as recusadas pelo limite do token). Sem o corpo e sem o telefone.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Respostas
200Registro.json{ "logs": [ { "at": "2026-10-29T21:00:00Z", "bytes": 96, "error": null, "runId": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b", "status": 202 } ] }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/flows/<id>/webhook/logs" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/flows/{id}/webhook/rotateGera um novo token do webhook de entradaChave de API
O token anterior deixa de valer na hora. O novo só aparece nesta resposta (a API guarda o SHA-256). Sem corpo.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}. Conta o remetente deste fluxo (rascunho e versão publicada) e o de todo fluxo que ele alcança por goto_flow, em qualquer profundidade. O token novo inicia o fluxo de fora, então a rotação passa pela mesma conferência.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Respostas
200Token novo.json{ "path": "/api/v1/hooks/flows/fwh_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "rotatedAt": "2026-10-29T17:00:00Z", "token": "fwh_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit), remetente ou alvo fora da lista da chave de cliente (SENDER_NOT_ALLOWED) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/flows/<id>/webhook/rotate" \
-H "Authorization: Bearer $API_KEY"Execuções de fluxo
Início manual, histórico passo a passo, cancelamento e estatísticas por bloco.
get/api/v1/marketing/flows/runs/{runID}Obtém uma execução com os passosChave de API
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
runIDobrigatório | path | string (uuid) | ID (UUID) da execução. Inválido → 400. |
Respostas
200Execução comstepsem ordem.json{ "contactId": "3b8e6f0a-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "currentNodeId": "n2", "error": null, "finishedAt": null, "flowId": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "id": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b", "origin": "keyword", "phone": "5581999990001", "startedAt": "2026-10-29T19:00:00Z", "status": "waiting", "version": 2, "waitingFor": "reply", "wakeAt": "2026-10-30T19:00:00Z" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/flows/runs/<runID>" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/flows/runs/{runID}/cancelCancela uma execuçãoChave de API
A execução vai a cancelled (erro cancelled); um bloco em andamento termina antes. Já terminada → 409 run_not_active com o estado. Sem corpo.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
runIDobrigatório | path | string (uuid) | ID (UUID) da execução. Inválido → 400. |
Respostas
200Execução cancelada, com os passos.json{ "contactId": "3b8e6f0a-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "currentNodeId": "n2", "error": null, "finishedAt": null, "flowId": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "id": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b", "origin": "keyword", "phone": "5581999990001", "startedAt": "2026-10-29T19:00:00Z", "status": "waiting", "version": 2, "waitingFor": "reply", "wakeAt": "2026-10-30T19:00:00Z" }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }409A execução já terminou (run_not_active).json{ "code": "run_not_active", "error": "run is not active", "status": "completed" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/flows/runs/<runID>/cancel" \
-H "Authorization: Bearer $API_KEY"get/api/v1/marketing/flows/{id}/runsLista as execuções do fluxoChave de API
Todas as versões, ordenadas por id, paginadas por cursor. Sem steps (veja GET /flows/runs/{runID}).
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
statusopcional | query | "running" | "waiting" | "completed" | "failed" | "cancelled" | |
cursoropcional | query | string (uuid) | nextCursor da página anterior (UUID). |
limitopcional | query | integer |
Respostas
200Página de execuções.json{ "nextCursor": "string", "runs": [ { "contactId": "3b8e6f0a-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "currentNodeId": "n2", "error": null, "finishedAt": null, "flowId": "6d1c0b2a-3e4f-4a5b-9c6d-7e8f9a0b1c2d", "id": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b", "origin": "keyword", "phone": "5581999990001", "startedAt": "2026-10-29T19:00:00Z", "status": "waiting", "version": 2, "waitingFor": "reply", "wakeAt": "2026-10-30T19:00:00Z" } ] }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/flows/<id>/runs" \
-H "Authorization: Bearer $API_KEY"post/api/v1/marketing/flows/{id}/startInicia o fluxo para contatos (início manual)Chave de API
Vale para qualquer tipo de gatilho. contactIds (1–1.000) ou tag (contatos com a tag, até 10.000; mais → 422 audience_too_large e nada começa). Execuções criadas em lotes de 500; se o fluxo for pausado ou apagado entre lotes, o resto volta em skipped com motivo flow_not_active. Fluxo não ativo (rascunho ou pausado) → 409 flow_not_active.
Com chave de cliente restrita a alguns números, remetente (número ou cluster) fora da lista: 403 {"error":"sender not allowed for this key","code":"SENDER_NOT_ALLOWED"}. Conta o remetente deste fluxo (rascunho e versão publicada) e o de todo fluxo que ele alcança por goto_flow, em qualquer profundidade.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
contactIdsopcional | array<string (uuid)> | |
tagopcional | string | Inicia para os contatos com a tag (até 10.000). |
{
"contactIds": [
"3b8e6f0a-1c2d-4e5f-8a9b-0c1d2e3f4a5b"
]
}Respostas
200Resultado do início.json{ "skipped": [ { "contactId": "3b8e6f0a-1c2d-4e5f-8a9b-0c1d2e3f4a5b", "reason": "already_running" } ], "started": 2 }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit), conta suspensa ou cancelada (ACCOUNT_SUSPENDED), remetente ou alvo fora da lista da chave de cliente (SENDER_NOT_ALLOWED) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "ACCOUNT_SUSPENDED", "error": "Tenant suspended. Contact support." }404Recurso inexistente.json{ "error": "invalid request" }409O fluxo não está ativo (flow_not_active).json{ "code": "flow_not_active", "error": "flow is not active" }422A tag tem mais de 10.000 contatos (audience_too_large).json{ "code": "string", "error": "string", "limit": 0, "total": 0 }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/marketing/flows/<id>/start" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"contactIds":["3b8e6f0a-1c2d-4e5f-8a9b-0c1d2e3f4a5b"]}'get/api/v1/marketing/flows/{id}/statsEstatísticas do fluxoChave de API
Contagem das execuções por estado e, por bloco, passos que entraram (entered) e saíram (exited), somando todas as versões. Quem está esperando num bloco entrou e não saiu.
Com chave de cliente restrita a alguns números, uma campanha ou fluxo cujo remetente não está todo na lista responde 404.
Chave: chave da plataforma, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) | ID (UUID) do fluxo. Inválido → 400. |
Respostas
200Estatísticas.json{ "active": 4, "cancelled": 1, "completed": 120, "failed": 2, "perNode": { "n1": { "entered": 127, "exited": 127 }, "n2": { "entered": 127, "exited": 123 } } }400Pedido inválido.json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Função fora do plano (plan_feature_disabled:marketing_enabledouflows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopoflows(CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Recurso inexistente.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }500Erro interno (sem detalhes do banco).json{ "error": "invalid request" }503Banco de marketing indisponível ou, com chave de cliente restrita a alguns números, falha ao conferir a chave (client key check unavailable).json{ "error": "client key check unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/marketing/flows/<id>/stats" \
-H "Authorization: Bearer $API_KEY"Webhook de entrada de fluxo
Uma chamada pública (com o token no caminho) que inicia um fluxo para um telefone.
post/api/v1/hooks/flows/{token}Inicia o fluxo por webhook de entradaSem chave
Fora da chave global: o token do caminho é a credencial (comparado por SHA-256 em tempo constante; o caminho não vai ao log de acesso). Resposta sempre com Cache-Control: no-store.
Ordem: o token vem antes de tudo. Fora do formato → 404 sem consultar o banco; bem formado e inexistente → 404. Só com token válido a API responde sobre a conta: limite do token, plano, cobrança, estado do fluxo (não ativo → 409 flow_not_active, antes de ler o corpo) e então o corpo. Assim um token inválido recebe 404 qualquer que seja o estado da conta.
Corpo: objeto JSON até 64 KiB. phone (texto ou número) obrigatório, normalizado como na importação; defaultCountry opcional (1–3 dígitos sem 0 inicial, padrão 55, não vira variável); name opcional (nome do contato quando ele é criado agora). Os campos viram {{webhook.<campo>}}: escalares e um nível de objeto ({{webhook.cliente.nome}}); listas e objetos mais fundos ficam vazios. O contato é criado se não existir, contando em max_contacts; opt-out nunca cria nem inicia.
Limites: por token, rajada de 30 e 2/s depois (por processo) → 429 rate_limited. Tokens bem formados inexistentes gastam um orçamento comum de 20/s por processo; gasto, um token não visto válido nas últimas 24 h recebe 429 rate_limited com Retry-After: 1 sem consultar o banco (igual para token real e falso). Fluxo acima de 60 inícios automáticos por minuto → 429 flow_rate_limited.
Cada chamada a um token válido (exceto as recusadas pelo limite do token) vai para o registro consultado em GET /api/v1/marketing/flows/{id}/webhook/logs.
Chave: nenhuma (o token do caminho é a credencial)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
tokenobrigatório | path | string | Token do webhook de entrada (fwh_ + 43 caracteres base64url), mostrado só ao criar, duplicar ou rotacionar o fluxo. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
defaultCountryopcional | string | DDI para números sem DDI; não vira variável. |
nameopcional | string | Nome do contato quando ele é criado agora (um contato existente não é alterado). |
phoneobrigatório | string | number | Telefone do contato, normalizado como na importação. |
{
"cliente": {
"nome": "Ana",
"plano": "ouro"
},
"name": "Ana",
"pedido": 123,
"phone": "+55 81 99999-0001"
}Respostas
202Aceito. ComrunIda execução foi criada; comrunId: nullnada começou ereasondiz por quê (optout,already_running).json{ "reason": "already_running", "runId": null }400Corpo inválido:invalid_body(não é objeto JSON),invalid_phone(comreason: os motivos da importação oumissing) ouinvalid_default_country.json{ "code": "invalid_body", "error": "body must be a JSON object" }403Token válido, mas: contato novo sem vaga (plan_limit,max_contacts), plano semmarketing_enabled/flows_enabled(plan_feature_disabled) ou conta suspensa/cancelada (ACCOUNT_SUSPENDED).json{ "code": "plan_limit", "error": "Plan limit reached: max_contacts.", "limit": "max_contacts" }404Token fora do formato, inexistente, errado ou rotacionado. Não diz se o fluxo existe nem o estado da conta.json{ "error": "not found" }409Fluxo pausado ou rascunho (flow_not_active).json{ "code": "flow_not_active", "error": "flow is not active" }413Corpo acima de 64 KiB (body_too_large).json{ "code": "body_too_large", "error": "body too large", "limit": 65536 }429rate_limited(limite do token, ou orçamento de tokens inexistentes gasto — este comRetry-After: 1) ouflow_rate_limited(fluxo acima de 60 inícios/min).json{ "code": "flow_rate_limited", "error": "too many starts for this flow" }500Erro interno.json{ "error": "flow webhook failed" }
Exemplo
curl -X POST "$API_URL/api/v1/hooks/flows/<token>" \
-H "Content-Type: application/json" \
-d '{"cliente":{"nome":"Ana","plano":"ouro"},"name":"Ana","pedido":123,"phone":"+55 81 99999-0001"}'IA
As chaves de IA (sempre cifradas), os agentes de IA, o atendente de cada número e o uso das chamadas de IA. Só a chave da plataforma.
get/api/v1/ai/agentsLista os agentes de IASó a chave da plataforma
Os agentes salvos, do mais antigo para o mais novo, com os valores dos cabeçalhos dos endpoints mascarados (••••) e, em cada um, numbers: os números em que está ligado e se o atendente está ligado ali, numa consulta só. Sempre Cache-Control: no-store.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Respostas
200Os agentes.json{ "agents": [ { "created_at": "2026-01-01T12:00:00Z", "credential_id": null, "flow_ids": [ null ], "handoff_assignee": null, "handoff_keywords": [ null ], "handoff_message": "string", "http_endpoints": [ null ], "id": "00000000-0000-4000-8000-000000000000", "max_consecutive_replies": 0, "max_tokens": 0, "max_tool_iterations": 0, "memory_messages": 0, "model": "string", "name": "string", "reply_delay_seconds": 0, "system_prompt": "string", "temperature": null, "timeout_seconds": 0, "tools": { "chamar_http": "act", "consultar_contato": "act", "consultar_negocios": "act", "criar_negocio": "act", "ganhar_negocio": "act", "iniciar_fluxo": "act", "marcar_etiqueta": "act", "mover_negocio": "act", "perder_negocio": "act", "salvar_campo": "act", "transferir_para_humano": "act" }, "updated_at": "2026-01-01T12:00:00Z", "numbers": [ null ] } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled; na criação e no teste, tambémai_agents_enabled), o limite de agentes do plano na criação (plan_limit,max_ai_agents) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível (sem banco).json{ "error": "AI storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/ai/agents" \
-H "Authorization: Bearer $API_KEY"post/api/v1/ai/agentsCria um agente de IASó a chave da plataforma
Só name é obrigatório; campo desconhecido, JSON inválido ou corpo acima de 128 KiB dão 400 invalid_body. O que não vier toma o padrão: system_prompt e model vazios (o modelo vazio usa o default_model da chave), credential_id, temperature e handoff_assignee null, max_tokens 0 (o padrão do provedor), memory_messages 10, tools {"transferir_para_humano":"act"}, sem endpoints nem fluxos, handoff_message vazia, handoff_keywords ["atendente","humano"], max_tool_iterations 3, timeout_seconds 20 e max_consecutive_replies 10. Sem credential_id o agente fica salvo, mas não responde.
Plano: sem ai_agents_enabled, 403 plan_feature_disabled; com max_ai_agents atingido, 403 plan_limit (limit: max_ai_agents), contado de forma atômica (duas criações simultâneas na última vaga não passam as duas).
Os valores dos cabeçalhos de http_endpoints são gravados cifrados com a chave de cifra do servidor (sem ela, 503 secrets_key_missing e nada é gravado) e voltam mascarados. Na criação não há segredo gravado: um valor mascarado é 400 MASKED_SECRET_NEW_DESTINATION. Uma URL de endpoint numa rede interna ou numa porta não permitida é 400 url_internal; um esquema que não é http(s) ou um usuário na URL é 400 invalid_http_endpoints.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
credential_idopcional | string (uuid) | null | Uma chave de IA existente, ou null (invalid_credential). |
flow_idsopcional | array<string (uuid)> | Fluxos existentes; repetidos contam uma vez (invalid_flows). |
handoff_assigneeopcional | string | null | Id opaco de até 200 caracteres; null ou "" = nenhum (invalid_handoff_assignee). |
handoff_keywordsopcional | array<string> | Até 20, de até 50 caracteres, nenhuma vazia; padrão ["atendente","humano"]; [] desliga (invalid_handoff_keywords). |
handoff_messageopcional | string | Até 1000 caracteres (invalid_handoff_message). |
http_endpointsopcional | array<object> | Substitui a lista inteira (invalid_http_endpoints, url_internal, MASKED_SECRET_NEW_DESTINATION). |
http_endpoints[].descriptionopcional | string | O que o endpoint faz, para o modelo decidir quando chamá-lo. |
http_endpoints[].headersopcional | object | Até 10 cabeçalhos (nome sem espaço nem :, até 100 caracteres; valor em uma linha, até 4096). Os valores são segredos: gravados cifrados e devolvidos sempre como ••••. Mandar de volta o valor mascarado mantém o gravado só no mesmo endpoint (mesmo name, method e url); senão, 400 MASKED_SECRET_NEW_DESTINATION. |
http_endpoints[].methodobrigatório | "GET" | "POST" | Sem diferenciar maiúsculas na entrada; volta em maiúsculas. |
http_endpoints[].nameobrigatório | string | Nome com que o modelo chama o endpoint (chamar_http); único no agente. |
http_endpoints[].urlobrigatório | string | URL http(s) absoluta e pública (rede interna ou porta não permitida = 400 url_internal; esquema não http(s) ou usuário na URL = 400 invalid_http_endpoints). A chamada também confere o destino depois do DNS e em cada redirecionamento. Nas leituras, os valores da query voltam mascarados (?token=•••); reenviada assim, a URL mantém a gravada só no mesmo endpoint (mesmo nome, método, esquema, host, caminho e chaves da query); se algo além de um valor mascarado mudou, 400 MASKED_SECRET_NEW_DESTINATION pedindo a URL completa. |
max_consecutive_repliesopcional | integer | Padrão 10 (invalid_max_consecutive_replies). |
max_tokensopcional | integer | 0 = o padrão do provedor (invalid_max_tokens). |
max_tool_iterationsopcional | integer | Padrão 3 (invalid_max_tool_iterations). |
memory_messagesopcional | integer | Padrão 10 (invalid_memory). |
modelopcional | string | Vazio = o default_model da chave (invalid_model). |
nameopcional | string | Obrigatório na criação (invalid_name). |
reply_delay_secondsopcional | integer | Padrão 8; 0 responde cada mensagem na hora (invalid_reply_delay). |
system_promptopcional | string | Até 8 KiB (invalid_system_prompt). |
temperatureopcional | number | null | De 0 a 2, ou null (invalid_temperature); 0 vale como null (o padrão do provedor). |
timeout_secondsopcional | integer | Padrão 20 (invalid_timeout). |
toolsopcional | any | Substitui o mapa inteiro. Padrão {"transferir_para_humano":"act"}. Nome desconhecido ou autonomia fora de act, suggest, off: invalid_tools. |
tools.chamar_httpopcional | "act" | "suggest" | "off" | |
tools.consultar_contatoopcional | "act" | "suggest" | "off" | |
tools.consultar_negociosopcional | "act" | "suggest" | "off" | |
tools.criar_negocioopcional | "act" | "suggest" | "off" | |
tools.ganhar_negocioopcional | "act" | "suggest" | "off" | |
tools.iniciar_fluxoopcional | "act" | "suggest" | "off" | |
tools.marcar_etiquetaopcional | "act" | "suggest" | "off" | |
tools.mover_negocioopcional | "act" | "suggest" | "off" | |
tools.perder_negocioopcional | "act" | "suggest" | "off" | |
tools.salvar_campoopcional | "act" | "suggest" | "off" | |
tools.transferir_para_humanoopcional | "act" | "suggest" | "off" |
{
"credential_id": "7d2f7b6e-9c1a-4c55-9f1e-2a6a3b1c0d11",
"http_endpoints": [
{
"description": "Consulta o status de um pedido pelo número.",
"headers": {
"Authorization": "Bearer segredo-da-loja"
},
"method": "GET",
"name": "consultar_pedido",
"url": "https://loja.example.com/api/pedidos"
}
],
"name": "Atendente da loja",
"system_prompt": "Você atende os clientes da loja. Seja breve e cordial.",
"tools": {
"chamar_http": "act",
"marcar_etiqueta": "suggest",
"transferir_para_humano": "act"
}
}Respostas
201Criado (os cabeçalhos mascarados).json{ "created_at": "2026-01-01T12:00:00Z", "credential_id": "00000000-0000-4000-8000-000000000000", "flow_ids": [ "00000000-0000-4000-8000-000000000000" ], "handoff_assignee": "string", "handoff_keywords": [ "string" ], "handoff_message": "string", "http_endpoints": [ { "description": "string", "headers": {}, "method": "GET", "name": "string", "url": "string" } ], "id": "00000000-0000-4000-8000-000000000000", "max_consecutive_replies": 0, "max_tokens": 0, "max_tool_iterations": 0, "memory_messages": 0, "model": "string", "name": "string", "reply_delay_seconds": 0, "system_prompt": "string", "temperature": 0, "timeout_seconds": 0, "tools": { "chamar_http": "act", "consultar_contato": "act", "consultar_negocios": "act", "criar_negocio": "act", "ganhar_negocio": "act", "iniciar_fluxo": "act", "marcar_etiqueta": "act", "mover_negocio": "act", "perder_negocio": "act", "salvar_campo": "act", "transferir_para_humano": "act" }, "updated_at": "2026-01-01T12:00:00Z" }400Corpo inválido (invalid_body) ou campo fora da regra, com o código do campo:invalid_name,invalid_system_prompt,invalid_credential(não é UUID ou a chave de IA não existe),invalid_model,invalid_temperature,invalid_max_tokens,invalid_memory,invalid_tools,invalid_http_endpoints,invalid_flows(não é UUID ou o fluxo não existe),invalid_handoff_message,invalid_handoff_keywords,invalid_handoff_assignee,invalid_max_tool_iterations,invalid_timeout,invalid_max_consecutive_replies. URL de endpoint que não é pública:url_internal. Valor de cabeçalho mascarado fora do mesmo endpoint gravado:MASKED_SECRET_NEW_DESTINATION. Nada é gravado.json{ "code": "MASKED_SECRET_NEW_DESTINATION", "error": "Send the key again when the URL, provider or format changes." }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled; na criação e no teste, tambémai_agents_enabled), o limite de agentes do plano na criação (plan_limit,max_ai_agents) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível, ou sem a chave de cifra do servidor para cifrar um cabeçalho novo (secrets_key_missing; nada é gravado).json{ "error": "AI storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/ai/agents" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"credential_id":"7d2f7b6e-9c1a-4c55-9f1e-2a6a3b1c0d11","http_endpoints":[{"description":"Consulta o status de um pedido pelo número.","headers":{"Authorization":"Bearer segredo-da-loja"},"method":"GET","name":"consultar_pedido","url":"https://loja.example.com/api/pedidos"}],"name":"Atendente da loja","system_prompt":"Você atende os clientes da loja. Seja breve e cordial.","tools":{"chamar_http":"act","marcar_etiqueta":"suggest","transferir_para_humano":"act"}}'get/api/v1/ai/agents/{agentID}Mostra um agente de IASó a chave da plataforma
O agente com os valores dos cabeçalhos dos endpoints mascarados (••••) e os números em que está ligado (numbers). Sempre Cache-Control: no-store.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
agentIDobrigatório | path | string | ID do agente (UUID). Um id que não é UUID dá 404 not_found. |
Respostas
200O agente.json{ "created_at": "2026-01-01T12:00:00Z", "credential_id": "00000000-0000-4000-8000-000000000000", "flow_ids": [ "00000000-0000-4000-8000-000000000000" ], "handoff_assignee": "string", "handoff_keywords": [ "string" ], "handoff_message": "string", "http_endpoints": [ { "description": "string", "headers": {}, "method": "GET", "name": "string", "url": "string" } ], "id": "00000000-0000-4000-8000-000000000000", "max_consecutive_replies": 0, "max_tokens": 0, "max_tool_iterations": 0, "memory_messages": 0, "model": "string", "name": "string", "reply_delay_seconds": 0, "system_prompt": "string", "temperature": 0, "timeout_seconds": 0, "tools": { "chamar_http": "act", "consultar_contato": "act", "consultar_negocios": "act", "criar_negocio": "act", "ganhar_negocio": "act", "iniciar_fluxo": "act", "marcar_etiqueta": "act", "mover_negocio": "act", "perder_negocio": "act", "salvar_campo": "act", "transferir_para_humano": "act" }, "updated_at": "2026-01-01T12:00:00Z", "numbers": [ { "enabled": false, "instance_id": "string" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled; na criação e no teste, tambémai_agents_enabled), o limite de agentes do plano na criação (plan_limit,max_ai_agents) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Agente inexistente (not_found).json{ "code": "not_found", "error": "agent not found" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível (sem banco).json{ "error": "AI storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/ai/agents/<agentID>" \
-H "Authorization: Bearer $API_KEY"patch/api/v1/ai/agents/{agentID}Altera um agente de IASó a chave da plataforma
Só os campos enviados mudam; campo desconhecido, JSON inválido, corpo vazio ou acima de 128 KiB dão 400 invalid_body. As mesmas validações da criação valem para cada campo enviado. Um erro de validação não muda nada.
http_endpoints, quando vem, substitui a lista inteira. Um valor de cabeçalho mascarado (como a leitura o devolve) mantém o segredo gravado só no mesmo endpoint: mesmo name, mesmo method e mesma url (esquema e host sem diferenciar maiúsculas, caminho sem a barra final). Com outro método ou outra URL, num endpoint renomeado ou num cabeçalho que não estava gravado, o segredo iria para outro destino: 400 MASKED_SECRET_NEW_DESTINATION, e é preciso mandar o valor de novo. Um cabeçalho que não vier na lista deixa de existir.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
agentIDobrigatório | path | string | ID do agente (UUID). Um id que não é UUID dá 404 not_found. |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
credential_idopcional | string (uuid) | null | Uma chave de IA existente, ou null (invalid_credential). |
flow_idsopcional | array<string (uuid)> | Fluxos existentes; repetidos contam uma vez (invalid_flows). |
handoff_assigneeopcional | string | null | Id opaco de até 200 caracteres; null ou "" = nenhum (invalid_handoff_assignee). |
handoff_keywordsopcional | array<string> | Até 20, de até 50 caracteres, nenhuma vazia; padrão ["atendente","humano"]; [] desliga (invalid_handoff_keywords). |
handoff_messageopcional | string | Até 1000 caracteres (invalid_handoff_message). |
http_endpointsopcional | array<object> | Substitui a lista inteira (invalid_http_endpoints, url_internal, MASKED_SECRET_NEW_DESTINATION). |
http_endpoints[].descriptionopcional | string | O que o endpoint faz, para o modelo decidir quando chamá-lo. |
http_endpoints[].headersopcional | object | Até 10 cabeçalhos (nome sem espaço nem :, até 100 caracteres; valor em uma linha, até 4096). Os valores são segredos: gravados cifrados e devolvidos sempre como ••••. Mandar de volta o valor mascarado mantém o gravado só no mesmo endpoint (mesmo name, method e url); senão, 400 MASKED_SECRET_NEW_DESTINATION. |
http_endpoints[].methodobrigatório | "GET" | "POST" | Sem diferenciar maiúsculas na entrada; volta em maiúsculas. |
http_endpoints[].nameobrigatório | string | Nome com que o modelo chama o endpoint (chamar_http); único no agente. |
http_endpoints[].urlobrigatório | string | URL http(s) absoluta e pública (rede interna ou porta não permitida = 400 url_internal; esquema não http(s) ou usuário na URL = 400 invalid_http_endpoints). A chamada também confere o destino depois do DNS e em cada redirecionamento. Nas leituras, os valores da query voltam mascarados (?token=•••); reenviada assim, a URL mantém a gravada só no mesmo endpoint (mesmo nome, método, esquema, host, caminho e chaves da query); se algo além de um valor mascarado mudou, 400 MASKED_SECRET_NEW_DESTINATION pedindo a URL completa. |
max_consecutive_repliesopcional | integer | Padrão 10 (invalid_max_consecutive_replies). |
max_tokensopcional | integer | 0 = o padrão do provedor (invalid_max_tokens). |
max_tool_iterationsopcional | integer | Padrão 3 (invalid_max_tool_iterations). |
memory_messagesopcional | integer | Padrão 10 (invalid_memory). |
modelopcional | string | Vazio = o default_model da chave (invalid_model). |
nameopcional | string | Obrigatório na criação (invalid_name). |
reply_delay_secondsopcional | integer | Padrão 8; 0 responde cada mensagem na hora (invalid_reply_delay). |
system_promptopcional | string | Até 8 KiB (invalid_system_prompt). |
temperatureopcional | number | null | De 0 a 2, ou null (invalid_temperature); 0 vale como null (o padrão do provedor). |
timeout_secondsopcional | integer | Padrão 20 (invalid_timeout). |
toolsopcional | any | Substitui o mapa inteiro. Padrão {"transferir_para_humano":"act"}. Nome desconhecido ou autonomia fora de act, suggest, off: invalid_tools. |
tools.chamar_httpopcional | "act" | "suggest" | "off" | |
tools.consultar_contatoopcional | "act" | "suggest" | "off" | |
tools.consultar_negociosopcional | "act" | "suggest" | "off" | |
tools.criar_negocioopcional | "act" | "suggest" | "off" | |
tools.ganhar_negocioopcional | "act" | "suggest" | "off" | |
tools.iniciar_fluxoopcional | "act" | "suggest" | "off" | |
tools.marcar_etiquetaopcional | "act" | "suggest" | "off" | |
tools.mover_negocioopcional | "act" | "suggest" | "off" | |
tools.perder_negocioopcional | "act" | "suggest" | "off" | |
tools.salvar_campoopcional | "act" | "suggest" | "off" | |
tools.transferir_para_humanoopcional | "act" | "suggest" | "off" |
{
"http_endpoints": [
{
"description": "Consulta o status de um pedido pelo número.",
"headers": {
"Authorization": "••••"
},
"method": "GET",
"name": "consultar_pedido",
"url": "https://loja.example.com/api/pedidos"
}
]
}Respostas
200Alterado (os cabeçalhos mascarados).json{ "created_at": "2026-01-01T12:00:00Z", "credential_id": "00000000-0000-4000-8000-000000000000", "flow_ids": [ "00000000-0000-4000-8000-000000000000" ], "handoff_assignee": "string", "handoff_keywords": [ "string" ], "handoff_message": "string", "http_endpoints": [ { "description": "string", "headers": {}, "method": "GET", "name": "string", "url": "string" } ], "id": "00000000-0000-4000-8000-000000000000", "max_consecutive_replies": 0, "max_tokens": 0, "max_tool_iterations": 0, "memory_messages": 0, "model": "string", "name": "string", "reply_delay_seconds": 0, "system_prompt": "string", "temperature": 0, "timeout_seconds": 0, "tools": { "chamar_http": "act", "consultar_contato": "act", "consultar_negocios": "act", "criar_negocio": "act", "ganhar_negocio": "act", "iniciar_fluxo": "act", "marcar_etiqueta": "act", "mover_negocio": "act", "perder_negocio": "act", "salvar_campo": "act", "transferir_para_humano": "act" }, "updated_at": "2026-01-01T12:00:00Z" }400Corpo inválido (invalid_body) ou campo fora da regra, com o código do campo:invalid_name,invalid_system_prompt,invalid_credential(não é UUID ou a chave de IA não existe),invalid_model,invalid_temperature,invalid_max_tokens,invalid_memory,invalid_tools,invalid_http_endpoints,invalid_flows(não é UUID ou o fluxo não existe),invalid_handoff_message,invalid_handoff_keywords,invalid_handoff_assignee,invalid_max_tool_iterations,invalid_timeout,invalid_max_consecutive_replies. URL de endpoint que não é pública:url_internal. Valor de cabeçalho mascarado fora do mesmo endpoint gravado:MASKED_SECRET_NEW_DESTINATION. Nada é gravado.json{ "code": "MASKED_SECRET_NEW_DESTINATION", "error": "Send the key again when the URL, provider or format changes." }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled; na criação e no teste, tambémai_agents_enabled), o limite de agentes do plano na criação (plan_limit,max_ai_agents) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Agente inexistente (not_found).json{ "code": "not_found", "error": "agent not found" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível, ou sem a chave de cifra do servidor para cifrar um cabeçalho novo (secrets_key_missing; nada é gravado).json{ "error": "AI storage unavailable" }
Exemplo
curl -X PATCH "$API_URL/api/v1/ai/agents/<agentID>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"http_endpoints":[{"description":"Consulta o status de um pedido pelo número.","headers":{"Authorization":"••••"},"method":"GET","name":"consultar_pedido","url":"https://loja.example.com/api/pedidos"}]}'delete/api/v1/ai/agents/{agentID}Apaga um agente de IASó a chave da plataforma
Apaga o agente e o tira dos números em que é atendente (o GET /api/v1/instances/{id}/agent desses números passa a dar 404 agent_not_set).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
agentIDobrigatório | path | string | ID do agente (UUID). Um id que não é UUID dá 404 not_found. |
Respostas
204Apagado.401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled; na criação e no teste, tambémai_agents_enabled), o limite de agentes do plano na criação (plan_limit,max_ai_agents) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Agente inexistente (not_found).json{ "code": "not_found", "error": "agent not found" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível (sem banco).json{ "error": "AI storage unavailable" }
Exemplo
curl -X DELETE "$API_URL/api/v1/ai/agents/<agentID>" \
-H "Authorization: Bearer $API_KEY"post/api/v1/ai/agents/{agentID}/testTesta um agente de IA sem enviar nadaSó a chave da plataforma
Um turno simulado do agente, para o "Testar" da tela: o mesmo contexto (o prompt, as regras fixas e os "Dados do contato"), o mesmo motor e o mesmo laço de ferramentas, com a conversa e o contato que o pedido traz. Nada sai e nada grava: nenhuma ferramenta executa (cada uma vira um item de tool_calls, com a autonomia que teria, e o modelo ouve que ela não foi executada); nenhuma mensagem é enviada; nada é escrito em conversa, contato, nota ou CRM. A chamada ao provedor é real: conta nas chamadas de IA do mês e deixa linhas em ai_usage com a origem test e o id do agente. Uma passagem para humano que o agente faria (transferir_para_humano em act) encerra o teste como no turno real: reply é a handoff_message. O tempo é o timeout_seconds do agente. Uma falha (provedor, cota, tempo, limite de ferramentas) vem com 200 e error.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
agentIDobrigatório | path | string | ID do agente (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
contactopcional | object | Os "Dados do contato" do teste; ausente, só um telefone fictício. |
contact.fieldsopcional | object | |
contact.nameopcional | string | |
contact.phoneopcional | string | |
contact.tagsopcional | array<string> | |
messagesobrigatório | array<object> | A conversa do teste, da mais antiga para a mais nova; a última é do usuário (o cliente). |
messages[].roleobrigatório | "user" | "assistant" | |
messages[].textobrigatório | string |
{
"contact": {
"fields": {
"cidade": "Recife"
},
"name": "Maria",
"phone": "+5511987654321",
"tags": [
"cliente"
]
},
"messages": [
{
"role": "user",
"text": "Oi"
},
{
"role": "assistant",
"text": "Olá! Como posso ajudar?"
},
{
"role": "user",
"text": "Quanto custa o plano anual?"
}
]
}Respostas
200O que o agente responderia e as ferramentas que chamaria.json{ "latency_ms": 840, "reply": "Oi, Maria! O plano anual custa R$ 1.200.", "tokens_in": 150, "tokens_out": 30, "tool_calls": [ { "args": { "etiqueta": "vip" }, "name": "marcar_etiqueta", "would": "act" } ] }400Corpo inválido (invalid_body);messagesfora de 1 a 20, com papel que não éuserouassistant, texto vazio ou acima de 4096 caracteres, ou a última que não é do usuário (invalid_messages);contactinválido (invalid_contact); o agente sem chave de IA (agent_without_key).json{ "code": "invalid_messages", "error": "messages: 1 to 20, the last one from the user" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled; na criação e no teste, tambémai_agents_enabled), o limite de agentes do plano na criação (plan_limit,max_ai_agents) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Agente inexistente (not_found).json{ "code": "not_found", "error": "agent not found" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível (sem banco).json{ "error": "AI storage unavailable" }
Exemplo
curl -X POST "$API_URL/api/v1/ai/agents/<agentID>/test" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"contact":{"fields":{"cidade":"Recife"},"name":"Maria","phone":"+5511987654321","tags":["cliente"]},"messages":[{"role":"user","text":"Oi"},{"role":"assistant","text":"Olá! Como posso ajudar?"},{"role":"user","text":"Quanto custa o plano anual?"}]}'get/api/v1/ai/credentialsLista as chaves de IA do clienteSó a chave da plataforma
Cada chave com a api_key mascarada. Sempre Cache-Control: no-store.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Respostas
200As chaves.json{ "credentials": [ { "api_key": "string", "base_url": "string", "created_at": "2026-01-01T12:00:00Z", "default_model": "string", "format": "openai_chat", "id": "00000000-0000-4000-8000-000000000000", "name": "string", "updated_at": "2026-01-01T12:00:00Z" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/ai/credentials" \
-H "Authorization: Bearer $API_KEY"post/api/v1/ai/credentialsCria uma chave de IASó a chave da plataforma
name, format, default_model e api_key obrigatórios. A chave é gravada cifrada com a chave de cifra do servidor; sem ela, 503 secrets_key_missing e nada é gravado.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
api_keyopcional | string | A chave do provedor. Mascarada (como a leitura a devolve) ou ausente mantém a gravada, menos quando format ou base_url mudam. |
base_urlopcional | string | URL http(s) sem usuário, query ou fragmento; vazia = o provedor do formato. |
default_modelopcional | string | |
formatopcional | "openai_chat" | "openai_responses" | "anthropic_messages" | "gemini" | |
nameopcional | string |
{
"api_key": "string",
"base_url": "string",
"default_model": "string",
"format": "openai_chat",
"name": "string"
}Respostas
201Criada (a chave mascarada).json{ "api_key": "string", "base_url": "string", "created_at": "2026-01-01T12:00:00Z", "default_model": "string", "format": "openai_chat", "id": "00000000-0000-4000-8000-000000000000", "name": "string", "updated_at": "2026-01-01T12:00:00Z" }400Campo ausente ou inválido (name_required,invalid_format,invalid_base_url,default_model_required,api_key_required).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }503Armazenamento indisponível, ou sem a chave de cifra do servidor para cifrar a chave (secrets_key_missing; nada é gravado).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/ai/credentials" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"api_key":"string","base_url":"string","default_model":"string","format":"openai_chat","name":"string"}'patch/api/v1/ai/credentials/{credentialID}Altera uma chave de IASó a chave da plataforma
Muda os campos enviados. Se format ou base_url mudam, a chave gravada iria para outro destino, então uma api_key nova é obrigatória: mascarada ou ausente, 400 MASKED_SECRET_NEW_DESTINATION e nada muda. No mesmo destino, a chave mascarada ou ausente mantém a gravada.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
credentialIDobrigatório | path | string | ID da chave de IA (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
api_keyopcional | string | A chave do provedor. Mascarada (como a leitura a devolve) ou ausente mantém a gravada, menos quando format ou base_url mudam. |
base_urlopcional | string | URL http(s) sem usuário, query ou fragmento; vazia = o provedor do formato. |
default_modelopcional | string | |
formatopcional | "openai_chat" | "openai_responses" | "anthropic_messages" | "gemini" | |
nameopcional | string |
{
"api_key": "string",
"base_url": "string",
"default_model": "string",
"format": "openai_chat",
"name": "string"
}Respostas
200Alterada (a chave mascarada).json{ "api_key": "string", "base_url": "string", "created_at": "2026-01-01T12:00:00Z", "default_model": "string", "format": "openai_chat", "id": "00000000-0000-4000-8000-000000000000", "name": "string", "updated_at": "2026-01-01T12:00:00Z" }400Campo inválido, ou destino novo sem uma chave nova (MASKED_SECRET_NEW_DESTINATION).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }503Armazenamento indisponível, ou sem a chave de cifra do servidor para cifrar a chave (secrets_key_missing; nada é gravado).json{ "error": "invalid request" }
Exemplo
curl -X PATCH "$API_URL/api/v1/ai/credentials/<credentialID>" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"api_key":"string","base_url":"string","default_model":"string","format":"openai_chat","name":"string"}'delete/api/v1/ai/credentials/{credentialID}Apaga uma chave de IASó a chave da plataforma
Recusa com 409 CREDENTIAL_IN_USE (e a lista used_by) uma chave que um fluxo, uma regra de cluster ou de aquecimento, ou um agente de IA usa. O banco também recusa (chave estrangeira ON DELETE RESTRICT em ai_agents.credential_id), então um agente salvo ao mesmo tempo não fica sem chave.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
credentialIDobrigatório | path | string | ID da chave de IA (UUID). |
Respostas
204Apagada.401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }409A chave está em uso (CREDENTIAL_IN_USE).json{ "code": "string", "error": "string", "used_by": [ { "id": "string", "kind": "flow", "name": "string" } ] }
Exemplo
curl -X DELETE "$API_URL/api/v1/ai/credentials/<credentialID>" \
-H "Authorization: Bearer $API_KEY"post/api/v1/ai/credentials/{credentialID}/testTesta uma chave de IASó a chave da plataforma
Uma chamada mínima pelo motor (origem test, ref credential:{credentialID}). É uma chamada real: conta em max_ai_rewrite_calls_per_month e deixa uma linha de uso. ?model= troca o modelo do teste. O resultado vem sempre em 200: ok false com o código do erro (ai_key_invalid, ai_timeout, ai_limit…).
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
credentialIDobrigatório | path | string | ID da chave de IA (UUID). |
modelopcional | query | string |
Respostas
200O resultado do teste.json{ "error": "string", "format": "string", "input_tokens": 0, "latency_ms": 0, "model": "string", "ok": false, "output_tokens": 0 }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/ai/credentials/<credentialID>/test" \
-H "Authorization: Bearer $API_KEY"get/api/v1/ai/usageUso das chamadas de IASó a chave da plataforma
Totais e grupos (group_by origin, model ou day) das chamadas de IA do período, filtrados por kind e ref da origem. month é a contagem do plano no mês (ai_calls), a mesma que o teto max_ai_rewrite_calls_per_month confere.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
fromopcional | query | string | RFC 3339 ou AAAA-MM-DD; padrão, o começo do mês UTC. |
toopcional | query | string | RFC 3339 ou AAAA-MM-DD (o dia inteiro); padrão, agora. |
kindopcional | query | "flow" | "middleware" | "agent" | "test" | |
refopcional | query | string | |
group_byopcional | query | "origin" | "model" | "day" |
Respostas
200O uso do período.json{ "from": "2026-01-01T12:00:00Z", "group_by": "string", "groups": [ { "avg_latency_ms": 0, "calls": 0, "errors": {}, "input_tokens": 0, "key": {}, "output_tokens": 0 } ], "month": { "ai_calls": 0, "limit": 0, "period": "string" }, "to": "2026-01-01T12:00:00Z", "totals": { "avg_latency_ms": 0, "calls": 0, "errors": {}, "input_tokens": 0, "key": {}, "output_tokens": 0 } }400from/toinválidos ou fora de ordem, ougroup_bydesconhecido (invalid_query).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }503O uso não pôde ser lido (usage_unavailable).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/ai/usage" \
-H "Authorization: Bearer $API_KEY"get/api/v1/instances/{id}/agentMostra o atendente de IA do númeroChave do número ou do cluster
O agente de IA que responde as conversas do número, se está ligado e em que horário. Sempre Cache-Control: no-store.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200O atendente do número.json{ "agent_id": "00000000-0000-4000-8000-000000000000", "enabled": false, "instance_id": "00000000-0000-4000-8000-000000000000", "schedule": { "days": [ 1, 2, 3, 4, 5 ], "end": "18:00", "start": "08:00", "timezone": "America/Sao_Paulo" }, "updated_at": "2026-01-01T12:00:00Z" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Chave de cliente (CLIENT_KEY_SCOPE); o atendente do número é configuração do número.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Número inexistente (instance not found, semcode) ou número sem atendente (agent_not_set).json{ "error": "instance not found" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível (sem banco).json{ "error": "AI storage unavailable" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/agent" \
-H "Authorization: Bearer $API_KEY"put/api/v1/instances/{id}/agentLiga um agente de IA ao númeroChave do número ou do cluster
Põe (ou troca) o agente que responde as conversas do número. enabled ausente vale true; schedule ausente ou null = sempre. Cada envio substitui o atendente inteiro: um schedule ausente apaga o horário gravado. Campo desconhecido, JSON inválido ou corpo acima de 16 KiB: 400 invalid_body.
O agente responde uma mensagem de texto de um contato (conversa 1:1) que nenhum fluxo consumiu nem iniciou, com o atendente ligado e dentro do horário, o plano com IA, o número sem pausa, a conversa sem responsável nem agente pausado (handled_by agent na caixa de entrada) e o contato fora de um fluxo em andamento.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
agent_idobrigatório | string (uuid) | Um agente salvo (invalid_agent). |
enabledopcional | boolean | |
scheduleopcional | object | null | Ausente ou null = sempre. Fuso IANA, de 1 a 7 dias de 0 a 6 e start e end HH:MM diferentes; senão, invalid_schedule. |
{
"agent_id": "3f1c2a9e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
"enabled": true,
"schedule": {
"days": [
1,
2,
3,
4,
5
],
"end": "18:00",
"start": "08:00",
"timezone": "America/Sao_Paulo"
}
}Respostas
200O atendente gravado.json{ "agent_id": "00000000-0000-4000-8000-000000000000", "enabled": false, "instance_id": "00000000-0000-4000-8000-000000000000", "schedule": { "days": [ 1, 2, 3, 4, 5 ], "end": "18:00", "start": "08:00", "timezone": "America/Sao_Paulo" }, "updated_at": "2026-01-01T12:00:00Z" }400Corpo inválido (invalid_body), horário inválido (invalid_schedule) ouagent_idque não é um agente salvo, inclusive ausente ou que não é UUID (invalid_agent). Nada muda.json{ "code": "invalid_agent", "error": "agent not found" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403IA fora do plano (plan_feature_disabled, featureai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Número inexistente (instance not found, semcode).json{ "error": "instance not found" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível (sem banco).json{ "error": "AI storage unavailable" }
Exemplo
curl -X PUT "$API_URL/api/v1/instances/<id>/agent" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent_id":"3f1c2a9e-5b7d-4e8f-9a0b-1c2d3e4f5a6b","enabled":true,"schedule":{"days":[1,2,3,4,5],"end":"18:00","start":"08:00","timezone":"America/Sao_Paulo"}}'delete/api/v1/instances/{id}/agentTira o agente de IA do númeroChave do número ou do cluster
O número deixa de ter atendente; o agente continua salvo. As conversas mantêm o agent_paused_at e passam a ter handled_by null.
Chave: chave da plataforma, chave do número
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
204Removido.401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Chave de cliente (CLIENT_KEY_SCOPE); o atendente do número é configuração do número.json{ "code": "CLIENT_KEY_SCOPE", "error": "forbidden" }404Número inexistente (instance not found, semcode) ou número sem atendente (agent_not_set).json{ "error": "instance not found" }500O agente não pôde ser lido ou gravado (ai_agent_unavailable; sem detalhes do banco). Ao criar ou alterar, também um cabeçalho que não pôde ser cifrado (secret_not_sealed; nada é gravado).json{ "code": "ai_agent_unavailable", "error": "the agent could not be read or saved" }503Armazenamento indisponível (sem banco).json{ "error": "AI storage unavailable" }
Exemplo
curl -X DELETE "$API_URL/api/v1/instances/<id>/agent" \
-H "Authorization: Bearer $API_KEY"Saúde e referência
A saúde da API e esta especificação.
get/api/v1/healthSaúde da APISem chave
Saúde do processo, sem chave. Nunca é barrada por plano nem por cobrança; tem limite de taxa.
Chave: nenhuma (o token do caminho é a credencial)
Respostas
200API no ar.json{ "billing_status": "active", "billing_status_updated_at": "2026-01-01T12:00:00Z", "clusters_in_memory": 0, "database": "connected", "instances_in_memory": 0, "status": "string", "uptime_seconds": 0, "version": "2.0.0", "warmers_in_memory": 0 }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/health"get/openapi.jsonEste documento em JSONSem chave
Documento OpenAPI público, sem chave (operações internas removidas). Cache de 5 minutos (Cache-Control: public, max-age=300). Um visualizador fica em /swagger/.
Chave: nenhuma (o token do caminho é a credencial)
Respostas
200Documento OpenAPI 3.1.json{}500Documento indisponível (openapi document unavailable).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/openapi.json"get/openapi.yamlEste documento em YAMLSem chave
O mesmo documento público de /openapi.json, em YAML, sem chave. Cache de 5 minutos.
Chave: nenhuma (o token do caminho é a credencial)
Respostas
200Documento OpenAPI 3.1.jsonstring500Documento indisponível (openapi document unavailable).json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/openapi.yaml"Número oficial (API da Meta)Em breve
Em breve: o número oficial vai chegar como um produto à parte. As rotas ficam aqui só como referência e ainda não estão disponíveis.
get/api/v1/instances/{id}/cloud-usageMensagens cobráveis do número oficialChave de API
As mensagens que a Meta marcou como cobráveis (pricing.billable) num mês, por categoria de preço. Cada mensagem conta uma vez, no primeiro status cobrável; um status seguinte não a muda. O mês é em UTC, como o uso do plano. O valor em dinheiro é o da Meta (a tabela de preços dela, pelo país): a API não o calcula. Num número por QR: 409 provider_unsupported.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
monthopcional | query | string | O mês, YYYY-MM (UTC); sem ele, o atual. |
Respostas
200A contagem do mês.json{ "billable_total": 0, "by_category": {}, "instance_id": "string", "month": "2026-10", "note": "string", "timezone": "string" }400Mês inválido (invalid_month).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Uma chave de cliente sem este número (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }404Instância inexistente.json{ "error": "invalid request" }409Um número por QR (provider_unsupported).json{ "code": "provider_unsupported", "error": "string", "provider": "whatsmeow" }503A contagem não pôde ser lida.json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/cloud-usage" \
-H "Authorization: Bearer $API_KEY"get/api/v1/settings/providersOs tipos de número desta instalaçãoSó a chave da plataforma
Os tipos de número que a instalação oferece: whatsmeow, cloud (oficial, pela API oficial da Meta) ou os dois, por a configuração do servidor. O painel mostra só as telas deles. Um tipo desligado: criar um número dele e as rotas só dele dão 409 provider_disabled. Sem segredo. Só a chave global.
Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).
Respostas
200Os tipos.json{ "graph_version": "v27.0", "providers": [ "whatsmeow", "cloud" ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Chave de cliente (CLIENT_KEY_SCOPE).json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/settings/providers" \
-H "Authorization: Bearer $API_KEY"get/webhooks/metaVerificação do webhook da MetaSem chave
A Meta assina o webhook dos números oficiais com este GET: com hub.mode=subscribe e o hub.verify_token igual ao token de verificação configurado no servidor, a resposta é o hub.challenge em texto. Não usa chave de API. Sem o token de verificação na instalação: 503 meta_webhook_unconfigured.
Chave: nenhuma (o token do caminho é a credencial)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
hub.modeobrigatório | query | string | |
hub.verify_tokenobrigatório | query | string | |
hub.challengeobrigatório | query | string |
Respostas
200Ohub.challenge, em texto.jsonstring403Modo ou token errado (verification refused).json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }503A instalação não tem o app secret e o token de verificação da Meta (meta_webhook_unconfigured), ou está desligando.json{ "error": "invalid request" }
Exemplo
curl -X GET "$API_URL/webhooks/meta?hub.mode=<hub.mode>&hub.verify_token=<hub.verify_token>&hub.challenge=<hub.challenge>"post/webhooks/metaReceber eventos da MetaSem chave
Os eventos dos números oficiais: mensagens, status das enviadas e a qualidade do número. Não usa chave de API: o corpo cru vem assinado com o app secret (X-Hub-Signature-256: sha256=<HMAC>), conferido em tempo constante, sob um limite por endereço folgado. A resposta é 200 logo, e o processamento segue em segundo plano: o número é achado pelo phone_number_id (um desconhecido é ignorado, com 200); uma mensagem repetida (o mesmo wamid) é gravada e entregue uma vez; cada mensagem nova segue o caminho de hoje (fluxos, agente, Chatwoot e o evento message do webhook do cliente); os status viram os recibos das mensagens e das campanhas. Corpo de no máximo 3 MB.
Chave: nenhuma (o token do caminho é a credencial)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
X-Hub-Signature-256obrigatório | header | string |
Corpo (application/json)
{}Respostas
200Recebido (ok), ou lido e ignorado (ignored).json{ "status": "ok" }401Assinatura ausente ou errada (invalid signature).json{ "error": "invalid request" }413Corpo acima de 3 MB.json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }503A instalação não tem o app secret e o token de verificação da Meta (meta_webhook_unconfigured), ou está desligando.json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/webhooks/meta" \
-H "Content-Type: application/json" \
-d '{}'post/api/v1/instances/{id}/send-templateEnvia um template aprovadoChave de API
Envia um template APPROVED da WABA do número oficial, também fora da janela de 24 h. Os valores preenchem as variáveis por posição (parameters) ou por nome (named); um cabeçalho de mídia leva header_media, um botão dinâmico buttons, e um template de autenticação code. O que falta ou sobra é 400 template_parameters antes de chamar a Meta. Passa pelo mesmo caminho dos outros envios: a cota do plano, a pausa, o histórico (com o texto preenchido) e os status. Só número oficial.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
header_parametersopcional | array<string> | Os valores das variáveis de um cabeçalho de texto. |
languageobrigatório | string | O código do idioma do template (pt_BR, en_US). |
nameobrigatório | string | |
namedopcional | object | Os valores por nome, num template named ({"first_name":"Ana"}). |
parametersopcional | array<string> | Os valores do corpo por posição: o 1º preenche {{1}}, e assim por diante. |
buttonsopcional | array<object> | Os valores dos botões dinâmicos, pela posição do botão no template (de 0): a parte variável de um botão de URL, ou o cupom de um botão de copiar código. Um botão fixo (resposta rápida, telefone, URL sem variável) não leva valor. |
buttons[].indexobrigatório | integer | |
buttons[].textobrigatório | string | |
codeopcional | string | O código de um template de autenticação; vai no corpo e no botão de código. |
header_mediaopcional | object | A mídia de um cabeçalho de imagem, vídeo ou documento: link (https público) ou id (uma mídia já enviada à Meta), um dos dois; filename só num documento. |
header_media.filenameopcional | string | |
header_media.idopcional | string | |
header_media.linkopcional | string (uri) | |
toobrigatório | string | O telefone do contato (ou o JID de um BSUID). |
{
"header_parameters": [
"string"
],
"language": "string",
"name": "string",
"named": {},
"parameters": [
"string"
],
"buttons": [
{
"index": 0,
"text": "string"
}
],
"code": "string",
"header_media": {
"filename": "string",
"id": "string",
"link": "https://example.com"
},
"to": "string"
}Respostas
200Aceito pela Meta.json{ "id": "string" }400template_not_approved(o template não estáAPPROVED),template_not_found(não está na lista guardada; sincronize),template_parameters(os valores não batem com as variáveis, o cabeçalho de mídia, os botões ou o código), ouinvalid_template(faltato,nameoulanguage).json{ "code": "template_not_approved", "error": "the template promo is REJECTED, not APPROVED" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403Cota do plano esgotada (plan_limit) ou conta suspensa (ACCOUNT_SUSPENDED).json{ "error": "invalid request" }404Recurso inexistente.json{ "error": "invalid request" }409O envio de modelo:provider_unsupportednum número por QR,provider_disabledquando a instalação não oferece números oficiais, ounumber_restrictedquando o número oficial não estáonline(statusestatus_reasondizem o motivo, e a Meta não é chamada).json{ "code": "number_restricted", "error": "this official number cannot send now (status restricted); POST /instances/:id/refresh reads its status from Meta again", "status": "restricted", "status_reason": "quality_red" }422O token foi recusado (cloud_auth_invalid); depois disso, o número ficarestrictede o próximo envio já recebe o mesmo 422 sem a Meta ser chamada, até trocar o token (PUT /instances/{id}/cloud/credentials).json{ "error": "invalid request" }429Número pausado ou limite da Meta (rate_limited).json{ "error": "invalid request" }502A Meta não respondeu (cloud_unavailable).json{ "error": "invalid request" }503A API não conseguiu abrir o token guardado do número (cloud_credentials_unavailable: a chave de cifra do servidor ou o banco). O número não ficarestricted; a próxima tentativa envia quando o servidor o lê. Vale também para o/send, o/send-media, as listas de templates, as campanhas e os fluxos.json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/send-template" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"header_parameters":["string"],"language":"string","name":"string","named":{},"parameters":["string"],"buttons":[{"index":0,"text":"string"}],"code":"string","header_media":{"filename":"string","id":"string","link":"https://example.com"},"to":"string"}'get/api/v1/instances/{id}/templatesLista os templates do número oficialChave de API
A cópia dos templates da WABA guardada aqui, com synced_at; status filtra (APPROVED). Não chama a Meta: o webhook de estado mantém a cópia em dia. sync=1 (o botão "sincronizar") sincroniza antes (GET /{waba}/message_templates, todas as páginas; os que a Meta não tem mais saem), no máximo uma vez a cada 60 s por WABA: antes disso vem a cópia com synced: false. Se a Meta não responde, vem a cópia com sync_error. Só número oficial.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
statusopcional | query | string | |
syncopcional | query | "1" | 1 sincroniza com a Meta antes (no máximo a cada 60 s por WABA). |
Respostas
200Os templates.json{ "sync_error": "string", "synced": false, "synced_at": "2026-01-01T12:00:00Z", "templates": [ { "category": "MARKETING", "components": [ {} ], "language": "string", "meta_id": "string", "name": "string", "parameter_format": "positional", "rejected_reason": "string", "status": "string", "synced_at": "2026-01-01T12:00:00Z", "updated_at": "2026-01-01T12:00:00Z" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403A chave do número só lista e envia templates: criar e sincronizar agem na WABA inteira, cujos templates são de todos os números dela, e pedem a chave da plataforma ou uma chave de cliente (INSTANCE_KEY_SCOPE). Também o plano ou a conta.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key lists and sends templates; creating or syncing them acts on the whole WhatsApp Business Account: use the platform key or a client key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }422O token do número não pôde ser lido (cloud_auth_invalid).json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }
Exemplo
curl -X GET "$API_URL/api/v1/instances/<id>/templates" \
-H "Authorization: Bearer $API_KEY"post/api/v1/instances/{id}/templatesCria um template na WABAChave de API
Cria o template pela Graph API (POST /{waba}/message_templates) e o guarda com o estado da Meta (PENDING enquanto ela revisa; a mudança chega pelo webhook message_template_status_update). Só número oficial.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Corpo (application/json)
| Campo | Tipo | Descrição |
|---|---|---|
categoryobrigatório | "MARKETING" | "UTILITY" | "AUTHENTICATION" | |
componentsobrigatório | array<object> | O formato da Meta; precisa de um BODY com texto (até 1024 caracteres). |
languageobrigatório | string | |
nameobrigatório | string | |
parameter_formatopcional | "positional" | "named" |
{
"category": "UTILITY",
"components": [
{
"example": {
"body_text": [
[
"Ana",
"A-123"
]
]
},
"text": "Olá {{1}}, seu pedido {{2}} está pronto.",
"type": "BODY"
}
],
"language": "pt_BR",
"name": "pedido_pronto"
}Respostas
201Criado.json{ "category": "MARKETING", "components": [ {} ], "language": "string", "meta_id": "string", "name": "string", "parameter_format": "positional", "rejected_reason": "string", "status": "string", "synced_at": "2026-01-01T12:00:00Z", "updated_at": "2026-01-01T12:00:00Z" }400Template inválido (invalid_template).json{ "error": "invalid request" }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403A chave do número só lista e envia templates: criar e sincronizar agem na WABA inteira, cujos templates são de todos os números dela, e pedem a chave da plataforma ou uma chave de cliente (INSTANCE_KEY_SCOPE). Também o plano ou a conta.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key lists and sends templates; creating or syncing them acts on the whole WhatsApp Business Account: use the platform key or a client key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }422A Meta recusou o template (template_refused) ou o token (cloud_auth_invalid).json{ "error": "invalid request" }429Limite de taxa da API, ou o limite de criação da WABA por esta API: 20 templates por hora, abaixo dos 100 da Meta (template_create_limited, comRetry-Afterem segundos).json{ "code": "template_create_limited", "error": "at most 20 templates are created per hour in this account" }502A Meta não respondeu (cloud_unavailable).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/templates" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"category":"UTILITY","components":[{"example":{"body_text":[["Ana","A-123"]]},"text":"Olá {{1}}, seu pedido {{2}} está pronto.","type":"BODY"}],"language":"pt_BR","name":"pedido_pronto"}'post/api/v1/instances/{id}/templates/syncSincroniza os templates com a MetaChave de API
O mesmo que GET …/templates?sync=1: sincroniza no máximo a cada 60 s por WABA e devolve a cópia; um erro da Meta vem em sync_error, com 200. Só número oficial.
Chave: chave da plataforma, chave do número, chave de API (wck_...)
Parâmetros
| Campo | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string | ID da instância (UUID). |
Respostas
200Os templates.json{ "sync_error": "string", "synced": false, "synced_at": "2026-01-01T12:00:00Z", "templates": [ { "category": "MARKETING", "components": [ {} ], "language": "string", "meta_id": "string", "name": "string", "parameter_format": "positional", "rejected_reason": "string", "status": "string", "synced_at": "2026-01-01T12:00:00Z", "updated_at": "2026-01-01T12:00:00Z" } ] }401Chave ausente ou inválida.json{ "error": "unauthorized: missing or invalid API key" }403A chave do número só lista e envia templates: criar e sincronizar agem na WABA inteira, cujos templates são de todos os números dela, e pedem a chave da plataforma ou uma chave de cliente (INSTANCE_KEY_SCOPE). Também o plano ou a conta.json{ "code": "INSTANCE_KEY_SCOPE", "error": "a number's key lists and sends templates; creating or syncing them acts on the whole WhatsApp Business Account: use the platform key or a client key" }404Recurso inexistente.json{ "error": "invalid request" }409O tipo do número não tem esta rota:provider_unsupportednum número oficial (provider: cloud), ouprovider_disabledquando a instalação não oferece o número por QR.json{ "code": "provider_disabled", "error": "this installation does not offer whatsmeow numbers", "provider": "whatsmeow" }422O token foi recusado (cloud_auth_invalid).json{ "error": "invalid request" }429Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).json{ "error": "rate limit exceeded, try again later" }502A Meta não respondeu (cloud_unavailable).json{ "error": "invalid request" }
Exemplo
curl -X POST "$API_URL/api/v1/instances/<id>/templates/sync" \
-H "Authorization: Bearer $API_KEY"