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.
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
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.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" } }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.readou, 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.
Authorization: Bearer fzk_XXXXXXXXXXXX_...| Escopo | O que permite |
|---|---|
workspaces:read | Ler as áreas de trabalho. |
instances:write | Criar números e reservar a vaga para conectar. |
instances:read | Ler 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:send | Enviar mensagens e mídia, cancelar a fila e criar campanhas. |
messages:read | Consultar envios, baixar mídia, ler conversas, a fila e as campanhas. |
engine:read | Ler dados do WhatsApp (grupos, contatos, perfil, canais), todos os eventos, CRM, Chatwoot e operações. |
engine:write | Mudar algo no WhatsApp ou nos dados do número: grupos, perfil, conversas, CRM, Chatwoot. |
crm:read | Ler o CRM: leads, funil, campos personalizados, atendimentos, respostas rápidas e automáticas (engine:read também serve). |
crm:write | Mudar o CRM: leads, etapas, mover contatos, campos, resolver e atribuir atendimentos, respostas automáticas (engine:write também serve). |
webhooks:read | Listar webhooks e o histórico de entregas. |
webhooks:write | Cadastrar, alterar, testar e remover webhooks; reenviar entregas. |
audiences:read | Listar públicos e ver os membros com telefone mascarado. |
audiences:write | Coletar, atualizar e apagar públicos de grupos. |
audiences:export | Exportar públicos para Meta e Google e ver telefones completos (exige declaração de base legal). |
calls:read | Ver ligações e gravações (sem o áudio) e ler os eventos call.* (por ID, por número e no SSE). |
calls:write | Fazer, atender, recusar, desligar e silenciar ligações (engine:write também serve nas chaves antigas). |
calls:recordings | Baixar e apagar gravações de ligações (calls:read lista as ligações sem o áudio). |
calls:admin | Administrar 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.
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"
}
}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ódigo | Significado |
|---|---|
200 | Pronto; data traz o resultado. |
201 | Criado. |
202 | Aceito: mensagem na fila, ou operação ainda em andamento (cabeçalho Location). |
204 | Feito, sem corpo. |
400 | Pedido inválido (invalid_input e outros códigos). |
401 | Chave ausente, inválida, revogada ou vencida. |
403 | Falta o escopo na chave (scope_denied) ou a conta está suspensa (organization_suspended). |
404 | Não existe, ou a chave não alcança esse recurso. |
409 | Conflito, como a mesma Idempotency-Key com outro conteúdo. |
422 | O WhatsApp ou uma regra do serviço recusou. |
429 | Limite 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. |
501 | O WhatsApp Web não oferece o recurso (not_supported_by_engine). Não adianta repetir. |
502 | Resultado incerto (retryable false): confira o estado antes de repetir; nunca reenvie às cegas. |
503 | Número desconectado ou serviço indisponível; tente mais tarde. |
504 | A 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 repitaEste 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 repitaA 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 repitaA pessoa já faz parte da equipe.
O que fazer: Nada a fazer; altere o papel dela, se for o caso.
already_sent409Não repitaO 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 repitaO 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 repitaA 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 repitaA 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 repitaO 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 repitaO público ainda está sendo coletado.
O que fazer: Espere a coleta terminar (`state`) e exporte depois.
audio_conversion_unavailable503Pode repetirA 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 repitaO 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 repitaA 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 repitaO 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 repitaMover no funil pede `before` ou `after`, não os dois.
O que fazer: Envie só um vizinho de referência.
billing_read_unavailable503Pode repetirA leitura da cobrança está indisponível no momento.
O que fazer: Tente mais tarde.
billing_role_required403Não repitaA 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 repetirA cobrança está indisponível no momento.
O que fazer: Tente mais tarde.
call_already_answering409Não repitaOutra 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 repitaA 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 repitaA 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 repitaA 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 repitaNa 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 repitaA 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 repitaO 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 repitaAs 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 repitaA 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 repetirO pagamento por cartão está indisponível no momento.
O que fazer: Tente mais tarde ou pague por Pix.
carousel_media_mixed422Não repitaO 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 repitaAs mídias do carrossel somadas passam do limite.
O que fazer: Use arquivos menores ou menos cartões.
chatwoot_url_invalid400Não repitaO 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 repitaO link de pagamento venceu.
O que fazer: Gere um checkout novo.
checkout_offer_unavailable503Pode repetirA oferta do checkout não pôde ser montada agora.
O que fazer: Tente mais tarde.
checkout_rejected422Não repitaO provedor de pagamento recusou o checkout.
O que fazer: Confira os dados de cobrança e tente de novo.
checkout_unavailable503Pode repetirO checkout está indisponível no momento.
O que fazer: Tente mais tarde.
collection_failed422Não repitaA 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 repitaJá existe uma coleta deste público em andamento.
O que fazer: Espere terminar.
collection_too_soon429Pode repetirA 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 repitaHá destinatários sem consentimento registrado (`rejected`, `total`).
O que fazer: Registre o consentimento no CRM ou retire esses contatos.
contact_already_linked409Não repitaEste contato já está ligado a essa conversa.
O que fazer: Nada a fazer.
contact_link_not_found404Não repitaA ligação entre contato e conversa não existe.
O que fazer: Confira os IDs.
conversation_not_found404Não repitaA conversa não existe neste número.
O que fazer: Confira o JID da conversa.
cursor_map_too_large400Não repitaO 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 repitaO `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 repitaExportar o público exige a declaração de base legal (LGPD).
O que fazer: Envie a declaração pedida.
delivery_in_progress409Não repitaA 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 repitaO número ainda está conectado; desconecte antes de excluir.
O que fazer: Chame `POST …/disconnect` e repita.
download_failed502Pode repetirNã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 repitaLimite de números em rascunho atingido.
O que fazer: Conecte ou exclua rascunhos antes de criar outro.
empty_media400Não repitaO arquivo enviado está vazio.
O que fazer: Envie o arquivo com conteúdo.
endpoint_disabled409Não repitaO 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 repitaJá existe um webhook ativo com essa URL nesta área de trabalho.
O que fazer: Use o endereço existente.
endpoint_limit_reached409Não repitaA á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 repitaO 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_error422DependeO 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 repitaO número não estava conectado ao WhatsApp ao executar a operação.
O que fazer: Confira `GET …/status`, reconecte e repita.
engine_timeout504Pode repetirA 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 repetirAs operações do WhatsApp estão desligadas neste ambiente.
O que fazer: Tente mais tarde.
existing_account409Não repitaO 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 repitaJá existe um campo personalizado com essa chave.
O que fazer: Use outra chave.
forbidden403Não repitaA 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 repitaA mídia da mensagem a encaminhar expirou.
O que fazer: Envie a mídia de novo como mensagem nova.
forward_media_too_large422Não repitaA 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 repitaA mídia da mensagem a encaminhar não está guardada.
O que fazer: Envie a mídia como mensagem nova.
forward_not_allowed422Não repitaEssa mensagem não pode ser encaminhada.
O que fazer: Envie o conteúdo como mensagem nova.
forward_not_supported422Não repitaEsse tipo de mensagem não pode ser encaminhado.
O que fazer: Envie o conteúdo como mensagem nova.
from_me_required400Não repitaInforme `from_me` (se a mensagem alvo é sua ou do contato).
O que fazer: Envie `from_me: true` ou `false`.
group_announce_onlyenvioNão repitaO 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 repetirAs informações do grupo não puderam ser lidas.
O que fazer: Tente de novo mais tarde.
group_not_found422Não repitaO 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 repetirA lista de grupos do número ainda está sendo carregada.
O que fazer: Tente de novo em alguns segundos.
groups_unavailable502Pode repetirA lista de grupos não pôde ser lida no número.
O que fazer: Tente de novo mais tarde.
history_import_off409Não repitaO 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 repitaA 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 repitaA `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 repitaEsta rota exige `Idempotency-Key`.
O que fazer: Envie um valor único por pedido (ex.: UUID).
image_too_large400Não repitaA imagem passa do tamanho aceito.
O que fazer: Envie uma imagem menor.
instance_not_in_workspace400Não repitaAlgum 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 repitaUma 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 repitaAção inválida para esta operação.
O que fazer: Confira os valores aceitos na documentação da rota.
invalid_auto_replies422Não repitaAs respostas automáticas têm um campo inválido (`field`).
O que fazer: Corrija o campo indicado.
invalid_before422Não repitaO marcador `before` da leitura é inválido.
O que fazer: Use o valor recebido na página anterior.
invalid_body400Não repitaO 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 repitaO 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 repitaID de ligação inválido.
O que fazer: Use o `call_id` do evento da ligação.
invalid_campaign_state409Não repitaA campanha não está num estado que permita esta ação.
O que fazer: Leia o estado atual da campanha.
invalid_caption422Não repitaLegenda inválida.
O que fazer: Encurte ou corrija a legenda.
invalid_color422Não repitaCor inválida.
O que fazer: Use uma cor aceita pela rota.
invalid_count422Não repitaQuantidade pedida inválida.
O que fazer: Use um valor dentro do limite da rota.
invalid_cursor400Não repitaO `cursor` não veio desta rota (ou desta consulta).
O que fazer: Recomece sem `cursor` ou use o `next_cursor` recebido.
invalid_description422Não repitaDescrição inválida (vazia ou longa demais).
O que fazer: Corrija o texto.
invalid_duration422Não repitaDuração inválida.
O que fazer: Use um valor aceito pela rota.
invalid_ephemeral_timer422Não repitaTempo de mensagens temporárias inválido.
O que fazer: Use um dos valores aceitos.
invalid_expiration422Não repitaValidade 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 repitaO valor não serve para o campo personalizado (`field`).
O que fazer: Envie um valor do tipo do campo.
invalid_file_name400Não repitaO nome de arquivo (`X-File-Name`) é inválido.
O que fazer: Use um nome simples, sem caminhos.
invalid_group_jid422Não repitaJID de grupo inválido.
O que fazer: Use o formato `<id>@g.us`.
invalid_group_name422Não repitaNome de grupo inválido (vazio ou longo demais).
O que fazer: Corrija o nome.
invalid_groups422Não repitaLista 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 repitaA 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 repitaO 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 repitaO 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 repitaConvite de grupo inválido.
O que fazer: Use um link ou código de convite válido.
invalid_invite_code422Não repitaCódigo de convite inválido.
O que fazer: Use o código do link `chat.whatsapp.com/<código>`.
invalid_jid400, 422Não repitaJID 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 repitaO corpo não é JSON válido.
O que fazer: Envie JSON válido com `Content-Type: application/json`.
invalid_label_id422Não repitaID 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 repitaTipo de mídia (`kind`) inválido no upload.
O que fazer: Use `image`, `video`, `audio`, `document` ou `sticker`.
invalid_media_url400Não repitaA URL da mídia é inválida.
O que fazer: Use uma URL https pública.
invalid_member_add_mode422Não repitaModo de entrada de participantes inválido.
O que fazer: Use um dos valores aceitos.
invalid_message422Não repitaA mensagem montada pelo modelo é inválida.
O que fazer: Revise o texto e as variáveis do modelo.
invalid_message_id422Não repitaID de mensagem inválido.
O que fazer: Use o ID da mensagem do WhatsApp.
invalid_message_ids422Não repitaLista de IDs de mensagem inválida.
O que fazer: Envie IDs válidos, dentro do limite.
invalid_name422Não repitaNome inválido.
O que fazer: Corrija o nome (tamanho e caracteres).
invalid_newsletter_jid422Não repitaJID de canal inválido.
O que fazer: Use o formato `<id>@newsletter`.
invalid_newsletter_name422Não repitaNome de canal inválido.
O que fazer: Corrija o nome.
invalid_or_expired_invitation400Não repitaO convite é inválido ou venceu.
O que fazer: Peça um convite novo.
invalid_origin400Não repitaNã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 repitaParticipante inválido.
O que fazer: Use um JID ou telefone válido.
invalid_participants422Não repitaLista de participantes inválida.
O que fazer: Envie participantes válidos, dentro do limite.
invalid_payload400, 422Não repitaO corpo recebido não tem o formato esperado.
O que fazer: Confira o formato e envie de novo.
invalid_phone422Não repitaTelefone inválido.
O que fazer: Use E.164 (ex.: `+5511912345678`).
invalid_placeholder422Não repitaVariável inválida ou desconhecida no texto (ex.: `{{nome}}`).
O que fazer: Use só as variáveis aceitas.
invalid_privacy_value422Não repitaValor de privacidade inválido.
O que fazer: Use um dos valores aceitos.
invalid_proxy_url400Não repitaA URL do proxy é inválida.
O que fazer: Use `http://`, `https://` ou `socks5://` com host e porta.
invalid_reaction422Não repitaReação inválida.
O que fazer: Envie um único emoji (ou vazio para remover).
invalid_schedule400, 422Não repitaData de agendamento fora da janela permitida.
O que fazer: Agende dentro dos limites informados na resposta.
invalid_sender_resultenvioNão repitaResultado 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 repitaID de publicação do canal inválido.
O que fazer: Use o `server_id` da publicação.
invalid_server_ids422Não repitaLista de IDs de publicação inválida.
O que fazer: Envie IDs válidos.
invalid_since422Não repitaData `since` inválida.
O que fazer: Use data ISO 8601.
invalid_status_styleenvioNão repitaEstilo do status (cor ou fonte) inválido (em `error_code` do envio).
O que fazer: Use as cores e fontes aceitas.
invalid_text422Não repitaTexto inválido (vazio ou longo demais).
O que fazer: Corrija o texto.
invalid_timer422Não repitaTempo inválido.
O que fazer: Use um valor aceito.
invalid_timestamp422Não repitaData/hora inválida.
O que fazer: Use um valor aceito pela rota.
invalid_token401Não repitaO 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 repitaO convite já foi aceito, cancelado ou venceu.
O que fazer: Crie um convite novo, se preciso.
invitation_email_mismatch403Não repitaA 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 repitaA mesma chave de pedido já criou um convite diferente.
O que fazer: Use uma `Idempotency-Key` nova.
invitation_not_found404Não repitaO convite não existe ou o link é inválido.
O que fazer: Confira o link.
invitation_recipient_mismatch403Não repitaO convite é para outra pessoa.
O que fazer: Use o convite certo.
invite_expired422Não repitaO convite do grupo venceu.
O que fazer: Peça um link novo.
invite_not_allowed422Não repitaO 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 repitaNão há pedido de entrada desta pessoa no grupo.
O que fazer: Atualize a lista de pedidos.
invite_revoked422Não repitaO convite do grupo foi revogado.
O que fazer: Peça um link novo.
last_stage409Não repitaO funil precisa de ao menos uma etapa.
O que fazer: Crie outra etapa antes de apagar esta.
media_content_mismatch415Não repitaO conteúdo do arquivo não bate com o tipo informado.
O que fazer: Envie o `Content-Type` correto.
media_expired422Não repitaA mídia expirou no WhatsApp.
O que fazer: Peça o arquivo de novo ao contato.
media_expires_before_schedule422Não repitaA 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 repitaO arquivo guardado não passou na conferência de integridade.
O que fazer: Envie a mídia de novo.
media_kind_mismatch422Não repitaA 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 repitaA 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 repitaA 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 repitaO arquivo passa do limite (16 MiB no upload; limites do WhatsApp por tipo).
O que fazer: Envie um arquivo menor.
media_unavailableenvioNão repitaA 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 repetirO 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 repitaA 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 repitaA 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 repitaNã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 repitaA URL da mídia redirecionou vezes demais.
O que fazer: Use a URL final do arquivo.
media_url_timeout422Não repitaA 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 repitaO endereço da URL da mídia não foi encontrado (DNS).
O que fazer: Confira o domínio.
member_limit_reached409Não repitaA equipe chegou ao limite de pessoas do plano.
O que fazer: Remova alguém ou mude de plano.
message_build_failedenvioNão repitaA 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 repitaO 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 repitaFalta o tipo do arquivo (`Content-Type`).
O que fazer: Envie o `Content-Type` da mídia.
missing_variables422Não repitaFaltam valores para variáveis do modelo (`missing`).
O que fazer: Envie todas as variáveis do modelo.
newsletter_not_found422Não repitaO canal não existe ou não está visível.
O que fazer: Confira o JID do canal.
newsletter_request_rejected422Não repitaO WhatsApp recusou o pedido ao canal.
O que fazer: Tente de outra forma ou mais tarde.
no_admin_groups422Não repitaNenhum dos grupos escolhidos é administrado pelo número.
O que fazer: Escolha grupos em que o número é admin.
no_consented_recipients422Não repitaNenhum destinatário tem consentimento registrado.
O que fazer: Registre o consentimento antes.
no_known_message422Não repitaNã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 repitaA 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 repitaO WhatsApp recusou o pedido ao canal (formato não aceito).
O que fazer: Revise o pedido.
not_allowed422Não repitaO WhatsApp não permite esta ação no canal.
O que fazer: Confira o seu papel no canal.
not_authorized422Não repitaO WhatsApp não autorizou a leitura (privacidade do contato).
O que fazer: Não há o que fazer pela API.
not_cancelable409Não repitaO agendamento não pode mais ser cancelado (`state`).
O que fazer: Leia o estado; se já saiu, acompanhe o envio.
not_found404, 422Não repitaNã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 repitaA 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 repitaO número não participa do grupo.
O que fazer: Adicione o número ao grupo antes.
not_logged_in422Não repitaO número não está logado no WhatsApp.
O que fazer: Reconecte por QR code.
not_on_whatsapp422Não repitaO telefone não tem WhatsApp.
O que fazer: Confira o número.
not_supported_by_engine501Não repitaO WhatsApp Web não oferece este recurso.
O que fazer: Não repita; o recurso não existe nesta API.
number_blocked409Não repitaO 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 repetirO número não está conectado ao WhatsApp agora.
O que fazer: Confira `GET …/status`; reconecte e tente de novo.
number_not_found404Não repitaO número não existe nesta conta.
O que fazer: Confira o `instance_id`.
number_paused409Não repitaOutra 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 repitaO 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 repitaA 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 repitaA 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 repitaO número exige o nome de quem envia (assinatura obrigatória).
O que fazer: Envie `operator_name` no envio.
operator_required403Não repitaA 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 repitaA data de consentimento está no futuro.
O que fazer: Envie a data real do consentimento.
options_only_for_select422Não repitaOpções só valem para campos de seleção.
O que fazer: Retire `options` ou mude o tipo do campo.
options_required422Não repitaCampos de seleção precisam de opções.
O que fazer: Envie `options`.
organization_key_required403Não repitaRota 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 repitaA conta está suspensa ou encerrada; nenhuma rota responde.
O que fazer: Fale com a equipe FlowZap.
outcome_unknown502Não repitaO 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 repitaSó dono ou administrador pode fazer esta ação.
O que fazer: Use uma chave de dono ou administrador.
owner_required403Não repitaSó o dono da conta pode fazer esta ação.
O que fazer: Use uma chave criada pelo dono.
pairing_recovery_required409Não repitaO 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 repitaO corpo passa do limite da rota.
O que fazer: Envie um corpo menor (mídia grande: upload binário).
picture_not_set422Não repitaO contato ou grupo não tem foto.
O que fazer: Nada a fazer.
plan_feature_required403Não repitaO plano da conta não inclui este recurso (API ou MCP).
O que fazer: Mude de plano.
post_lookup_failed422Pode repetirA publicação do canal não pôde ser localizada agora.
O que fazer: Tente de novo mais tarde.
post_not_found422Não repitaA publicação do canal não existe.
O que fazer: Confira o `server_id`.
privacy_hidden422Não repitaA privacidade do contato esconde esta informação.
O que fazer: Não há o que fazer pela API.
privacy_token_missing422Não repitaFalta o token de privacidade do contato para esta leitura.
O que fazer: Converse com o contato primeiro.
private_chat_required400Não repitaEsta ação só vale em conversa privada (não em grupo).
O que fazer: Use um JID de pessoa.
provider_rate_limited503Pode repetirO provedor de pagamento limitou os pedidos.
O que fazer: Tente mais tarde.
provider_rejectedenvioNão repitaO 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 repitaO host do proxy não é permitido (rede privada).
O que fazer: Use um proxy público.
push_name_missing422Não repitaO contato não tem nome público.
O que fazer: Nada a fazer.
qr_unavailable503Pode repetirO QR code ainda não está disponível.
O que fazer: Tente de novo em alguns segundos.
queue_full429Pode repetirA 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 repitaO intervalo `Range` pedido está fora do arquivo.
O que fazer: Peça um intervalo dentro do tamanho (`Content-Range`).
rate_limited429, 422Pode repetirLimite de pedidos ou de envios atingido.
O que fazer: Espere o tempo de `Retry-After`.
readiness_check_failedenvioPode repetirA checagem antes do envio falhou e nada saiu (em `error_code` do envio).
O que fazer: Reenvie.
reauth_failed403Não repitaA confirmação de identidade falhou.
O que fazer: Confirme a senha/MFA e tente de novo.
recipient_not_registeredenvioNão repitaO destinatário não tem WhatsApp (em `error_code` do envio).
O que fazer: Confira o número.
recipient_unknown422Não repitaO 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 repitaO número não tem o módulo de gravações.
O que fazer: Contrate o adicional de gravações.
recording_not_found404Não repitaA 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 repitaA 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 repitaA escolha passa da quantidade de números com gravação contratada.
O que fazer: Escolha menos números ou contrate mais.
recording_unavailable503Pode repetirA gravação não pôde ser lida agora.
O que fazer: Tente mais tarde.
recordings_busy503Pode repetirMuitos downloads de gravação ao mesmo tempo.
O que fazer: Tente de novo em alguns segundos.
recordings_unavailable503Pode repetirAs gravações estão indisponíveis no momento.
O que fazer: Tente mais tarde.
redelivery_limit_reached409Não repitaA entrega de webhook já teve 10 rodadas.
O que fazer: Leia o evento pela API.
rejected_by_whatsapp422Não repitaO WhatsApp recusou o pedido.
O que fazer: Revise o pedido.
renewal_checkout_unavailable409Não repitaNão há checkout de renovação disponível para esse ciclo.
O que fazer: Leia `GET /v1/billing/renewal-attention`.
renewal_conflict409Não repitaA renovação já mudou enquanto o pedido rodava.
O que fazer: Leia a assinatura e tente de novo, se ainda fizer sentido.
renewal_unavailable503Pode repetirA renovação está indisponível no momento.
O que fazer: Tente mais tarde.
result_expired409, 410Não repitaO resultado da operação já foi apagado (dados pessoais ficam 1 hora).
O que fazer: Faça a leitura de novo.
retry503Pode repetirConflito momentâneo ao gravar; nada foi alterado.
O que fazer: Repita o pedido.
scope_denied403Não repitaA chave não tem o escopo desta rota.
O que fazer: Crie uma chave com o escopo (veja `x-scopes`).
self_removal_denied403Não repitaA pessoa não pode remover a si mesma por aqui.
O que fazer: Peça a outro administrador.
send_failed409Não repitaO agendamento falhou ao enviar.
O que fazer: Leia o agendamento e envie de novo se preciso.
send_prepare_failedenvioPode repetirO envio falhou antes de sair do aparelho (em `error_code` do envio).
O que fazer: Reenvie (nada saiu).
send_unavailable503Pode repetirO 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 repitaInforme quem enviou a mensagem alvo (`sender`), obrigatório em grupos.
O que fazer: Envie o JID do autor.
session_disconnectedenvioPode repetirO número desconectou antes de enviar; nada saiu (em `error_code` do envio).
O que fazer: Reconecte e reenvie.
shortcut_exists409Não repitaJá existe uma resposta rápida com esse atalho.
O que fazer: Use outro atalho.
slot_limit_reached429Não repitaNão há vaga livre de número no plano.
O que fazer: Libere uma vaga ou mude de plano.
slug_taken409Não repitaO endereço (slug) do link já está em uso.
O que fazer: Escolha outro.
stage_exists409Não repitaJá existe uma etapa com esse nome.
O que fazer: Use outro nome.
stream_token_expired401Não repitaO 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 repitaO 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 repitaJá existe uma etiqueta com esse nome.
O que fazer: Use outro nome.
target_index_building503Pode repetirO índice para localizar a mensagem alvo ainda está sendo montado.
O que fazer: Tente de novo em alguns segundos.
target_not_editable422Não repitaSó mensagens enviadas pelo número podem ser editadas.
O que fazer: Edite uma mensagem sua (até 15 minutos).
target_not_found404Não repitaA mensagem alvo não foi encontrada neste número.
O que fazer: Confira o ID da mensagem.
target_not_revocable422Não repitaMensagem 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 repitaSó quem administra a equipe pode fazer esta ação.
O que fazer: Use uma chave de dono ou administrador.
template_name_exists409Não repitaJá existe um modelo com esse nome.
O que fazer: Use outro nome.
template_not_found404Não repitaO modelo não existe.
O que fazer: Confira o ID.
template_read_only403Não repitaModelo 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 repitaJá há um atendimento aberto para essa conversa.
O que fazer: Use o atendimento existente.
ticket_not_open409Não repitaO atendimento não está aberto.
O que fazer: Reabra antes.
ticket_pending409Não repitaO atendimento está pendente; retire a pendência antes.
O que fazer: Limpe a pendência e repita.
too_many_active_broadcasts409Não repitaLimite de envios em grupos ativos ao mesmo tempo.
O que fazer: Espere um terminar.
too_many_active_campaigns409Não repitaLimite de campanhas ativas ao mesmo tempo.
O que fazer: Espere uma terminar.
too_many_fields422Não repitaLimite de campos personalizados atingido.
O que fazer: Apague campos que não usa.
too_many_recipients422Não repitaDestinatários demais para uma campanha.
O que fazer: Divida em campanhas menores.
too_many_scheduled409Não repitaLimite de agendamentos pendentes atingido.
O que fazer: Espere ou cancele agendamentos.
too_many_stages422Não repitaLimite de etapas do funil atingido.
O que fazer: Apague etapas que não usa.
transport_ambiguousenvioNão repitaA 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 repitaChave ausente, inválida, revogada ou vencida.
O que fazer: Envie `Authorization: Bearer fzk_…` com uma chave válida.
unavailable503Pode repetirO 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 repitaO vizinho informado para mover no funil não existe.
O que fazer: Atualize o funil e repita.
unknown_stage422Não repitaEtapa do funil desconhecida.
O que fazer: Use um ID de `GET …/crm/pipeline`.
unknown_tag422Não repitaEtiqueta de lead desconhecida.
O que fazer: Use uma etiqueta existente.
unsafe_webhook_destination400Não repitaA 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 repitaTipo de arquivo não aceito para esse envio.
O que fazer: Use um dos tipos aceitos.
use_message_routes404Não repitaEsse ID é de mensagem; leia pelas rotas de mensagem.
O que fazer: Use `GET /v1/messages/{id}` ou `GET …/inbound/{id}`.
user_not_member422Não repitaA pessoa indicada não é da equipe.
O que fazer: Use um ID de `GET /v1/team/members`.
voice_note_too_large413Não repitaA nota de voz convertida passa do limite.
O que fazer: Envie um áudio menor.
voice_note_too_long413Não repitaA nota de voz é longa demais.
O que fazer: Envie um áudio mais curto.
webhook_dns_unavailable503Pode repetirO DNS do endereço do webhook não respondeu agora.
O que fazer: Tente de novo mais tarde.
webhook_secret_unavailable503Pode repetirO 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 repitaFalta `workspace_id` na consulta.
O que fazer: Envie `?workspace_id=`.
workspace_slot_limit_reached429Não repitaA á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
- GET
/v1 /account /export Baixar os dados da conta
- GET
/v1 /workspaces Listar áreas de trabalho
- GET
/v1 /workspaces /{workspaceId} Ler uma área de trabalho
- GET
/v1 /operations /{id} Consultar uma operação
- POST
/v1 /owner-invitations /preview Abrir um convite para ser dono
- POST
/v1 /owner-invitations /accept Aceitar um convite para ser dono
Exemplo: Listar áreas de trabalho
curl https://flowzap.flowpost.com.br/v1/workspaces \
-H "Authorization: Bearer $FLOWZAP_KEY"{
"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
- POST
/v1 /workspaces /{workspaceId} /instances Criar número
- POST
{número}/reservations Reservar vaga para conectar
- GET
{número}/status Situação do número (telefone e motivo da desconexão)
- GET
{número}/capabilities O que esta conexão pode fazer (capacidades)
- PATCH
{número}Renomear número
- DELETE
{número}Excluir número
- POST
{número}/connect Iniciar conexão por QR code
- GET
{número}/qr Ler o QR code de pareamento
- POST
{número}/disconnect Desconectar (sair do WhatsApp)
- POST
{número}/restart Reconectar a sessão
- GET
{número}/limits Limites de novas conversas
- GET
{número}/queue Ver a fila de envios
- DELETE
{número}/queue Cancelar envios na fila
- GET
{número}/settings /delay Ler intervalo entre envios
- PUT
{número}/settings /delay Definir intervalo entre envios
- GET
{número}/settings /signature Ler assinatura do atendente
- PUT
{número}/settings /signature Ligar ou desligar assinatura do atendente
- GET
{número}/settings /history Ler importação de histórico
- PUT
{número}/settings /history Ligar ou desligar importação de histórico
- GET
{número}/proxy /managed Proxy gerenciado
- GET
{número}/proxy Ler proxy do número
- PUT
{número}/proxy Definir proxy do número
- DELETE
{número}/proxy Remover proxy
Exemplo: Ver a situação do número
curl https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/status \
-H "Authorization: Bearer $FLOWZAP_KEY"{
"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
- DELETE
/v1 /team /members /{membershipId} Remover uma pessoa da equipe
- GET
/v1 /team /invitations Listar convites da equipe
- POST
/v1 /team /invitations Convidar uma pessoa
- DELETE
/v1 /team /invitations /{invitationId} Cancelar um convite
Exemplo: Convidar uma pessoa
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}'{
"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
- GET
/v1 /billing /offers Listar ofertas de planos
- GET
/v1 /billing /renewal-attention Ver pendências da renovação
- GET
/v1 /billing /addons /calls Ver ligações contratadas
- POST
/v1 /billing /addons /calls Mudar a quantidade de números com ligações
- GET
/v1 /billing /addons /recordings Ver Gravações no FlowZap contratadas
- POST
/v1 /billing /addons /recordings Mudar a quantidade de números com Gravações no FlowZap
- POST
/v1 /billing /checkout /pix Contratar um plano por Pix
- POST
/v1 /billing /checkout /card Contratar um plano com cartão de crédito
- POST
/v1 /billing /renewal-cycles /{cycleId} /checkout /pix Pagar a renovação por Pix
- POST
/v1 /billing /subscription /renewal Encerrar (ou manter) a assinatura no fim do período
- POST
/v1 /billing /plan-changes /{changeId} /confirm Confirmar a mudança de plano agendada
Exemplo: Contratar mais números com ligações
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"}'{
"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
- GET
/v1 /messages Buscar envios por referência
- GET
/v1 /messages /{id} Consultar um envio
- GET
/v1 /messages /{id} /receipts Quem recebeu e leu (grupos)
- POST
{número}/media Enviar arquivo de mídia (upload)
- GET
{número}/media /{id} Ler dados de uma mídia
- GET
{número}/media /{id} /content Baixar uma mídia enviada
- DELETE
{número}/media /{id} Apagar uma mídia
- GET
{número}/inbound /{inboxId} /media Baixar mídia recebida
- POST
{número}/status-posts Publicar no Status
- GET
{número}/status-posts Listar publicações no Status
Exemplo: Enviar uma imagem já carregada
# 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"
}'{
"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
- GET
{número}/chats /count Contar conversas
- POST
{número}/conversations /links Juntar uma conversa sem telefone a um telefone
- DELETE
{número}/conversations /links /{linkId} Desfazer o vínculo de uma conversa
- GET
{número}/chats /{jid} /messages Mensagens de uma conversa
- GET
{número}/messages /search Buscar mensagens por texto
- POST
{número}/chats /{jid} /archive Arquivar ou desarquivar
- POST
{número}/chats /{jid} /read Marcar conversa como lida ou não lida
- POST
{número}/chats /{jid} /pin Fixar ou desafixar conversa
- POST
{número}/chats /{jid} /mute Silenciar conversa
- DELETE
{número}/chats /{jid} Apagar conversa no WhatsApp
- POST
{número}/chats /{jid} /ephemeral Mensagens temporárias da conversa
- POST
{número}/chats /{jid} /history-sync Pedir mensagens antigas ao celular
- POST
{número}/messages /read Marcar mensagens como lidas
- POST
{número}/messages /{messageId} /star Favoritar mensagem
- POST
{número}/messages /{messageId} /pin Fixar mensagem na conversa
- GET
{número}/labels Listar etiquetas do WhatsApp
- POST
{número}/labels Criar ou editar etiqueta
- DELETE
{número}/labels /{labelId} Apagar etiqueta
- POST
{número}/labels /refresh Sincronizar etiquetas com o celular
- GET
{número}/chats /{jid} /labels Etiquetas de uma conversa
- POST
{número}/chats /{jid} /labels Aplicar ou tirar etiqueta da conversa
Exemplo: Listar a conversa mais recente
curl "https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/chats?limit=1" \
-H "Authorization: Bearer $FLOWZAP_KEY"{
"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
- POST
/v1 /workspaces /{workspaceId} /message-templates Criar modelo
- GET
/v1 /workspaces /{workspaceId} /message-templates /{id} Ler um modelo
- PUT
/v1 /workspaces /{workspaceId} /message-templates /{id} Alterar um modelo
- DELETE
/v1 /workspaces /{workspaceId} /message-templates /{id} Apagar um modelo
- POST
{número}/messages /template Enviar por modelo (agora ou agendado)
- POST
{número}/scheduled-messages Agendar mensagem
- GET
{número}/scheduled-messages Listar mensagens agendadas
- GET
{número}/scheduled-messages /{id} Ler uma mensagem agendada
- POST
{número}/scheduled-messages /{id} /cancel Cancelar mensagem agendada
Exemplo: Lembrete de Pix agendado por modelo
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"
}'{
"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
- GET
{número}/groups Listar grupos do número
- POST
{número}/groups /join Entrar em grupo por convite
- GET
{número}/groups /invites /{code} Ver grupo pelo convite
- GET
{número}/groups /{jid} Dados do grupo e participantes
- GET
{número}/groups /{jid} /invite-link Link de convite
- POST
{número}/groups /{jid} /invite-link /reset Gerar novo link de convite
- POST
{número}/groups /{jid} /leave Sair do grupo
- PUT
{número}/groups /{jid} /name Renomear grupo
- PUT
{número}/groups /{jid} /description Alterar descrição do grupo
- PUT
{número}/groups /{jid} /announce Só administradores enviam
- PUT
{número}/groups /{jid} /locked Só administradores editam o grupo
- PUT
{número}/groups /{jid} /join-approval Aprovar entrada pelo link
- PUT
{número}/groups /{jid} /member-add-mode Quem pode adicionar membros
- PUT
{número}/groups /{jid} /ephemeral Mensagens temporárias do grupo
- PUT
{número}/groups /{jid} /image Trocar foto do grupo
- POST
{número}/groups /{jid} /participants Adicionar, remover, promover ou rebaixar
- POST
{número}/groups /{jid} /invite-message Enviar convite individual
- GET
{número}/groups /{jid} /requests Pedidos de entrada pendentes
- POST
{número}/groups /{jid} /requests Aprovar ou recusar pedidos de entrada
- POST
{número}/communities Criar comunidade
- GET
{número}/communities /{jid} /groups Grupos de uma comunidade
- POST
{número}/communities /{jid} /groups Vincular ou desvincular grupos
Exemplo: Criar um grupo
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"] }'{
"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
- POST
{número}/contacts /check Verificar se telefones têm WhatsApp
- POST
{número}/contacts Adicionar contato à agenda
- DELETE
{número}/contacts /{jid} Remover contato da agenda
- GET
{número}/contacts /{jid} Dados de um contato
- GET
{número}/contacts /{jid} /avatar Foto de perfil de um contato
- POST
{número}/contacts /{jid} /block Bloquear ou desbloquear
- GET
{número}/blocklist Lista de bloqueados
- GET
{número}/profile Perfil do próprio número
- PUT
{número}/profile /name Alterar nome de exibição
- PUT
{número}/profile /status Alterar recado (sobre)
- PUT
{número}/profile /image Trocar foto de perfil
- GET
{número}/privacy Ler configurações de privacidade
- PUT
{número}/privacy Alterar uma configuração de privacidade
- POST
{número}/presence Ficar online ou offline
- POST
{número}/presence /chat Mostrar digitando ou gravando
- POST
{número}/presence /subscribe Acompanhar presença de um contato
Exemplo: Verificar quem tem WhatsApp
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"] }'{
"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
- GET
{número}/group-broadcasts Listar envios para grupos
- GET
{número}/group-broadcasts /{id} Ler um envio para grupos
- GET
{número}/group-broadcasts /{id} /report Resultado por grupo
- POST
{número}/group-broadcasts /{id} /pause Pausar envio para grupos
- POST
{número}/group-broadcasts /{id} /resume Retomar envio para grupos
- POST
{número}/group-broadcasts /{id} /cancel Cancelar envio para grupos
- POST
{número}/launch-links Criar link de lançamento
- GET
{número}/launch-links Listar links de lançamento
- GET
{número}/launch-links /{id} Ler um link de lançamento
- PUT
{número}/launch-links /{id} Alterar link de lançamento
- DELETE
{número}/launch-links /{id} Apagar link de lançamento
Exemplo: Um link que enche três grupos em ordem
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
}'{
"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)
- POST
{número}/calls /{callId} /answer Atender ligação (uma vez; com ou sem aviso de gravação)
- POST
{número}/calls /{callId} /decline Recusar ligação que está tocando
- POST
{número}/calls /{callId} /hangup Desligar ligação
- POST
{número}/calls /{callId} /mute Silenciar ou reativar o áudio enviado
- POST
{número}/calls /{callId} /media-ticket Novo bilhete de áudio
- POST
{número}/calls /{callId} /reject Recusar chamada recebida no celular
- GET
{número}/calls Histórico de ligações do número
- GET
{número}/calls /{callId} Ver ligação
- GET
{número}/calls /{callId} /recording Baixar a gravação (Ogg/Opus, aceita Range)
- DELETE
{número}/calls /{callId} /recording Apagar a gravação
- GET
{número}/call-recording Ver a gravação das ligações do número
- PUT
{número}/call-recording Ligar ou desligar a gravação e o aviso falado padrão
- GET
/v1 /calls /numbers Ver os números com ligações
- PUT
/v1 /calls /numbers Escolher os números com ligações
Exemplo: Fazer uma ligação com áudio
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}'{
"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
- POST
/v1 /calls /media-origins Cadastrar uma origem do áudio no navegador
- DELETE
/v1 /calls /media-origins Remover uma origem do áudio no navegador
- GET
/v1 /calls /test-numbers Ver os números de teste do piloto
- PUT
/v1 /calls /test-numbers Definir os números de teste do piloto
- GET
{número}/calls /readiness Ver se o número está pronto para ligações
Exemplo: Liberar a origem de produção para o áudio
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"}'{
"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
- POST
{número}/newsletters /{jid} /admins Convidar administrador do canal
- POST
{número}/newsletters Criar canal
- GET
{número}/newsletters Canais que o número segue
- GET
{número}/newsletters /invites /{code} Ver canal pelo convite
- GET
{número}/newsletters /{jid} Dados do canal
- GET
{número}/newsletters /{jid} /messages Publicações do canal
- GET
{número}/newsletters /{jid} /updates Novidades (visualizações e reações)
- POST
{número}/newsletters /{jid} /follow Seguir ou deixar de seguir
- POST
{número}/newsletters /{jid} /mute Silenciar canal
- POST
{número}/newsletters /{jid} /viewed Marcar publicações como vistas
- POST
{número}/newsletters /{jid} /reaction Reagir a uma publicação
- POST
{número}/newsletters /{jid} /live Receber novidades ao vivo
- POST
{número}/newsletters /{jid} /posts Publicar texto no canal
- PUT
{número}/newsletters /{jid} /posts /{serverId} Editar publicação
- DELETE
{número}/newsletters /{jid} /posts /{serverId} Apagar publicação
Exemplo: Publicar texto num canal seu
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." }'{
"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
- GET
{número}/business /catalog Listar catálogo
- POST
{número}/business /catalog Criar produto
- GET
{número}/business /catalog /{productId} Ler produto
- PUT
{número}/business /catalog /{productId} Editar produto
- DELETE
{número}/business /catalog /{productId} Apagar produto
- GET
{número}/business /profile Perfil comercial do próprio número
- GET
{número}/business /profile /{jid} Perfil comercial de um contato
Exemplo: Ler o perfil comercial de um contato
curl https://flowzap.flowpost.com.br/v1/workspaces/$WORKSPACE/instances/$NUMERO/business/profile/5511955554444@s.whatsapp.net \
-H "Authorization: Bearer $FLOWZAP_KEY"{
"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)
- POST
/v1 /events /stream-token Token curto (5 min) para o fluxo SSE no navegador
- GET
/v1 /events /{id} Ler um evento (motor, atendimento, funil ou gravação)
- GET
{número}/events Eventos de um número, em ordem
- GET
{número}/inbound Mensagens recebidas
- GET
{número}/inbound /{id} Ler uma mensagem recebida
- POST
/v1 /webhook-endpoints Cadastrar endereço de webhook
- GET
/v1 /webhook-endpoints Listar endereços de webhook
- GET
/v1 /webhook-endpoints /{id} Ver um endereço de webhook
- PATCH
/v1 /webhook-endpoints /{id} Alterar endereço, filtros ou pausar/reativar
- POST
/v1 /webhook-endpoints /{id} /ping Testar o endereço (aviso webhook.ping)
- DELETE
/v1 /webhook-endpoints /{id} Remover endereço de webhook
- POST
/v1 /webhook-endpoints /{id} /rotate-secret Trocar o segredo de um webhook
- GET
/v1 /webhook-deliveries Histórico de entregas, com filtros e cursor
- POST
/v1 /webhook-deliveries /{id} /retry Reenviar uma entrega de webhook
Exemplo: Conferir a assinatura de um webhook (Node.js)
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)
);
});
}{
"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
- GET
{número}/crm /leads /{contact} Ler um lead
- PUT
{número}/crm /leads /{contact} Criar ou atualizar lead
- DELETE
{número}/crm /leads /{contact} Apagar lead
- POST
{número}/crm /leads /{contact} /opt-out Registrar saída da lista (opt-out)
- GET
{número}/crm /leads /{contact} /notes Anotações do lead
- POST
{número}/crm /leads /{contact} /notes Criar anotação
- DELETE
{número}/crm /notes /{id} Apagar anotação
- GET
{número}/crm /tags Listar etiquetas de lead
- POST
{número}/crm /tags Criar etiqueta de lead
- DELETE
{número}/crm /tags /{id} Apagar etiqueta de lead
- GET
{número}/quick-replies Listar respostas rápidas
- POST
{número}/quick-replies Criar resposta rápida
- PUT
{número}/quick-replies /{id} Editar resposta rápida
- DELETE
{número}/quick-replies /{id} Apagar resposta rápida
Exemplo: Registrar um lead com consentimento
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" }
}'{
"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
- GET
{número}/campaigns Listar campanhas
- GET
{número}/campaigns /summary Painel de campanhas do número
- GET
{número}/campaigns /{id} Ler campanha e contagens
- GET
{número}/campaigns /{id} /recipients Destinatários e resultado
- GET
{número}/campaigns /{id} /report Painel da campanha
- POST
{número}/campaigns /{id} /pause Pausar campanha
- POST
{número}/campaigns /{id} /resume Retomar campanha
- POST
{número}/campaigns /{id} /cancel Cancelar campanha
Exemplo: Agendar uma campanha para uma etiqueta de leads
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
}'{
"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
- PUT
{número}/chatwoot Ligar ou alterar integração com o Chatwoot
- DELETE
{número}/chatwoot Remover integração com o Chatwoot
- POST
/v1 /chatwoot /hooks /{token} Webhook chamado pelo Chatwoot
Exemplo: Ligar o Chatwoot a um número
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
}'{
"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
- POST
{número}/crm /stages Criar etapa
- PATCH
{número}/crm /stages /{id} Alterar etapa
- DELETE
{número}/crm /stages /{id} Apagar etapa
- GET
{número}/crm /pipeline Ver funil
- POST
{número}/crm /leads /{contact} /move Mover contato de etapa
- GET
{número}/crm /fields Listar campos personalizados
- POST
{número}/crm /fields Criar campo personalizado
- PATCH
{número}/crm /fields /{id} Alterar campo personalizado
- DELETE
{número}/crm /fields /{id} Apagar campo personalizado
- GET
{número}/tickets Listar atendimentos
- POST
{número}/tickets Abrir atendimento
- GET
{número}/tickets /csat-summary Resumo da pesquisa de satisfação
- POST
{número}/tickets /bulk Alterar vários atendimentos
- GET
{número}/tickets /{id} Ler atendimento
- GET
{número}/tickets /{id} /events Histórico do atendimento
- POST
{número}/tickets /{contact} /resolve Resolver atendimento
- POST
{número}/tickets /{contact} /reopen Reabrir atendimento
- PUT
{número}/tickets /{contact} /assignee Atribuir atendimento
- PUT
{número}/tickets /{contact} /pending Marcar pendência no atendimento
- DELETE
{número}/tickets /{contact} /pending Retirar pendência do atendimento
Exemplo: Mover um contato para a etapa Proposta
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" }'{
"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
- PUT
{número}/auto-replies Alterar respostas automáticas
Exemplo: Ligar boas-vindas com menu e pesquisa de satisfação
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!"
}
}'{
"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
- GET
{número}/audiences Listar públicos
- GET
{número}/audiences /{id} Ler um público
- DELETE
{número}/audiences /{id} Apagar um público
- POST
{número}/audiences /{id} /refresh Atualizar um público
- GET
{número}/audiences /{id} /members Membros de um público
- POST
{número}/audiences /{id} /exports Exportar para Meta, Google ou planilha
- GET
{número}/audiences /{id} /exports Histórico de exportações
- DELETE
{número}/audiences /members /{phone} Tirar uma pessoa de todos os públicos
Exemplo: Coletar dois grupos num público
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"]
}'{
"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
- GET
/v1 /public /content /items /{type} /{slug} Ler um conteúdo publicado
- GET
/v1 /public /content /authors /{slug} Ler um autor
- GET
/v1 /public /content /sitemap-entries Entradas do sitemap
- GET
/v1 /public /content /feed-entries Entradas do feed RSS
- GET
/v1 /public /content /llms-entries Entradas do llms.txt
Exemplo: Listar os artigos publicados
curl "https://flowzap.flowpost.com.br/v1/public/content/items?type=article&page=1"{
"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.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.
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.
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).
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).
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.