DOCUMENTAÇÃO DA API

Referência da API FlowZap

269 endpoints em 22 áreas, do envio de mensagens a grupos, canais, CRM e webhooks. Esta página segue a especificação OpenAPI 3.1 do projeto; uma verificação automática confere que toda rota do código está nela.

Base da API: https://flowzap.flowpost.com.br. 11 rotas respondem 501 porque o WhatsApp Web não oferece o recurso; elas estão marcadas abaixo.

Crie a conta e gere a chave em Integrações (proprietário ou administrador). A API está em todos os planos.

Nas rotas de um número, {número} quer dizer /v1/workspaces/{workspaceId}/instances/{instanceId}.

Início rápido

  1. Tenha uma chave de API

    No console, em Integrações, o proprietário ou um administrador da organização cria a chave, que aparece uma única vez: guarde-a como segredo. Dê só os escopos necessários e, se quiser, prenda a chave a uma área de trabalho ou a um número.

    Os IDs da área de trabalho ($WORKSPACE) e do número ($NUMERO) ficam na mesma tela, com botão de copiar.

  2. Envie a primeira mensagem

    Idempotency-Key é obrigatória: se a rede cair e o seu sistema repetir o pedido com a mesma chave, a mensagem sai uma vez só. expires_at é o prazo para o envio acontecer (no máximo 7 dias à frente).

    Pedido
    curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/messages \
      -H "Authorization: Bearer $FLOWZAP_KEY" \
      -H "Idempotency-Key: pedido-4821-confirmacao" \
      -H "Content-Type: application/json" \
      -d '{
        "to": { "kind": "phone", "value": "+5511912345678" },
        "type": "text",
        "text": { "body": "Seu pedido 4821 saiu para entrega." },
        "client_reference": "pedido-4821",
        "expires_at": "2026-10-01T18:00:00Z"
      }'
    Resposta202 Accepted
    {
      "data": {
        "id": "e7a1c3d9-0b4f-4e62-9a85-1d3c7b2f6e04",
        "state": "queued",
        "provider_message_id": "3EB0A1B2C3D4E5F6071829",
        "client_reference": "pedido-4821",
        "expires_at": "2026-10-01T18:00:00.000Z",
        "created_at": "2026-10-01T12:00:00.000Z"
      }
    }
  3. Acompanhe o resultado

    O 202 confirma que a mensagem entrou na fila. Para saber se saiu, foi entregue ou lida, consulte o envio ou cadastre um webhook: cada mudança chega como message.provider_accepted, message.delivered, message.read ou, se der errado, message.failed.

    Pedido
    # Consultar o envio (escopo messages:read)
    curl https://flowzap.flowpost.com.br/v1/messages/e7a1c3d9-0b4f-4e62-9a85-1d3c7b2f6e04 \
      -H "Authorization: Bearer $FLOWZAP_KEY"
    
    # Ou receber avisos a cada mudança (webhooks:write, chave da área de trabalho)
    curl -X POST https://flowzap.flowpost.com.br/v1/webhook-endpoints \
      -H "Authorization: Bearer $FLOWZAP_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "workspace_id": "'$WORKSPACE'", "url": "https://seu-sistema.com.br/flowzap" }'

Contrato e arquivos

Versão do contrato: 1.3.0-preview.20261116. Os arquivos abaixo saem do mesmo contrato desta página a cada publicação, com endereço fixo.

  • openapi.jsonOpenAPI 3.1 em JSON, um arquivo só: gere clientes ou importe no Swagger, Insomnia ou Postman.
  • openapi.yamlO mesmo contrato em YAML.
  • Coleção do PostmanTodas as rotas por área, com corpo de exemplo e Idempotency-Key nova a cada pedido.

No Postman, importe a coleção e preencha as variáveis da coleção: api_key (a sua chave), workspace_id e instance_id; host já vem com o endereço da API. A coleção não traz nenhuma chave.

Autenticação e escopos

Toda chamada leva a chave de API no cabeçalho Authorization. A chave pertence a uma organização e pode ficar presa a uma área de trabalho ou a um único número: fora desse alcance, a resposta é 404. Cada rota exige um escopo; sem ele, 403 scope_denied. A única exceção é o webhook chamado pelo Chatwoot, identificado por um token no endereço.

Cabeçalho
Authorization: Bearer fzk_XXXXXXXXXXXX_...
Escopos de uma chave
EscopoO que permite
workspaces:readLer as áreas de trabalho.
instances:writeCriar números e reservar a vaga para conectar.
instances:readLer os números: lista (com o telefone completo do próprio número), situação, limites, fila e capacidades (engine:read também serve, sem o telefone completo).
messages:sendEnviar mensagens e mídia, cancelar a fila e criar campanhas.
messages:readConsultar envios, baixar mídia, ler conversas, a fila e as campanhas.
engine:readLer dados do WhatsApp (grupos, contatos, perfil, canais), todos os eventos, CRM, Chatwoot e operações.
engine:writeMudar algo no WhatsApp ou nos dados do número: grupos, perfil, conversas, CRM, Chatwoot.
crm:readLer o CRM: leads, funil, campos personalizados, atendimentos, respostas rápidas e automáticas (engine:read também serve).
crm:writeMudar o CRM: leads, etapas, mover contatos, campos, resolver e atribuir atendimentos, respostas automáticas (engine:write também serve).
webhooks:readListar webhooks e o histórico de entregas.
webhooks:writeCadastrar, alterar, testar e remover webhooks; reenviar entregas.
audiences:readListar públicos e ver os membros com telefone mascarado.
audiences:writeColetar, atualizar e apagar públicos de grupos.
audiences:exportExportar públicos para Meta e Google e ver telefones completos (exige declaração de base legal).
calls:readVer ligações e gravações (sem o áudio) e ler os eventos call.* (por ID, por número e no SSE).
calls:writeFazer, atender, recusar, desligar e silenciar ligações (engine:write também serve nas chaves antigas).
calls:recordingsBaixar e apagar gravações de ligações (calls:read lista as ligações sem o áudio).
calls:adminAdministrar as ligações da conta: origens do áudio no navegador e números de teste do piloto (só chave da organização inteira, de dona ou administradora; nunca por OAuth).

Operações, erros e limites

Operações no WhatsApp

Rotas que precisam do WhatsApp (grupos, perfil, contatos, conversas, canais) são executadas pelo número conectado. A API espera até 15 segundos: responde 200 com o resultado em data ou 202 com o endereço da operação em Location. Consulte GET /v1/operations/{id} até terminar. 422 quer dizer que o WhatsApp recusou; 502, que o resultado é incerto (confira antes de repetir); 504, que a operação venceu sem ser executada. Todo 202 traz Retry-After (segundos até consultar de novo); com ?envelope=1, GET /v1/operations/{id} responde sempre 200 com state, result e error no mesmo corpo.

Enviar mensagem é diferente: a resposta é sempre 202 com o envio na fila, e o resultado chega pelos eventos message.*.

Toda resposta traz X-Request-Id (envie o seu, de 8 a 128 caracteres, para correlacionar); em erro, error.request_id é o mesmo valor e fica no nosso log: informe-o ao suporte. retryable segue uma regra única: 429 é repetível e vem sempre com Retry-After (menos as cotas do plano); 503 e 504 também; 502 de resultado incerto, 501 e os demais 4xx não. O significado de cada code está no catálogo de erros.

Operação em andamento
HTTP/1.1 202 Accepted
Location: /v1/operations/0b8f4d2e-6c1a-4f37-9e50-a2d7c3b1e864
Retry-After: 1

{
  "data": {
    "operation_id": "0b8f4d2e-6c1a-4f37-9e50-a2d7c3b1e864",
    "state": "running"
  }
}
Erro (sempre neste formato)
HTTP/1.1 403 Forbidden
X-Request-Id: 7f1e2d3c-4b5a-4968-8776-5a4b3c2d1e0f

{
  "error": {
    "code": "scope_denied",
    "message": "scope_denied",
    "request_id": "7f1e2d3c-4b5a-4968-8776-5a4b3c2d1e0f",
    "retryable": false
  }
}

Idempotência

Idempotency-Key é obrigatória para enviar mensagens, criar campanhas e criar números, e aceita nas operações. Repetir o pedido com a mesma chave devolve o mesmo resultado, com o cabeçalho Idempotent-Replay: true, sem fazer de novo. A mesma chave com outro conteúdo recebe 409 idempotency_conflict.

Limites

Pedidos por minuto conforme o plano, somando todas as chaves da organização: toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; acima do limite, 429 rate_limited com Retry-After. Envio: 60 mensagens por minuto, com rajada de 10, por chave e número. Com a fila do número no limite do plano, novos pedidos recebem 429 queue_full. Plano, limites e uso em GET /v1/account. Corpo JSON até 1 MB; mídia até 16 MiB, enviada como arquivo binário.

Códigos de resposta
CódigoSignificado
200Pronto; data traz o resultado.
201Criado.
202Aceito: mensagem na fila, ou operação ainda em andamento (cabeçalho Location).
204Feito, sem corpo.
400Pedido inválido (invalid_input e outros códigos).
401Chave ausente, inválida, revogada ou vencida.
403Falta o escopo na chave (scope_denied) ou a conta está suspensa (organization_suspended).
404Não existe, ou a chave não alcança esse recurso.
409Conflito, como a mesma Idempotency-Key com outro conteúdo.
422O WhatsApp ou uma regra do serviço recusou.
429Limite de pedidos ou de envio (rate_limited) ou fila cheia (queue_full); sempre com Retry-After. Cotas do plano (slot_limit_reached…) não liberam esperando.
501O WhatsApp Web não oferece o recurso (not_supported_by_engine). Não adianta repetir.
502Resultado incerto (retryable false): confira o estado antes de repetir; nunca reenvie às cegas.
503Número desconectado ou serviço indisponível; tente mais tarde.
504A operação venceu sem ser executada; pode repetir.

Catálogo de erros

Todo erro traz error.code (estável), retryable e request_id, o mesmo valor do cabeçalho X-Request-Id — cite-o ao falar com o suporte. Um 429 pode ser repetido depois do Retry-After; um 502 de resultado incerto nunca deve ser repetido às cegas. Códigos sem status são motivos de falha de envio, em error_code da mensagem.

