Ir para o conteúdo

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

CampoOndeTipoDescrição
removedopcionalquery"only"only lista só os números removidos (só a chave global).

Respostas

  • 200 Lista de instâncias (ou de números removidos, com removed=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"
      }
    ]
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 removed=only com chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 503 removed=only: não foi possível ler os números removidos; tente de novo.

    json
    {
      "error": "removed numbers unavailable"
    }

Exemplo

bash
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)

CampoTipoDescrição
access_tokenopcionalstringprovider: cloud: o token do usuário de sistema. Fica cifrado e nunca volta.
nameobrigatóriostring
phone_number_idopcionalstringprovider: cloud: o id do número na API oficial da Meta.
pinopcionalstringprovider: 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_idopcionalstringprovider: cloud: o id da conta do WhatsApp Business.
json
{
  "name": "Atendimento"
}

Respostas

  • 201 Instância criada. Um número oficial pode vir com warnings, 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/meta dá 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"
      ]
    }
  • 400 name ausente ou corpo inválido; invalid_provider (tipo desconhecido); invalid_cloud_number (um campo do número oficial inválido).

    json
    {
      "error": "name required"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Sem vaga em max_instances ou armazenamento no teto (max_storage_mb) (plan_limit), ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED). Um número oficial sem cloud_numbers_enabled no plano: plan_feature_disabled.

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 409 provider_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: o phone_number_id já é 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)"
    }
  • 422 A 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)"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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 (sem code).

    json
    {
      "code": "INSTANCE_NOT_STORED",
      "error": "could not store the change; nothing changed"
    }
  • 502 A 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"
    }
  • 503 Nã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

bash
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

  • 200 Resumo por número.

    json
    {
      "instances": [
        {
          "instanceId": "string",
          "level": "good",
          "reasons": [
            "string"
          ],
          "suggestedDailyLimit": 0
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Não foi possível calcular a saúde (HEALTH_UNAVAILABLE); tente de novo.

    json
    {
      "code": "HEALTH_UNAVAILABLE",
      "error": "health not available"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Número removido (ou já removido antes).

    json
    {
      "removed_at": "2026-10-31T12:00:00Z",
      "status": "removed"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
access_tokenobrigatóriostringO token de usuário de sistema da Meta (de 20 a 1000 caracteres, sem espaços).
json
{
  "access_token": "string"
}

Respostas

  • 200 O 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"
    }
  • 400 Token ausente ou fora do formato (invalid_cloud_number).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Uma chave de cliente sem este número (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 422 A 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"
    }
  • 502 A Graph API não respondeu (cloud_unavailable).

    json
    {
      "error": "invalid request"
    }
  • 503 sem a chave de cifra do servidor (secrets_key_missing).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
limitopcionalqueryintegerPágina (padrão 50; inválido ou <= 0 vira 50).
offsetopcionalqueryintegerDeslocamento (padrão 0).
event_typeopcionalquerystringTipo de evento exato.
searchopcionalquerystringBusca (sem diferenciar maiúsculas) no tipo e no payload.

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
limitopcionalqueryintegerPágina (padrão 50; inválido ou <= 0 vira 50).
offsetopcionalqueryintegerDeslocamento (padrão 0).
categoryopcionalquerystringCategoria exata.
severityopcionalquerystringSeveridade exata.
searchopcionalquerystringBusca (sem diferenciar maiúsculas) em tipo, mensagem, categoria e payload.

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Dispositivo desconectado.

    json
    {
      "status": "disconnected"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Saú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
      }
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Não foi possível calcular a saúde (HEALTH_UNAVAILABLE); tente de novo.

    json
    {
      "code": "HEALTH_UNAVAILABLE",
      "error": "health not available"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
limitopcionalqueryintegerQuantos retratos (padrão 200; máximo 1000, acima disso vira 1000).

Respostas

  • 200 Histó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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID do número removido (UUID).

Respostas

  • 204 Histórico apagado.

  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O número está ativo (INSTANCE_NOT_REMOVED).

    json
    {
      "code": "INSTANCE_NOT_REMOVED",
      "error": "number is not removed: remove it first"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O histórico não foi apagado; nada mudou (HISTORY_NOT_DELETED).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 405 Método não suportado no modo sem sessão.

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
idopcionalstring | integer
jsonrpcobrigatóriostring
methodobrigatóriostring
paramsopcionalobject
json
{
  "id": "string",
  "jsonrpc": "string",
  "method": "tools/list",
  "params": {}
}

Respostas

  • 200 Resposta JSON-RPC.

    json
    {}
  • 202 Notificação aceita (sem resposta).

  • 400 Mensagem JSON-RPC inválida.

  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Chave de cliente sem o escopo numbers ou com o número fora da lista dela (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 405 Método não suportado no modo sem sessão.

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
pausedopcionalboolean
json
{
  "paused": true
}

Respostas

  • 200 Atualizado.

    json
    {
      "paused": false,
      "status": "string"
    }
  • 400 Corpo JSON inválido.

    json
    {
      "error": "paused required"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ao retomar (paused: false ou ausente); pausar continua liberado.

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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_image traz o QR atual (imagem em data URL).
  • paired: o dispositivo já está ligado a uma conta; use reconnect em 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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Estado do QR.

    json
    {
      "message": "QR not ready, try again",
      "status": "generating"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
secondsopcionalinteger
json
{
  "seconds": 3600
}

Respostas

  • 200 Atualizado.

    json
    {
      "reachout_cooldown_seconds": 0,
      "status": "string"
    }
  • 400 Corpo JSON inválido ou seconds negativo.

    json
    {
      "error": "seconds required"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Instância inexistente.

    json
    {
      "error": "not found"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Reconexão iniciada.

    json
    {
      "status": "reconnecting"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Recarga iniciada.

    json
    {
      "status": "refreshing"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Um número oficial atualizado há menos de um minuto (refresh_too_soon); tente depois do Retry-After.

    json
    {
      "error": "invalid request"
    }
  • 502 Número oficial com a Graph API sem responder (cloud_unavailable).

    json
    {
      "error": "invalid request"
    }
  • 503 Nú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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID do número removido (UUID).

Respostas

  • 200 Número restaurado (com a chave nova em api_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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Sem vaga em max_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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O número está ativo (INSTANCE_NOT_REMOVED).

    json
    {
      "code": "INSTANCE_NOT_REMOVED",
      "error": "number is not removed"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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 (sem code).

    json
    {
      "code": "INSTANCE_NOT_STORED",
      "error": "could not store the change; nothing changed"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Nova chave.

    json
    {
      "api_key": "string"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Mé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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Instâ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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
bodyobrigatóriostring
toobrigatóriostringTelefone ou JID do destinatário.
json
{
  "body": "Olá!",
  "to": "5511999990000"
}

Respostas

  • 200 Mensagem aceita pelo WhatsApp.

    json
    {
      "id": "3EB0A1B2C3D4E5F60718"
    }
  • 400 to/body ausentes, telefone inválido ou destinatário sem WhatsApp. Num número oficial: recipient_invalid (um grupo ou um LID não é destinatário) e cloud_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"
    }
  • 401 Chave ausente ou inválida, ou a sessão do WhatsApp foi deslogada/banida (categoria auth).

    json
    {
      "error": "invalid request"
    }
  • 403 Cota 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ó com error).

    json
    {
      "code": "plan_limit",
      "error": "Plan limit reached: max_messages_per_month.",
      "limit": "max_messages_per_month"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Nú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; status e status_reason dizem o motivo, a Meta não é chamada, e POST /instances/{id}/refresh relê 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"
    }
  • 410 O 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"
    }
  • 422 Número oficial, a Meta recusou o token (cloud_auth_invalid, o mesmo status do cadastro); o número fica restricted, 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"
    }
  • 429 Instância pausada, travada por reachout (Retry-After 3600), limite de taxa do WhatsApp (Retry-After 300) ou limite de taxa global da API (Retry-After 1).

    json
    {
      "error": "instance is temporarily locked after a reachout error"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 502 Erro do servidor do WhatsApp.

    json
    {
      "error": "invalid request"
    }
  • 503 Instâ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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/x-www-form-urlencoded)

CampoTipoDescrição
captionopcionalstring
file_urlobrigatóriostring (uri)
toobrigatóriostring
typeopcional"image" | "video" | "audio" | "document"
json
{
  "caption": "Nosso catálogo",
  "file_url": "https://cdn.example.com/catalogo.pdf",
  "to": "5511999990000",
  "type": "document"
}

Respostas

  • 200 Mí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"
    }
  • 400 to ausente, 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) e cloud_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) e media_type_unsupported (um tipo que a Meta não aceita naquele tipo de mídia; mande como documento).

    json
    {
      "error": "to required"
    }
  • 401 Chave ausente ou inválida, ou a sessão do WhatsApp foi deslogada/banida (categoria auth).

    json
    {
      "error": "invalid request"
    }
  • 403 Cota 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Nú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; status e status_reason dizem o motivo, a Meta não é chamada, e POST /instances/{id}/refresh relê 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"
    }
  • 410 O 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"
    }
  • 413 Arquivo 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"
    }
  • 422 A URL de mídia do cliente não pôde ser baixada (MEDIA_DOWNLOAD_FAILED). Num número oficial, também cloud_auth_invalid (a Meta recusou o token; o número fica restricted, 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"
    }
  • 429 Instância pausada, travada por reachout, limite de taxa do WhatsApp ou da API.

    json
    {
      "error": "invalid request"
    }
  • 500 Falha nossa ao preparar a mídia (MEDIA_PREPARE_FAILED) ou erro desconhecido no envio.

    json
    {
      "error": "invalid request"
    }
  • 502 Erro do servidor do WhatsApp.

    json
    {
      "error": "invalid request"
    }
  • 503 Instância sem cliente, falha de rede com o WhatsApp, ou uso do mês ilegível (usage_unavailable).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
bodyobrigatóriostring
quoted_message_idobrigatóriostringID no WhatsApp da mensagem citada.
quoted_senderobrigatóriostringTelefone ou JID de quem enviou a mensagem citada.
toobrigatóriostring
json
{
  "body": "Perfeito, combinado.",
  "quoted_message_id": "3EB0FFEEDDCCBBAA0011",
  "quoted_sender": "5511999990000",
  "to": "5511999990000"
}

Respostas

  • 200 Resposta 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"
    }
  • 400 Campos ausentes, to/quoted_sender inválidos, ou destinatário sem WhatsApp. Num número oficial: recipient_invalid (um grupo ou um LID não é destinatário) e cloud_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"
    }
  • 401 Chave ausente ou inválida, ou a sessão do WhatsApp foi deslogada/banida (categoria auth).

    json
    {
      "error": "invalid request"
    }
  • 403 Cota 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Nú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; status e status_reason dizem o motivo, a Meta não é chamada, e POST /instances/{id}/refresh relê 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"
    }
  • 410 O 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"
    }
  • 422 Número oficial, a Meta recusou o token (cloud_auth_invalid, o mesmo status do cadastro); o número fica restricted, 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"
    }
  • 429 Instância pausada, travada por reachout, limite de taxa do WhatsApp ou da API.

    json
    {
      "error": "invalid request"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 502 Erro do servidor do WhatsApp.

    json
    {
      "error": "invalid request"
    }
  • 503 Instância sem cliente, falha de rede com o WhatsApp, ou uso do mês ilegível (usage_unavailable).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Conversas.

    json
    {
      "chats": [
        {
          "archived": false,
          "jid": "string",
          "last_message_time": "2026-01-01T12:00:00Z",
          "muted": false,
          "name": "string",
          "pinned": false,
          "unread_count": 0
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Contatos.

    json
    {
      "contacts": [
        {
          "conversation_key": "string",
          "jid": "string",
          "name": "string",
          "push_name": "string"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Grupos.

    json
    {
      "groups": [
        {
          "announce_only": false,
          "is_community": false,
          "jid": "string",
          "locked": false,
          "member_count": 0,
          "name": "string",
          "owner_jid": "string",
          "participants": [
            "string"
          ]
        }
      ]
    }
  • 401 Chave ausente ou inválida, ou a instância não está logada no WhatsApp (not logged in).

    json
    {
      "error": "not logged in"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Instância sem cliente.

    json
    {
      "error": "not ready"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
limitopcionalqueryintegerTamanho da página; valores ≤ 0 ou inválidos voltam ao padrão.
offsetopcionalqueryintegerDeslocamento; valores negativos ou inválidos viram 0.
directionopcionalquery"inbound" | "outbound"Filtra pela direção.
sourceopcionalquerystringFiltra pela origem exata (instance, cluster, chatwoot, campaign, flow, warmer…).
searchopcionalquerystringBusca sem diferenciar maiúsculas em body, from, sender, source e conversation_key.

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
instanceIdsopcionalquerystringIds de instância separados por vírgula: só as conversas desses números (o SaaS manda os que a pessoa pode ver). Ausente = todos.
statusopcionalquery"open" | "resolved"Abertas ou resolvidas; ausente = as duas.
assigneeopcionalquerystringSó as atribuídas a este id.
unassignedopcionalquery"true" | "false"true = sem responsável; false = com responsável.
unreadopcionalquery"true" | "false"true = com não lidas; false = sem.
pinnedopcionalquery"true" | "false"true = só fixadas; false = só não fixadas.
labelopcionalquerystringSó as que têm esta etiqueta: tag do contato ou etiqueta da conversa.
qopcionalquerystringBusca sem caixa e sem acento no telefone, no nome do contato e no texto das mensagens.
cursoropcionalquerystringO next_cursor da página anterior.
limitopcionalqueryintegerItens por página.

Respostas

  • 200 Uma 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"
    }
  • 400 Pedido inválido (code INBOX_INVALID_REQUEST).

    json
    {
      "code": "INBOX_INVALID_REQUEST",
      "error": "status must be open or resolved"
    }
  • 401 Sem a chave global (a chave de instância não vale aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "inbox operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "inbox storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
instanceIdobrigatóriopathstring (uuid)Número (instância) da conversa.
keyobrigatóriopathstringconversation_key da conversa.
beforeopcionalquerystringO next_before da página anterior.
limitopcionalqueryintegerMensagens por página.

Respostas

  • 200 A 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"
        }
      ]
    }
  • 400 Pedido inválido (code INBOX_INVALID_REQUEST).

    json
    {
      "code": "INBOX_INVALID_REQUEST",
      "error": "status must be open or resolved"
    }
  • 401 Sem a chave global (a chave de instância não vale aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 A 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "inbox operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "inbox storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
instanceIdobrigatóriopathstring (uuid)Número (instância) da conversa.
keyobrigatóriopathstringconversation_key da conversa.

Corpo (application/json)

CampoTipoDescrição
agent_pausedopcionalbooleantrue 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.
assigneeopcionalstring | nullAtribui 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).
labelsopcionalarray<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.
pinnedopcionalboolean
readopcionalbooleanMarca como lida: zera unread_count e grava last_read_at.
statusopcional"open" | "resolved"
json
{
  "assignee": "person-123"
}

Respostas

  • 200 A 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"
    }
  • 400 Pedido inválido (code INBOX_INVALID_REQUEST).

    json
    {
      "code": "INBOX_INVALID_REQUEST",
      "error": "status must be open or resolved"
    }
  • 401 Sem a chave global (a chave de instância não vale aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 A 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"
    }
  • 409 O número da conversa foi removido da conta: o histórico é só leitura (INSTANCE_REMOVED).

    json
    {
      "code": "INSTANCE_REMOVED",
      "error": "number was removed"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "inbox operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "inbox storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
instanceIdobrigatóriopathstring (uuid)Número (instância) da conversa.
keyobrigatóriopathstringconversation_key da conversa.

Corpo (application/json)

CampoTipoDescrição
nameopcionalstring
json
{
  "name": "Ana Cliente"
}

Respostas

  • 201 A 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"
    }
  • 400 Pedido 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"
    }
  • 401 Sem a chave global (a chave de instância não vale aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing 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"
    }
  • 404 A 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"
    }
  • 409 O contato já existe (CONTACT_EXISTS), ou o número da conversa foi removido (INSTANCE_REMOVED).

    json
    {
      "code": "CONTACT_EXISTS",
      "error": "contact already exists"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "inbox operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "inbox storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
instanceIdobrigatóriopathstring (uuid)Número (instância) da conversa.
keyobrigatóriopathstringconversation_key da conversa.

Corpo (application/json)

CampoTipoDescrição
authorobrigatóriostringId opaco de quem escreveu.
bodyobrigatóriostring
json
{
  "author": "person-123",
  "body": "Cliente pediu retorno amanhã cedo."
}

Respostas

  • 201 A 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"
    }
  • 400 Pedido inválido (code INBOX_INVALID_REQUEST).

    json
    {
      "code": "INBOX_INVALID_REQUEST",
      "error": "status must be open or resolved"
    }
  • 401 Sem a chave global (a chave de instância não vale aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 A 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"
    }
  • 409 O número da conversa foi removido da conta: o histórico é só leitura (INSTANCE_REMOVED).

    json
    {
      "code": "INSTANCE_REMOVED",
      "error": "number was removed"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "inbox operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "inbox storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
instanceIdsopcionalquerystringIds de instância separados por vírgula: só as conversas desses números (o SaaS manda os que a pessoa pode ver). Ausente = todos.
assigneeopcionalquerystringQuem está olhando: conta as abertas dele em mine.

Respostas

  • 200 Os 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
    }
  • 400 Pedido inválido (code INBOX_INVALID_REQUEST).

    json
    {
      "code": "INBOX_INVALID_REQUEST",
      "error": "instanceIds must be instance ids separated by commas"
    }
  • 401 Sem a chave global (a chave de instância não vale aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "inbox operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "inbox storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
contactIDobrigatóriopathstring (uuid)Id do contato.

Respostas

  • 200 Os 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
        }
      ]
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "contact not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
pipeline_idopcionalquerystring (uuid)Só deste funil.
stage_idopcionalquerystring (uuid)Só desta etapa.
owneropcionalquerystringSó deste responsável.
statusopcionalquery"open" | "won" | "lost"Abertos, ganhos ou perdidos; ausente = todos.
tagopcionalquerystringSó os de contato com esta tag.
qopcionalquerystringBusca no título e no nome do contato (sem caixa) e no telefone do contato.
instance_idopcionalqueryarray<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.
cursoropcionalquerystringO next_cursor da página anterior.
limitopcionalqueryintegerItens por página.

Respostas

  • 200 Uma 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"
    }
  • 400 Filtro inválido: status (invalid_status), instance_id (invalid_instance: não é UUID ou mais de 100), limit (invalid_limit) ou cursor (invalid_cursor).

    json
    {
      "code": "invalid_cursor",
      "error": "invalid cursor"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
X-WAAPI-ActoropcionalheaderstringQuem 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)

CampoTipoDescrição
contact_idopcionalstring (uuid)Contato existente. Não envie junto com phone.
currencyopcionalstring
expected_close_atopcionalstring | null (date-time)
fieldsopcionalobjectOs campos personalizados: só as chaves do esquema ativo, cada uma pelo tipo; os obrigatórios precisam vir. Fora disso, 400 field_invalid com field.
owneropcionalstring | null
phoneopcionalstringTelefone E.164 (+, espaços, -, (, ) e . são ignorados). Sem contato com ele, o contato é criado. Não envie junto com contact_id.
pipeline_idobrigatóriostring (uuid)
sourceopcional"manual" | "inbox" | "flow" | "import"
stage_idopcionalstring (uuid)Etapa aberta do funil; ausente = a primeira aberta.
titleobrigatóriostring
value_centsopcionalinteger | null (int64)
json
{
  "currency": "BRL",
  "phone": "+5511987654321",
  "pipeline_id": "3a9d1c2e-4b5f-4c6d-8e7f-9a0b1c2d3e4f",
  "title": "Plano anual",
  "value_cents": 120000
}

Respostas

  • 201 O 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
    }
  • 400 Corpo 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_phone ou invalid_stage (etapa de ganho ou de perda).

    json
    {
      "code": "invalid_contact",
      "error": "send contact_id or phone, not both"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite max_contacts do plano ao criar o contato pelo telefone (plan_limit), função crm_enabled fora do plano (plan_feature_disabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Funil inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "pipeline not found"
    }
  • 409 A etapa não é do funil (stage_not_in_pipeline).

    json
    {
      "code": "stage_not_in_pipeline",
      "error": "the stage is not in this pipeline"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
pipeline_idopcionalquerystring (uuid)
statusopcionalquery"open" | "won" | "lost"
owneropcionalquerystring
instance_idopcionalqueryarray<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.
idsopcionalquerystringIds de negócio, separados por vírgula ou repetidos (até 500).
cursoropcionalquerystringO next_cursor da página anterior.
limitopcionalqueryinteger

Respostas

  • 200 Uma página de negócios; next_cursor null 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"
    }
  • 400 Filtro, ids ou cursor inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 422 limit acima de 500 (limit_too_large) ou mais de 500 ids (too_many_ids).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
pipeline_idopcionalquerystring (uuid)
statusopcionalquery"open" | "won" | "lost"
owneropcionalquerystring
instance_idopcionalqueryarray<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

  • 200 O CSV.

    json
    string
  • 400 Acima de 50.000 linhas (export_too_large) ou filtro inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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

bash
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)

CampoTipoDescrição
dealsobrigatórioarray<any>
deals[].closed_atopcionalstring | null (date-time)
deals[].contactopcionalobject | null
deals[].contact.idopcionalstring
deals[].contact.nameopcionalstring
deals[].contact.phoneopcionalstring
deals[].created_atopcionalstring (date-time)
deals[].currencyopcionalstring
deals[].expected_close_atopcionalstring | null (date-time)
deals[].fieldsopcionalobject
deals[].idopcionalstring (uuid)
deals[].lost_reasonopcionalstring | null
deals[].notesopcionalarray<object>
deals[].notes[].actoropcionalstring
deals[].notes[].atopcionalstring (date-time)
deals[].notes[].textopcionalstring
deals[].owneropcionalstring | null
deals[].pipelineopcionalobject
deals[].pipeline.idopcionalstring
deals[].pipeline.nameopcionalstring
deals[].sourceopcionalstring
deals[].stageopcionalobject
deals[].stage.idopcionalstring
deals[].stage.kindopcional"open" | "won" | "lost"
deals[].stage.nameopcionalstring
deals[].stage_entered_atopcionalstring (date-time)
deals[].statusopcional"open" | "won" | "lost"
deals[].tasksopcionalarray<object>
deals[].tasks[].created_atopcionalstring (date-time)
deals[].tasks[].done_atopcionalstring | null (date-time)
deals[].tasks[].due_atopcionalstring | null (date-time)
deals[].tasks[].owneropcionalstring | null
deals[].tasks[].titleopcionalstring
deals[].titleopcionalstring
deals[].updated_atopcionalstring (date-time)
deals[].value_centsopcionalinteger | null
deals[].originobrigatórioobject
deals[].origin.apiobrigatóriostringA API de origem (o SaaS dá o nome).
deals[].origin.idobrigatóriostringO id do negócio na origem.
mappingopcionalobject
mapping.pipelinesopcionalobjectId do funil de origem para o id do funil de destino.
mapping.stagesopcionalobjectId da etapa de origem para o id da etapa de destino (do funil de destino).
json
{
  "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

  • 200 O 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"
          ]
        }
      ]
    }
  • 400 Corpo inválido (invalid_body).

    json
    {
      "error": "invalid request"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 413 Mais de 500 negócios ou mais de 16 MB (batch_too_large).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.

Respostas

  • 200 O 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
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.
X-WAAPI-ActoropcionalheaderstringQuem 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)

CampoTipoDescrição
currencyopcionalstring
expected_close_atopcionalstring | null (date-time)
fieldsopcionalobjectJunta aos campos salvos; null apaga a chave (menos num obrigatório). Cada valor pelo tipo do esquema; fora disso, 400 field_invalid com field.
owneropcionalstring | null
titleopcionalstring
value_centsopcionalinteger | null (int64)
json
{
  "currency": "string",
  "expected_close_at": "2026-01-01T12:00:00Z",
  "fields": {},
  "owner": "string",
  "title": "string",
  "value_cents": 0
}

Respostas

  • 200 O 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
    }
  • 400 Corpo 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"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.

Respostas

  • 200 O 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"
        }
      ]
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.
X-WAAPI-ActoropcionalheaderstringQuem 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)

CampoTipoDescrição
reasonobrigatóriostring
json
{
  "reason": "string"
}

Respostas

  • 200 O 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
    }
  • 400 Corpo inválido (invalid_body) ou motivo vazio ou acima de 500 caracteres (invalid_reason).

    json
    {
      "code": "invalid_body",
      "error": "invalid JSON body"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 409 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.
X-WAAPI-ActoropcionalheaderstringQuem 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)

CampoTipoDescrição
positionopcionalinteger | nullPosição na coluna de destino; ausente ou além do fim = o fim.
reasonopcionalstringMotivo da perda; obrigatório quando o destino é a etapa de perda e o negócio ainda não está perdido.
stage_idobrigatóriostring (uuid)Etapa do mesmo funil (aberta, de ganho ou de perda).
json
{
  "position": 0,
  "reason": "string",
  "stage_id": "00000000-0000-4000-8000-000000000000"
}

Respostas

  • 200 O 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
    }
  • 400 Corpo inválido (invalid_body), posição negativa (invalid_position), stage_id ausente ou que não é UUID (invalid_stage), ou etapa de perda sem reason ou com mais de 500 caracteres (invalid_reason).

    json
    {
      "code": "invalid_body",
      "error": "invalid JSON body"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 409 A 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.
X-WAAPI-ActoropcionalheaderstringQuem 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)

CampoTipoDescrição
textobrigatóriostring
json
{
  "text": "string"
}

Respostas

  • 201 O 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"
    }
  • 400 Corpo inválido (invalid_body) ou texto vazio ou acima de 5000 caracteres (invalid_text).

    json
    {
      "code": "invalid_body",
      "error": "invalid JSON body"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.
X-WAAPI-ActoropcionalheaderstringQuem 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)

CampoTipoDescrição
stage_idobrigatóriostring (uuid)Etapa aberta do mesmo funil.
json
{
  "stage_id": "00000000-0000-4000-8000-000000000000"
}

Respostas

  • 200 O 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
    }
  • 400 Corpo inválido (invalid_body) ou stage_id ausente, que não é UUID ou que não é etapa aberta (invalid_stage).

    json
    {
      "code": "invalid_body",
      "error": "invalid JSON body"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 409 A 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.

Respostas

  • 200 As 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"
        }
      ]
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.
X-WAAPI-ActoropcionalheaderstringQuem 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)

CampoTipoDescrição
due_atopcionalstring | null (date-time)RFC 3339; null ou ausente = sem prazo.
owneropcionalstring | null
titleobrigatóriostringUma linha.
json
{
  "due_at": "2026-01-01T12:00:00Z",
  "owner": "string",
  "title": "string"
}

Respostas

  • 201 A 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"
    }
  • 400 Corpo 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"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 409 O negócio já tem 50 tarefas abertas (too_many_tasks).

    json
    {
      "code": "too_many_tasks",
      "error": "a deal has at most 50 open tasks"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do negócio.
X-WAAPI-ActoropcionalheaderstringQuem 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

  • 200 O 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
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Negócio inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "deal not found"
    }
  • 409 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
entityobrigatórioquery"deal" | "contact"
archivedopcionalqueryboolean

Respostas

  • 200 Os 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"
        }
      ]
    }
  • 400 entity inválida (invalid_entity).

    json
    {
      "error": "invalid request"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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

bash
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)

CampoTipoDescrição
entityobrigatório"deal" | "contact"
keyobrigatóriostring
labelobrigatóriostring
optionsopcionalarray<string>
positionopcionalinteger
requiredopcionalboolean
typeobrigatório"text" | "number" | "date" | "select" | "bool"
json
{
  "entity": "deal",
  "key": "string",
  "label": "string",
  "options": [
    "string"
  ],
  "position": 0,
  "required": false,
  "type": "text"
}

Respostas

  • 201 Criado.

    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"
    }
  • 400 Corpo inválido (invalid_key, invalid_type, invalid_label, invalid_options, invalid_entity).

    json
    {
      "error": "invalid request"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 409 Chave já usada (field_key_taken) ou 50 campos (too_many_fields).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)

Corpo (application/json)

CampoTipoDescrição
labelopcionalstring
optionsopcionalarray<string>
positionopcionalinteger
requiredopcionalboolean
json
{
  "label": "string",
  "options": [
    "string"
  ],
  "position": 0,
  "required": false
}

Respostas

  • 200 O 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"
    }
  • 400 Corpo inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Campo inexistente ou arquivado (not_found).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)

Respostas

  • 204 Arquivado.

  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Campo inexistente ou já arquivado (not_found).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

  • 200 Os 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
            }
          ]
        }
      ]
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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)

CampoTipoDescrição
nameobrigatóriostringSem espaços nas pontas.
json
{
  "name": "string"
}

Respostas

  • 201 O 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
        }
      ]
    }
  • 400 Corpo 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"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite max_pipelines do plano (plan_limit), função crm_enabled fora do plano (plan_feature_disabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do funil.

Corpo (application/json)

CampoTipoDescrição
archivedopcionalboolean | nulltrue arquiva (sai da lista; os negócios ficam); false desarquiva.
nameopcionalstring | null
positionopcionalinteger | null
json
{
  "archived": false,
  "name": "string",
  "position": 0
}