285 de 285 códigos

  • account_exists409Não repita

    Este e-mail já tem conta e o convite de dono não pode criar outra.

    O que fazer: Entre no console com esse e-mail e aceite o convite com a sessão.

  • addon_change_refused409Não repita

    A cobrança recusou a mudança do adicional (motivo em `reason`).

    O que fazer: Leia `reason`, ajuste a quantidade ou regularize a assinatura e tente de novo.

  • after_sequence_requires_instance400Não repita

    `after_sequence` só vale com um número (`instance_id`), porque a sequência é por número.

    O que fazer: Envie `instance_id` junto ou use `Last-Event-ID`.

  • already_member409Não repita

    A pessoa já faz parte da equipe.

    O que fazer: Nada a fazer; altere o papel dela, se for o caso.

  • already_sent409Não repita

    O agendamento já foi enviado (o envio está em `message_id`).

    O que fazer: Acompanhe o envio por `GET /v1/messages/{id}`; não cancele nem reagende.

  • api_access_token_required400Não repita

    O Chatwoot precisa do token de acesso da API para ser ligado.

    O que fazer: Envie `api_access_token` do usuário/agente do Chatwoot.

  • api_key_active409Não repita

    A chave ainda está ativa: só uma chave revogada ou expirada pode ser excluída da lista.

    O que fazer: Revogue a chave antes de excluí-la.

  • api_key_not_active409Não repita

    A chave foi revogada ou expirou: o nome e as permissões não mudam mais.

    O que fazer: Crie outra chave com o nome e as permissões desejados.

  • audience_empty422Não repita

    O público não tem membros para exportar.

    O que fazer: Colete o público de novo ou escolha outros grupos.

  • audience_not_ready409Não repita

    O público ainda está sendo coletado.

    O que fazer: Espere a coleta terminar (`state`) e exporte depois.

  • audio_conversion_unavailable503Pode repetir

    A conversão de áudio para nota de voz está indisponível no momento.

    O que fazer: Tente mais tarde ou envie o áudio já em OGG/Opus.

  • audio_unreadable422Não repita

    O arquivo de áudio não pôde ser lido (vazio ou corrompido).

    O que fazer: Envie outro arquivo de áudio válido.

  • author_not_allowed403Não repita

    A anotação não pode ser atribuída a essa pessoa com esta chave.

    O que fazer: Omita `author_user_id` ou use uma chave criada por essa pessoa (ou por quem pode agir por ela).

  • bad_request422Não repita

    O WhatsApp recusou o pedido do canal como inválido.

    O que fazer: Confira os parâmetros do canal e tente de outra forma.

  • before_or_after400Não repita

    Mover no funil pede `before` ou `after`, não os dois.

    O que fazer: Envie só um vizinho de referência.

  • billing_read_unavailable503Pode repetir

    A leitura da cobrança está indisponível no momento.

    O que fazer: Tente mais tarde.

  • billing_role_required403Não repita

    A chave não age por uma pessoa com papel de cobrança (dono ou financeiro).

    O que fazer: Use uma chave criada pelo dono ou por quem cuida da cobrança.

  • billing_unavailable503Pode repetir

    A cobrança está indisponível no momento.

    O que fazer: Tente mais tarde.

  • call_already_answering409Não repita

    Outra pessoa já está atendendo esta ligação.

    O que fazer: Não repita; leia o estado da ligação (`GET …/calls/{callId}` ou eventos `call.*`).

  • call_ended409Não repita

    A ligação já terminou; não há mais áudio para conectar.

    O que fazer: Não repita; leia o histórico da ligação.

  • call_not_ringing409Não repita

    A ligação não está tocando neste número (já atendida, recusada ou encerrada).

    O que fazer: Não repita; acompanhe pelos eventos `call.*`.

  • call_quantity_exceeded409Não repita

    A escolha passa da quantidade de números com ligações contratada.

    O que fazer: Escolha menos números ou contrate mais em `POST /v1/billing/addons/calls`.

  • call_target_not_allowed403Não repita

    Na fase de testes, só os números de teste cadastrados podem receber ligações.

    O que fazer: Ligue para um número de teste ou contrate o módulo de ligações.

  • call_test_numbers_limit409Não repita

    A lista passa de 20 números de teste diferentes, ou de 40 números diferentes incluídos nos últimos 30 dias.

    O que fazer: Envie no máximo 20 números diferentes; para ligar para qualquer contato, contrate ligações e escolha os números (`PUT /v1/calls/numbers`).

  • call_trial_not_enabled409Não repita

    O piloto de ligações não está ligado nesta conta, então não há números de teste a definir.

    O que fazer: Contrate ligações e escolha os números (`PUT /v1/calls/numbers`), ou peça à equipe FlowZap para ligar o piloto.

  • calls_not_enabled403, 422Não repita

    As ligações não estão ligadas para este número.

    O que fazer: Ligue o módulo de ligações para o número (console ou `PUT /v1/calls/numbers`).

  • capacity_unavailable403Não repita

    A conta não tem vagas de número no plano em vigor.

    O que fazer: Revise o plano ou fale com a equipe FlowZap.

  • card_checkout_unavailable503Pode repetir

    O pagamento por cartão está indisponível no momento.

    O que fazer: Tente mais tarde ou pague por Pix.

  • carousel_media_mixed422Não repita

    O carrossel mistura fotos e vídeos; todos os cartões precisam do mesmo tipo.

    O que fazer: Use só imagens ou só vídeos nos cartões.

  • carousel_media_too_large413Não repita

    As mídias do carrossel somadas passam do limite.

    O que fazer: Use arquivos menores ou menos cartões.

  • chatwoot_url_invalid400Não repita

    O endereço do Chatwoot é inválido ou não é público.

    O que fazer: Use a URL https pública da sua instalação do Chatwoot.

  • checkout_expired410Não repita

    O link de pagamento venceu.

    O que fazer: Gere um checkout novo.

  • checkout_offer_unavailable503Pode repetir

    A oferta do checkout não pôde ser montada agora.

    O que fazer: Tente mais tarde.

  • checkout_rejected422Não repita

    O provedor de pagamento recusou o checkout.

    O que fazer: Confira os dados de cobrança e tente de novo.

  • checkout_unavailable503Pode repetir

    O checkout está indisponível no momento.

    O que fazer: Tente mais tarde.

  • collection_failed422Não repita

    A coleta do público falhou no número.

    O que fazer: Veja os detalhes da resposta, confira se o número está conectado e colete de novo.

  • collection_in_progress409Não repita

    Já existe uma coleta deste público em andamento.

    O que fazer: Espere terminar.

  • collection_too_soon429Pode repetir

    A coleta foi feita há pouco; há um intervalo mínimo entre coletas.

    O que fazer: Espere o tempo de `Retry-After` (ou o informado na resposta).

  • consent_required422Não repita

    Há destinatários sem consentimento registrado (`rejected`, `total`).

    O que fazer: Registre o consentimento no CRM ou retire esses contatos.

  • contact_already_linked409Não repita

    Este contato já está ligado a essa conversa.

    O que fazer: Nada a fazer.

  • contact_link_not_found404Não repita

    A ligação entre contato e conversa não existe.

    O que fazer: Confira os IDs.

  • conversation_not_found404Não repita

    A conversa não existe neste número.

    O que fazer: Confira o JID da conversa.

  • cursor_map_too_large400Não repita

    O cursor em mapa (`cursor=map`) ficaria grande demais para os números da chave.

    O que fazer: Use uma chave ou fluxo por número (`instance_id`) e retome com `GET …/events`.

  • cursor_needs_stage400Não repita

    O `cursor` do funil só vale junto com a etapa (`stage_id`) em que foi gerado.

    O que fazer: Repita com o mesmo `stage_id`.

  • declaration_required422Não repita

    Exportar o público exige a declaração de base legal (LGPD).

    O que fazer: Envie a declaração pedida.

  • delivery_in_progress409Não repita

    A entrega de webhook ainda está na fila (`pending`, `sending` ou `held`).

    O que fazer: Espere terminar; acompanhe em `GET /v1/webhook-deliveries`.

  • disconnect_first409Não repita

    O número ainda está conectado; desconecte antes de excluir.

    O que fazer: Chame `POST …/disconnect` e repita.

  • download_failed502Pode repetir

    Não foi possível baixar a mídia recebida do WhatsApp.

    O que fazer: Tente de novo mais tarde; mídias antigas podem ter expirado no WhatsApp.

  • draft_limit_reached429Não repita

    Limite de números em rascunho atingido.

    O que fazer: Conecte ou exclua rascunhos antes de criar outro.

  • empty_media400Não repita

    O arquivo enviado está vazio.

    O que fazer: Envie o arquivo com conteúdo.

  • endpoint_disabled409Não repita

    O endereço de webhook foi removido (ou respondeu 410); não pode ser alterado, testado nem receber reenvio.

    O que fazer: Cadastre um endereço novo.

  • endpoint_exists409Não repita

    Já existe um webhook ativo com essa URL nesta área de trabalho.

    O que fazer: Use o endereço existente.

  • endpoint_limit_reached409Não repita

    A área de trabalho chegou ao limite de webhooks do plano.

    O que fazer: Remova um endereço ou mude de plano.

  • engine_capability_missing422Não repita

    O motor do WhatsApp deste número não oferece esta ação.

    O que fazer: Não repita; a ação não está disponível.

  • engine_error422Depende

    O número falhou ao executar uma leitura no WhatsApp.

    O que fazer: Leituras podem ser repetidas depois; persistindo, confira a conexão do número.

  • engine_not_connected422Não repita

    O número não estava conectado ao WhatsApp ao executar a operação.

    O que fazer: Confira `GET …/status`, reconecte e repita.

  • engine_timeout504Pode repetir

    A operação venceu antes de o número executá-la; nada foi feito.

    O que fazer: Pode repetir (de preferência com a mesma `Idempotency-Key`).

  • engine_unavailable503Pode repetir

    As operações do WhatsApp estão desligadas neste ambiente.

    O que fazer: Tente mais tarde.

  • existing_account409Não repita

    O e-mail convidado já tem conta em outra organização ou o convite pede cadastro novo.

    O que fazer: Convide outro e-mail ou peça para a pessoa entrar com a conta existente.

  • field_exists409Não repita

    Já existe um campo personalizado com essa chave.

    O que fazer: Use outra chave.

  • forbidden403Não repita

    A pessoa da chave não pode fazer esta ação.

    O que fazer: Use uma chave de quem administra a área.

  • forward_media_expired422Não repita

    A mídia da mensagem a encaminhar expirou.

    O que fazer: Envie a mídia de novo como mensagem nova.

  • forward_media_too_large422Não repita

    A mídia da mensagem a encaminhar passa do limite de envio.

    O que fazer: Envie um arquivo menor como mensagem nova.

  • forward_media_unavailable422Não repita

    A mídia da mensagem a encaminhar não está guardada.

    O que fazer: Envie a mídia como mensagem nova.

  • forward_not_allowed422Não repita

    Essa mensagem não pode ser encaminhada.

    O que fazer: Envie o conteúdo como mensagem nova.

  • forward_not_supported422Não repita

    Esse tipo de mensagem não pode ser encaminhado.

    O que fazer: Envie o conteúdo como mensagem nova.

  • from_me_required400Não repita

    Informe `from_me` (se a mensagem alvo é sua ou do contato).

    O que fazer: Envie `from_me: true` ou `false`.

  • group_announce_onlyenvioNão repita

    O grupo só aceita mensagens de administradores e o número não é admin (em `error_code` do envio).

    O que fazer: Peça para ser admin ou envie em outro canal.

  • group_info_unavailable422Pode repetir

    As informações do grupo não puderam ser lidas.

    O que fazer: Tente de novo mais tarde.

  • group_not_found422Não repita

    O grupo não existe ou o número não o vê.

    O que fazer: Confira o JID do grupo e se o número participa dele.

  • groups_not_ready503Pode repetir

    A lista de grupos do número ainda está sendo carregada.

    O que fazer: Tente de novo em alguns segundos.

  • groups_unavailable502Pode repetir

    A lista de grupos não pôde ser lida no número.

    O que fazer: Tente de novo mais tarde.

  • history_import_off409Não repita

    O número não importa histórico do WhatsApp (desligado em `settings/history`).

    O que fazer: Ligue a importação em `PUT …/settings/history` e repita.

  • idempotency_conflict409Não repita

    A mesma `Idempotency-Key` já foi usada com outro conteúdo.

    O que fazer: Use uma chave nova para um pedido diferente; para repetir, envie exatamente o mesmo corpo.

  • idempotency_key_mismatch400Não repita

    A `Idempotency-Key` do cabeçalho difere da do corpo.

    O que fazer: Envie a mesma chave nos dois ou só no cabeçalho.

  • idempotency_key_required400Não repita

    Esta rota exige `Idempotency-Key`.

    O que fazer: Envie um valor único por pedido (ex.: UUID).

  • image_too_large400Não repita

    A imagem passa do tamanho aceito.

    O que fazer: Envie uma imagem menor.

  • instance_not_in_workspace400Não repita

    Algum número em `instance_ids` não é desta área de trabalho (ou foi excluído).

    O que fazer: Use IDs de `GET /v1/workspaces/{id}/instances`.

  • instance_requires_workspace400Não repita

    Uma chave presa a um número também precisa da área de trabalho dele.

    O que fazer: Informe `workspace_id` junto com `instance_id`.

  • invalid_action422Não repita

    Ação inválida para esta operação.

    O que fazer: Confira os valores aceitos na documentação da rota.

  • invalid_auto_replies422Não repita

    As respostas automáticas têm um campo inválido (`field`).

    O que fazer: Corrija o campo indicado.

  • invalid_before422Não repita

    O marcador `before` da leitura é inválido.

    O que fazer: Use o valor recebido na página anterior.

  • invalid_body400Não repita

    O corpo do upload é inválido.

    O que fazer: Envie o arquivo como corpo binário (`application/octet-stream` ou o tipo da mídia).

  • invalid_broadcast_state409Não repita

    O envio em grupos não está num estado que permita esta ação.

    O que fazer: Leia o estado atual e escolha outra ação.

  • invalid_call_id422Não repita

    ID de ligação inválido.

    O que fazer: Use o `call_id` do evento da ligação.

  • invalid_campaign_state409Não repita

    A campanha não está num estado que permita esta ação.

    O que fazer: Leia o estado atual da campanha.

  • invalid_caption422Não repita

    Legenda inválida.

    O que fazer: Encurte ou corrija a legenda.

  • invalid_color422Não repita

    Cor inválida.

    O que fazer: Use uma cor aceita pela rota.

  • invalid_count422Não repita

    Quantidade pedida inválida.

    O que fazer: Use um valor dentro do limite da rota.

  • invalid_cursor400Não repita

    O `cursor` não veio desta rota (ou desta consulta).

    O que fazer: Recomece sem `cursor` ou use o `next_cursor` recebido.

  • invalid_description422Não repita

    Descrição inválida (vazia ou longa demais).

    O que fazer: Corrija o texto.

  • invalid_duration422Não repita

    Duração inválida.

    O que fazer: Use um valor aceito pela rota.

  • invalid_ephemeral_timer422Não repita

    Tempo de mensagens temporárias inválido.

    O que fazer: Use um dos valores aceitos.

  • invalid_expiration422Não repita

    Validade inválida.

    O que fazer: Use um valor aceito pela rota.

  • invalid_expiry400Não repita

    `expires_at` inválido (no passado ou longe demais).

    O que fazer: Envie uma data futura dentro do limite.

  • invalid_field_value422Não repita

    O valor não serve para o campo personalizado (`field`).

    O que fazer: Envie um valor do tipo do campo.

  • invalid_file_name400Não repita

    O nome de arquivo (`X-File-Name`) é inválido.

    O que fazer: Use um nome simples, sem caminhos.

  • invalid_group_jid422Não repita

    JID de grupo inválido.

    O que fazer: Use o formato `<id>@g.us`.

  • invalid_group_name422Não repita

    Nome de grupo inválido (vazio ou longo demais).

    O que fazer: Corrija o nome.

  • invalid_groups422Não repita

    Lista de grupos inválida.

    O que fazer: Envie JIDs de grupo válidos.

  • invalid_idempotency_key400Não repita

    `Idempotency-Key` com formato inválido.

    O que fazer: Use até 128 caracteres: letras, números e `_ . : -`.

  • invalid_image400, 422Não repita

    A imagem não pôde ser lida ou não é de um tipo aceito.

    O que fazer: Envie JPEG ou PNG válido.

  • invalid_input400Não repita

    O pedido não segue o formato da rota (corpo, parâmetros ou consulta).

    O que fazer: Corrija o pedido conforme o contrato (OpenAPI).

  • invalid_instance_state409Não repita

    O número não está num estado que permita esta ação (ex.: conectar um número excluído ou arquivado).

    O que fazer: Leia o estado do número.

  • invalid_invite422Não repita

    Convite de grupo inválido.

    O que fazer: Use um link ou código de convite válido.

  • invalid_invite_code422Não repita

    Código de convite inválido.

    O que fazer: Use o código do link `chat.whatsapp.com/<código>`.

  • invalid_jid400, 422Não repita

    JID inválido (no caminho ou no corpo).

    O que fazer: Use `<número>@s.whatsapp.net`, `<id>@lid` ou `<id>@g.us`.

  • invalid_json400Não repita

    O corpo não é JSON válido.

    O que fazer: Envie JSON válido com `Content-Type: application/json`.

  • invalid_label_id422Não repita

    ID de etiqueta inválido.

    O que fazer: Use um ID de `GET …/labels`.

  • invalid_last_event_id400Não repita

    `Last-Event-ID` (ou `last_event_id`) não está num formato aceito.

    O que fazer: Reenvie o último `id` recebido no fluxo, sem alterar.

  • invalid_media_kind400Não repita

    Tipo de mídia (`kind`) inválido no upload.

    O que fazer: Use `image`, `video`, `audio`, `document` ou `sticker`.

  • invalid_media_url400Não repita

    A URL da mídia é inválida.

    O que fazer: Use uma URL https pública.

  • invalid_member_add_mode422Não repita

    Modo de entrada de participantes inválido.

    O que fazer: Use um dos valores aceitos.

  • invalid_message422Não repita

    A mensagem montada pelo modelo é inválida.

    O que fazer: Revise o texto e as variáveis do modelo.

  • invalid_message_id422Não repita

    ID de mensagem inválido.

    O que fazer: Use o ID da mensagem do WhatsApp.

  • invalid_message_ids422Não repita

    Lista de IDs de mensagem inválida.

    O que fazer: Envie IDs válidos, dentro do limite.

  • invalid_name422Não repita

    Nome inválido.

    O que fazer: Corrija o nome (tamanho e caracteres).

  • invalid_newsletter_jid422Não repita

    JID de canal inválido.

    O que fazer: Use o formato `<id>@newsletter`.

  • invalid_newsletter_name422Não repita

    Nome de canal inválido.

    O que fazer: Corrija o nome.

  • invalid_or_expired_invitation400Não repita

    O convite é inválido ou venceu.

    O que fazer: Peça um convite novo.

  • invalid_origin400Não repita

    Não é uma origem exata aceita: use `https://host[:porta]` (ou `http://localhost[:porta]` e `http://127.0.0.1[:porta]` para desenvolvimento), sem caminho, `?`, `#`, usuário e senha ou `*`.

    O que fazer: Envie só o esquema, o host e a porta do sistema que abre o áudio, por exemplo `https://app.exemplo.com.br`.

  • invalid_participant422Não repita

    Participante inválido.

    O que fazer: Use um JID ou telefone válido.

  • invalid_participants422Não repita

    Lista de participantes inválida.

    O que fazer: Envie participantes válidos, dentro do limite.

  • invalid_payload400, 422Não repita

    O corpo recebido não tem o formato esperado.

    O que fazer: Confira o formato e envie de novo.

  • invalid_phone422Não repita

    Telefone inválido.

    O que fazer: Use E.164 (ex.: `+5511912345678`).

  • invalid_placeholder422Não repita

    Variável inválida ou desconhecida no texto (ex.: `{{nome}}`).

    O que fazer: Use só as variáveis aceitas.

  • invalid_privacy_value422Não repita

    Valor de privacidade inválido.

    O que fazer: Use um dos valores aceitos.

  • invalid_proxy_url400Não repita

    A URL do proxy é inválida.

    O que fazer: Use `http://`, `https://` ou `socks5://` com host e porta.

  • invalid_reaction422Não repita

    Reação inválida.

    O que fazer: Envie um único emoji (ou vazio para remover).

  • invalid_schedule400, 422Não repita

    Data de agendamento fora da janela permitida.

    O que fazer: Agende dentro dos limites informados na resposta.

  • invalid_sender_resultenvioNão repita

    Resultado inesperado do envio; o desfecho é incerto (em `error_code` do envio).

    O que fazer: Não reenvie às cegas; confira a conversa.

  • invalid_server_id422Não repita

    ID de publicação do canal inválido.

    O que fazer: Use o `server_id` da publicação.

  • invalid_server_ids422Não repita

    Lista de IDs de publicação inválida.

    O que fazer: Envie IDs válidos.

  • invalid_since422Não repita

    Data `since` inválida.

    O que fazer: Use data ISO 8601.

  • invalid_status_styleenvioNão repita

    Estilo do status (cor ou fonte) inválido (em `error_code` do envio).

    O que fazer: Use as cores e fontes aceitas.

  • invalid_text422Não repita

    Texto inválido (vazio ou longo demais).

    O que fazer: Corrija o texto.

  • invalid_timer422Não repita

    Tempo inválido.

    O que fazer: Use um valor aceito.

  • invalid_timestamp422Não repita

    Data/hora inválida.

    O que fazer: Use um valor aceito pela rota.

  • invalid_token401Não repita

    O token OAuth não foi emitido para este recurso.

    O que fazer: Peça um token para a API (não para o MCP).

  • invitation_closed409Não repita

    O convite já foi aceito, cancelado ou venceu.

    O que fazer: Crie um convite novo, se preciso.

  • invitation_email_mismatch403Não repita

    A sessão é de um e-mail diferente do convidado.

    O que fazer: Entre com o e-mail que recebeu o convite.

  • invitation_idempotency_conflict409Não repita

    A mesma chave de pedido já criou um convite diferente.

    O que fazer: Use uma `Idempotency-Key` nova.

  • invitation_not_found404Não repita

    O convite não existe ou o link é inválido.

    O que fazer: Confira o link.

  • invitation_recipient_mismatch403Não repita

    O convite é para outra pessoa.

    O que fazer: Use o convite certo.

  • invite_expired422Não repita

    O convite do grupo venceu.

    O que fazer: Peça um link novo.

  • invite_not_allowed422Não repita

    O número não pode gerar ou usar este convite (não é admin ou o grupo não permite).

    O que fazer: Peça a um admin.

  • invite_not_requested422Não repita

    Não há pedido de entrada desta pessoa no grupo.

    O que fazer: Atualize a lista de pedidos.

  • invite_revoked422Não repita

    O convite do grupo foi revogado.

    O que fazer: Peça um link novo.

  • last_stage409Não repita

    O funil precisa de ao menos uma etapa.

    O que fazer: Crie outra etapa antes de apagar esta.

  • media_content_mismatch415Não repita

    O conteúdo do arquivo não bate com o tipo informado.

    O que fazer: Envie o `Content-Type` correto.

  • media_expired422Não repita

    A mídia expirou no WhatsApp.

    O que fazer: Peça o arquivo de novo ao contato.

  • media_expires_before_schedule422Não repita

    A mídia guardada vence antes da data agendada.

    O que fazer: Envie a mídia de novo mais perto da data ou agende antes.

  • media_integrity_failed422Não repita

    O arquivo guardado não passou na conferência de integridade.

    O que fazer: Envie a mídia de novo.

  • media_kind_mismatch422Não repita

    A mídia guardada é de outro tipo que o do envio.

    O que fazer: Use uma mídia do tipo da mensagem.

  • media_not_found404, 422Não repita

    A mídia não existe, expirou ou não é deste número.

    O que fazer: Faça o upload de novo.

  • media_origins_limit409Não repita

    A conta já tem 10 origens liberadas para o áudio no navegador.

    O que fazer: Remova uma origem em `DELETE /v1/calls/media-origins` antes de cadastrar outra.

  • media_too_large413, 422Não repita

    O arquivo passa do limite (16 MiB no upload; limites do WhatsApp por tipo).

    O que fazer: Envie um arquivo menor.

  • media_unavailableenvioNão repita

    A mídia do envio não estava disponível na hora de enviar (em `error_code` do envio).

    O que fazer: Faça o upload de novo e reenvie.

  • media_upload_failedenvioPode repetir

    O envio da mídia ao WhatsApp falhou antes da mensagem sair (em `error_code` do envio).

    O que fazer: Reenvie (nada saiu).

  • media_url_blocked422Não repita

    A URL da mídia aponta para um destino não permitido (rede privada).

    O que fazer: Use uma URL pública.

  • media_url_content_type422Não repita

    A URL respondeu com um tipo de conteúdo não aceito.

    O que fazer: Sirva o arquivo com o `Content-Type` certo.

  • media_url_failed422Não repita

    Não foi possível baixar a mídia da URL.

    O que fazer: Confira se a URL responde 200 sem login.

  • media_url_redirects422Não repita

    A URL da mídia redirecionou vezes demais.

    O que fazer: Use a URL final do arquivo.

  • media_url_timeout422Não repita

    A URL da mídia demorou demais para responder.

    O que fazer: Use um servidor mais rápido ou faça o upload.

  • media_url_unresolvable422Não repita

    O endereço da URL da mídia não foi encontrado (DNS).

    O que fazer: Confira o domínio.

  • member_limit_reached409Não repita

    A equipe chegou ao limite de pessoas do plano.

    O que fazer: Remova alguém ou mude de plano.

  • message_build_failedenvioNão repita

    A mensagem não pôde ser montada para o WhatsApp (em `error_code` do envio).

    O que fazer: Revise o conteúdo e envie de novo.

  • message_type_not_supportedenvioNão repita

    O tipo de mensagem não é suportado pelo motor (em `error_code` do envio).

    O que fazer: Use outro tipo de mensagem.

  • mime_type_required415Não repita

    Falta o tipo do arquivo (`Content-Type`).

    O que fazer: Envie o `Content-Type` da mídia.

  • missing_variables422Não repita

    Faltam valores para variáveis do modelo (`missing`).

    O que fazer: Envie todas as variáveis do modelo.

  • newsletter_not_found422Não repita

    O canal não existe ou não está visível.

    O que fazer: Confira o JID do canal.

  • newsletter_request_rejected422Não repita

    O WhatsApp recusou o pedido ao canal.

    O que fazer: Tente de outra forma ou mais tarde.

  • no_admin_groups422Não repita

    Nenhum dos grupos escolhidos é administrado pelo número.

    O que fazer: Escolha grupos em que o número é admin.

  • no_consented_recipients422Não repita

    Nenhum destinatário tem consentimento registrado.

    O que fazer: Registre o consentimento antes.

  • no_known_message422Não repita

    Não há mensagem guardada nessa conversa para ancorar o pedido de histórico.

    O que fazer: Espere uma mensagem chegar ou envie uma.

  • no_person_for_key422Não repita

    A ação precisa de uma pessoa e a chave não age por ninguém.

    O que fazer: Use uma chave criada por uma pessoa da equipe.

  • not_acceptable422Não repita

    O WhatsApp recusou o pedido ao canal (formato não aceito).

    O que fazer: Revise o pedido.

  • not_allowed422Não repita

    O WhatsApp não permite esta ação no canal.

    O que fazer: Confira o seu papel no canal.

  • not_authorized422Não repita

    O WhatsApp não autorizou a leitura (privacidade do contato).

    O que fazer: Não há o que fazer pela API.

  • not_cancelable409Não repita

    O agendamento não pode mais ser cancelado (`state`).

    O que fazer: Leia o estado; se já saiu, acompanhe o envio.

  • not_found404, 422Não repita

    Não existe, ou a chave não alcança esse recurso (área de trabalho ou número de outra chave).

    O que fazer: Confira o ID e o alcance da chave.

  • not_group_admin422Não repita

    A ação exige que o número seja admin do grupo.

    O que fazer: Peça para ser admin ou use outro número.

  • not_group_member422Não repita

    O número não participa do grupo.

    O que fazer: Adicione o número ao grupo antes.

  • not_logged_in422Não repita

    O número não está logado no WhatsApp.

    O que fazer: Reconecte por QR code.

  • not_on_whatsapp422Não repita

    O telefone não tem WhatsApp.

    O que fazer: Confira o número.

  • not_supported_by_engine501Não repita

    O WhatsApp Web não oferece este recurso.

    O que fazer: Não repita; o recurso não existe nesta API.

  • number_blocked409Não repita

    O WhatsApp bloqueou o número; não dá para reconectar enquanto o bloqueio vale.

    O que fazer: Veja `last_connection_event.ban_expires_at` em `GET …/status` e tente depois do fim do bloqueio.

  • number_not_connected503, 422Pode repetir

    O número não está conectado ao WhatsApp agora.

    O que fazer: Confira `GET …/status`; reconecte e tente de novo.

  • number_not_found404Não repita

    O número não existe nesta conta.

    O que fazer: Confira o `instance_id`.

  • number_paused409Não repita

    Outra sessão do WhatsApp assumiu o número ou a versão foi recusada; reconectar pelo QR não resolve agora.

    O que fazer: Feche a outra sessão (WhatsApp Web ou outro aparelho) e use `POST …/restart`.

  • number_still_linked409Não repita

    O número continua ligado ao WhatsApp (conectado, reconectando ou fora do ar); não precisa ler o QR de novo.

    O que fazer: Use `POST …/restart` para reconectar sem QR, ou `POST …/disconnect` antes de parear outro telefone.

  • numbers_over_limit409Não repita

    A conta tem mais números que o plano permite; envios estão pausados.

    O que fazer: Exclua números ou mude de plano.

  • operation_failed422Não repita

    A operação falhou no WhatsApp sem motivo específico.

    O que fazer: Confira o pedido e o estado; repita só se fizer sentido.

  • operator_name_required409Não repita

    O número exige o nome de quem envia (assinatura obrigatória).

    O que fazer: Envie `operator_name` no envio.

  • operator_required403Não repita

    A ação precisa de uma pessoa operadora e a chave não age por ninguém.

    O que fazer: Use uma chave criada por uma pessoa da equipe.

  • opted_in_in_future400Não repita

    A data de consentimento está no futuro.

    O que fazer: Envie a data real do consentimento.

  • options_only_for_select422Não repita

    Opções só valem para campos de seleção.

    O que fazer: Retire `options` ou mude o tipo do campo.

  • options_required422Não repita

    Campos de seleção precisam de opções.

    O que fazer: Envie `options`.

  • organization_key_required403Não repita

    Rota de administração da conta: só uma chave da organização inteira serve; esta chave está presa a uma área de trabalho ou a um número.

    O que fazer: Use uma chave da organização inteira, criada por dona ou administradora da conta inteira e guardada no servidor.

  • organization_suspended403Não repita

    A conta está suspensa ou encerrada; nenhuma rota responde.

    O que fazer: Fale com a equipe FlowZap.

  • outcome_unknown502Não repita

    O WhatsApp pode ter aplicado a mudança ou não (resultado incerto).

    O que fazer: Não repita às cegas: confira o estado antes; repetir com a mesma `Idempotency-Key` devolve o mesmo resultado.

  • owner_or_admin_required403Não repita

    Só dono ou administrador pode fazer esta ação.

    O que fazer: Use uma chave de dono ou administrador.

  • owner_required403Não repita

    Só o dono da conta pode fazer esta ação.

    O que fazer: Use uma chave criada pelo dono.

  • pairing_recovery_required409Não repita

    O número precisa ser recuperado antes de parear de novo.

    O que fazer: Siga a recuperação do número no console.

  • payload_too_large413Não repita

    O corpo passa do limite da rota.

    O que fazer: Envie um corpo menor (mídia grande: upload binário).

  • picture_not_set422Não repita

    O contato ou grupo não tem foto.

    O que fazer: Nada a fazer.

  • plan_feature_required403Não repita

    O plano da conta não inclui este recurso (API ou MCP).

    O que fazer: Mude de plano.

  • post_lookup_failed422Pode repetir

    A publicação do canal não pôde ser localizada agora.

    O que fazer: Tente de novo mais tarde.

  • post_not_found422Não repita

    A publicação do canal não existe.

    O que fazer: Confira o `server_id`.

  • privacy_hidden422Não repita

    A privacidade do contato esconde esta informação.

    O que fazer: Não há o que fazer pela API.

  • privacy_token_missing422Não repita

    Falta o token de privacidade do contato para esta leitura.

    O que fazer: Converse com o contato primeiro.

  • private_chat_required400Não repita

    Esta ação só vale em conversa privada (não em grupo).

    O que fazer: Use um JID de pessoa.

  • provider_rate_limited503Pode repetir

    O provedor de pagamento limitou os pedidos.

    O que fazer: Tente mais tarde.

  • provider_rejectedenvioNão repita

    O WhatsApp recusou o envio (em `error_code` do envio).

    O que fazer: Revise destino e conteúdo; não reenvie igual.

  • proxy_host_not_allowed400Não repita

    O host do proxy não é permitido (rede privada).

    O que fazer: Use um proxy público.

  • push_name_missing422Não repita

    O contato não tem nome público.

    O que fazer: Nada a fazer.

  • qr_unavailable503Pode repetir

    O QR code ainda não está disponível.

    O que fazer: Tente de novo em alguns segundos.

  • queue_full429Pode repetir

    A fila do número já tem os envios aguardando que o plano permite.

    O que fazer: Espere o `Retry-After` e acompanhe a fila (`GET …/queue`).

  • range_not_satisfiable416Não repita

    O intervalo `Range` pedido está fora do arquivo.

    O que fazer: Peça um intervalo dentro do tamanho (`Content-Range`).

  • rate_limited429, 422Pode repetir

    Limite de pedidos ou de envios atingido.

    O que fazer: Espere o tempo de `Retry-After`.

  • readiness_check_failedenvioPode repetir

    A checagem antes do envio falhou e nada saiu (em `error_code` do envio).

    O que fazer: Reenvie.

  • reauth_failed403Não repita

    A confirmação de identidade falhou.

    O que fazer: Confirme a senha/MFA e tente de novo.

  • recipient_not_registeredenvioNão repita

    O destinatário não tem WhatsApp (em `error_code` do envio).

    O que fazer: Confira o número.

  • recipient_unknown422Não repita

    O Chatwoot pediu envio para um contato que o FlowZap não reconhece.

    O que fazer: Confira o contato/conversa no Chatwoot.

  • recording_module_required403Não repita

    O número não tem o módulo de gravações.

    O que fazer: Contrate o adicional de gravações.

  • recording_not_found404Não repita

    A ligação não tem gravação disponível; `reason` diz por quê: `not_recorded`, `failed`, `expired` ou `deleted`.

    O que fazer: Confira o `reason`; para guardar por mais tempo, baixe a gravação quando chegar `call.recording_ready`.

  • recording_not_ready409Não repita

    A gravação ainda está gravando ou sendo processada (`recording_state`: `recording` ou `processing`).

    O que fazer: Espere o evento `call.recording_ready` (ou `call.recording_failed`).

  • recording_quantity_exceeded409Não repita

    A escolha passa da quantidade de números com gravação contratada.

    O que fazer: Escolha menos números ou contrate mais.

  • recording_unavailable503Pode repetir

    A gravação não pôde ser lida agora.

    O que fazer: Tente mais tarde.

  • recordings_busy503Pode repetir

    Muitos downloads de gravação ao mesmo tempo.

    O que fazer: Tente de novo em alguns segundos.

  • recordings_unavailable503Pode repetir

    As gravações estão indisponíveis no momento.

    O que fazer: Tente mais tarde.

  • redelivery_limit_reached409Não repita

    A entrega de webhook já teve 10 rodadas.

    O que fazer: Leia o evento pela API.

  • rejected_by_whatsapp422Não repita

    O WhatsApp recusou o pedido.

    O que fazer: Revise o pedido.

  • renewal_checkout_unavailable409Não repita

    Não há checkout de renovação disponível para esse ciclo.

    O que fazer: Leia `GET /v1/billing/renewal-attention`.

  • renewal_conflict409Não repita

    A renovação já mudou enquanto o pedido rodava.

    O que fazer: Leia a assinatura e tente de novo, se ainda fizer sentido.

  • renewal_unavailable503Pode repetir

    A renovação está indisponível no momento.

    O que fazer: Tente mais tarde.

  • result_expired409, 410Não repita

    O resultado da operação já foi apagado (dados pessoais ficam 1 hora).

    O que fazer: Faça a leitura de novo.

  • retry503Pode repetir

    Conflito momentâneo ao gravar; nada foi alterado.

    O que fazer: Repita o pedido.

  • scope_denied403Não repita

    A chave não tem o escopo desta rota.

    O que fazer: Crie uma chave com o escopo (veja `x-scopes`).

  • self_removal_denied403Não repita

    A pessoa não pode remover a si mesma por aqui.

    O que fazer: Peça a outro administrador.

  • send_failed409Não repita

    O agendamento falhou ao enviar.

    O que fazer: Leia o agendamento e envie de novo se preciso.

  • send_prepare_failedenvioPode repetir

    O envio falhou antes de sair do aparelho (em `error_code` do envio).

    O que fazer: Reenvie (nada saiu).

  • send_unavailable503Pode repetir

    O envio não está liberado para a conta ou o número agora (assinatura ou vaga).

    O que fazer: Confira a assinatura e o número; tente mais tarde.

  • sender_required400, 422Não repita

    Informe quem enviou a mensagem alvo (`sender`), obrigatório em grupos.

    O que fazer: Envie o JID do autor.

  • session_disconnectedenvioPode repetir

    O número desconectou antes de enviar; nada saiu (em `error_code` do envio).

    O que fazer: Reconecte e reenvie.

  • shortcut_exists409Não repita

    Já existe uma resposta rápida com esse atalho.

    O que fazer: Use outro atalho.

  • slot_limit_reached429Não repita

    Não há vaga livre de número no plano.

    O que fazer: Libere uma vaga ou mude de plano.

  • slug_taken409Não repita

    O endereço (slug) do link já está em uso.

    O que fazer: Escolha outro.

  • stage_exists409Não repita

    Já existe uma etapa com esse nome.

    O que fazer: Use outro nome.

  • stream_token_expired401Não repita

    O token de fluxo (`?token=`) venceu (vale 5 minutos).

    O que fazer: Peça outro em `POST /v1/events/stream-token` e reconecte.

  • stream_token_requires_api_key403Não repita

    O token de fluxo só é emitido para chave de API (`fzk_`), não para token OAuth (`fzo_`).

    O que fazer: Com OAuth, abra `GET /v1/events/stream` com o cabeçalho `Authorization`; ou peça o token com uma chave de API.

  • tag_exists409Não repita

    Já existe uma etiqueta com esse nome.

    O que fazer: Use outro nome.

  • target_index_building503Pode repetir

    O índice para localizar a mensagem alvo ainda está sendo montado.

    O que fazer: Tente de novo em alguns segundos.

  • target_not_editable422Não repita

    Só mensagens enviadas pelo número podem ser editadas.

    O que fazer: Edite uma mensagem sua (até 15 minutos).

  • target_not_found404Não repita

    A mensagem alvo não foi encontrada neste número.

    O que fazer: Confira o ID da mensagem.

  • target_not_revocable422Não repita

    Mensagem de outra pessoa só é apagada para todos em grupo, por admin.

    O que fazer: Apague só mensagens suas ou, em grupo, como admin.

  • team_manager_required403Não repita

    Só quem administra a equipe pode fazer esta ação.

    O que fazer: Use uma chave de dono ou administrador.

  • template_name_exists409Não repita

    Já existe um modelo com esse nome.

    O que fazer: Use outro nome.

  • template_not_found404Não repita

    O modelo não existe.

    O que fazer: Confira o ID.

  • template_read_only403Não repita

    Modelo da organização não pode ser alterado por uma chave presa a área de trabalho.

    O que fazer: Use uma chave da organização.

  • ticket_already_open409Não repita

    Já há um atendimento aberto para essa conversa.

    O que fazer: Use o atendimento existente.

  • ticket_not_open409Não repita

    O atendimento não está aberto.

    O que fazer: Reabra antes.

  • ticket_pending409Não repita

    O atendimento está pendente; retire a pendência antes.

    O que fazer: Limpe a pendência e repita.

  • too_many_active_broadcasts409Não repita

    Limite de envios em grupos ativos ao mesmo tempo.

    O que fazer: Espere um terminar.

  • too_many_active_campaigns409Não repita

    Limite de campanhas ativas ao mesmo tempo.

    O que fazer: Espere uma terminar.

  • too_many_fields422Não repita

    Limite de campos personalizados atingido.

    O que fazer: Apague campos que não usa.

  • too_many_recipients422Não repita

    Destinatários demais para uma campanha.

    O que fazer: Divida em campanhas menores.

  • too_many_scheduled409Não repita

    Limite de agendamentos pendentes atingido.

    O que fazer: Espere ou cancele agendamentos.

  • too_many_stages422Não repita

    Limite de etapas do funil atingido.

    O que fazer: Apague etapas que não usa.

  • transport_ambiguousenvioNão repita

    A conexão falhou durante o envio: a mensagem pode ter saído (em `error_code`, estado `unknown`).

    O que fazer: Não reenvie às cegas; confira a conversa.

  • unauthorized401Não repita

    Chave ausente, inválida, revogada ou vencida.

    O que fazer: Envie `Authorization: Bearer fzk_…` com uma chave válida.

  • unavailable503Pode repetir

    O serviço está indisponível no momento.

    O que fazer: Tente de novo mais tarde (com a mesma `Idempotency-Key`, se houver).

  • unknown_neighbor422Não repita

    O vizinho informado para mover no funil não existe.

    O que fazer: Atualize o funil e repita.

  • unknown_stage422Não repita

    Etapa do funil desconhecida.

    O que fazer: Use um ID de `GET …/crm/pipeline`.

  • unknown_tag422Não repita

    Etiqueta de lead desconhecida.

    O que fazer: Use uma etiqueta existente.

  • unsafe_webhook_destination400Não repita

    A URL do webhook aponta para destino não permitido (rede privada, porta ou esquema).

    O que fazer: Use uma URL https pública.

  • unsupported_media_type415Não repita

    Tipo de arquivo não aceito para esse envio.

    O que fazer: Use um dos tipos aceitos.

  • use_message_routes404Não repita

    Esse ID é de mensagem; leia pelas rotas de mensagem.

    O que fazer: Use `GET /v1/messages/{id}` ou `GET …/inbound/{id}`.

  • user_not_member422Não repita

    A pessoa indicada não é da equipe.

    O que fazer: Use um ID de `GET /v1/team/members`.

  • voice_note_too_large413Não repita

    A nota de voz convertida passa do limite.

    O que fazer: Envie um áudio menor.

  • voice_note_too_long413Não repita

    A nota de voz é longa demais.

    O que fazer: Envie um áudio mais curto.

  • webhook_dns_unavailable503Pode repetir

    O DNS do endereço do webhook não respondeu agora.

    O que fazer: Tente de novo mais tarde.

  • webhook_secret_unavailable503Pode repetir

    O segredo do webhook não pôde ser aberto no servidor.

    O que fazer: Tente mais tarde; persistindo, troque o segredo ou fale com o suporte.

  • workspace_id_required400Não repita

    Falta `workspace_id` na consulta.

    O que fazer: Envie `?workspace_id=`.

  • workspace_slot_limit_reached429Não repita

    A área de trabalho chegou ao limite de números.

    O que fazer: Use outra área ou mude de plano.

Reconciliação e falhas

Três regras: toda escrita leva uma Idempotency-Key e, se a resposta se perder, repita o mesmo pedido com a mesma chave; resultado incerto nunca é reenviado às cegas; eventos são avisos e podem repetir ou faltar, então deduplique por event_id e, na dúvida, leia o recurso pela API. Os eventos ficam disponíveis por pelo menos 90 dias. O guia completo está em docs/api/reconciliacao.md.

Tempo esgotado ou resposta perdida num envio
Repita o mesmo pedido com a mesma Idempotency-Key: volta o mesmo envio (Idempotent-Replay: true), nunca dois. Sem o id, busque em GET /v1/messages?client_reference=…
Envio em unknown ou resposta 502
Pode ter saído. Não reenvie automaticamente: espere message.delivered/read, confira a conversa e só então decida, com chave nova.
failed, expired ou canceled
Nada saiu. Corrija a causa e envie de novo com chave nova.
Operação 202
Consulte GET /v1/operations/{id} a cada Retry-After segundos (ou use ?envelope=1). 504: nada foi feito, pode repetir.
Evento repetido ou fora de ordem
Trate cada event_id uma vez e ordene por sequence dentro do número; o estado atual está na API.
Webhook ou SSE fora do ar
Recupere pelo número com GET …/events?after_sequence=<último sequence>; reenvie entregas dead com POST /v1/webhook-deliveries/{id}/retry. Para manutenção, pause o endereço: os avisos ficam guardados até 7 dias.
Número caiu ou reiniciou
GET …/status traz disconnect_reason e GET …/capabilities diz se pode enviar. Novos envios recebem 503 até voltar; os já aceitos esperam até expires_at.
Dois atendentes na mesma ligação
Só o primeiro answer vale; o segundo recebe 409 call_already_answering. Não repita.