Respostas

  • 200 O 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
        }
      ]
    }
  • 400 Corpo inválido (invalid_body), nome inválido (invalid_name) ou posição negativa (invalid_position).

    json
    {
      "code": "invalid_body",
      "error": "invalid JSON body"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Desarquivar acima do limite max_pipelines do plano (plan_limit; o funil continua arquivado), função crm_enabled fora do plano (plan_feature_disabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Funil inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "pipeline not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do funil.
fromopcionalquerystringInício, RFC 3339 ou YYYY-MM-DD (UTC). Ausente = 30 dias antes de to.
toopcionalquerystringFim (exclusivo), RFC 3339 ou YYYY-MM-DD (o fim desse dia, UTC). Ausente = agora. No máximo 366 dias depois de from.
groupopcionalquery"day" | "week" | "month"Os períodos do valor ganho (a semana começa na segunda).
owneropcionalquerystringSó deste responsável.
instance_idopcionalqueryarray<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

  • 200 Os 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"
        }
      ]
    }
  • 400 Período inválido (invalid_period), group inválido (invalid_group) ou instance_id inválido (invalid_instance).

    json
    {
      "error": "invalid request"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Funil inexistente, ou id que não é UUID (not_found).

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do funil.

Corpo (application/json)

CampoTipoDescrição
coloropcionalstring
kindopcional"" | "open"Só open (ou ausente): cada funil tem uma etapa de ganho e uma de perda.
nameobrigatóriostring
json
{
  "color": "string",
  "kind": "",
  "name": "string"
}

Respostas

  • 201 A etapa criada.

    json
    {
      "color": "",
      "id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b",
      "kind": "open",
      "name": "Proposta",
      "position": 2
    }
  • 400 Corpo inválido (invalid_body), nome inválido (invalid_name), kind diferente de open (invalid_kind) ou cor acima de 32 caracteres (invalid_color).

    json
    {
      "code": "invalid_color",
      "error": "color is limited to 32 characters"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Funil inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "pipeline not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do funil.

Corpo (application/json)

CampoTipoDescrição
stage_idsobrigatórioarray<string (uuid)>Todas as etapas abertas do funil, cada uma uma vez, na ordem nova.
json
{
  "stage_ids": [
    "00000000-0000-4000-8000-000000000000"
  ]
}

Respostas

  • 200 O 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
        }
      ]
    }
  • 400 Corpo inválido (invalid_body) ou stage_ids que não é exatamente o conjunto das etapas abertas (invalid_stage_ids).

    json
    {
      "code": "invalid_body",
      "error": "invalid JSON body"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Funil inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "pipeline not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id do funil.
owneropcionalquerystringSó deste responsável.
statusopcionalquery"open" | "won" | "lost"Abertos, ganhos ou perdidos; ausente = todos.
tagopcionalquerystringSó os de contato com esta tag.
qopcionalquerystringBusca no título e no nome do contato (sem caixa) e no telefone do contato.
instance_idopcionalqueryarray<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

  • 200 As 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": {}
        }
      ]
    }
  • 400 Filtro inválido: status (invalid_status) ou instance_id (invalid_instance).

    json
    {
      "code": "invalid_instance",
      "error": "instance_id must be a number's id"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Funil inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "pipeline not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id da etapa.

Corpo (application/json)

CampoTipoDescrição
coloropcionalstring | null
nameopcionalstring | null
json
{
  "color": "string",
  "name": "string"
}

Respostas

  • 200 A etapa.

    json
    {
      "color": "",
      "id": "6f1c2b8e-2d4b-4a51-9a7e-0c1d2e3f4a5b",
      "kind": "open",
      "name": "Proposta",
      "position": 2
    }
  • 400 Corpo 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"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Etapa inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "stage not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id da etapa.
move_toopcionalquerystring (uuid)Etapa aberta do mesmo funil que recebe os negócios. Obrigatório quando a etapa tem negócios.
X-WAAPI-ActoropcionalheaderstringQuem 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

  • 204 Etapa removida.

  • 400 Etapa de ganho ou de perda (invalid_stage), ou move_to que não é etapa aberta (invalid_stage).

    json
    {
      "code": "invalid_stage",
      "error": "move_to must be an open stage"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Etapa inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "stage not found"
    }
  • 409 A etapa tem negócios e falta move_to (stage_has_deals), ou move_to nã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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
owneropcionalquerystringSó deste responsável.
statusopcionalquery"overdue" | "today" | "upcoming" | "done"
tzopcionalquerystringFuso IANA do "hoje" (por exemplo America/Sao_Paulo).
limitopcionalqueryinteger
cursoropcionalquerystringO next_cursor da página anterior.

Respostas

  • 200 Uma 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"
        }
      ]
    }
  • 400 status (invalid_status), tz (invalid_tz), limit (invalid_limit) ou cursor (invalid_cursor) inválido.

    json
    {
      "code": "invalid_status",
      "error": "status must be overdue, today, upcoming or done"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id da tarefa.
X-WAAPI-ActoropcionalheaderstringQuem 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)

CampoTipoDescrição
doneopcionalbooleantrue conclui (evento task_done), false reabre (task_reopened, dentro do limite de 50 abertas).
due_atopcionalstringRFC 3339; "" tira o prazo.
owneropcionalstring"" tira o responsável.
titleopcionalstring
json
{
  "done": false,
  "due_at": "string",
  "owner": "string",
  "title": "string"
}

Respostas

  • 200 A 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"
    }
  • 400 Corpo inválido ou vazio (invalid_body), invalid_title, invalid_due_at ou invalid_owner.

    json
    {
      "code": "invalid_body",
      "error": "nothing to change"
    }
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Tarefa inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "task not found"
    }
  • 409 Reabrir passaria de 50 tarefas abertas (too_many_tasks).

    json
    {
      "code": "too_many_tasks",
      "error": "a deal has at most 50 open tasks"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)Id da tarefa.