Guia de ligações

Para integrar um softphone ou uma central de atendimento às ligações de WhatsApp (beta). Tempos em UTC: requested_at, started_at (início do toque), answered_at, audio_connected_at e ended_at; wait_duration_ms é a espera, talk_duration_ms a conversa e duration_ms inclui o toque. Identidade: id (histórico), call_id (WhatsApp), media_session_id (igual ao operation_id), phone (formato internacional, null quando o WhatsApp não informou) e actor_label. O guia completo, com exemplos de eventos, está em docs/api/guia-ligacoes.md.

Liberar as ligações
Contratadas: contrate a quantidade (POST /v1/billing/addons/calls) ou use a da licença e escolha os números (PUT /v1/calls/numbers; cada número que mudou reconecta: now, later com retry_after_s ou not_connected). Piloto: a equipe FlowZap liga a liberação de teste e você define até 20 números de teste em PUT /v1/calls/test-numbers. Consulte em GET /v1/calls/numbers (trial), em calls.mode de GET …/capabilities e em GET …/calls/readiness, que diz por que o número não liga sem discar.
Que chave usar
Administração (números, origens, números de teste): chave da organização inteira com calls:admin, criada por dona ou administradora, só no servidor; chave presa a número recebe 403 organization_key_required e quem perdeu o papel, 403 owner_or_admin_required. Operação: chave presa ao número com calls:read e calls:write. Gravações: calls:recordings, à parte.
Origens do áudio
Cadastre a origem exata de cada sistema em POST /v1/calls/media-origins (até 10, https://host[:porta], sem curinga). A lista é por conta: homologação e produção são contas separadas. Página de outra origem: o WebSocket fecha com 4003 e o bilhete não é consumido.
Bilhete
Sai na resposta 202 de POST …/calls com audio e de …/answer (media.url). Vale 60 s e uma conexão; venceu antes de conectar, peça outro em POST …/calls/{media_session_id}/media-ticket ou repita o pedido com a mesma Idempotency-Key. O seu servidor chama a API e entrega ao navegador só media.url; a chave nunca vai para o navegador.
WebSocket
Binário PCM16 little-endian, mono, 16 kHz, quadros de 20 ms (640 bytes) nos dois sentidos; controle em JSON (state, ping, pong). 30 s sem receber nada fecham (4008): mande silêncio ou ping a cada 10 s. Fechamentos: 1000, 1001, 1013, 4001 (bilhete), 4003 (origem), 4008, 4009. Se cair, a ligação termina; não há retomada.
Navegador e celular
Orientação, não garantia testada: crie o AudioContext depois do clique, peça o microfone antes de chamar a API (exige HTTPS e permissão; microfone negado é erro do navegador, não da API), reamostre para 16 kHz e, no Android e no iOS, mantenha a tela da ligação aberta: segundo plano ou tela bloqueada podem suspender o áudio e derrubar o WebSocket.
Vários atendentes
O seu servidor recebe call.ringing (webhook ou SSE) e avisa os atendentes. O primeiro …/answer vence; os outros recebem 409 call_already_answering e param de tocar com esse 409 ou ao ver call.answered/call.ended. Mande actor_label para saber quem atendeu, recusou ou desligou.
Resposta perdida ou incerta
Repita com a mesma Idempotency-Key: volta a mesma operação, nunca uma segunda ligação. Em 502, consulte GET /v1/operations/{id} e GET …/calls/{callId}; nunca redisque para descobrir o resultado.

Situação da ligação

ringingcall.started, call.ringing
Chamando ou tocando. Feita com áudio: o telefone só toca depois que o seu WebSocket conecta.
answeredcall.answered
Atendida; a voz ainda não conectou. Recebida: só atende no WhatsApp depois que o seu WebSocket conecta.
in_progresscall.media_connected
A voz passa (audio_connected_at). Sem este evento, a ligação nunca teve voz.
completedcall.ended
Atendida e encerrada; ended_by diz quem desligou.
missed / no_answercall.ended
Ninguém atendeu em 45 s (recebida / feita).
declinedcall.ended
Recusada. O WhatsApp não informa ocupado: ocupado também aparece assim.
cancelledcall.ended
Encerrada antes do atendimento.
failedcall.ended
Falhou, por exemplo media_failed (o áudio não conectou).

O que fazer em cada situação

Chave, escopo ou papel
401 unauthorized (chave inválida, revogada ou vencida); 403 scope_denied (falta o escopo); 403 organization_key_required (chave presa a número em rota de administração); 403 owner_or_admin_required (quem criou a chave não é mais dona nem administradora); 403 organization_suspended (conta suspensa).
Número ou destino
403 calls_not_enabled (o número não tem ligações); 403 call_target_not_allowed (piloto: destino fora dos números de teste); 409 call_quantity_exceeded (escolha acima da quantidade contratada); 503 number_not_connected (número desconectado); 400 invalid_input ou operação com invalid_phone (telefone inválido).
Áudio
Origem recusada: o WebSocket fecha com 4003 (não é erro HTTP). Bilhete vencido ou usado: 4001, peça outro. Microfone negado: erro do navegador, a API não fica sabendo. Falha do áudio: media_failed na operação ou em call.ended. Sem áudio: não há código próprio; falta call.media_connected. Sem capacidade agora: 1013.
Estado da ligação
Operação com call_in_progress (o número já está numa ligação); 409 call_already_answering (outra pessoa atendeu); 409 call_not_ringing (já não toca); 409 call_ended (bilhete para ligação encerrada); 409 idempotency_conflict (mesma chave, outro conteúdo).
Limite, indisponibilidade e tempo
429 rate_limited: espere Retry-After. 503 engine_unavailable: repita depois. Sem resposta: repita com a mesma Idempotency-Key. 504 engine_timeout: nada foi feito. 502 outcome_unknown: consulte a operação e a ligação, nunca redisque.
Gravação
403 scope_denied sem calls:recordings; 409 recording_not_ready com recording_state (gravando ou convertendo); 404 recording_not_found com reason not_recorded (veja recording_state: skipped_off, skipped_quota), failed, expired ou deleted; 416 com Content-Range quando o Range está fora do arquivo.

Gravações e eventos

Ligar
Desligada por padrão, por número: GET/PUT …/call-recording. Só grava ligações com áudio pelo FlowZap. Cada ligação gravada começa com o aviso falado (LGPD), que a ligação pode dispensar com recording_notice: false; sem o aviso, a empresa informa a gravação de outra forma.
Prazo e espaço
Conta a partir de quando ficou pronta (retention_until): 7 dias sem o módulo Gravações no FlowZap, de 7 a 90 com ele. Reduzir encurta as já guardadas; aumentar não alonga. 10 GiB por conta; no limite, a ligação segue sem gravar (skipped_quota).
Baixar e apagar
GET …/calls/{callId}/recording com calls:recordings: Ogg/Opus estéreo 16 kHz, Range (206), HEAD, sem cache, cada download registrado. Ao receber call.recording_ready, guarde no seu armazenamento. DELETE apaga na hora e pode ser repetido; a ligação fica no histórico (deleted_reason: api).
Eventos
call.started, call.ringing, call.answered, call.media_connected, call.ended (com reason), call.recording_ready, call.recording_failed (failure_reason) e call.recording_deleted. O aviso traz só IDs, assinado; o conteúdo sai em GET /v1/events/{id}. Ordene por sequence no número e trate cada event_id uma vez.

Limitações

  • Só voz individual: sem vídeo, sem ligação em grupo, sem transferência.
  • Uma ligação por número por vez (call_in_progress).
  • 10 sessões de áudio simultâneas por organização; até 2 h por sessão.
  • A queda do WebSocket encerra a ligação; não há retomada.

Áreas de trabalho e operações

Uma organização tem áreas de trabalho, e cada área tem números. Rotas que dependem do WhatsApp podem responder 202; o resultado fica em /v1/operations/{id}. O convite de dono enviado pela equipe FlowZap é aberto e aceito sem chave de API.

  • GET
    /v1/account

    Ver plano, limites e uso da conta

    account:readDisponível
  • GET
    /v1/account/export

    Baixar os dados da conta

    account:readDisponível
  • GET
    /v1/workspaces

    Listar áreas de trabalho

    workspaces:readDisponível
  • GET
    /v1/workspaces/{workspaceId}

    Ler uma área de trabalho

    workspaces:readDisponível
  • GET
    /v1/operations/{id}

    Consultar uma operação

    engine:readDisponível
  • POST
    /v1/owner-invitations/preview

    Abrir um convite para ser dono

    sem chaveDisponível
  • POST
    /v1/owner-invitations/accept

    Aceitar um convite para ser dono

    sem chaveDisponível

Exemplo: Listar áreas de trabalho

Pedido
curl https://flowzap.flowpost.com.br/v1/workspaces \
  -H "Authorization: Bearer $FLOWZAP_KEY"
Resposta200 OK
{
  "data": [
    {
      "id": "8d3f2a61-4b7e-4c1a-9f0d-2e6b5c4a7d10",
      "organization_id": "5b0c9e7a-2f41-4d8b-a6c3-7e1f0d9b4a25",
      "name": "Atendimento"
    }
  ]
}

Números

Crie o número, reserve a vaga, leia o QR code e conecte pelo celular. Aqui também ficam a fila de envios, a pausa entre envios e o proxy próprio.

  • GET
    /v1/workspaces/{workspaceId}/instances

    Listar números

    instances:readDisponível
  • POST
    /v1/workspaces/{workspaceId}/instances

    Criar número

    instances:writeDisponível
  • POST
    {número}/reservations

    Reservar vaga para conectar

    instances:writeDisponível
  • GET
    {número}/status

    Situação do número (telefone e motivo da desconexão)

    instances:readDisponível
  • GET
    {número}/capabilities

    O que esta conexão pode fazer (capacidades)

    instances:readDisponível
  • PATCH
    {número}

    Renomear número

    engine:writeDisponível
  • DELETE
    {número}

    Excluir número

    engine:writeDisponível
  • POST
    {número}/connect

    Iniciar conexão por QR code

    engine:writeDisponível
  • GET
    {número}/qr

    Ler o QR code de pareamento

    engine:readDisponível
  • POST
    {número}/disconnect

    Desconectar (sair do WhatsApp)

    engine:writeDisponível
  • POST
    {número}/restart

    Reconectar a sessão

    engine:writeDisponível
  • GET
    {número}/limits

    Limites de novas conversas

    instances:readDisponível
  • GET
    {número}/queue

    Ver a fila de envios

    messages:readDisponível
  • DELETE
    {número}/queue

    Cancelar envios na fila

    messages:sendDisponível
  • GET
    {número}/settings/delay

    Ler intervalo entre envios

    engine:readDisponível
  • PUT
    {número}/settings/delay

    Definir intervalo entre envios

    engine:writeDisponível
  • GET
    {número}/settings/signature

    Ler assinatura do atendente

    engine:readDisponível
  • PUT
    {número}/settings/signature

    Ligar ou desligar assinatura do atendente

    engine:writeDisponível
  • GET
    {número}/settings/history

    Ler importação de histórico

    engine:readDisponível
  • PUT
    {número}/settings/history

    Ligar ou desligar importação de histórico

    engine:writeDisponível
  • GET
    {número}/proxy/managed

    Proxy gerenciado

    engine:readNão suportado pelo WhatsApp Web
  • GET
    {número}/proxy

    Ler proxy do número

    engine:readDisponível
  • PUT
    {número}/proxy

    Definir proxy do número

    engine:writeDisponível
  • DELETE
    {número}/proxy

    Remover proxy

    engine:writeDisponível

Exemplo: Ver a situação do número

Pedido
curl https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/status \
  -H "Authorization: Bearer $FLOWZAP_KEY"
Resposta200 OK
{
  "data": {
    "id": "c41e9b27-6a3d-4f58-b0e2-91d7f3a5c8e4",
    "name": "Vendas",
    "state": "active",
    "session_state": "connected",
    "connected": true,
    "phone_masked": "+55 11 9****-5678",
    "worker_alive": true,
    "lease_until": "2026-10-01T12:00:30.000Z",
    "reservation_state": "occupied",
    "reservation_expires_at": null,
    "created_at": "2026-09-28T14:03:11.000Z"
  }
}

Equipe

Convide, liste e remova pessoas da equipe com as mesmas regras do console. A chave age por quem a criou, com o papel dessa pessoa: convida no máximo administrador e nunca remove o dono. Transferir a propriedade da conta e gerenciar chaves continuam só no console.

  • GET
    /v1/team/members

    Listar pessoas da equipe

    team:readDisponível
  • DELETE
    /v1/team/members/{membershipId}

    Remover uma pessoa da equipe

    team:writeDisponível
  • GET
    /v1/team/invitations

    Listar convites da equipe

    team:readDisponível
  • POST
    /v1/team/invitations

    Convidar uma pessoa

    team:writeDisponível
  • DELETE
    /v1/team/invitations/{invitationId}

    Cancelar um convite

    team:writeDisponível

Exemplo: Convidar uma pessoa

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/team/invitations \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: convite-ana-2026-10" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@exemplo.com.br", "role": "operator", "workspace_id": null}'
Resposta201 Created
{
  "data": {
    "id": "3f6b1c2e-8a4d-4e7f-9b0a-1c2d3e4f5a6b",
    "email": "ana@exemplo.com.br",
    "role": "operator",
    "workspace_id": null
  }
}

Cobrança

Assinatura, ofertas, ligações, Gravações no FlowZap e pagamentos com as mesmas regras do console. A chave age por quem a criou, que precisa ser dono ou responsável pela cobrança da conta. O pagamento acontece sempre na página do Asaas: a resposta traz o link, e o cartão nunca passa pelo FlowZap.

  • GET
    /v1/billing/subscription

    Ver assinatura, faturas e pagamentos pendentes

    billing:readDisponível
  • GET
    /v1/billing/offers

    Listar ofertas de planos

    billing:readDisponível
  • GET
    /v1/billing/renewal-attention

    Ver pendências da renovação

    billing:readDisponível
  • GET
    /v1/billing/addons/calls

    Ver ligações contratadas

    billing:readDisponível
  • POST
    /v1/billing/addons/calls

    Mudar a quantidade de números com ligações

    billing:writeDisponível
  • GET
    /v1/billing/addons/recordings

    Ver Gravações no FlowZap contratadas

    billing:readDisponível
  • POST
    /v1/billing/addons/recordings

    Mudar a quantidade de números com Gravações no FlowZap

    billing:writeDisponível
  • POST
    /v1/billing/checkout/pix

    Contratar um plano por Pix

    billing:writeDisponível
  • POST
    /v1/billing/checkout/card

    Contratar um plano com cartão de crédito

    billing:writeDisponível
  • POST
    /v1/billing/renewal-cycles/{cycleId}/checkout/pix

    Pagar a renovação por Pix

    billing:writeDisponível
  • POST
    /v1/billing/subscription/renewal

    Encerrar (ou manter) a assinatura no fim do período

    billing:writeDisponível
  • POST
    /v1/billing/plan-changes/{changeId}/confirm

    Confirmar a mudança de plano agendada

    billing:writeDisponível

Exemplo: Contratar mais números com ligações

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/billing/addons/calls \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: ligacoes-mais-um-2026-10" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3, "method": "pix"}'
Resposta201 Created
{
  "data": {
    "result": "checkout",
    "change_id": "7c1e9a2b-3d4f-4a5b-8c6d-9e0f1a2b3c4d",
    "from_quantity": 2,
    "to_quantity": 3,
    "amount_minor": 2600,
    "method": "pix",
    "checkout_id": "a1b2c3d4-0000-4000-8000-000000000001",
    "link": "https://www.asaas.com/checkoutSession/show/a1b2c3d4-0000-4000-8000-000000000001"
  }
}

Mensagens e mídia

Um único endpoint envia todos os tipos: texto, imagem, vídeo, áudio, documento, figurinha, localização, contato, reação, enquete, botões, lista, edição, apagar, encaminhar e status, para telefone, grupo ou JID (inclusive LID). Mídia pode ir por upload, base64 ou link https; downloads aceitam intervalos de bytes (Range). Depois de um timeout, busque o envio pela sua referência em vez de reenviar. Apagar só para mim não é suportado.

  • POST
    {número}/messages

    Enviar mensagem

    messages:sendDisponível
  • GET
    /v1/messages

    Buscar envios por referência

    messages:readDisponível
  • GET
    /v1/messages/{id}

    Consultar um envio

    messages:readDisponível
  • GET
    /v1/messages/{id}/receipts

    Quem recebeu e leu (grupos)

    messages:readDisponível
  • POST
    {número}/media

    Enviar arquivo de mídia (upload)

    messages:sendDisponível
  • GET
    {número}/media/{id}

    Ler dados de uma mídia

    messages:readDisponível
  • GET
    {número}/media/{id}/content

    Baixar uma mídia enviada

    messages:readDisponível
  • DELETE
    {número}/media/{id}

    Apagar uma mídia

    messages:sendDisponível
  • GET
    {número}/inbound/{inboxId}/media

    Baixar mídia recebida

    messages:readDisponível
  • POST
    {número}/status-posts

    Publicar no Status

    engine:writeDisponível
  • GET
    {número}/status-posts

    Listar publicações no Status

    engine:readDisponível

Exemplo: Enviar uma imagem já carregada

Pedido
# 1. Envie o arquivo (corpo binário, até 16 MiB)
curl -X POST "https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/media?kind=image" \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @cardapio.jpg

# 2. Envie a mensagem com o id devolvido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/messages \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: cardapio-cliente-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "kind": "phone", "value": "+5511912345678" },
    "type": "image",
    "media": { "id": "3f9d0c52-8e1b-4a7f-b6d4-0c2e9a1f5b73" },
    "caption": "Cardápio de hoje",
    "expires_at": "2026-10-01T18:00:00Z"
  }'
Resposta202 Accepted
{
  "data": {
    "id": "e7a1c3d9-0b4f-4e62-9a85-1d3c7b2f6e04",
    "state": "queued",
    "provider_message_id": "3EB0A1B2C3D4E5F6071829",
    "client_reference": null,
    "expires_at": "2026-10-01T18:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z"
  }
}

Conversas e etiquetas

A leitura usa o histórico guardado pelo FlowZap (as 2000 mensagens mais recentes de cada origem). As ações (arquivar, fixar, silenciar, etiquetar) são feitas no WhatsApp do número.

  • GET
    {número}/chats

    Listar conversas

    messages:readDisponível
  • GET
    {número}/chats/count

    Contar conversas

    messages:readDisponível
  • POST
    {número}/conversations/links

    Juntar uma conversa sem telefone a um telefone

    messages:sendDisponível
  • DELETE
    {número}/conversations/links/{linkId}

    Desfazer o vínculo de uma conversa

    messages:sendDisponível
  • GET
    {número}/chats/{jid}/messages

    Mensagens de uma conversa

    messages:readDisponível
  • GET
    {número}/messages/search

    Buscar mensagens por texto

    messages:readDisponível
  • POST
    {número}/chats/{jid}/archive

    Arquivar ou desarquivar

    engine:writeDisponível
  • POST
    {número}/chats/{jid}/read

    Marcar conversa como lida ou não lida

    engine:writeDisponível
  • POST
    {número}/chats/{jid}/pin

    Fixar ou desafixar conversa

    engine:writeDisponível
  • POST
    {número}/chats/{jid}/mute

    Silenciar conversa

    engine:writeDisponível
  • DELETE
    {número}/chats/{jid}

    Apagar conversa no WhatsApp

    engine:writeDisponível
  • POST
    {número}/chats/{jid}/ephemeral

    Mensagens temporárias da conversa

    engine:writeDisponível
  • POST
    {número}/chats/{jid}/history-sync

    Pedir mensagens antigas ao celular

    engine:writeDisponível
  • POST
    {número}/messages/read

    Marcar mensagens como lidas

    engine:writeDisponível
  • POST
    {número}/messages/{messageId}/star

    Favoritar mensagem

    engine:writeDisponível
  • POST
    {número}/messages/{messageId}/pin

    Fixar mensagem na conversa

    engine:writeDisponível
  • GET
    {número}/labels

    Listar etiquetas do WhatsApp

    engine:readDisponível
  • POST
    {número}/labels

    Criar ou editar etiqueta

    engine:writeDisponível
  • DELETE
    {número}/labels/{labelId}

    Apagar etiqueta

    engine:writeDisponível
  • POST
    {número}/labels/refresh

    Sincronizar etiquetas com o celular

    engine:writeDisponível
  • GET
    {número}/chats/{jid}/labels

    Etiquetas de uma conversa

    engine:readDisponível
  • POST
    {número}/chats/{jid}/labels

    Aplicar ou tirar etiqueta da conversa

    engine:writeDisponível

Exemplo: Listar a conversa mais recente

Pedido
curl "https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/chats?limit=1" \
  -H "Authorization: Bearer $FLOWZAP_KEY"
Resposta200 OK
{
  "data": [
    {
      "jid": "5511912345678@s.whatsapp.net",
      "alt_jid": null,
      "is_group": false,
      "name": "Mariana Souza",
      "last_message": {
        "id": "3A5F09C2B1E4D7A8C6F0",
        "direction": "in",
        "kind": "text",
        "text": "Vocês abrem no sábado?",
        "timestamp": "2026-10-01T11:58:02.000Z"
      },
      "inbound_count": 4,
      "outbound_count": 3,
      "unread_count": 1,
      "last_activity_at": "2026-10-01T11:58:02.000Z"
    }
  ],
  "next_cursor": "WyIyMDI2LTEwLTAxVDExOjU4OjAyLjAwMFoiLCI1NTExOTEyMzQ1Njc4QHMud2hhdHNhcHAubmV0Il0",
  "window": { "rows_per_source": 2000, "truncated": false, "skipped": 0 }
}

Modelos e envios agendados