Respostas

  • 204 Apagada.

  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 404 Tarefa inexistente, ou id que não é UUID (not_found).

    json
    {
      "code": "not_found",
      "error": "task not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (crm_unavailable, sem detalhes do banco).

    json
    {
      "code": "crm_unavailable",
      "error": "crm operation failed"
    }
  • 503 Banco indisponível.

    json
    {
      "error": "crm storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
Last-Event-IDopcionalheaderstringO id do último evento recebido, para retomar.

Respostas

  • 200 O fluxo de eventos.

    json
    id: 42
    event: crm.deal
    data: {"type":"crm.deal","instance_id":"","data":{"deal_id":"…","pipeline_id":"…","stage_id":"…","change":"stage"}}
    
    
  • 401 Sem a chave global (a chave de instância e a de cluster não valem aqui).

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função crm_enabled fora 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"
    }
  • 429 Mais de 10 fluxos abertos com a mesma chave (too_many_streams), ou o limite de requisições.

    json
    {
      "error": "invalid request"
    }
  • 503 O tempo real não está disponível (sem banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Proxy da instância.

    json
    {
      "countries": {
        "BR": 120,
        "US": 900
      },
      "country": "BR",
      "current": "http://•••@203.0.113.10:8080",
      "enabled": true,
      "provider": "webshare.io"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
countryobrigatóriostring
json
{
  "country": "BR"
}

Respostas

  • 200 País gravado.

    json
    {
      "country": "string",
      "proxy": "string",
      "status": "string"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Proxy 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 503 Nã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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
urlobrigatóriostring
json
{
  "url": "http://usuario:senha@proxy.example.com:8080"
}

Respostas

  • 200 Em 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"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Proxy 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 503 sem a chave de cifra do servidor (secrets_key_missing) ou uso do plano ilegível (usage_unavailable).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 O 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 410 O 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
countryopcionalquerystringCódigo do país (alternativa ao campo de formulário).

Corpo (application/x-www-form-urlencoded)

CampoTipoDescrição
countryopcionalstringCódigo do país do proxy.
json
{
  "country": "BR"
}

Respostas

  • 200 Proxy trocado.

    json
    {
      "country": "string",
      "current": "string",
      "enabled": false,
      "provider": "string"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Proxy 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Não há outro IP no pool do provedor (NO_OTHER_PROXY); o proxy atual fica. Também provider_disabled sem o número por QR na instalação, ou provider_unsupported num número oficial.

    json
    {
      "code": "NO_OTHER_PROXY",
      "error": "no other valid proxy in the pool to rotate to"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Nã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

bash
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

  • 200 O provedor em uso.

    json
    {
      "api_key_last4": "9f3a",
      "plan_id": "12345",
      "provider": "webshare",
      "source": "settings",
      "updated_at": "2026-11-07T10:00:00Z"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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

bash
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)

CampoTipoDescrição
api_keyopcionalstring
plan_idopcionalstring
providerobrigatóriostring
json
{
  "api_key": "string",
  "plan_id": "string",
  "provider": "string"
}

Respostas

  • 200 Salvo; o provedor em uso.

    json
    {
      "api_key_last4": "9f3a",
      "plan_id": "12345",
      "provider": "webshare",
      "source": "settings",
      "updated_at": "2026-11-07T10:00:00Z"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 503 sem a chave de cifra do servidor (secrets_key_missing) ou o banco indisponível.

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

  • 200 O 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Destinos 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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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:

RegraMensagem
URL ausente ou em brancowebhook url is required
URL que não parseiawebhook url is invalid
Esquema diferente de https (http só em desenvolvimento)webhook url must be https
user:pass@ na URLwebhook url must not include credentials
Host vaziowebhook url host is required
Porta abaixo de 1024 que não seja a padrão do esquemawebhook 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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
targetsobrigatórioarray<object>Lista nova completa; [] remove todos os destinos. Ausente ou null = 400 invalid targets.
targets[].eventsopcionalarray | nullEventos enviados a este destino; * = todos. Vazio, null ou ausente = todos (gravado como *).
targets[].urlopcionalstring (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.
json
{
  "targets": [
    {
      "events": [
        "*"
      ],
      "url": "https://hooks.example.com/waapi"
    }
  ]
}

Respostas

  • 200 Destinos gravados (URL mascarada); secret só 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"
        }
      ]
    }
  • 400 Corpo 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Falha ao gravar (WEBHOOK_NOT_STORED): nada muda.

    json
    {
      "code": "WEBHOOK_NOT_STORED",
      "error": "webhook not updated: could not store it"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
urlopcionalstringDestino a girar; ausente ou vazio = todos.
json
{}

Respostas

  • 200 Todos os destinos do número; secret só 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"
        }
      ]
    }
  • 400 Corpo 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Número inexistente, ou nenhum destino com essa url (ou nenhum destino) (WEBHOOK_NOT_FOUND).

    json
    {
      "code": "WEBHOOK_NOT_FOUND",
      "error": "webhook destination not found"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Falha ao gravar (WEBHOOK_NOT_STORED): nada muda.

    json
    {
      "code": "WEBHOOK_NOT_STORED",
      "error": "webhook not updated: could not store it"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
urlobrigatóriostringDestino gravado, como gravado ou mascarado como veio do GET.
json
{
  "url": "https://hooks.example.com/w?client=%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2"
}

Respostas

  • 200 O teste foi feito. ok só com resposta 2xx do receptor; status = código HTTP do receptor ou 0 quando nada respondeu; error vazio 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
    }
  • 400 Corpo ilegível ou sem url (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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Número inexistente (not found), ou nenhum destino gravado com essa url (WEBHOOK_TARGET_NOT_FOUND).

    json
    {
      "code": "WEBHOOK_TARGET_NOT_FOUND",
      "error": "webhook destination not found"
    }
  • 410 O 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"
    }
  • 429 Limite próprio do teste: no máximo 6 testes por número em qualquer minuto (WEBHOOK_TEST_RATE_LIMITED, com Retry-After em 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Configuraçã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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
account_idobrigatóriostring
api_tokenobrigatóriostringToken de acesso de um usuário/agente do Chatwoot. Valor mascarado (como veio do GET) mantém o gravado.
base_urlobrigatóriostringURL do Chatwoot (a barra final é removida).
enabledopcionalboolean
inbox_idopcionalstringCaixa existente a usar; vazio reaproveita a gravada ou cria uma nova.
inbox_nameopcionalstring
source_nameopcionalstring
webhook_tokenopcionalstringCredencial de /webhooks/chatwoot; vazio = gerado pela API. Valor mascarado mantém o gravado.
json
{
  "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

  • 200 Configuraçã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"
    }
  • 400 Faltam base_url, account_id ou api_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 outra base_url ou account_id (MASKED_SECRET_NEW_DESTINATION; nada muda).

    json
    {
      "error": "base_url, account_id and api_token required"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Nã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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Removida.

    json
    {
      "status": "string"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
limitopcionalqueryintegerMáximo de linhas (padrão 50; valor inválido ou <= 0 vira 50).
statusopcionalquerystringFiltra por status exato (ex. success, error, skipped).

Respostas

  • 200 Linhas 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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Caixa apagada.

    json
    {
      "status": "string"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
limitopcionalqueryintegerMáximo de linhas (padrão 50; valor inválido ou <= 0 vira 50).
statusopcionalquerystringFiltra por status exato (sent, scheduled, ignored, blocked, error).

Respostas

  • 200 Linhas 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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
tokenopcionalquerystringwebhook_token da integração (ou use o header X-Chatwoot-Token).
X-Chatwoot-TokenopcionalheaderstringAlternativa à query token.

Corpo (application/json)

CampoTipoDescrição
attachmentsopcionalarray | null
attachments[].data_urlopcionalstring
attachments[].file_nameopcionalstring
attachments[].file_typeopcionalstring
attachments[].idopcionalinteger
attachments[].thumb_urlopcionalstring
contentopcionalstring | null
content_attributesopcionalobject | null
conversationopcionalobject
conversation.contact_inboxopcionalobject
conversation.contact_inbox.source_idopcionalstring
conversation.idopcionalinteger
conversation.inbox_idopcionalinteger
conversation.metaopcionalobject
conversation.meta.senderopcionalobject
conversation.meta.sender.emailopcionalstring
conversation.meta.sender.identifieropcionalstring
conversation.meta.sender.nameopcionalstring
conversation.meta.sender.phone_numberopcionalstring
conversation.statusopcionalstring
eventopcionalstring
message_typeopcionalstring
senderopcionalobject
sender.emailopcionalstring
sender.identifieropcionalstring
sender.nameopcionalstring
sender.phone_numberopcionalstring
json
{
  "content": "Olá, como posso ajudar?",
  "conversation": {
    "id": 42,
    "inbox_id": 7,
    "meta": {
      "sender": {
        "phone_number": "+5511999990000"
      }
    }
  },
  "event": "message_created",
  "message_type": "outgoing"
}

Respostas

  • 200 Evento tratado.

    json
    {
      "error": "Tenant suspended. Contact support.",
      "status": "blocked"
    }
  • 400 Corpo ilegível (invalid body), JSON inválido (invalid json) ou sem telefone (missing source_id).

    json
    {
      "error": "invalid request"
    }
  • 401 Token ausente (missing token), integração inexistente ou desligada, ou token errado (unauthorized).

    json
    {
      "error": "invalid request"
    }
  • 404 Caixa sem instância (inbox not mapped).

    json
    {
      "error": "invalid request"
    }
  • 413 Corpo acima de 1 MiB (body too large); um tamanho declarado maior é recusado sem ler.

    json
    {
      "error": "body too large"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Não foi possível conferir o token; tente de novo.

    json
    {
      "error": "token check unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
statusopcionalquery"pending" | "sending" | "completed" | "failed" | "cancelled"
limitopcionalqueryintegerPágina (1–200; fora disso vira 50).
offsetopcionalqueryintegerDeslocamento (negativo vira 0).

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID da instância (UUID; outro formato = 400 invalid UUID filter).

Corpo (application/json)

CampoTipoDescrição
statusopcionalstringStatus separados por vírgula; vazio = failed,cancelled.
json
{
  "status": "failed,cancelled"
}

Respostas

  • 200 Quantidade de jobs devolvidos à fila.

    json
    {
      "retried": 0
    }
  • 400 ID que não é UUID (invalid UUID filter) ou JSON inválido (invalid retry-all request).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled) ou conta suspensa/cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "string",
      "error": "string",
      "feature": "string"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
job_idobrigatóriopathstringID do job.

Respostas

  • 200 Job cancelado.

    json
    {
      "job_id": "string",
      "status": "string"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Conta 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:false ou 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
job_idobrigatóriopathstringID do job.

Respostas

  • 200 Job de volta à fila.

    json
    {
      "job_id": "string",
      "status": "string"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled) ou conta suspensa/cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "string",
      "error": "string",
      "feature": "string"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 410 O 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

  • 200 Clusters (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"
      }
    ]
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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)

CampoTipoDescrição
nameobrigatóriostring
json
{
  "name": "Atendimento"
}

Respostas

  • 201 Cluster 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"
    }
  • 400 name ausente ({"error":"name required"}).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite do plano max_clusters atingido (plan_limit) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
revealopcionalquery"1"1 devolve a api_key completa.

Respostas

  • 200 O 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.

Respostas

  • 200 Apagado.

    json
    {
      "status": "deleted"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
event_typeopcionalquerystringFiltro exato, ex. cluster.member.added.
searchopcionalquerystringBusca (ILIKE) no evento e no payload.
limitopcionalqueryintegerItens por página (inteiro > 0; inválido vale 50).
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
dashboard_urlopcionalstring
json
{
  "dashboard_url": "https://painel.example.com"
}

Respostas

  • 200 Atualizado.

    json
    {
      "status": "updated"
    }
  • 400 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
error_notification_emailopcionalstringVazio desliga o canal.
error_notification_urlopcionalstringVazio desliga o canal.
json
{
  "error_notification_email": "ops@example.com",
  "error_notification_url": "https://hooks.example.com/waapi/alerts"
}

Respostas

  • 200 Atualizado.

    json
    {
      "status": "updated"
    }
  • 400 URL 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
instance_idopcionalquerystring (uuid)Filtra por instância.
categoryopcionalquery"client" | "rate_limit" | "reachout" | "auth" | "network" | "server" | "unknown" | "billing"
severityopcionalquery"critical" | "error" | "warning"
searchopcionalquerystringBusca (ILIKE) em evento, mensagem, categoria e payload.
limitopcionalqueryintegerItens por página (inteiro > 0; inválido vale 50).
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.

Respostas

  • 200 Membros, 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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Falha ao ler a pausa do plano dos membros.

    json
    {
      "error": "could not read the members"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
instance_idobrigatóriostring (uuid)
json
{
  "instance_id": "9b2f4c1e-3a5d-4e7f-8a1b-2c3d4e5f6a7b"
}

Respostas

  • 200 Incluído.

    json
    {
      "status": "added"
    }
  • 400 instance_id ausente (instance_id required) ou instância inexistente (instance not found).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite do plano max_cluster_members atingido (plan_limit) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
idobrigatóriopathstring (uuid)ID da instância membro.

Respostas

  • 200 Removido.

    json
    {
      "status": "removed"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Só 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})"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
idobrigatóriopathstring (uuid)ID da instância membro.

Corpo (application/json)

CampoTipoDescrição
pausedopcionalboolean
json
{
  "paused": true
}

Respostas

  • 200 Atualizado.

    json
    {
      "paused": false,
      "status": "string"
    }
  • 400 Corpo inválido (paused required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ao retomar (paused: false ou 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})"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
idobrigatóriopathstring (uuid)ID da instância membro.

Corpo (application/json)

CampoTipoDescrição
secondsopcionalintegerSegundos; negativo vira 0.
json
{
  "seconds": 3600
}

Respostas

  • 200 Atualizado. reachout_cooldown_seconds ecoa o valor enviado.

    json
    {
      "reachout_cooldown_seconds": 0,
      "status": "string"
    }
  • 400 Corpo inválido (seconds required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Só 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})"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
instance_idopcionalquerystring (uuid)Só as de um membro.
directionopcionalquery"inbound" | "outbound"
sourceopcionalquerystringOrigem, ex. cluster, api, whatsapp.
searchopcionalquerystringBusca (sem diferenciar maiúsculas) em corpo, remetente, origem e conversa.
limitopcionalqueryintegerItens por página (inteiro > 0; inválido vale 50).
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 instance_id não é membro ativo do cluster (instance not in cluster), ou chave de cliente sem o escopo numbers ou com membro do cluster fora da lista dela (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 503 Não foi possível conferir a chave de cliente; tente de novo.

    json
    {
      "error": "client key check unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.

Respostas

  • 200 Middlewares.

    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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
configopcionalobject | objectPadrão {}.
enabledopcionalboolean
positionopcionalintegerNegativo vira 0.
typeobrigatóriostring
json
{
  "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

  • 201 Middleware criado (a api_key da config volta 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"
    }
  • 400 type ausente (type required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função do plano ai_rewrite_enabled desligada (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
midobrigatóriopathstring (uuid)ID do middleware.

Corpo (application/json)

CampoTipoDescrição
configopcionalobjectMesclada à configuração atual.
enabledopcionalboolean
positionopcionalinteger
json
{
  "enabled": false
}

Respostas

  • 200 Atualizado.

    json
    {
      "status": "updated"
    }
  • 400 Corpo inválido (invalid body), ou outra base_url, provider ou format com a api_key mascarada 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."
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função do plano ai_rewrite_enabled desligada (plan_feature_disabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED) numa alteração que não desliga o middleware (enabled: false passa).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
midobrigatóriopathstring (uuid)ID do middleware.

Respostas

  • 200 Removido.

    json
    {
      "status": "deleted"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
modeobrigatóriostringrandom ou warmer_pairs; outro valor é gravado e tratado como random.
json
{
  "mode": "random"
}

Respostas

  • 200 Atualizado.

    json
    {
      "mode": "random",
      "status": "updated"
    }
  • 400 mode ausente (mode required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
statusopcionalquery"pending" | "sending" | "completed" | "failed" | "cancelled"
limitopcionalqueryinteger1–200; fora disso vale 50.
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
instance_idopcionalstring (uuid)Só jobs que pediram ou já tentaram esta instância.
statusopcionalstringEstados separados por vírgula; padrão failed,cancelled.
json
{
  "instance_id": "00000000-0000-4000-8000-000000000000",
  "status": "failed,cancelled"
}

Respostas

  • 200 Quantidade reenfileirada.

    json
    {
      "retried": 3
    }
  • 400 JSON inválido (invalid retry-all request) ou instance_id não é UUID (invalid UUID filter).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função queue_enabled fora do plano ou conta suspensa (ACCOUNT_SUSPENDED).

    json
    {
      "code": "string",
      "error": "string",
      "feature": "string"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
job_idobrigatóriopathstring (uuid)ID do job de envio.

Respostas

  • 200 O job (com attempts, last_error e message_id quando 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
job_idobrigatóriopathstring (uuid)ID do job de envio.

Respostas

  • 200 Cancelado.

    json
    {
      "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "status": "cancelled"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Job em estado que não permite cancelar (job not found or cannot be cancelled). Também provider_disabled sem o número por QR na instalação, ou provider_unsupported num número oficial.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
job_idobrigatóriopathstring (uuid)ID do job de envio.

Respostas

  • 200 Reenfileirado.

    json
    {
      "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "status": "retrying"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função queue_enabled fora do plano ou conta suspensa (ACCOUNT_SUSPENDED).

    json
    {
      "code": "string",
      "error": "string",
      "feature": "string"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Job em estado que não permite reenvio (job not found or cannot be retried). Também provider_disabled sem o número por QR na instalação, ou provider_unsupported num número oficial.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
secondsopcionalintegerSegundos; negativo vira 0.
json
{
  "seconds": 3600
}

Respostas

  • 200 Atualizado. reachout_cooldown_seconds ecoa o valor enviado.

    json
    {
      "reachout_cooldown_seconds": 0,
      "status": "string"
    }
  • 400 Corpo inválido (seconds required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
bodyobrigatóriostring
fromobrigatóriostringTelefone ou JID do remetente.
instance_idopcionalstring (uuid)Membro que deve receber; sem ele, o modo do cluster escolhe.
json
{
  "body": "Oi, quero saber do meu pedido.",
  "from": "5511999990000"
}

Respostas

  • 200 Mensagem ingerida.

    json
    {
      "instance_id": "9b2f4c1e-3a5d-4e7f-8a1b-2c3d4e5f6a7b",
      "message_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "status": "received"
    }
  • 400 from ou body ausente (from and body required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 instance_id pedido não é membro ativo do cluster (instance not in cluster).

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 422 Um middleware bloqueou a mensagem (blocked by middleware), ex. ai_rewrite com on_failure = block.

    json
    {
      "error": "blocked by middleware"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 503 Nenhum membro disponível (no available instance in cluster) ou cluster degradado (cluster is temporarily degraded, try again later).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.
searchopcionalquerystringBusca (ILIKE) no destinatário.
limitopcionalqueryinteger1–200; fora disso vale 50.
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (uuid)ID do cluster. Com a chave global, um cluster inexistente responde 404 cluster not found; com uma chave de cluster, 401.

Respostas

  • 200 Nova chave (completa).

    json
    {
      "api_key": "3f1c0a9e7b2d4c6f8a1e5d7c9b3a2f4e6d8c0b1a3e5f7d9c"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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:

  1. instance_id pedido, 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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
bodyobrigatóriostring
instance_idopcionalstring (uuid)Membro preferido; se indisponível ou falhar, outro membro é tentado.
toobrigatóriostringTelefone (com DDI) ou JID do destinatário.
json
{
  "body": "Olá! Seu pedido foi enviado.",
  "to": "5511999990000"
}

Respostas

  • 202 Job criado na fila do cluster.

    json
    {
      "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "status": "pending"
    }
  • 400 to ou body ausente (to and body required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite do plano (max_messages_per_month ou max_cluster_send_jobs; max_clusters num 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 escopo numbers ou com membro do cluster fora da lista dela (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 422 Um middleware bloqueou a mensagem (blocked by middleware), ex. ai_rewrite com on_failure = block.

    json
    {
      "error": "blocked by middleware"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Nã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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
captionopcionalstring
fileopcionalstringArquivo enviado. Use este ou file_url.
file_urlopcionalstring (uri)URL pública baixada pelo servidor (validada contra destinos internos).
instance_idopcionalstring (uuid)
toobrigatóriostring
typeopcional"image" | "video" | "audio" | "document"Padrão deduzido do MIME do arquivo.
json
{
  "caption": "string",
  "file": "string",
  "file_url": "https://example.com",
  "instance_id": "00000000-0000-4000-8000-000000000000",
  "to": "string",
  "type": "image"
}

Respostas

  • 202 Job criado na fila do cluster.

    json
    {
      "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "status": "pending"
    }
  • 400 to ausente, ou sem file nem file_url (MEDIA_INVALID_INPUT).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite do plano (max_messages_per_month, max_cluster_send_jobs ou, só na mídia, max_storage_mb; max_clusters num 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 escopo numbers ou 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 413 Arquivo 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"
    }
  • 422 Um 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Falha nossa ao guardar a mídia (MEDIA_PREPARE_FAILED) ou ao criar o job.

    json
    {
      "error": "invalid request"
    }
  • 503 Nã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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
bodyobrigatóriostring
instance_idopcionalstring (uuid)
quoted_message_idobrigatóriostringID da mensagem citada no WhatsApp.
quoted_senderobrigatóriostringRemetente da mensagem citada.
toobrigatóriostring
json
{
  "body": "Combinado, obrigado!",
  "instance_id": "9b2f4c1e-3a5d-4e7f-8a1b-2c3d4e5f6a7b",
  "quoted_message_id": "3EB0A1B2C3D4E5F6A7B8",
  "quoted_sender": "5581988887777",
  "to": "5581988887777"
}

Respostas

  • 202 Job criado na fila do cluster.

    json
    {
      "job_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "status": "pending"
    }
  • 400 Campo obrigatório ausente (to, body, quoted_message_id and quoted_sender required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite do plano (max_messages_per_month ou max_cluster_send_jobs; max_clusters num 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 escopo numbers ou com membro do cluster fora da lista dela (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 422 Um middleware bloqueou a mensagem (blocked by middleware), ex. ai_rewrite com on_failure = block.

    json
    {
      "error": "blocked by middleware"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Nã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

bash
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

CampoOndeTipoDescrição
cidobrigatóriopathstring (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)

CampoTipoDescrição
webhook_tokenopcionalstringValor mascarado (como veio da leitura) mantém o token atual.
webhook_urlopcionalstringVazio desliga o webhook.
json
{
  "webhook_token": "segredo-exemplo",
  "webhook_url": "https://hooks.example.com/waapi/cluster"
}

Respostas

  • 200 Atualizado.

    json
    {
      "status": "updated"
    }
  • 400 URL do webhook inválida ou não permitida, corpo que não é o JSON esperado (INVALID_BODY), ou webhook_token mascarado (como a leitura o devolve) com outra webhook_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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

  • 200 Aquecimentos.

    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"
      }
    ]
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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)

CampoTipoDescrição
nameobrigatóriostring
json
{
  "name": "Aquecimento chips novos"
}

Respostas

  • 201 Aquecimento 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"
    }
  • 400 name ausente ({"error":"name required"}).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função warmup_enabled fora do plano (plan_feature_disabled), plano com teto max_warmer_jobs 0 (plan_limit) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Respostas

  • 200 Aquecimento.

    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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Respostas

  • 200 Excluído.

    json
    {
      "status": "deleted"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
event_typeopcionalquerystringTipo exato do evento.
searchopcionalquerystringBusca em tipo e payload.
limitopcionalqueryintegerTamanho da página; inválido ou ≤ 0 vale 50 (sem teto).
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Aquecimento inexistente (também usado quando a consulta ao banco falha).

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
instance_idopcionalquerystring (uuid)
categoryopcionalquerystringEx.: rate_limit, reachout, auth.
severityopcionalquery"critical" | "error" | "warning"
searchopcionalquerystring
limitopcionalqueryintegerTamanho da página; inválido ou ≤ 0 vale 50 (sem teto).
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Aquecimento inexistente (também usado quando a consulta ao banco falha).

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Respostas

  • 200 Horas do dia.

    json
    {
      "heatmap": [
        {
          "hour": 0,
          "received": 0,
          "sent": 0,
          "total": 0
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Aquecimento inexistente (também usado quando a consulta ao banco falha).

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Respostas

  • 200 Membros.

    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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Corpo (application/json)

CampoTipoDescrição
instance_idobrigatóriostring (uuid)
json
{
  "instance_id": "0d1e2f3a-4b5c-4d6e-8f70-819203a4b5c6"
}

Respostas

  • 200 Adicionado.

    json
    {
      "status": "added"
    }
  • 400 instance_id ausente, instância inexistente (instance not found) ou falha ao gravar.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
idobrigatóriopathstring (uuid)ID da instância membro.

Respostas

  • 200 Removido.

    json
    {
      "status": "removed"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Só 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})"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
idobrigatóriopathstring (uuid)ID da instância membro.

Corpo (application/json)

CampoTipoDescrição
pausedopcionalboolean
json
{
  "paused": true
}

Respostas

  • 200 Atualizado.

    json
    {
      "paused": true,
      "status": "updated"
    }
  • 400 Corpo inválido ({"error":"paused required"}).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Conta suspensa ou cancelada (ACCOUNT_SUSPENDED) ao retomar (paused: false ou 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})"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O banco falhou ao gravar a pausa: nada muda; tente de novo.

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
idobrigatóriopathstring (uuid)ID da instância membro.

Corpo (application/json)

CampoTipoDescrição
secondsopcionalintegerSegundos; negativo vira 0.
json
{
  "seconds": 900
}

Respostas

  • 200 Atualizado.

    json
    {
      "reachout_cooldown_seconds": 900,
      "status": "updated"
    }
  • 400 Corpo inválido ({"error":"seconds required"}).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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})"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
instance_idopcionalquerystring (uuid)Restringe a um membro; uma instância fora do aquecimento responde 404.
directionopcionalquery"inbound" | "outbound"
sourceopcionalquerystringEx.: warmer.
searchopcionalquerystring
limitopcionalqueryintegerTamanho da página; inválido ou ≤ 0 vale 50 (sem teto).
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Aquecimento inexistente, instance_id fora do aquecimento (instance not in warmer) ou falha na consulta.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Respostas

  • 200 Etapas.

    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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Corpo (application/json)

CampoTipoDescrição
configopcionalobjectConfiguraçã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_keyopcionalstring
config.apply_on_inboundopcionalboolean
config.apply_on_outboundopcionalboolean
config.base_urlopcionalstring (uri)
config.max_tokensopcionalinteger
config.modelopcionalstring
config.on_failureopcional"passthrough" | "block"
config.promptopcionalstring
config.provideropcional"openrouter" | "custom"
config.temperatureopcionalnumber
enabledopcionalboolean
positionopcionalintegerNegativo vira 0.
typeobrigatóriostringTipo 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.
json
{
  "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

  • 201 Etapa 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"
    }
  • 400 type ausente ({"error":"type required"}).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
midobrigatóriopathstring (uuid)ID da etapa (middleware).

Corpo (application/json)

CampoTipoDescrição
configopcionalobjectConfiguraçã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_keyopcionalstring
config.apply_on_inboundopcionalboolean
config.apply_on_outboundopcionalboolean
config.base_urlopcionalstring (uri)
config.max_tokensopcionalinteger
config.modelopcionalstring
config.on_failureopcional"passthrough" | "block"
config.promptopcionalstring
config.provideropcional"openrouter" | "custom"
config.temperatureopcionalnumber
enabledopcionalboolean
positionopcionalinteger
json
{
  "enabled": false
}

Respostas

  • 200 Atualizada.

    json
    {
      "status": "updated"
    }
  • 400 Corpo inválido ({"error":"invalid body"}), ou outra base_url, provider ou format com a api_key mascarada 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."
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
midobrigatóriopathstring (uuid)ID da etapa (middleware).

Respostas

  • 200 Excluída.

    json
    {
      "status": "deleted"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
statusopcionalquery"pending" | "sending" | "completed" | "failed" | "cancelled"Filtra por um status.
limitopcionalqueryinteger1–200; fora disso vale 50.
offsetopcionalqueryinteger

Respostas

  • 200 Pá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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Corpo (application/json)

CampoTipoDescrição
instance_idopcionalstring (uuid)Só jobs em que esta instância é remetente, destinatária ou aparece numa tentativa.
statusopcionalstringStatus separados por vírgula; padrão failed,cancelled.
json
{
  "instance_id": "00000000-0000-4000-8000-000000000000",
  "status": "failed,cancelled"
}

Respostas

  • 200 Quantidade reenfileirada.

    json
    {
      "retried": 4
    }
  • 400 JSON inválido (invalid retry-all request) ou instance_id que não é UUID (invalid UUID filter).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
job_idobrigatóriopathstring (uuid)ID do job de envio.

Respostas

  • 200 Job.

    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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Aquecimento inexistente ou job que não pertence a ele.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
job_idobrigatóriopathstring (uuid)ID do job de envio.

Respostas

  • 200 Cancelado.

    json
    {
      "job_id": "3f1c2b9a-6d1e-4a0b-9c55-0a1b2c3d4e5f",
      "status": "cancelled"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).
job_idobrigatóriopathstring (uuid)ID do job de envio.

Respostas

  • 200 Reenfileirado.

    json
    {
      "job_id": "3f1c2b9a-6d1e-4a0b-9c55-0a1b2c3d4e5f",
      "status": "retrying"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Corpo (application/json)

CampoTipoDescrição
secondsopcionalintegerSegundos; negativo vira 0.
json
{
  "seconds": 900
}

Respostas

  • 200 Atualizado.

    json
    {
      "reachout_cooldown_seconds": 900,
      "status": "updated"
    }
  • 400 Corpo inválido ({"error":"seconds required"}).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Corpo (application/json)

CampoTipoDescrição
active_window_endopcionalstringHH:MM; vazio = sem janela.
active_window_startopcionalstringHH:MM; vazio = sem janela.
continuousopcionalboolean
max_messagesopcionalintegerNegativo vira 0; 0 = sem teto.
messages_per_houropcionalintegerNegativo vira 0.
json
{
  "active_window_end": "20:00",
  "active_window_start": "08:00",
  "continuous": false,
  "max_messages": 500,
  "messages_per_hour": 30
}

Respostas

  • 200 Atualizado.

    json
    {
      "status": "updated"
    }
  • 400 Corpo inválido ({"error":"invalid body"}).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Limite 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"
    }
  • 404 Aquecimento inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Respostas

  • 200 Estatí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
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Aquecimento inexistente (também usado quando a consulta ao banco falha).

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Corpo (application/json)

CampoTipoDescrição
statusobrigatório"active" | "paused" | "stopped"
json
{
  "status": "active"
}

Respostas

  • 200 Status trocado.

    json
    {
      "status": "updated",
      "warmer_status": "active"
    }
  • 400 status ausente (status required) ou inválido (invalid status).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Pedido de active com warmup_enabled fora do plano (plan_feature_disabled), no teto max_warmer_jobs (plan_limit) ou com a conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 O 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

bash
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

CampoOndeTipoDescrição
widobrigatóriopathstring (uuid)ID do aquecimento. Inexistente responde 404 {"error":"warmer not found"} antes das checagens da própria rota (plano, corpo).

Respostas

  • 200 Baldes por hora.

    json
    {
      "timeline": [
        {
          "bucket": "2026-01-01T12:00:00Z",
          "bucket_text": "14:00",
          "received": 0,
          "sent": 0,
          "total": 0
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 404 Aquecimento inexistente (também usado quando a consulta ao banco falha).

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
curl -X GET "$API_URL/api/v1/warmers/<wid>/timeline" \
  -H "Authorization: Bearer $API_KEY"

Contatos e tags

A base de contatos do Marketing: importação, tags e opt-out.

get/api/v1/marketing/contactsLista contatosChave de API

Paginação por cursor (ordem por ID).

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
tagopcionalquerystringSó contatos com esta tag.
qopcionalquerystringPrefixo do nome (sem caixa) ou do telefone.
optedOutopcionalquery"true" | "false"true = só revogados; false = só com consentimento.
cursoropcionalquerystring (uuid)Cursor opaco: o nextCursor da página anterior.
limitopcionalqueryintegerItens por página.

Respostas

  • 200 Página de contatos (ordem por ID).

    json
    {
      "contacts": [
        {
          "consent_last_event_at": null,
          "consent_last_event_reason": null,
          "created_at": "2026-10-01T12:00:00Z",
          "fields": {
            "cidade": "Recife"
          },
          "id": "c0a8012e-0000-4000-8000-000000000001",
          "name": "Maria",
          "opted_out_at": null,
          "opted_out_reason": null,
          "optout_only": false,
          "phone_e164": "5511999990000",
          "tags": [
            "clientes"
          ],
          "updated_at": "2026-10-01T12:00:00Z"
        }
      ],
      "nextCursor": "string"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X GET "$API_URL/api/v1/marketing/contacts" \
  -H "Authorization: Bearer $API_KEY"
get/api/v1/marketing/contacts/exportExporta os contatos com o consentimentoSó a chave da plataforma

A exportação dos contatos para outra API, a que o job de cópia do SaaS lê, por cursor, em ordem de telefone. Cada contato vai com o telefone, o nome, os campos, as tags com a cor (tags_detail), o opt-out (opted_out_at, opted_out_reason) e o último evento de consentimento, lidos do registro de opt-out. Os telefones que saíram sem ser contato também vão, com id null e optout_only true, para o destino nunca mandar mensagem a quem saiu. Aceita os filtros da lista (tag, q, optedOut; um telefone sem contato só sai sem tag e sem optedOut=false) ou ids para exportar um a um. Importe com POST /marketing/contacts/import, mandando o opt-out de cada linha. Só a chave global: uma chave de cliente recebe 403 CLIENT_KEY_SCOPE.

Chave: só a chave da plataforma, que fica com a equipe da plataforma. A sua chave de API recebe 403 (ou 401).

Parâmetros

CampoOndeTipoDescrição
tagopcionalquerystring
qopcionalquerystringPrefixo do nome (sem caixa) ou do telefone.
optedOutopcionalquery"true" | "false"
idsopcionalquerystringIds de contato, separados por vírgula ou repetidos (até 500).
cursoropcionalquerystringO nextCursor da página anterior.
limitopcionalqueryinteger

Respostas

  • 200 Uma página de contatos; nextCursor null na última.

    json
    {
      "contacts": [
        {
          "consent_last_event_at": null,
          "consent_last_event_reason": null,
          "created_at": "2026-10-01T12:00:00Z",
          "fields": {
            "cidade": "Recife"
          },
          "id": "string",
          "name": "Maria",
          "opted_out_at": null,
          "opted_out_reason": null,
          "optout_only": false,
          "phone_e164": "5511999990000",
          "tags": [
            "clientes"
          ],
          "updated_at": "2026-10-01T12:00:00Z"
        }
      ],
      "nextCursor": "string"
    }
  • 400 Filtro, ids ou cursor inválido (invalid_ids, invalid_cursor, invalid_limit).

    json
    {
      "error": "invalid request"
    }
  • 401 Sem a chave global.

    json
    {
      "error": "invalid request"
    }
  • 403 Uma chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 422 limit acima de 1000 (limit_too_large) ou mais de 500 ids (too_many_ids).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
curl -X GET "$API_URL/api/v1/marketing/contacts/export" \
  -H "Authorization: Bearer $API_KEY"
post/api/v1/marketing/contacts/importImporta contatosChave de API

Até 5000 linhas por pedido. Telefones são normalizados para E.164; linhas inválidas ou repetidas no arquivo vão para discarded sem falhar o pedido. Contato existente é atualizado (nome, campos mesclados, tags somadas) e não consome max_contacts. Opt-outs já registrados para o telefone continuam valendo.

Chave: chave da plataforma, chave de API (wck_...)

Corpo (application/json)

CampoTipoDescrição
defaultCountryopcionalstringDDI para números nacionais.
rowsobrigatórioarray<object>
rows[].consent_last_event_atopcionalstring | null (date-time)O último evento de consentimento da origem. Só com opted_out_at.
rows[].consent_last_event_reasonopcionalstring | nullO motivo do último evento. Só com opted_out_at.
rows[].fieldsopcionalobjectCampos livres (qualquer JSON por chave; até 100 chaves de até 100 bytes). Mesclados aos existentes (chave a chave).
rows[].nameopcionalstring | nullAusente/null mantém o nome atual.
rows[].opted_out_atopcionalstring | null (date-time)O opt-out da origem: grava o opt-out deste telefone, mantendo a data mais antiga entre a da origem e a do destino. Uma linha sem opt-out nunca apaga o opt-out do destino.
rows[].opted_out_reasonopcionalstring | nullO motivo do opt-out (padrão import). Só com opted_out_at.
rows[].optout_onlyopcionalbooleanUm telefone que saiu sem ser contato: grava só o opt-out, sem perfil e sem ocupar vaga do plano. Exige opted_out_at.
rows[].phoneopcionalstringTelefone livre (dígitos, espaços e +()-./). + ou 00 = internacional; senão usa defaultCountry. No Brasil, DDD é validado e o 9º dígito é inserido em celulares de 8 dígitos.
rows[].tagsopcionalarray<object>As tags desta linha, com a cor (o tags_detail da exportação). Uma tag que não existe é criada com a cor dada (gray sem cor); uma que existe mantém a dela.
rows[].tags[].colorobrigatório"gray" | "red" | "orange" | "amber" | "green" | "teal" | "blue" | "indigo" | "violet" | "pink" | "brown" | "black"Cor da tag, da paleta fixa. Padrão gray.
rows[].tags[].nameobrigatóriostring
tagsopcionalarray<string>Tags aplicadas a todas as linhas importadas.
json
{
  "defaultCountry": "55",
  "rows": [
    {
      "fields": {
        "cidade": "Recife"
      },
      "name": "Maria",
      "phone": "(11) 99999-0000"
    },
    {
      "phone": "+55 81 99999-0001"
    }
  ],
  "tags": [
    "clientes"
  ]
}

Respostas

  • 200 Importação concluída.

    json
    {
      "discarded": [
        {
          "reason": "invalid_ddd",
          "row": 2
        }
      ],
      "imported": 1,
      "updated": 0
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano, ou teto max_contacts atingido: neste caso as linhas que couberam FORAM gravadas e o corpo traz os contadores mais code:"plan_limit", limit:"max_contacts" (linhas recusadas com reason:"plan_limit"), ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X POST "$API_URL/api/v1/marketing/contacts/import" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"defaultCountry":"55","rows":[{"fields":{"cidade":"Recife"},"name":"Maria","phone":"(11) 99999-0000"},{"phone":"+55 81 99999-0001"}],"tags":["clientes"]}'
post/api/v1/marketing/contacts/tagsAdiciona e remove tags em loteChave de API

Seleciona por contactIds (até 5000) ou por filter (exatamente um dos dois). Tags novas em add são criadas.

Chave: chave da plataforma, chave de API (wck_...)

Corpo (application/json)

CampoTipoDescrição
addopcionalarray<string>
contactIdsopcionalarray<string (uuid)>
filteropcionalobject
filter.optedOutopcionalbooleantrue = só revogados; false = só com consentimento.
filter.qopcionalstringPrefixo do nome (sem caixa) ou do telefone. Literal: %, _ e \ não são curingas.
filter.tagopcionalstringContatos com esta tag.
removeopcionalarray<string>
json
{
  "add": [
    "clientes"
  ],
  "filter": {
    "optedOut": false,
    "tag": "leads"
  },
  "remove": [
    "leads"
  ]
}

Respostas

  • 200 Tags aplicadas.

    json
    {
      "updated": 0
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X POST "$API_URL/api/v1/marketing/contacts/tags" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add":["clientes"],"filter":{"optedOut":false,"tag":"leads"},"remove":["leads"]}'
get/api/v1/marketing/contacts/{contactID}Mostra um contatoChave de API

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
contactIDobrigatóriopathstring (uuid)ID (UUID) do contato.

Respostas

  • 200 Contato.

    json
    {
      "consent_last_event_at": null,
      "consent_last_event_reason": null,
      "created_at": "2026-10-01T12:00:00Z",
      "fields": {
        "cidade": "Recife"
      },
      "id": "c0a8012e-0000-4000-8000-000000000001",
      "name": "Maria",
      "opted_out_at": null,
      "opted_out_reason": null,
      "optout_only": false,
      "phone_e164": "5511999990000",
      "tags": [
        "clientes"
      ],
      "updated_at": "2026-10-01T12:00:00Z"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X GET "$API_URL/api/v1/marketing/contacts/<contactID>" \
  -H "Authorization: Bearer $API_KEY"
patch/api/v1/marketing/contacts/{contactID}Atualiza nome e campos do contatoChave de API

fields é mesclado aos existentes; name ausente mantém o atual. Tags e telefone não mudam aqui.

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
contactIDobrigatóriopathstring (uuid)ID (UUID) do contato.

Corpo (application/json)

CampoTipoDescrição
fieldsopcionalobjectCampos livres (qualquer JSON por chave; até 100 chaves de até 100 bytes). Mesclados aos existentes (chave a chave).
nameopcionalstring | nullAusente/null mantém o nome.
json
{
  "fields": {
    "plano": "ouro"
  },
  "name": "Maria Silva"
}

Respostas

  • 200 Contato atualizado.

    json
    {
      "consent_last_event_at": null,
      "consent_last_event_reason": null,
      "created_at": "2026-10-01T12:00:00Z",
      "fields": {
        "cidade": "Recife"
      },
      "id": "c0a8012e-0000-4000-8000-000000000001",
      "name": "Maria",
      "opted_out_at": null,
      "opted_out_reason": null,
      "optout_only": false,
      "phone_e164": "5511999990000",
      "tags": [
        "clientes"
      ],
      "updated_at": "2026-10-01T12:00:00Z"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X PATCH "$API_URL/api/v1/marketing/contacts/<contactID>" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"plano":"ouro"},"name":"Maria Silva"}'
delete/api/v1/marketing/contacts/{contactID}Apaga o contatoChave de API

Apaga também o registro de opt-out do telefone. Destinatários de campanha ficam com contactId null. Antes de apagar, as tags do contato passam a ser etiquetas (labels) das conversas da caixa de entrada com esse telefone, em todos os números (menos a conversa oculta do próprio número).

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
contactIDobrigatóriopathstring (uuid)ID (UUID) do contato.

Respostas

  • 204 Apagado.

  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X DELETE "$API_URL/api/v1/marketing/contacts/<contactID>" \
  -H "Authorization: Bearer $API_KEY"
get/api/v1/marketing/contacts/{contactID}/conversationsConversas do contatoChave de API

As conversas da caixa de entrada com o telefone do contato, em cada número, da mais recente para a mais antiga ("Abrir conversa"). Com chave de cliente restrita a alguns números, só as desses números.

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
contactIDobrigatóriopathstring (uuid)ID (UUID) do contato.

Respostas

  • 200 As conversas.

    json
    {
      "conversations": [
        {
          "assignee": "string",
          "instanceId": "00000000-0000-4000-8000-000000000000",
          "instanceRemoved": false,
          "key": "string",
          "lastMessageAt": "2026-01-01T12:00:00Z",
          "status": "open",
          "unreadCount": 0
        }
      ]
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X GET "$API_URL/api/v1/marketing/contacts/<contactID>/conversations" \
  -H "Authorization: Bearer $API_KEY"
post/api/v1/marketing/contacts/{contactID}/optinRestaura o consentimentoChave de API

Limpa o opt-out do contato e do telefone; último evento optin:manual. Sem corpo.

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
contactIDobrigatóriopathstring (uuid)ID (UUID) do contato.

Respostas

  • 200 Contato sem opt-out.

    json
    {
      "consent_last_event_at": null,
      "consent_last_event_reason": null,
      "created_at": "2026-10-01T12:00:00Z",
      "fields": {
        "cidade": "Recife"
      },
      "id": "c0a8012e-0000-4000-8000-000000000001",
      "name": "Maria",
      "opted_out_at": null,
      "opted_out_reason": null,
      "optout_only": false,
      "phone_e164": "5511999990000",
      "tags": [
        "clientes"
      ],
      "updated_at": "2026-10-01T12:00:00Z"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X POST "$API_URL/api/v1/marketing/contacts/<contactID>/optin" \
  -H "Authorization: Bearer $API_KEY"
post/api/v1/marketing/contacts/{contactID}/optoutRegistra opt-out manualChave de API

Grava a revogação com motivo manual. A primeira revogação (opted_out_at, opted_out_reason) é preservada; o último evento é atualizado. Sem corpo.

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
contactIDobrigatóriopathstring (uuid)ID (UUID) do contato.

Respostas

  • 200 Contato com o opt-out.

    json
    {
      "consent_last_event_at": null,
      "consent_last_event_reason": null,
      "created_at": "2026-10-01T12:00:00Z",
      "fields": {
        "cidade": "Recife"
      },
      "id": "c0a8012e-0000-4000-8000-000000000001",
      "name": "Maria",
      "opted_out_at": null,
      "opted_out_reason": null,
      "optout_only": false,
      "phone_e164": "5511999990000",
      "tags": [
        "clientes"
      ],
      "updated_at": "2026-10-01T12:00:00Z"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X POST "$API_URL/api/v1/marketing/contacts/<contactID>/optout" \
  -H "Authorization: Bearer $API_KEY"
get/api/v1/marketing/optout/keywordsLista as palavras de opt-outChave de API

Chave: chave da plataforma, chave de API (wck_...)

Respostas

  • 200 Palavras atuais.

    json
    {
      "keywords": [
        "sair",
        "parar",
        "cancelar"
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X GET "$API_URL/api/v1/marketing/optout/keywords" \
  -H "Authorization: Bearer $API_KEY"
put/api/v1/marketing/optout/keywordsSubstitui as palavras de opt-outChave de API

Uma mensagem recebida cujo texto inteiro, ou a primeira palavra, é uma destas palavras (normalizadas) registra opt-out do remetente.

Chave: chave da plataforma, chave de API (wck_...)

Corpo (application/json)

CampoTipoDescrição
keywordsobrigatórioarray<string>Lista completa (substitui a atual). null é recusado; [] desliga o opt-out por palavra.
json
{
  "keywords": [
    "Sair",
    "PARAR!"
  ]
}

Respostas

  • 200 Lista normalizada gravada.

    json
    {
      "keywords": [
        "sair",
        "parar",
        "cancelar"
      ]
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X PUT "$API_URL/api/v1/marketing/optout/keywords" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["Sair","PARAR!"]}'
get/api/v1/marketing/tagsLista tags com contagemChave de API

Chave: chave da plataforma, chave de API (wck_...)

Respostas

  • 200 Tags em ordem alfabética.

    json
    {
      "tags": [
        {
          "color": "green",
          "count": 42,
          "description": "Compraram pelo menos uma vez",
          "name": "clientes"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X GET "$API_URL/api/v1/marketing/tags" \
  -H "Authorization: Bearer $API_KEY"
post/api/v1/marketing/tagsCria uma tagChave de API

Idempotente: tag existente responde 200.

Chave: chave da plataforma, chave de API (wck_...)

Corpo (application/json)

CampoTipoDescrição
nameobrigatóriostringNome de tag: aparado; não vazio; até 100 caracteres; sem NUL, CR ou LF. Duplicatas são removidas.
json
{
  "name": "clientes"
}

Respostas

  • 200 Tag criada (ou já existente).

    json
    {
      "name": "string"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled) ou conta suspensa ou cancelada (ACCOUNT_SUSPENDED).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X POST "$API_URL/api/v1/marketing/tags" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"clientes"}'
delete/api/v1/marketing/tagsApaga uma tag pelo nome na queryChave de API

Mesmo comportamento de DELETE /api/v1/marketing/tags/{name}, para nomes com /. Remove a tag de todos os contatos. Tira a tag também das etiquetas das conversas sem contato da caixa de entrada, na mesma transação. Um nome que não é tag do Marketing (por exemplo, só uma etiqueta de atendimento numa conversa): 404, e nada muda.

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
nameobrigatórioquerystringNome da tag.

Respostas

  • 204 Apagada.

  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Não existe tag do Marketing com esse nome.

    json
    {
      "error": "tag not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X DELETE "$API_URL/api/v1/marketing/tags?name=<name>" \
  -H "Authorization: Bearer $API_KEY"
patch/api/v1/marketing/tags/{name}Muda a cor e a descrição de uma tagChave de API

A cor é da paleta fixa e a descrição tem até 200 caracteres. Muda só o que vier; renomear não é por aqui.

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
nameobrigatóriopathstringNome da tag (sem barra; para nomes com / use DELETE /api/v1/marketing/tags?name=).

Corpo (application/json)

CampoTipoDescrição
coloropcional"gray" | "red" | "orange" | "amber" | "green" | "teal" | "blue" | "indigo" | "violet" | "pink" | "brown" | "black"Cor da tag, da paleta fixa. Padrão gray.
descriptionopcionalstringAté 200 caracteres; chega sem espaços nas pontas.
json
{
  "color": "red",
  "description": "Pagamento em atraso"
}

Respostas

  • 200 A tag como ficou, com a contagem de contatos.

    json
    {
      "color": "gray",
      "count": 0,
      "description": "string",
      "name": "string"
    }
  • 400 Cor fora da paleta (invalid_color), descrição com mais de 200 caracteres (invalid_description) ou corpo sem color nem description (invalid_tag).

    json
    {
      "code": "invalid_color",
      "error": "color must be one of gray, red, orange, amber, green, teal, blue, indigo, violet, pink, brown, black"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Não existe tag do Marketing com esse nome.

    json
    {
      "error": "tag not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X PATCH "$API_URL/api/v1/marketing/tags/<name>" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"color":"red","description":"Pagamento em atraso"}'
delete/api/v1/marketing/tags/{name}Apaga uma tagChave de API

Remove a tag de todos os contatos. Tira a tag também das etiquetas das conversas sem contato da caixa de entrada, na mesma transação. Um nome que não é tag do Marketing (por exemplo, só uma etiqueta de atendimento numa conversa): 404, e nada muda.

Chave: chave da plataforma, chave de API (wck_...)

Parâmetros

CampoOndeTipoDescrição
nameobrigatóriopathstringNome da tag (sem barra; para nomes com / use DELETE /api/v1/marketing/tags?name=).

Respostas

  • 204 Apagada.

  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Não existe tag do Marketing com esse nome.

    json
    {
      "error": "tag not found"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
curl -X DELETE "$API_URL/api/v1/marketing/tags/<name>" \
  -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

CampoOndeTipoDescrição
cursoropcionalquerystring (uuid)Cursor opaco: o nextCursor da página anterior.
limitopcionalqueryintegerItens por página.

Respostas

  • 200 Pá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"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
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)

CampoTipoDescrição
audienceobrigatórioobjecttags e/ou crmStages (pelo menos um). Com os dois, a união: cada contato entra uma vez.
audience.crmStagesopcionalobjectOs 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óriostring (uuid)
audience.crmStages.stageIdsobrigatórioarray<string (uuid)>
audience.tagsopcionalarray<string>Contatos com qualquer uma destas tags. Pode ser vazio quando há crmStages.
defaultsopcionalobjectValor por variável quando o contato não tem o campo.
messageobrigatórioobject
message.mediaUrlopcionalstring (uri)URL http(s) obrigatória em image/video/document.
message.templateopcionalCampaignTemplateO 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_parametersopcionalarray<string>Os valores das variáveis de um cabeçalho de texto.
message.template.languageobrigatóriostringO código do idioma do template (pt_BR, en_US).
message.template.nameobrigatóriostring
message.template.namedopcionalobjectOs valores por nome, num template named ({"first_name":"Ana"}).
message.template.parametersopcionalarray<string>Os valores do corpo por posição: o 1º preenche {{1}}, e assim por diante.
message.template.buttonsopcionalarray<object>Os valores dos botões dinâmicos, pela posição do botão no template (de 0).
message.template.buttons[].indexobrigatóriointeger
message.template.buttons[].textobrigatóriostring
message.template.codeopcionalstringRecusado (400 template_authentication_campaign); o código de autenticação vai só no envio direto.
message.template.header_mediaopcionalobjectlink (https público) ou id (uma mídia já enviada à Meta), um dos dois; filename só num documento.
message.template.header_media.filenameopcionalstring
message.template.header_media.idopcionalstring
message.template.header_media.linkopcionalstring (uri)
message.textopcionalstringObrigató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óriostringNão pode ser só espaços.
ratePerMinuteopcionalintegerEnvios por minuto; acima de max_campaign_rate_per_minute dá 403 plan_limit.
scheduledAtopcionalstring | null (date-time)Início futuro: ao dar start a campanha fica scheduled até esta hora.
senderobrigatórioobjectExatamente 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.clusterIdopcionalstring (uuid)
sender.instanceIdsopcionalarray<string (uuid)>
timezoneopcionalstringFuso IANA da janela.
windowopcionalobjectJanela diária de envio (HH:MM); início e fim diferentes.
window.endopcionalstring
window.startopcionalstring
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"
  }
}

Respostas

  • 201 Campanha criada em draft.

    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"
    }
  • 400 Pedido 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_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."
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.

Respostas

  • 200 Campanha.

    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"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.

Corpo (application/json)

CampoTipoDescrição
audienceobrigatórioobjecttags e/ou crmStages (pelo menos um). Com os dois, a união: cada contato entra uma vez.
audience.crmStagesopcionalobjectOs 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óriostring (uuid)
audience.crmStages.stageIdsobrigatórioarray<string (uuid)>
audience.tagsopcionalarray<string>Contatos com qualquer uma destas tags. Pode ser vazio quando há crmStages.
defaultsopcionalobjectValor por variável quando o contato não tem o campo.
messageobrigatórioobject
message.mediaUrlopcionalstring (uri)URL http(s) obrigatória em image/video/document.
message.templateopcionalCampaignTemplateO 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_parametersopcionalarray<string>Os valores das variáveis de um cabeçalho de texto.
message.template.languageobrigatóriostringO código do idioma do template (pt_BR, en_US).
message.template.nameobrigatóriostring
message.template.namedopcionalobjectOs valores por nome, num template named ({"first_name":"Ana"}).
message.template.parametersopcionalarray<string>Os valores do corpo por posição: o 1º preenche {{1}}, e assim por diante.
message.template.buttonsopcionalarray<object>Os valores dos botões dinâmicos, pela posição do botão no template (de 0).
message.template.buttons[].indexobrigatóriointeger
message.template.buttons[].textobrigatóriostring
message.template.codeopcionalstringRecusado (400 template_authentication_campaign); o código de autenticação vai só no envio direto.
message.template.header_mediaopcionalobjectlink (https público) ou id (uma mídia já enviada à Meta), um dos dois; filename só num documento.
message.template.header_media.filenameopcionalstring
message.template.header_media.idopcionalstring
message.template.header_media.linkopcionalstring (uri)
message.textopcionalstringObrigató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óriostringNão pode ser só espaços.
ratePerMinuteopcionalintegerEnvios por minuto; acima de max_campaign_rate_per_minute dá 403 plan_limit.
scheduledAtopcionalstring | null (date-time)Início futuro: ao dar start a campanha fica scheduled até esta hora.
senderobrigatórioobjectExatamente 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.clusterIdopcionalstring (uuid)
sender.instanceIdsopcionalarray<string (uuid)>
timezoneopcionalstringFuso IANA da janela.
windowopcionalobjectJanela diária de envio (HH:MM); início e fim diferentes.
window.endopcionalstring
window.startopcionalstring
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"
  }
}

Respostas

  • 200 Campanha 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"
    }
  • 400 Pedido 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 campanha scheduled (o público é refeito), remetente sem número existente (invalid campaign sender).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.

Respostas

  • 200 Campanha 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"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.

Respostas

  • 200 Campanha 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"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.

Corpo (application/json)

CampoTipoDescrição
contactIdopcionalstring (uuid)Opcional: renderiza o texto para este contato (após o start, com o snapshot congelado).
json
{
  "contactId": "c0a8012e-0000-4000-8000-000000000001"
}

Respostas

  • 200 Prévia.

    json
    {
      "audience": {
        "eligible": 115,
        "skippedOptOut": 5,
        "total": 120
      },
      "text": "Olá Maria, oferta em Recife!"
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.
statusopcionalquery"pending" | "sent" | "delivered" | "read" | "failed" | "skipped_optout" | "skipped_duplicate"Filtra por status.
cursoropcionalquerystring (uuid)Cursor opaco: o nextCursor da página anterior.
limitopcionalqueryintegerItens por página.

Respostas

  • 200 Pá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"
        }
      ]
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.
cursoropcionalquerystring (uuid)Cursor opaco: o nextCursor da página anterior.
limitopcionalqueryintegerItens por página.

Respostas

  • 200 Relató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"
        }
      }
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.

Respostas

  • 200 Campanha 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"
    }
  • 400 Pedido 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled), campanha pausada pelo plano que não cabe mais em max_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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.

Respostas

  • 200 Campanha 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"
    }
  • 400 Pedido 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_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."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Conflito com o estado atual.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) da campanha.

Respostas

  • 200 Estatí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"
      }
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
monthopcionalquerystringMês AAAA-MM (UTC); padrão: mês atual.

Respostas

  • 200 Resumo.

    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
    }
  • 400 Pedido inválido (JSON malformado, campo desconhecido, valor fora dos limites ou ID inválido).

    json
    {
      "error": "invalid marketing request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Marketing fora do plano (plan_feature_disabled, feature marketing_enabled).

    json
    {
      "code": "plan_feature_disabled",
      "error": "Feature not included in your plan: marketing_enabled.",
      "feature": "marketing_enabled"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
statusopcionalquery"draft" | "active" | "paused"
cursoropcionalquerystring (uuid)nextCursor da página anterior (UUID).
limitopcionalqueryinteger

Respostas

  • 200 Pá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"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco de marketing indisponível.

    json
    {
      "error": "marketing storage unavailable"
    }

Exemplo

bash
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)

CampoTipoDescrição
graphopcionalobjectGrafo do editor, guardado como enviado (JSONB). Até 500 nós e 2.000 arestas; listas vazias valem.
graph.edgesobrigatórioarray<object>
graph.edges[].idobrigatóriostring
graph.edges[].sourceobrigatóriostring
graph.edges[].sourceHandleopcionalstring | null
graph.edges[].targetobrigatóriostring
graph.nodesobrigatórioarray<object>
graph.nodes[].dataopcionalobject | null
graph.nodes[].idobrigatóriostring
graph.nodes[].positionopcionalobject
graph.nodes[].position.xopcionalnumber
graph.nodes[].position.yopcionalnumber
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" | stringUm dos tipos de FlowNodeType; outro valor é aceito no salvamento e recusado no publish (unknown_node_type).
nameobrigatóriostring1–200 caracteres após aparar espaços.
ratePerMinuteopcionalintegerEnvios por minuto, por remetente. Teto: max_campaign_rate_per_minute do plano.
senderopcionalobjectRemetente: 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.clusterIdopcionalstring (uuid)
sender.instanceIdsopcionalarray<string (uuid)>
triggeropcionalobjectGatilho. 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.configopcionalobject
trigger.config.campaignIdsopcionalarray<string (uuid)>
trigger.config.cooldownHoursopcionalinteger
trigger.config.fromStageIdsopcionalarray<string (uuid)>
trigger.config.keywordsopcionalarray<string>
trigger.config.matchopcional"exact" | "contains"
trigger.config.pipelineIdopcionalstring (uuid)
trigger.config.stageIdsopcionalarray<string (uuid)>
trigger.config.withinHoursopcionalinteger
trigger.typeobrigatório"message" | "keyword" | "campaign_reply" | "webhook" | "deal_stage_changed" | "manual"
json
{
  "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

  • 201 Rascunho 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"
      }
    }
  • 400 Pedido 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_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 escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Respostas

  • 200 Fluxo.

    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"
      }
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Corpo (application/json)

CampoTipoDescrição
graphopcionalobjectGrafo do editor, guardado como enviado (JSONB). Até 500 nós e 2.000 arestas; listas vazias valem.
graph.edgesobrigatórioarray<object>
graph.edges[].idobrigatóriostring
graph.edges[].sourceobrigatóriostring
graph.edges[].sourceHandleopcionalstring | null
graph.edges[].targetobrigatóriostring
graph.nodesobrigatórioarray<object>
graph.nodes[].dataopcionalobject | null
graph.nodes[].idobrigatóriostring
graph.nodes[].positionopcionalobject
graph.nodes[].position.xopcionalnumber
graph.nodes[].position.yopcionalnumber
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" | stringUm dos tipos de FlowNodeType; outro valor é aceito no salvamento e recusado no publish (unknown_node_type).
nameopcionalstring
ratePerMinuteopcionalinteger
revisionopcionalintegerRevisão esperada (trava otimista).
senderopcionalobjectRemetente: 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.clusterIdopcionalstring (uuid)
sender.instanceIdsopcionalarray<string (uuid)>
triggeropcionalobjectGatilho. 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.configopcionalobject
trigger.config.campaignIdsopcionalarray<string (uuid)>
trigger.config.cooldownHoursopcionalinteger
trigger.config.fromStageIdsopcionalarray<string (uuid)>
trigger.config.keywordsopcionalarray<string>
trigger.config.matchopcional"exact" | "contains"
trigger.config.pipelineIdopcionalstring (uuid)
trigger.config.stageIdsopcionalarray<string (uuid)>
trigger.config.withinHoursopcionalinteger
trigger.typeobrigatório"message" | "keyword" | "campaign_reply" | "webhook" | "deal_stage_changed" | "manual"
json
{
  "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

  • 200 Fluxo 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"
      }
    }
  • 400 Pedido 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_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 escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 A revisão enviada não é a atual (revision_conflict).

    json
    {
      "code": "revision_conflict",
      "error": "flow revision changed",
      "revision": 4
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.
forceopcionalquery"true" | "false"

Respostas

  • 204 Apagado.

  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O fluxo tem execuções ativas (flow_has_active_runs).

    json
    {
      "activeRuns": 3,
      "code": "flow_has_active_runs",
      "error": "flow has active runs"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Corpo (application/json)

CampoTipoDescrição
nameopcionalstringPadrão "<nome> (cópia)".
json
{
  "name": "string"
}

Respostas

  • 201 Rascunho 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"
      }
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_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 escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Respostas

  • 200 Fluxo.

    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"
      }
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O fluxo nunca foi publicado (flow_not_published).

    json
    {
      "code": "flow_not_published",
      "error": "flow is not published"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Respostas

  • 200 Fluxo 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"
      }
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_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 escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 422 O 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"
        }
      ]
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Respostas

  • 200 Fluxo.

    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"
      }
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_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 escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O fluxo nunca foi publicado (flow_not_published).

    json
    {
      "code": "flow_not_published",
      "error": "flow is not published"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Respostas

  • 200 Registro.

    json
    {
      "logs": [
        {
          "at": "2026-10-29T21:00:00Z",
          "bytes": 96,
          "error": null,
          "runId": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b",
          "status": 202
        }
      ]
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Respostas

  • 200 Token novo.

    json
    {
      "path": "/api/v1/hooks/flows/fwh_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "rotatedAt": "2026-10-29T17:00:00Z",
      "token": "fwh_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_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 escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
runIDobrigatóriopathstring (uuid)ID (UUID) da execução. Inválido → 400.

Respostas

  • 200 Execução com steps em 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"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
runIDobrigatóriopathstring (uuid)ID (UUID) da execução. Inválido → 400.

Respostas

  • 200 Execuçã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"
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 A execução já terminou (run_not_active).

    json
    {
      "code": "run_not_active",
      "error": "run is not active",
      "status": "completed"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.
statusopcionalquery"running" | "waiting" | "completed" | "failed" | "cancelled"
cursoropcionalquerystring (uuid)nextCursor da página anterior (UUID).
limitopcionalqueryinteger

Respostas

  • 200 Pá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"
        }
      ]
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Corpo (application/json)

CampoTipoDescrição
contactIdsopcionalarray<string (uuid)>
tagopcionalstringInicia para os contatos com a tag (até 10.000).
json
{
  "contactIds": [
    "3b8e6f0a-1c2d-4e5f-8a9b-0c1d2e3f4a5b"
  ]
}

Respostas

  • 200 Resultado do início.

    json
    {
      "skipped": [
        {
          "contactId": "3b8e6f0a-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
          "reason": "already_running"
        }
      ],
      "started": 2
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_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 escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "ACCOUNT_SUSPENDED",
      "error": "Tenant suspended. Contact support."
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O fluxo não está ativo (flow_not_active).

    json
    {
      "code": "flow_not_active",
      "error": "flow is not active"
    }
  • 422 A tag tem mais de 10.000 contatos (audience_too_large).

    json
    {
      "code": "string",
      "error": "string",
      "limit": 0,
      "total": 0
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstring (uuid)ID (UUID) do fluxo. Inválido → 400.

Respostas

  • 200 Estatísticas.

    json
    {
      "active": 4,
      "cancelled": 1,
      "completed": 120,
      "failed": 2,
      "perNode": {
        "n1": {
          "entered": 127,
          "exited": 127
        },
        "n2": {
          "entered": 127,
          "exited": 123
        }
      }
    }
  • 400 Pedido inválido.

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Função fora do plano (plan_feature_disabled: marketing_enabled ou flows_enabled), limite do plano (plan_limit) ou chave de cliente sem o escopo flows (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 500 Erro interno (sem detalhes do banco).

    json
    {
      "error": "invalid request"
    }
  • 503 Banco 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

bash
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

CampoOndeTipoDescrição
tokenobrigatóriopathstringToken do webhook de entrada (fwh_ + 43 caracteres base64url), mostrado só ao criar, duplicar ou rotacionar o fluxo.

Corpo (application/json)

CampoTipoDescrição
defaultCountryopcionalstringDDI para números sem DDI; não vira variável.
nameopcionalstringNome do contato quando ele é criado agora (um contato existente não é alterado).
phoneobrigatóriostring | numberTelefone do contato, normalizado como na importação.
json
{
  "cliente": {
    "nome": "Ana",
    "plano": "ouro"
  },
  "name": "Ana",
  "pedido": 123,
  "phone": "+55 81 99999-0001"
}

Respostas

  • 202 Aceito. Com runId a execução foi criada; com runId: null nada começou e reason diz por quê (optout, already_running).

    json
    {
      "reason": "already_running",
      "runId": null
    }
  • 400 Corpo inválido: invalid_body (não é objeto JSON), invalid_phone (com reason: os motivos da importação ou missing) ou invalid_default_country.

    json
    {
      "code": "invalid_body",
      "error": "body must be a JSON object"
    }
  • 403 Token válido, mas: contato novo sem vaga (plan_limit, max_contacts), plano sem marketing_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"
    }
  • 404 Token fora do formato, inexistente, errado ou rotacionado. Não diz se o fluxo existe nem o estado da conta.

    json
    {
      "error": "not found"
    }
  • 409 Fluxo pausado ou rascunho (flow_not_active).

    json
    {
      "code": "flow_not_active",
      "error": "flow is not active"
    }
  • 413 Corpo acima de 64 KiB (body_too_large).

    json
    {
      "code": "body_too_large",
      "error": "body too large",
      "limit": 65536
    }
  • 429 rate_limited (limite do token, ou orçamento de tokens inexistentes gasto — este com Retry-After: 1) ou flow_rate_limited (fluxo acima de 60 inícios/min).

    json
    {
      "code": "flow_rate_limited",
      "error": "too many starts for this flow"
    }
  • 500 Erro interno.

    json
    {
      "error": "flow webhook failed"
    }

Exemplo

bash
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

  • 200 Os 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
          ]
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled; na criação e no teste, também ai_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"
    }
  • 500 O 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"
    }
  • 503 Armazenamento indisponível (sem banco).

    json
    {
      "error": "AI storage unavailable"
    }

Exemplo

bash
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)

CampoTipoDescrição
credential_idopcionalstring (uuid) | nullUma chave de IA existente, ou null (invalid_credential).
flow_idsopcionalarray<string (uuid)>Fluxos existentes; repetidos contam uma vez (invalid_flows).
handoff_assigneeopcionalstring | nullId opaco de até 200 caracteres; null ou "" = nenhum (invalid_handoff_assignee).
handoff_keywordsopcionalarray<string>Até 20, de até 50 caracteres, nenhuma vazia; padrão ["atendente","humano"]; [] desliga (invalid_handoff_keywords).
handoff_messageopcionalstringAté 1000 caracteres (invalid_handoff_message).
http_endpointsopcionalarray<object>Substitui a lista inteira (invalid_http_endpoints, url_internal, MASKED_SECRET_NEW_DESTINATION).
http_endpoints[].descriptionopcionalstringO que o endpoint faz, para o modelo decidir quando chamá-lo.
http_endpoints[].headersopcionalobjectAté 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óriostringNome com que o modelo chama o endpoint (chamar_http); único no agente.
http_endpoints[].urlobrigatóriostringURL 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_repliesopcionalintegerPadrão 10 (invalid_max_consecutive_replies).
max_tokensopcionalinteger0 = o padrão do provedor (invalid_max_tokens).
max_tool_iterationsopcionalintegerPadrão 3 (invalid_max_tool_iterations).
memory_messagesopcionalintegerPadrão 10 (invalid_memory).
modelopcionalstringVazio = o default_model da chave (invalid_model).
nameopcionalstringObrigatório na criação (invalid_name).
reply_delay_secondsopcionalintegerPadrão 8; 0 responde cada mensagem na hora (invalid_reply_delay).
system_promptopcionalstringAté 8 KiB (invalid_system_prompt).
temperatureopcionalnumber | nullDe 0 a 2, ou null (invalid_temperature); 0 vale como null (o padrão do provedor).
timeout_secondsopcionalintegerPadrão 20 (invalid_timeout).
toolsopcionalanySubstitui 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"
json
{
  "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

  • 201 Criado (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"
    }
  • 400 Corpo 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."
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled; na criação e no teste, também ai_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"
    }
  • 500 O 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"
    }
  • 503 Armazenamento 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

bash
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

CampoOndeTipoDescrição
agentIDobrigatóriopathstringID do agente (UUID). Um id que não é UUID dá 404 not_found.

Respostas

  • 200 O 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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled; na criação e no teste, também ai_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"
    }
  • 404 Agente inexistente (not_found).

    json
    {
      "code": "not_found",
      "error": "agent not found"
    }
  • 500 O 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"
    }
  • 503 Armazenamento indisponível (sem banco).

    json
    {
      "error": "AI storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
agentIDobrigatóriopathstringID do agente (UUID). Um id que não é UUID dá 404 not_found.

Corpo (application/json)

CampoTipoDescrição
credential_idopcionalstring (uuid) | nullUma chave de IA existente, ou null (invalid_credential).
flow_idsopcionalarray<string (uuid)>Fluxos existentes; repetidos contam uma vez (invalid_flows).
handoff_assigneeopcionalstring | nullId opaco de até 200 caracteres; null ou "" = nenhum (invalid_handoff_assignee).
handoff_keywordsopcionalarray<string>Até 20, de até 50 caracteres, nenhuma vazia; padrão ["atendente","humano"]; [] desliga (invalid_handoff_keywords).
handoff_messageopcionalstringAté 1000 caracteres (invalid_handoff_message).
http_endpointsopcionalarray<object>Substitui a lista inteira (invalid_http_endpoints, url_internal, MASKED_SECRET_NEW_DESTINATION).
http_endpoints[].descriptionopcionalstringO que o endpoint faz, para o modelo decidir quando chamá-lo.
http_endpoints[].headersopcionalobjectAté 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óriostringNome com que o modelo chama o endpoint (chamar_http); único no agente.
http_endpoints[].urlobrigatóriostringURL 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_repliesopcionalintegerPadrão 10 (invalid_max_consecutive_replies).
max_tokensopcionalinteger0 = o padrão do provedor (invalid_max_tokens).
max_tool_iterationsopcionalintegerPadrão 3 (invalid_max_tool_iterations).
memory_messagesopcionalintegerPadrão 10 (invalid_memory).
modelopcionalstringVazio = o default_model da chave (invalid_model).
nameopcionalstringObrigatório na criação (invalid_name).
reply_delay_secondsopcionalintegerPadrão 8; 0 responde cada mensagem na hora (invalid_reply_delay).
system_promptopcionalstringAté 8 KiB (invalid_system_prompt).
temperatureopcionalnumber | nullDe 0 a 2, ou null (invalid_temperature); 0 vale como null (o padrão do provedor).
timeout_secondsopcionalintegerPadrão 20 (invalid_timeout).
toolsopcionalanySubstitui 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"
json
{
  "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

  • 200 Alterado (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"
    }
  • 400 Corpo 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."
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled; na criação e no teste, também ai_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"
    }
  • 404 Agente inexistente (not_found).

    json
    {
      "code": "not_found",
      "error": "agent not found"
    }
  • 500 O 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"
    }
  • 503 Armazenamento 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

bash
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

CampoOndeTipoDescrição
agentIDobrigatóriopathstringID do agente (UUID). Um id que não é UUID dá 404 not_found.

Respostas

  • 204 Apagado.

  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled; na criação e no teste, também ai_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"
    }
  • 404 Agente inexistente (not_found).

    json
    {
      "code": "not_found",
      "error": "agent not found"
    }
  • 500 O 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"
    }
  • 503 Armazenamento indisponível (sem banco).

    json
    {
      "error": "AI storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
agentIDobrigatóriopathstringID do agente (UUID).

Corpo (application/json)

CampoTipoDescrição
contactopcionalobjectOs "Dados do contato" do teste; ausente, só um telefone fictício.
contact.fieldsopcionalobject
contact.nameopcionalstring
contact.phoneopcionalstring
contact.tagsopcionalarray<string>
messagesobrigatórioarray<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óriostring
json
{
  "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

  • 200 O 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"
        }
      ]
    }
  • 400 Corpo inválido (invalid_body); messages fora de 1 a 20, com papel que não é user ou assistant, texto vazio ou acima de 4096 caracteres, ou a última que não é do usuário (invalid_messages); contact invá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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled; na criação e no teste, também ai_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"
    }
  • 404 Agente inexistente (not_found).

    json
    {
      "code": "not_found",
      "error": "agent not found"
    }
  • 500 O 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"
    }
  • 503 Armazenamento indisponível (sem banco).

    json
    {
      "error": "AI storage unavailable"
    }

Exemplo

bash
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

  • 200 As 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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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)

CampoTipoDescrição
api_keyopcionalstringA chave do provedor. Mascarada (como a leitura a devolve) ou ausente mantém a gravada, menos quando format ou base_url mudam.
base_urlopcionalstringURL http(s) sem usuário, query ou fragmento; vazia = o provedor do formato.
default_modelopcionalstring
formatopcional"openai_chat" | "openai_responses" | "anthropic_messages" | "gemini"
nameopcionalstring
json
{
  "api_key": "string",
  "base_url": "string",
  "default_model": "string",
  "format": "openai_chat",
  "name": "string"
}

Respostas

  • 201 Criada (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"
    }
  • 400 Campo ausente ou inválido (name_required, invalid_format, invalid_base_url, default_model_required, api_key_required).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 503 Armazenamento indisponível, ou sem a chave de cifra do servidor para cifrar a chave (secrets_key_missing; nada é gravado).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
credentialIDobrigatóriopathstringID da chave de IA (UUID).

Corpo (application/json)

CampoTipoDescrição
api_keyopcionalstringA chave do provedor. Mascarada (como a leitura a devolve) ou ausente mantém a gravada, menos quando format ou base_url mudam.
base_urlopcionalstringURL http(s) sem usuário, query ou fragmento; vazia = o provedor do formato.
default_modelopcionalstring
formatopcional"openai_chat" | "openai_responses" | "anthropic_messages" | "gemini"
nameopcionalstring
json
{
  "api_key": "string",
  "base_url": "string",
  "default_model": "string",
  "format": "openai_chat",
  "name": "string"
}

Respostas

  • 200 Alterada (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"
    }
  • 400 Campo inválido, ou destino novo sem uma chave nova (MASKED_SECRET_NEW_DESTINATION).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 503 Armazenamento indisponível, ou sem a chave de cifra do servidor para cifrar a chave (secrets_key_missing; nada é gravado).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
credentialIDobrigatóriopathstringID da chave de IA (UUID).

Respostas

  • 204 Apagada.

  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 A chave está em uso (CREDENTIAL_IN_USE).

    json
    {
      "code": "string",
      "error": "string",
      "used_by": [
        {
          "id": "string",
          "kind": "flow",
          "name": "string"
        }
      ]
    }

Exemplo

bash
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

CampoOndeTipoDescrição
credentialIDobrigatóriopathstringID da chave de IA (UUID).
modelopcionalquerystring

Respostas

  • 200 O resultado do teste.

    json
    {
      "error": "string",
      "format": "string",
      "input_tokens": 0,
      "latency_ms": 0,
      "model": "string",
      "ok": false,
      "output_tokens": 0
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
fromopcionalquerystringRFC 3339 ou AAAA-MM-DD; padrão, o começo do mês UTC.
toopcionalquerystringRFC 3339 ou AAAA-MM-DD (o dia inteiro); padrão, agora.
kindopcionalquery"flow" | "middleware" | "agent" | "test"
refopcionalquerystring
group_byopcionalquery"origin" | "model" | "day"

Respostas

  • 200 O 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
      }
    }
  • 400 from/to inválidos ou fora de ordem, ou group_by desconhecido (invalid_query).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 503 O uso não pôde ser lido (usage_unavailable).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 O 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"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Chave de cliente (CLIENT_KEY_SCOPE); o atendente do número é configuração do número.

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Número inexistente (instance not found, sem code) ou número sem atendente (agent_not_set).

    json
    {
      "error": "instance not found"
    }
  • 500 O 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"
    }
  • 503 Armazenamento indisponível (sem banco).

    json
    {
      "error": "AI storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
agent_idobrigatóriostring (uuid)Um agente salvo (invalid_agent).
enabledopcionalboolean
scheduleopcionalobject | nullAusente 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.
json
{
  "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

  • 200 O 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"
    }
  • 400 Corpo inválido (invalid_body), horário inválido (invalid_schedule) ou agent_id que não é um agente salvo, inclusive ausente ou que não é UUID (invalid_agent). Nada muda.

    json
    {
      "code": "invalid_agent",
      "error": "agent not found"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 IA fora do plano (plan_feature_disabled, feature ai_rewrite_enabled) ou chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Número inexistente (instance not found, sem code).

    json
    {
      "error": "instance not found"
    }
  • 500 O 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"
    }
  • 503 Armazenamento indisponível (sem banco).

    json
    {
      "error": "AI storage unavailable"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 204 Removido.

  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Chave de cliente (CLIENT_KEY_SCOPE); o atendente do número é configuração do número.

    json
    {
      "code": "CLIENT_KEY_SCOPE",
      "error": "forbidden"
    }
  • 404 Número inexistente (instance not found, sem code) ou número sem atendente (agent_not_set).

    json
    {
      "error": "instance not found"
    }
  • 500 O 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"
    }
  • 503 Armazenamento indisponível (sem banco).

    json
    {
      "error": "AI storage unavailable"
    }

Exemplo

bash
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

  • 200 API 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
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

  • 200 Documento OpenAPI 3.1.

    json
    {}
  • 500 Documento indisponível (openapi document unavailable).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

  • 200 Documento OpenAPI 3.1.

    json
    string
  • 500 Documento indisponível (openapi document unavailable).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
monthopcionalquerystringO mês, YYYY-MM (UTC); sem ele, o atual.

Respostas

  • 200 A contagem do mês.

    json
    {
      "billable_total": 0,
      "by_category": {},
      "instance_id": "string",
      "month": "2026-10",
      "note": "string",
      "timezone": "string"
    }
  • 400 Mês inválido (invalid_month).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Uma chave de cliente sem este número (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 404 Instância inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 Um número por QR (provider_unsupported).

    json
    {
      "code": "provider_unsupported",
      "error": "string",
      "provider": "whatsmeow"
    }
  • 503 A contagem não pôde ser lida.

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

  • 200 Os tipos.

    json
    {
      "graph_version": "v27.0",
      "providers": [
        "whatsmeow",
        "cloud"
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Chave de cliente (CLIENT_KEY_SCOPE).

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
hub.modeobrigatórioquerystring
hub.verify_tokenobrigatórioquerystring
hub.challengeobrigatórioquerystring

Respostas

  • 200 O hub.challenge, em texto.

    json
    string
  • 403 Modo ou token errado (verification refused).

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 503 A 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

bash
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

CampoOndeTipoDescrição
X-Hub-Signature-256obrigatórioheaderstring

Corpo (application/json)

json
{}

Respostas

  • 200 Recebido (ok), ou lido e ignorado (ignored).

    json
    {
      "status": "ok"
    }
  • 401 Assinatura ausente ou errada (invalid signature).

    json
    {
      "error": "invalid request"
    }
  • 413 Corpo acima de 3 MB.

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 503 A 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
header_parametersopcionalarray<string>Os valores das variáveis de um cabeçalho de texto.
languageobrigatóriostringO código do idioma do template (pt_BR, en_US).
nameobrigatóriostring
namedopcionalobjectOs valores por nome, num template named ({"first_name":"Ana"}).
parametersopcionalarray<string>Os valores do corpo por posição: o 1º preenche {{1}}, e assim por diante.
buttonsopcionalarray<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óriointeger
buttons[].textobrigatóriostring
codeopcionalstringO código de um template de autenticação; vai no corpo e no botão de código.
header_mediaopcionalobjectA 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.filenameopcionalstring
header_media.idopcionalstring
header_media.linkopcionalstring (uri)
toobrigatóriostringO telefone do contato (ou o JID de um BSUID).
json
{
  "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

  • 200 Aceito pela Meta.

    json
    {
      "id": "string"
    }
  • 400 template_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), ou invalid_template (falta to, name ou language).

    json
    {
      "code": "template_not_approved",
      "error": "the template promo is REJECTED, not APPROVED"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 Cota do plano esgotada (plan_limit) ou conta suspensa (ACCOUNT_SUSPENDED).

    json
    {
      "error": "invalid request"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O envio de modelo: provider_unsupported num número por QR, provider_disabled quando a instalação não oferece números oficiais, ou number_restricted quando o número oficial não está online (status e status_reason dizem 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"
    }
  • 422 O token foi recusado (cloud_auth_invalid); depois disso, o número fica restricted 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"
    }
  • 429 Número pausado ou limite da Meta (rate_limited).

    json
    {
      "error": "invalid request"
    }
  • 502 A Meta não respondeu (cloud_unavailable).

    json
    {
      "error": "invalid request"
    }
  • 503 A 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 fica restricted; 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

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).
statusopcionalquerystring
syncopcionalquery"1"1 sincroniza com a Meta antes (no máximo a cada 60 s por WABA).

Respostas

  • 200 Os 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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 A 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 422 O token do número não pôde ser lido (cloud_auth_invalid).

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Corpo (application/json)

CampoTipoDescrição
categoryobrigatório"MARKETING" | "UTILITY" | "AUTHENTICATION"
componentsobrigatórioarray<object>O formato da Meta; precisa de um BODY com texto (até 1024 caracteres).
languageobrigatóriostring
nameobrigatóriostring
parameter_formatopcional"positional" | "named"
json
{
  "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

  • 201 Criado.

    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"
    }
  • 400 Template inválido (invalid_template).

    json
    {
      "error": "invalid request"
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 A 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 422 A Meta recusou o template (template_refused) ou o token (cloud_auth_invalid).

    json
    {
      "error": "invalid request"
    }
  • 429 Limite 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, com Retry-After em segundos).

    json
    {
      "code": "template_create_limited",
      "error": "at most 20 templates are created per hour in this account"
    }
  • 502 A Meta não respondeu (cloud_unavailable).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
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

CampoOndeTipoDescrição
idobrigatóriopathstringID da instância (UUID).

Respostas

  • 200 Os 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"
        }
      ]
    }
  • 401 Chave ausente ou inválida.

    json
    {
      "error": "unauthorized: missing or invalid API key"
    }
  • 403 A 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"
    }
  • 404 Recurso inexistente.

    json
    {
      "error": "invalid request"
    }
  • 409 O tipo do número não tem esta rota: provider_unsupported num número oficial (provider: cloud), ou provider_disabled quando 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"
    }
  • 422 O token foi recusado (cloud_auth_invalid).

    json
    {
      "error": "invalid request"
    }
  • 429 Limite de taxa comum da API (por chave autenticada ou, sem ela, por endereço).

    json
    {
      "error": "rate limit exceeded, try again later"
    }
  • 502 A Meta não respondeu (cloud_unavailable).

    json
    {
      "error": "invalid request"
    }

Exemplo

bash
curl -X POST "$API_URL/api/v1/instances/<id>/templates/sync" \
  -H "Authorization: Bearer $API_KEY"