Avisos, cobranças e lembretes prontos: crie o modelo uma vez, com o nome da pessoa vindo do CRM ({{primeiro_nome}}) e variáveis preenchidas no envio ({{var:valor}}, {{var:link}}, {{var:data}}), e envie para uma pessoa na hora ou num horário marcado, de 1 minuto a 90 dias à frente. O envio passa pelas mesmas regras de POST …/messages, nunca sai duas vezes (nem se o serviço reiniciar) e, se o número estiver desconectado no horário, é tentado por 1 hora antes de virar falha com o motivo. Faltou variável: 422 com os nomes que faltam.

  • GET
    /v1/workspaces/{workspaceId}/message-templates

    Listar modelos

    messages:readDisponível
  • POST
    /v1/workspaces/{workspaceId}/message-templates

    Criar modelo

    messages:sendDisponível
  • GET
    /v1/workspaces/{workspaceId}/message-templates/{id}

    Ler um modelo

    messages:readDisponível
  • PUT
    /v1/workspaces/{workspaceId}/message-templates/{id}

    Alterar um modelo

    messages:sendDisponível
  • DELETE
    /v1/workspaces/{workspaceId}/message-templates/{id}

    Apagar um modelo

    messages:sendDisponível
  • POST
    {número}/messages/template

    Enviar por modelo (agora ou agendado)

    messages:sendDisponível
  • POST
    {número}/scheduled-messages

    Agendar mensagem

    messages:sendDisponível
  • GET
    {número}/scheduled-messages

    Listar mensagens agendadas

    messages:readDisponível
  • GET
    {número}/scheduled-messages/{id}

    Ler uma mensagem agendada

    messages:readDisponível
  • POST
    {número}/scheduled-messages/{id}/cancel

    Cancelar mensagem agendada

    messages:sendDisponível

Exemplo: Lembrete de Pix agendado por modelo

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/messages/template \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: fatura-2026-10" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "kind": "phone", "value": "+5511912345678" },
    "template_id": "2f1c9a54-6b0d-4c8e-9a7b-3d5e8f1a2b3c",
    "variables": { "valor": "R$ 189,90", "data": "20/10", "pix": "00020126580014br.gov.bcb.pix…" },
    "scheduled_at": "2026-10-19T09:00:00-03:00"
  }'
Resposta201 Created
{
  "data": {
    "id": "9d2b1f0e-7c3a-4e5b-8a6d-1f2e3d4c5b6a",
    "state": "scheduled",
    "to": { "kind": "phone", "value": "+5511912345678" },
    "scheduled_at": "2026-10-19T12:00:00.000Z",
    "message_type": "text",
    "preview": "Olá Ana, o pagamento de R$ 189,90 vence em 20/10. Pix copia e cola: 00020126580014br.gov.bcb.pix…",
    "template_id": "2f1c9a54-6b0d-4c8e-9a7b-3d5e8f1a2b3c",
    "template_name": "Lembrete de Pix",
    "client_reference": null,
    "attempts": 0,
    "error_code": null,
    "message_id": null,
    "message_state": null,
    "accepted_at": null,
    "canceled_at": null,
    "created_at": "2026-10-12T15:00:00.000Z"
  }
}

Grupos e comunidades

Criar e administrar grupos e comunidades. Cada rota é executada pelo número conectado e responde com o resultado do WhatsApp.

  • POST
    {número}/groups

    Criar grupo

    engine:writeDisponível
  • GET
    {número}/groups

    Listar grupos do número

    engine:readDisponível
  • POST
    {número}/groups/join

    Entrar em grupo por convite

    engine:writeDisponível
  • GET
    {número}/groups/invites/{code}

    Ver grupo pelo convite

    engine:readDisponível
  • GET
    {número}/groups/{jid}

    Dados do grupo e participantes

    engine:readDisponível
  • GET
    {número}/groups/{jid}/invite-link

    Link de convite

    engine:readDisponível
  • POST
    {número}/groups/{jid}/invite-link/reset

    Gerar novo link de convite

    engine:writeDisponível
  • POST
    {número}/groups/{jid}/leave

    Sair do grupo

    engine:writeDisponível
  • PUT
    {número}/groups/{jid}/name

    Renomear grupo

    engine:writeDisponível
  • PUT
    {número}/groups/{jid}/description

    Alterar descrição do grupo

    engine:writeDisponível
  • PUT
    {número}/groups/{jid}/announce

    Só administradores enviam

    engine:writeDisponível
  • PUT
    {número}/groups/{jid}/locked

    Só administradores editam o grupo

    engine:writeDisponível
  • PUT
    {número}/groups/{jid}/join-approval

    Aprovar entrada pelo link

    engine:writeDisponível
  • PUT
    {número}/groups/{jid}/member-add-mode

    Quem pode adicionar membros

    engine:writeDisponível
  • PUT
    {número}/groups/{jid}/ephemeral

    Mensagens temporárias do grupo

    engine:writeDisponível
  • PUT
    {número}/groups/{jid}/image

    Trocar foto do grupo

    engine:writeDisponível
  • POST
    {número}/groups/{jid}/participants

    Adicionar, remover, promover ou rebaixar

    engine:writeDisponível
  • POST
    {número}/groups/{jid}/invite-message

    Enviar convite individual

    engine:writeDisponível
  • GET
    {número}/groups/{jid}/requests

    Pedidos de entrada pendentes

    engine:readDisponível
  • POST
    {número}/groups/{jid}/requests

    Aprovar ou recusar pedidos de entrada

    engine:writeDisponível
  • POST
    {número}/communities

    Criar comunidade

    engine:writeDisponível
  • GET
    {número}/communities/{jid}/groups

    Grupos de uma comunidade

    engine:readDisponível
  • POST
    {número}/communities/{jid}/groups

    Vincular ou desvincular grupos

    engine:writeDisponível

Exemplo: Criar um grupo

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/groups \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: grupo-clientes-vip" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Clientes VIP", "participants": ["+5511912345678"] }'
Resposta200 OK
{
  "data": {
    "jid": "120363025246125888@g.us",
    "name": "Clientes VIP",
    "topic": "",
    "owner": "5511955554444@s.whatsapp.net",
    "owner_phone": "+5511955554444",
    "created_at": "2026-10-01T12:00:00Z",
    "participant_count": 2,
    "addressing_mode": "pn",
    "is_admin": true,
    "announce": false,
    "locked": false,
    "join_approval": false,
    "member_add_mode": "admins",
    "ephemeral_seconds": 0,
    "is_community": false,
    "parent_jid": null,
    "is_default_subgroup": false,
    "suspended": false,
    "participants": [
      {
        "jid": "5511955554444@s.whatsapp.net",
        "phone": "+5511955554444",
        "phone_source": "jid",
        "lid": "203841779187761@lid",
        "is_admin": true,
        "is_super_admin": true,
        "is_me": true,
        "masked_phone": null
      },
      {
        "jid": "5511912345678@s.whatsapp.net",
        "phone": "+5511912345678",
        "phone_source": "jid",
        "lid": null,
        "is_admin": false,
        "is_super_admin": false,
        "is_me": false,
        "display_name": "Ana Souza",
        "masked_phone": null
      }
    ]
  }
}

Contatos e perfil

Verifique quem tem WhatsApp, leia contatos e fotos, bloqueie, recuse chamadas e ajuste perfil, privacidade e presença do número.

  • GET
    {número}/contacts

    Listar contatos da agenda

    engine:readDisponível
  • POST
    {número}/contacts/check

    Verificar se telefones têm WhatsApp

    engine:readDisponível
  • POST
    {número}/contacts

    Adicionar contato à agenda

    engine:writeNão suportado pelo WhatsApp Web
  • DELETE
    {número}/contacts/{jid}

    Remover contato da agenda

    engine:writeNão suportado pelo WhatsApp Web
  • GET
    {número}/contacts/{jid}

    Dados de um contato

    engine:readDisponível
  • GET
    {número}/contacts/{jid}/avatar

    Foto de perfil de um contato

    engine:readDisponível
  • POST
    {número}/contacts/{jid}/block

    Bloquear ou desbloquear

    engine:writeDisponível
  • GET
    {número}/blocklist

    Lista de bloqueados

    engine:readDisponível
  • GET
    {número}/profile

    Perfil do próprio número

    engine:readDisponível
  • PUT
    {número}/profile/name

    Alterar nome de exibição

    engine:writeDisponível
  • PUT
    {número}/profile/status

    Alterar recado (sobre)

    engine:writeDisponível
  • PUT
    {número}/profile/image

    Trocar foto de perfil

    engine:writeDisponível
  • GET
    {número}/privacy

    Ler configurações de privacidade

    engine:readDisponível
  • PUT
    {número}/privacy

    Alterar uma configuração de privacidade

    engine:writeDisponível
  • POST
    {número}/presence

    Ficar online ou offline

    engine:writeDisponível
  • POST
    {número}/presence/chat

    Mostrar digitando ou gravando

    engine:writeDisponível
  • POST
    {número}/presence/subscribe

    Acompanhar presença de um contato

    engine:writeDisponível

Exemplo: Verificar quem tem WhatsApp

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/contacts/check \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phones": ["+5511912345678", "+5511900000000"] }'
Resposta200 OK
{
  "data": {
    "items": [
      {
        "phone": "+5511912345678",
        "exists": true,
        "jid": "5511912345678@s.whatsapp.net",
        "lid": null,
        "verified_name": null
      },
      {
        "phone": "+5511900000000",
        "exists": false,
        "jid": null,
        "lid": null,
        "verified_name": null
      }
    ]
  }
}

Lançamento em grupos

Para lançamentos em grupos de WhatsApp: a mesma mensagem para vários grupos que o seu número administra, com pausa entre grupos, limite diário e pausa automática se muitas falharem; e um link público que leva cada pessoa ao primeiro grupo com vaga, lendo as vagas no WhatsApp no máximo a cada 2 minutos e criando o próximo grupo sozinho quando todos lotam (se você ligar). Grupos em que o número só participa não recebem envios: são os seus grupos. Os cliques são só números por grupo, sem dados de quem clicou.

  • POST
    {número}/group-broadcasts

    Enviar mensagem a vários grupos administrados

    messages:sendDisponível
  • GET
    {número}/group-broadcasts

    Listar envios para grupos

    messages:readDisponível
  • GET
    {número}/group-broadcasts/{id}

    Ler um envio para grupos

    messages:readDisponível
  • GET
    {número}/group-broadcasts/{id}/report

    Resultado por grupo

    messages:readDisponível
  • POST
    {número}/group-broadcasts/{id}/pause

    Pausar envio para grupos

    messages:sendDisponível
  • POST
    {número}/group-broadcasts/{id}/resume

    Retomar envio para grupos

    messages:sendDisponível
  • POST
    {número}/group-broadcasts/{id}/cancel

    Cancelar envio para grupos

    messages:sendDisponível
  • POST
    {número}/launch-links

    Criar link de lançamento

    engine:writeDisponível
  • GET
    {número}/launch-links

    Listar links de lançamento

    engine:readDisponível
  • GET
    {número}/launch-links/{id}

    Ler um link de lançamento

    engine:readDisponível
  • PUT
    {número}/launch-links/{id}

    Alterar link de lançamento

    engine:writeDisponível
  • DELETE
    {número}/launch-links/{id}

    Apagar link de lançamento

    engine:writeDisponível

Exemplo: Um link que enche três grupos em ordem

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/launch-links \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: link-outubro-01" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "lancamento-outubro",
    "name": "Lançamento de outubro",
    "groups": ["120363000000000001@g.us", "120363000000000002@g.us", "120363000000000003@g.us"],
    "cap": 500
  }'
Resposta201 Created
{
  "data": {
    "id": "8c0b6a1e-3f2d-4c5b-9a7e-1d2c3b4a5f60",
    "slug": "lancamento-outubro",
    "url": "https://flowzap.flowpost.com.br/g/lancamento-outubro",
    "cap": 500,
    "active": true,
    "clicks": 0,
    "current_group_jid": "120363000000000001@g.us",
    "groups": [
      { "group_jid": "120363000000000001@g.us", "participant_count": 312, "full": false, "invite_ready": true }
    ]
  }
}

Ligações

Beta, para números com ligações. Faça, atenda, recuse, desligue e silencie ligações do número. Com áudio, a resposta traz um bilhete (60 s, uso único) para o WebSocket de áudio: PCM16 mono 16 kHz, quadros de 20 ms (640 bytes) nos dois sentidos; softphones web em outro domínio são liberados por origem exata. Cada ligação recebida é atendida uma vez: o segundo atendimento recebe 409 call_already_answering. As ações de ligação aceitam calls:write (ou engine:write, em chaves antigas). Escolha quais números da conta têm ligações dentro da quantidade contratada. Consulte o histórico de ligações e, com a gravação ligada no número (aviso falado no início, que o número ou cada ligação pode dispensar com recording_notice), baixe o áudio por 7 dias, ou até 90 com o módulo Gravações no FlowZap.

  • POST
    {número}/calls

    Fazer ligação (de teste ou com áudio)

    calls:writeDisponível
  • POST
    {número}/calls/{callId}/answer

    Atender ligação (uma vez; com ou sem aviso de gravação)

    calls:writeDisponível
  • POST
    {número}/calls/{callId}/decline

    Recusar ligação que está tocando

    calls:writeDisponível
  • POST
    {número}/calls/{callId}/hangup

    Desligar ligação

    calls:writeDisponível
  • POST
    {número}/calls/{callId}/mute

    Silenciar ou reativar o áudio enviado

    calls:writeDisponível
  • POST
    {número}/calls/{callId}/media-ticket

    Novo bilhete de áudio

    calls:writeDisponível
  • POST
    {número}/calls/{callId}/reject

    Recusar chamada recebida no celular

    calls:writeDisponível
  • GET
    {número}/calls

    Histórico de ligações do número

    calls:readDisponível
  • GET
    {número}/calls/{callId}

    Ver ligação

    calls:readDisponível
  • GET
    {número}/calls/{callId}/recording

    Baixar a gravação (Ogg/Opus, aceita Range)

    calls:recordingsDisponível
  • DELETE
    {número}/calls/{callId}/recording

    Apagar a gravação

    calls:write + calls:recordingsDisponível
  • GET
    {número}/call-recording

    Ver a gravação das ligações do número

    calls:readDisponível
  • PUT
    {número}/call-recording

    Ligar ou desligar a gravação e o aviso falado padrão

    calls:writeDisponível
  • GET
    /v1/calls/numbers

    Ver os números com ligações

    calls:readDisponível
  • PUT
    /v1/calls/numbers

    Escolher os números com ligações

    calls:writeDisponível

Exemplo: Fazer uma ligação com áudio

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/calls \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: ligacao-0042" \
  -H "Content-Type: application/json" \
  -d '{"to": "+5511912345678", "audio": true}'
Resposta202 Accepted
{
  "data": {
    "operation_id": "5b0f3c2e-8d41-4a7e-9c16-2f7e1d9a4b30",
    "state": "queued",
    "media_session_id": "5b0f3c2e-8d41-4a7e-9c16-2f7e1d9a4b30",
    "media": {
      "url": "wss://flowzap.flowpost.com.br/v1/calls/media?ticket=…",
      "ticket": "…",
      "expires_at": "2026-10-10T12:01:00.000Z"
    }
  }
}

Ligações: administração da conta

Beta. Com uma chave da organização inteira, de dona ou administradora da conta inteira, guardada no servidor (chave presa a área de trabalho ou número: 403 organization_key_required): libere até 10 origens exatas (https://host[:porta]) para o áudio das ligações no navegador, defina até 20 números de teste do piloto enquanto ele estiver ligado e veja se um número está pronto para fazer e atender ligações, com o motivo objetivo quando não estiver. Alterações pedem calls:admin (nunca concedido por OAuth) e ficam registradas; consultas aceitam calls:read.

  • GET
    /v1/calls/media-origins

    Ver as origens do áudio no navegador

    calls:readDisponível
  • POST
    /v1/calls/media-origins

    Cadastrar uma origem do áudio no navegador

    calls:adminDisponível
  • DELETE
    /v1/calls/media-origins

    Remover uma origem do áudio no navegador

    calls:adminDisponível
  • GET
    /v1/calls/test-numbers

    Ver os números de teste do piloto

    calls:readDisponível
  • PUT
    /v1/calls/test-numbers

    Definir os números de teste do piloto

    calls:adminDisponível
  • GET
    {número}/calls/readiness

    Ver se o número está pronto para ligações

    calls:readDisponível

Exemplo: Liberar a origem de produção para o áudio

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/calls/media-origins \
  -H "Authorization: Bearer $FLOWZAP_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin": "https://app.exemplo.com.br"}'
Resposta201 Created
{
  "data": {
    "limit": 10,
    "origins": [
      {
        "origin": "https://app.exemplo.com.br",
        "created_at": "2026-11-03T13:12:00.000Z"
      }
    ]
  }
}

Canais

Canais (newsletters) do WhatsApp: seguir, ler, reagir, criar e publicar texto. Pesquisa pública e administração de canais não existem no WhatsApp Web.

  • GET
    {número}/newsletters/search

    Pesquisar canais públicos

    engine:readNão suportado pelo WhatsApp Web
  • POST
    {número}/newsletters/{jid}/admins

    Convidar administrador do canal

    engine:writeNão suportado pelo WhatsApp Web
  • POST
    {número}/newsletters

    Criar canal

    engine:writeDisponível
  • GET
    {número}/newsletters

    Canais que o número segue

    engine:readDisponível
  • GET
    {número}/newsletters/invites/{code}

    Ver canal pelo convite

    engine:readDisponível
  • GET
    {número}/newsletters/{jid}

    Dados do canal

    engine:readDisponível
  • GET
    {número}/newsletters/{jid}/messages

    Publicações do canal

    engine:readDisponível
  • GET
    {número}/newsletters/{jid}/updates

    Novidades (visualizações e reações)

    engine:readDisponível
  • POST
    {número}/newsletters/{jid}/follow

    Seguir ou deixar de seguir

    engine:writeDisponível
  • POST
    {número}/newsletters/{jid}/mute

    Silenciar canal

    engine:writeDisponível
  • POST
    {número}/newsletters/{jid}/viewed

    Marcar publicações como vistas

    engine:writeDisponível
  • POST
    {número}/newsletters/{jid}/reaction

    Reagir a uma publicação

    engine:writeDisponível
  • POST
    {número}/newsletters/{jid}/live

    Receber novidades ao vivo

    engine:writeDisponível
  • POST
    {número}/newsletters/{jid}/posts

    Publicar texto no canal

    engine:writeDisponível
  • PUT
    {número}/newsletters/{jid}/posts/{serverId}

    Editar publicação

    engine:writeDisponível
  • DELETE
    {número}/newsletters/{jid}/posts/{serverId}

    Apagar publicação

    engine:writeDisponível

Exemplo: Publicar texto num canal seu

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/newsletters/120363144038483540@newsletter/posts \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: canal-promo-sexta" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Sexta tem frete grátis para todo o Brasil." }'
Resposta200 OK
{
  "data": {
    "jid": "120363144038483540@newsletter",
    "id": "3EB0B7C2D9E4F1A6038571",
    "server_id": 128,
    "timestamp": "2026-10-01T12:00:01Z"
  }
}

Perfil comercial

Leitura do perfil comercial do número ou de um contato. Catálogo e edição do perfil não existem no WhatsApp Web: as rotas respondem 501.

  • PUT
    {número}/business/profile

    Editar perfil comercial

    engine:writeNão suportado pelo WhatsApp Web
  • GET
    {número}/business/catalog

    Listar catálogo

    engine:readNão suportado pelo WhatsApp Web
  • POST
    {número}/business/catalog

    Criar produto

    engine:writeNão suportado pelo WhatsApp Web
  • GET
    {número}/business/catalog/{productId}

    Ler produto

    engine:readNão suportado pelo WhatsApp Web
  • PUT
    {número}/business/catalog/{productId}

    Editar produto

    engine:writeNão suportado pelo WhatsApp Web
  • DELETE
    {número}/business/catalog/{productId}

    Apagar produto

    engine:writeNão suportado pelo WhatsApp Web
  • GET
    {número}/business/profile

    Perfil comercial do próprio número

    engine:readDisponível
  • GET
    {número}/business/profile/{jid}

    Perfil comercial de um contato

    engine:readDisponível

Exemplo: Ler o perfil comercial de um contato

Pedido
curl https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/business/profile/5511955554444@s.whatsapp.net \
  -H "Authorization: Bearer $FLOWZAP_KEY"
Resposta200 OK
{
  "data": {
    "jid": "5511955554444@s.whatsapp.net",
    "address": "Rua das Flores, 100 — São Paulo",
    "email": "contato@loja.example",
    "categories": [{ "id": "1001", "name": "Loja de roupas" }],
    "profile_options": {},
    "business_hours": null
  }
}

Eventos, webhooks e SSE

Três formas de acompanhar o que acontece: webhook assinado (com filtro por tipo e número, pausa sem perda, teste e reenvio), fluxo SSE (também no navegador, com token curto) ou leitura em ordem por número. Os avisos trazem só o tipo e os IDs; o conteúdo é lido pela API. Ordene por sequence dentro do número e trate cada event_id uma vez; calls:read lê os eventos de ligação e crm:read os de atendimento e funil.

  • GET
    /v1/events/stream

    Receber eventos ao vivo (SSE)

    engine:readDisponível
  • POST
    /v1/events/stream-token

    Token curto (5 min) para o fluxo SSE no navegador

    engine:readDisponível
  • GET
    /v1/events/{id}

    Ler um evento (motor, atendimento, funil ou gravação)

    engine:readDisponível
  • GET
    {número}/events

    Eventos de um número, em ordem

    engine:readDisponível
  • GET
    {número}/inbound

    Mensagens recebidas

    engine:readDisponível
  • GET
    {número}/inbound/{id}

    Ler uma mensagem recebida

    engine:readDisponível
  • POST
    /v1/webhook-endpoints

    Cadastrar endereço de webhook

    webhooks:writeDisponível
  • GET
    /v1/webhook-endpoints

    Listar endereços de webhook

    webhooks:readDisponível
  • GET
    /v1/webhook-endpoints/{id}

    Ver um endereço de webhook

    webhooks:readDisponível
  • PATCH
    /v1/webhook-endpoints/{id}

    Alterar endereço, filtros ou pausar/reativar

    webhooks:writeDisponível
  • POST
    /v1/webhook-endpoints/{id}/ping

    Testar o endereço (aviso webhook.ping)

    webhooks:writeDisponível
  • DELETE
    /v1/webhook-endpoints/{id}

    Remover endereço de webhook

    webhooks:writeDisponível
  • POST
    /v1/webhook-endpoints/{id}/rotate-secret

    Trocar o segredo de um webhook

    webhooks:writeDisponível
  • GET
    /v1/webhook-deliveries

    Histórico de entregas, com filtros e cursor

    webhooks:readDisponível
  • POST
    /v1/webhook-deliveries/{id}/retry

    Reenviar uma entrega de webhook

    webhooks:writeDisponível

Exemplo: Conferir a assinatura de um webhook (Node.js)

Código de verificação
import { createHmac, timingSafeEqual } from "node:crypto";

// raw: corpo exato recebido (Buffer); secret: o "secret" do cadastro.
// Nas 24 h depois de trocar o segredo, X-Flow-Signature traz dois valores
// separados por vírgula (novo e anterior): vale se um deles conferir.
export function assinaturaValida(headers, raw, secret) {
  const timestamp = headers["x-flow-timestamp"];
  const eventId = headers["x-flow-event-id"];
  const idade = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!(idade <= 300)) return false;
  const esperado = createHmac("sha256", Buffer.from(secret, "base64url"))
    .update(`${timestamp}.${eventId}.`)
    .update(raw)
    .digest();
  return String(headers["x-flow-signature"]).split(",").some((valor) => {
    const [versao, , hex] = valor.trim().split(":");
    const recebido = Buffer.from(hex ?? "", "hex");
    return (
      versao === "v1" &&
      recebido.length === esperado.length &&
      timingSafeEqual(recebido, esperado)
    );
  });
}
Aviso recebidoPOST no seu endereço
{
  "event_id": "4c2b8e1f-7a93-4d05-b6e8-2f1a0c9d3b57",
  "schema_version": "1.0",
  "type": "message.received",
  "occurred_at": "2026-10-01T12:00:00.000Z",
  "organization_id": "5b0c9e7a-2f41-4d8b-a6c3-7e1f0d9b4a25",
  "workspace_id": "8d3f2a61-4b7e-4c1a-9f0d-2e6b5c4a7d10",
  "instance_id": "c41e9b27-6a3d-4f58-b0e2-91d7f3a5c8e4",
  "sequence": 42,
  "data": { "resource_id": "9e3d7c1a-5b2f-4e80-a4c6-0d8b1f2e7a39" }
}

CRM e respostas rápidas

Leads por número, com consentimento registrado (data e origem), etiquetas de lead, anotações e respostas rápidas. São dados do FlowZap, cifrados, e não mudam nada no WhatsApp.

  • GET
    {número}/crm/leads

    Listar leads

    engine:readDisponível
  • GET
    {número}/crm/leads/{contact}

    Ler um lead

    engine:readDisponível
  • PUT
    {número}/crm/leads/{contact}

    Criar ou atualizar lead

    engine:writeDisponível
  • DELETE
    {número}/crm/leads/{contact}

    Apagar lead

    engine:writeDisponível
  • POST
    {número}/crm/leads/{contact}/opt-out

    Registrar saída da lista (opt-out)

    engine:writeDisponível
  • GET
    {número}/crm/leads/{contact}/notes

    Anotações do lead

    engine:readDisponível
  • POST
    {número}/crm/leads/{contact}/notes

    Criar anotação

    engine:writeDisponível
  • DELETE
    {número}/crm/notes/{id}

    Apagar anotação

    engine:writeDisponível
  • GET
    {número}/crm/tags

    Listar etiquetas de lead

    engine:readDisponível
  • POST
    {número}/crm/tags

    Criar etiqueta de lead

    engine:writeDisponível
  • DELETE
    {número}/crm/tags/{id}

    Apagar etiqueta de lead

    engine:writeDisponível
  • GET
    {número}/quick-replies

    Listar respostas rápidas

    engine:readDisponível
  • POST
    {número}/quick-replies

    Criar resposta rápida

    engine:writeDisponível
  • PUT
    {número}/quick-replies/{id}

    Editar resposta rápida

    engine:writeDisponível
  • DELETE
    {número}/quick-replies/{id}

    Apagar resposta rápida

    engine:writeDisponível

Exemplo: Registrar um lead com consentimento

Pedido
curl -X PUT https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/crm/leads/%2B5511912345678 \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mariana Souza",
    "status": "cliente",
    "opted_in": { "at": "2026-09-30T15:20:00Z", "source": "formulário do site" }
  }'
Resposta201 Created
{
  "data": {
    "id": "a6f0d2c4-91b3-4e7a-8c15-3d9e2b7f0a61",
    "contact": "+5511912345678",
    "name": "Mariana Souza",
    "status": "cliente",
    "assigned_user_id": null,
    "tags": [],
    "fields": {},
    "opted_in": { "at": "2026-09-30T15:20:00.000Z", "source": "formulário do site" },
    "opted_out_at": null,
    "consented": true,
    "created_at": "2026-10-01T12:00:00.000Z",
    "updated_at": "2026-10-01T12:00:00.000Z"
  }
}

Campanhas

Envio em massa só para quem deu consentimento, com variações de texto, personalização ({{primeiro_nome|cliente}}), limite diário por número, janela de envio, pausa automática de segurança, painéis e pausar, retomar e cancelar.

  • POST
    {número}/campaigns

    Criar campanha

    messages:sendDisponível
  • GET
    {número}/campaigns

    Listar campanhas

    messages:readDisponível
  • GET
    {número}/campaigns/summary

    Painel de campanhas do número

    messages:readDisponível
  • GET
    {número}/campaigns/{id}

    Ler campanha e contagens

    messages:readDisponível
  • GET
    {número}/campaigns/{id}/recipients

    Destinatários e resultado

    messages:readDisponível
  • GET
    {número}/campaigns/{id}/report

    Painel da campanha

    messages:readDisponível
  • POST
    {número}/campaigns/{id}/pause

    Pausar campanha

    messages:sendDisponível
  • POST
    {número}/campaigns/{id}/resume

    Retomar campanha

    messages:sendDisponível
  • POST
    {número}/campaigns/{id}/cancel

    Cancelar campanha

    messages:sendDisponível

Exemplo: Agendar uma campanha para uma etiqueta de leads

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/campaigns \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: campanha-reabertura-outubro" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aviso de reabertura",
    "message": { "type": "text" },
    "variants": [
      { "text": "Oi, {{primeiro_nome|cliente}}! Reabrimos no sábado, das 9h às 18h." },
      { "text": "{{primeiro_nome|Olá}}, voltamos: sábado, das 9h às 18h." }
    ],
    "recipients": { "tag_id": "d1b7e4a2-6c30-4f9e-8a51-2e7c0b9d4f36" },
    "scheduled_at": "2026-10-02T12:00:00Z",
    "respect_business_hours": true,
    "daily_limit": 150
  }'
Resposta201 Created
{
  "data": {
    "id": "f2c8a0e6-3d71-4b95-9e24-7a1c5d0b8e43",
    "name": "Aviso de reabertura",
    "message_type": "text",
    "state": "scheduled",
    "pause_reason": null,
    "scheduled_at": "2026-10-02T12:00:00.000Z",
    "next_send_at": "2026-10-02T12:00:00.000Z",
    "delay_ms": { "min": 5000, "max": 15000 },
    "respect_business_hours": true,
    "window": { "days": [1, 2, 3, 4, 5, 6], "start": "08:00", "end": "20:00", "tz": "America/Sao_Paulo" },
    "daily_limit": 150,
    "variant_count": 2,
    "total_recipients": 120,
    "skipped_unconsented": 0,
    "created_at": "2026-10-01T12:00:00.000Z",
    "started_at": null,
    "finished_at": null
  }
}

Chatwoot, n8n e Make

O Chatwoot se liga por número: as mensagens chegam na caixa de entrada e as respostas dos atendentes saem pelo WhatsApp. n8n e Make usam os webhooks e a API: recebem o aviso, conferem a assinatura, buscam a mensagem e respondem.

  • GET
    {número}/chatwoot

    Ler integração com o Chatwoot

    engine:readDisponível
  • PUT
    {número}/chatwoot

    Ligar ou alterar integração com o Chatwoot

    engine:writeDisponível
  • DELETE
    {número}/chatwoot

    Remover integração com o Chatwoot

    engine:writeDisponível
  • POST
    /v1/chatwoot/hooks/{token}

    Webhook chamado pelo Chatwoot

    sem chaveDisponível

Exemplo: Ligar o Chatwoot a um número

Pedido
curl -X PUT https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/chatwoot \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://chatwoot.suaempresa.com.br",
    "account_id": 1,
    "inbox_id": 7,
    "api_access_token": "<token de acesso do Chatwoot>",
    "enabled": true
  }'
Resposta200 OK
{
  "data": {
    "instance_id": "c41e9b27-6a3d-4f58-b0e2-91d7f3a5c8e4",
    "url": "https://chatwoot.suaempresa.com.br",
    "account_id": 1,
    "inbox_id": 7,
    "api_access_token": "****x9Qa",
    "enabled": true,
    "sign_messages": false,
    "reopen_conversation": true,
    "ignore_groups": true,
    "webhook_url": "https://flowzap.flowpost.com.br/v1/chatwoot/hooks/<token>",
    "last_error_code": null,
    "last_error_at": null,
    "created_at": "2026-10-01T12:00:00.000Z",
    "updated_at": "2026-10-01T12:00:00.000Z"
  }
}

Funil e atendimentos

O funil de contatos por etapa (kanban), com campos personalizados, e os atendimentos de cada conversa: Aberto ou Resolvido, com responsável e pesquisa de satisfação de 1 a 5. Um grupo também pode ter atendimento, aberto à mão (contato group:<jid>), sem funil e sem pesquisa. Mudanças geram eventos de webhook (ticket.opened, ticket.resolved, lead.stage_changed, csat.answered…).

  • GET
    {número}/crm/stages

    Listar etapas do funil

    crm:readDisponível
  • POST
    {número}/crm/stages

    Criar etapa

    crm:writeDisponível
  • PATCH
    {número}/crm/stages/{id}

    Alterar etapa

    crm:writeDisponível
  • DELETE
    {número}/crm/stages/{id}

    Apagar etapa

    crm:writeDisponível
  • GET
    {número}/crm/pipeline

    Ver funil

    crm:readDisponível
  • POST
    {número}/crm/leads/{contact}/move

    Mover contato de etapa

    crm:writeDisponível
  • GET
    {número}/crm/fields

    Listar campos personalizados

    crm:readDisponível
  • POST
    {número}/crm/fields

    Criar campo personalizado

    crm:writeDisponível
  • PATCH
    {número}/crm/fields/{id}

    Alterar campo personalizado

    crm:writeDisponível
  • DELETE
    {número}/crm/fields/{id}

    Apagar campo personalizado

    crm:writeDisponível
  • GET
    {número}/tickets

    Listar atendimentos

    crm:readDisponível
  • POST
    {número}/tickets

    Abrir atendimento

    crm:writeDisponível
  • GET
    {número}/tickets/csat-summary

    Resumo da pesquisa de satisfação

    crm:readDisponível
  • POST
    {número}/tickets/bulk

    Alterar vários atendimentos

    crm:writeDisponível
  • GET
    {número}/tickets/{id}

    Ler atendimento

    crm:readDisponível
  • GET
    {número}/tickets/{id}/events

    Histórico do atendimento

    crm:readDisponível
  • POST
    {número}/tickets/{contact}/resolve

    Resolver atendimento

    crm:writeDisponível
  • POST
    {número}/tickets/{contact}/reopen

    Reabrir atendimento

    crm:writeDisponível
  • PUT
    {número}/tickets/{contact}/assignee

    Atribuir atendimento

    crm:writeDisponível
  • PUT
    {número}/tickets/{contact}/pending

    Marcar pendência no atendimento

    crm:writeDisponível
  • DELETE
    {número}/tickets/{contact}/pending

    Retirar pendência do atendimento

    crm:writeDisponível

Exemplo: Mover um contato para a etapa Proposta

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/crm/leads/%2B5511912345678/move \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "3f9a1c2e-7b4d-4e61-9a0f-5c2d8e1b7a46" }'
Resposta200 OK
{
  "data": {
    "id": "a6f0d2c4-91b3-4e7a-8c15-3d9e2b7f0a61",
    "contact": "+5511912345678",
    "name": "Mariana Souza",
    "stage_id": "3f9a1c2e-7b4d-4e61-9a0f-5c2d8e1b7a46",
    "tags": [],
    "assigned_user_id": null,
    "last_activity_at": "2026-10-13T14:02:00.000Z",
    "open_ticket": true,
    "created_at": "2026-10-01T12:00:00.000Z"
  }
}

Respostas automáticas

Boas-vindas, fora do horário, menu numerado (cada opção pode mover o contato de etapa, pôr etiqueta e definir o responsável), palavras-chave e a pesquisa de satisfação de 1 a 5. Só respondem quem escreveu primeiro, nunca em grupos, no máximo 5 por contato por hora, e param quando alguém da equipe responde. O PUT substitui a configuração inteira.

  • GET
    {número}/auto-replies

    Ver respostas automáticas

    crm:readDisponível
  • PUT
    {número}/auto-replies

    Alterar respostas automáticas

    crm:writeDisponível

Exemplo: Ligar boas-vindas com menu e pesquisa de satisfação

Pedido
curl -X PUT https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/auto-replies \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "welcome": { "enabled": true, "text": "Olá! Que bom falar com você.", "cooldown_hours": 24 },
    "away": {
      "enabled": true,
      "text": "Estamos fora do horário. Respondemos a partir das 8h.",
      "hours": { "days": [1,2,3,4,5,6], "start": "08:00", "end": "20:00", "tz": "America/Sao_Paulo" },
      "cooldown_hours": 12
    },
    "menu": {
      "enabled": true,
      "text": "Digite o número da opção:",
      "options": [
        { "key": "1", "label": "Comprar", "reply": "Ótimo! Já chamo alguém de vendas.", "stage_id": null, "tag_id": null, "assign_user_id": null },
        { "key": "2", "label": "Suporte", "reply": "Conte o que aconteceu, por favor.", "stage_id": null, "tag_id": null, "assign_user_id": null }
      ]
    },
    "keywords": [ { "match": "contains", "terms": ["preço", "valor"], "reply": "Nossos planos: https://exemplo.com.br/planos" } ],
    "pause_minutes_after_human": 120,
    "auto_create_lead": true,
    "csat": {
      "enabled": true,
      "text": "Como você avalia nosso atendimento? Responda de 1 a 5 (1 = ruim, 5 = ótimo).",
      "thanks_text": "Obrigado pela avaliação!"
    }
  }'
Resposta200 OK
{
  "data": {
    "enabled": true,
    "welcome": { "enabled": true, "text": "Olá! Que bom falar com você.", "cooldown_hours": 24 },
    "away": { "enabled": true, "text": "Estamos fora do horário. Respondemos a partir das 8h.", "hours": { "days": [1,2,3,4,5,6], "start": "08:00", "end": "20:00", "tz": "America/Sao_Paulo" }, "cooldown_hours": 12 },
    "menu": { "enabled": true, "text": "Digite o número da opção:", "options": [ { "key": "1", "label": "Comprar", "reply": "Ótimo! Já chamo alguém de vendas.", "stage_id": null, "tag_id": null, "assign_user_id": null }, { "key": "2", "label": "Suporte", "reply": "Conte o que aconteceu, por favor.", "stage_id": null, "tag_id": null, "assign_user_id": null } ] },
    "keywords": [ { "match": "contains", "terms": ["preço", "valor"], "reply": "Nossos planos: https://exemplo.com.br/planos" } ],
    "pause_minutes_after_human": 120,
    "auto_create_lead": true,
    "csat": { "enabled": true, "text": "Como você avalia nosso atendimento? Responda de 1 a 5 (1 = ruim, 5 = ótimo).", "thanks_text": "Obrigado pela avaliação!" },
    "updated_at": "2026-10-13T14:02:00.000Z",
    "updated_by": { "id": "5b8e2f1a-0c3d-4a7e-9f61-2d4c8b0e7a13", "name": "Mariana Souza" }
  }
}

Públicos de anúncios

Junte as pessoas dos grupos em que o seu número já está num público para anúncios e exporte para o Meta (Público Personalizado), o Google (Customer Match) ou uma planilha CSV com telefones e nomes legíveis, para eventos. O FlowZap lê os grupos uma vez por coleta, nunca entra em grupos e nunca manda mensagem para quem está no público. Telefones ficam cifrados, saem dos arquivos de anúncios em SHA-256 e são apagados depois de 180 dias sem atualizar. Cada exportação pede a sua declaração de base legal (LGPD) e fica registrada.

  • POST
    {número}/audiences

    Coletar um público

    audiences:writeDisponível
  • GET
    {número}/audiences

    Listar públicos

    audiences:readDisponível
  • GET
    {número}/audiences/{id}

    Ler um público

    audiences:readDisponível
  • DELETE
    {número}/audiences/{id}

    Apagar um público

    audiences:writeDisponível
  • POST
    {número}/audiences/{id}/refresh

    Atualizar um público

    audiences:writeDisponível
  • GET
    {número}/audiences/{id}/members

    Membros de um público

    audiences:readDisponível
  • POST
    {número}/audiences/{id}/exports

    Exportar para Meta, Google ou planilha

    audiences:exportDisponível
  • GET
    {número}/audiences/{id}/exports

    Histórico de exportações

    audiences:readDisponível
  • DELETE
    {número}/audiences/members/{phone}

    Tirar uma pessoa de todos os públicos

    audiences:writeDisponível

Exemplo: Coletar dois grupos num público

Pedido
curl -X POST https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/audiences \
  -H "Authorization: Bearer $FLOWZAP_KEY" \
  -H "Idempotency-Key: publico-clientes-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clientes e vizinhança",
    "group_jids": ["120363000000000001@g.us", "120363000000000002@g.us"]
  }'
Resposta201 Created
{
  "data": {
    "id": "5b1e7c2a-0d4f-4a8e-9b3c-6f2d1e8a7c90",
    "name": "Clientes e vizinhança",
    "state": "ready",
    "error_code": null,
    "selection": {
      "all": false,
      "group_jids": ["120363000000000001@g.us", "120363000000000002@g.us"]
    },
    "member_count": 248,
    "admin_member_count": 131,
    "participants_without_phone": 12,
    "missing_group_jids": [],
    "created_at": "2026-10-10T14:00:00.000Z",
    "collect_requested_at": "2026-10-10T14:00:00.000Z",
    "refreshed_at": "2026-10-10T14:00:03.000Z",
    "expires_at": "2027-04-08T14:00:03.000Z"
  }
}

Conteúdo público

Sem chave de API: o que está publicado no blog, no glossário, nos comparativos, nos segmentos e nas páginas de autor, com o HTML já sanitizado e o JSON-LD pronto. Respostas com cache de 60 segundos.

  • GET
    /v1/public/content/items

    Listar conteúdos publicados

    sem chaveDisponível
  • GET
    /v1/public/content/items/{type}/{slug}

    Ler um conteúdo publicado

    sem chaveDisponível
  • GET
    /v1/public/content/authors/{slug}

    Ler um autor

    sem chaveDisponível
  • GET
    /v1/public/content/sitemap-entries

    Entradas do sitemap

    sem chaveDisponível
  • GET
    /v1/public/content/feed-entries

    Entradas do feed RSS

    sem chaveDisponível
  • GET
    /v1/public/content/llms-entries

    Entradas do llms.txt

    sem chaveDisponível

Exemplo: Listar os artigos publicados

Pedido
curl "https://flowzap.flowpost.com.br/v1/public/content/items?type=article&page=1"
Resposta200 OK
{
  "data": [
    {
      "type": "article",
      "slug": "atendimento-em-equipe-no-whatsapp",
      "path": "/blog/atendimento-em-equipe-no-whatsapp",
      "title": "Atendimento em equipe no WhatsApp",
      "reading_minutes": 6,
      "published_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1,
  "total_pages": 1
}

Versões e mudanças

Mudanças aditivas (rota, campo, evento ou código de erro novo) chegam sem aviso prévio: ignore o que a sua integração não conhece. Mudança incompatível só numa versão nova, com pelo menos 90 dias de aviso pelos cabeçalhos Deprecation e Sunset e registro nesta lista. Avisos de manutenção e incidentes ficam em Status.

  1. 1.3.0-preview.2026111616/11/2026

    • Reconectar um número que o celular desconectou: POST …/connect (ou …/reservations) num número já usado começa um pareamento novo no mesmo número, sem ocupar outra vaga; conversas, campanhas e ajustes continuam e os envios na fila são cancelados.
    • Códigos novos number_still_linked, number_blocked e number_paused (409) quando o número não pode ser reconectado pelo QR.
    • Lista de números com last_phone_masked (telefone da última conexão) e phone_changed (reconectado com outro telefone); GET …/qr nunca responde linked para um número desconectado pelo celular.
  2. 1.2.1-preview.2026111414/11/2026

    • Resultados de leituras com dados de pessoas (agenda de contatos, verificação de números, foto de perfil e download de mídia) passam a ficar 1 hora, como os de grupos; depois, 410 result_expired.
  3. 1.2.0-preview.2026110303/11/2026

    • Origens do áudio no navegador por conta (GET/POST/DELETE /v1/calls/media-origins), assinadas no bilhete; origem recusada fecha com 4003 origin_not_allowed, visível no JavaScript.
    • Números de teste do piloto pela API (GET/PUT /v1/calls/test-numbers) e diagnóstico por número e destino (GET …/calls/readiness).
    • Escopo calls:admin para administrar as ligações da conta (só chave da organização inteira, nunca OAuth).
    • Ligações com actor_label do atendente externo, state, ended_by, requested_at, audio_connected_at, tempo de espera e tempo falado; evento call.media_connected.
    • O telefone só toca, e a ligação recebida só é atendida, depois que o WebSocket de áudio do atendente conecta.
    • Gravações com mime, canais, frequência e deleted_reason; reason no 404 e recording_state no 409; evento call.recording_failed.
    • Rota beta: PUT /v1/calls/numbers com chave presa a número responde 403 organization_key_required (antes 404).
  4. 1.1.0-preview.2026103030/10/2026

    • Mensagens: envio por JID (telefone ou LID), busca por client_reference, citação e encaminhamento nativos, menções por LID, actor_label do atendente e checagem de grupo antes do envio (não participa, só admins, grupo inexistente).
    • Mídia com Range/206; recebidas e histórico com inbox_id, mídia, citação, menções, encaminhamento, voz e dimensões.
    • Histórico da conversa inteira com cursor assinado e fim explícito (end_of_history); pedido de mensagens antigas com as regras do console.
    • Conversas com arquivada, fixada, silenciada e etiquetas do celular; contatos com nome da agenda, do WhatsApp e comercial.
    • Atendimento com motivo e atendente externo em cada ação, trilha por atendimento e updated_since; anotações com cursor.
    • Contrato OpenAPI 3.1 para baixar (/openapi.json e /openapi.yaml) e coleção do Postman.
    • X-Request-Id em todas as respostas, igual a error.request_id; retryable com regra única (429 com Retry-After, 502 incerto nunca repetível).
    • Catálogo de erros com o que fazer em cada código.
    • Webhooks: ver e alterar um endereço (URL, filtros por tipo e por número, pausar e reativar), aviso de teste, reenvio de entrega e histórico com filtros e cursor; endereço pausado guarda os avisos em vez de perdê-los.
    • Eventos de atendimento, funil, satisfação e gravações por ID; calls:read lê os eventos de ligação; token curto (5 min) para SSE no navegador e cursor exato com vários números (cursor=map).
    • Números: capacidades por conexão, telefone completo do próprio número (instances:read), motivo da desconexão no status e paginação por cursor de áreas e números; operações com Retry-After e ?envelope=1.
    • Ligações: o segundo atendimento da mesma ligação recebe 409 call_already_answering; todas as ações aceitam calls:write ou engine:write; origens extras do softphone configuráveis no servidor de áudio.
    • Guia de reconciliação (tempo esgotado, resultado incerto, eventos repetidos, retomada e quedas).
  5. 1.0.0-preview10/2026

    • Primeira prévia pública: mensagens, números, grupos, canais, contatos, conversas, CRM, atendimentos, campanhas, ligações (beta), eventos, SSE e webhooks assinados.

Crie a conta e gere a chave em Integrações (proprietário ou administrador). A API está em todos os planos.