Autenticação

Cada requisição carrega quatro cabeçalhos. A chave identifica quem chama. O segredo nunca é enviado — ele assina. O carimbo de tempo e o nonce impedem que uma requisição capturada seja reenviada depois.

A string assinada

Concatene exatamente nesta ordem, separando por quebra de linha. O corpo entra como hash, não inteiro — assim a assinatura funciona com streaming.

Listar instâncias

Todos os números conectados à sua conta, com o estado de cada um. Use no início do seu app para descobrir por qual instância enviar.

Detalhar instância

Estado completo de um número, incluindo consumo das últimas 24 horas e quando o acesso vence. Consulte no máximo uma vez por minuto — o resto vem por notificação, que é mais rápido e não gasta seu limite.

Enviar mensagem

Envia texto, mídia, botões, lista ou carrossel para um número. Só funciona dentro da janela de 24 horas — se o contato não escreveu nos últimos um dia, use um modelo aprovado.

Listar modelos

Os modelos aprovados da conta WhatsApp Business (WABA) a que este número pertence. O modelo pertence ao WABA, não ao número: dois números do mesmo WABA devolvem a mesma lista.

Cada item traz fields — exatamente o que precisa ser preenchido para enviar aquele modelo, já com o exemplo aprovado. É o que evita descobrir na Meta, em forma de código numérico, que faltava o parâmetro do botão de URL.

Enviar modelo

Único jeito de iniciar conversa com quem não escreveu nas últimas 24 horas. O modelo precisa estar aprovado pela Meta — aprovação leva de minutos a algumas horas.

Listar mensagens

Mensagens de todas as conversas, das mais recentes para as mais antigas. Útil para auditoria e para reconciliar o que sua base perdeu.

O campo sent_from_phone distingue o que saiu pela API do que o dono digitou no celular. Sua automação precisa dele para não responder por cima de uma resposta humana.

media é null em mensagem de texto. Em foto, áudio, vídeo ou documento traz mime_type, filename e download_path — veja Receber mídia.

Marcar como lida

Os dois traços azuis no celular do contato. Sem isto, você responde pela API e a pessoa do outro lado continua vendo a mensagem dela como não lida — o que parece defeito do WhatsApp e chega como reclamação para você.

Só vale para mensagem recebida (direction: inbound) que já tenha wamid. Zera também o contador de não lidas da conversa, para o painel e o celular do contato não discordarem.

A chamada vai direto à Meta, sem passar pela fila: recibo atrasado não serve para nada, e ele não disputa a vazão do número com mensagem de verdade.

Listar conversas

Devolve conversas ordenadas pela última mensagem. Paginação por cursor — nunca por offset, que pula ou repete registros quando chegam mensagens durante a leitura.

Histórico da conversa

Mensagens de uma conversa em ordem cronológica, com o histórico que já existia no celular antes de você conectar — a coexistência importa o passado, não só o futuro.

Listar oportunidades

Oportunidades do funil com etapa, valor e a conversa de origem. Cada lead aponta para a conversa que o gerou — é assim que seu CRM mostra o histórico junto do negócio.

Mover de etapa

Avança ou recua uma oportunidade. Dispara lead.stage_changed e grava quem moveu no histórico.

Receber notificações

Quando chega mensagem, muda status ou um lead avança, chamamos a URL que você cadastrou no painel. Verifique a assinatura antes de processar e responda 200 rápido — deixe o trabalho pesado para depois da resposta.

Verificar a assinatura

Mesmo esquema da API, na direção contrária: assinamos com o segredo whsec_ da sua instância.

Reenvio e duplicatas

Se o seu endpoint não responder 200, tentamos de novo em 0 s, 30 s, 2 min, 10 min, 1 h, 6 h e 24 h. Depois disso o evento vai para a fila de falhas, visível no painel, com reenvio manual.

Endpoint que falha 100% das entregas por 24 horas é desativado automaticamente e você é avisado por e-mail. Um endpoint morto consumindo tentativas atrasa as notificações que funcionam.

Tipos de evento

Escolha quais você quer receber no painel, por instância.

message.sent_from_phone só existe em instâncias com coexistência. É como seu sistema fica sabendo que o dono já respondeu pelo celular — sem ele, sua automação responde por cima e o cliente recebe duas respostas.

Limites e cobrança

Dois limites diferentes, que se confundem com facilidade: vazão é quão rápido, volume é quantas pessoas.

A Meta cobra por conversa de 24 horas, não por mensagem. Quem inicia define a categoria e o preço: conversa iniciada pelo cliente é mais barata que conversa iniciada por modelo. O campo billable na resposta diz se aquele envio abriu uma conversa cobrada.

Erros

Todo erro devolve o mesmo formato, com code estável para você tratar em código e message em português para mostrar a quem opera.

Todo erro traz request_id no corpo, dentro de error. Guarde no seu log — é por ele que o suporte encontra a requisição exata.

Como integrar

Para n8n existe node oficial: n8n-nodes-fluxo, com 36 ações e a assinatura já resolvida — veja abaixo. Em qualquer outra linguagem a API é HTTP puro e a assinatura são seis linhas concatenadas. Copie o exemplo e adapte: os dois erros mais comuns são assinar o corpo já re-serializado e esquecer a query string no caminho.

Postos de estado

O estado de uma mensagem enviada avança por posto e nunca retrocede. A Meta entrega os avisos fora de ordem, e é o posto — não a ordem de chegada — que decide o que vale.

Compare sempre por rank. Um delivered atrasado chegando depois de um read não desfaz a leitura — do nosso lado ele é simplesmente ignorado, e do seu também deveria ser.

Paginação e janelas

GET /conversations pagina por cursor. Mande de volta o next_cursor que veio na resposta anterior; null é fim da lista.

O cursor é um carimbo de tempo codificado, não um deslocamento. Isso importa: com offset, mensagens chegando no meio da paginação empurram a lista e fazem você pular ou repetir conversas. Com cursor, não.

GET /messages não pagina por cursor: ele limita a janela a 90 dias por consulta — a tabela é particionada por mês, e uma varredura sem limite atravessaria todas as partições de uma vez. Sem since, a consulta usa os últimos 7 dias. Passando de 90, a resposta é 422 range_too_wide.

Identificadores e ambientes

Todo identificador é um ULID com prefixo. Diferente de UUID aleatório, o ULID é ordenável por tempo — ordenar por id é ordenar por criação, e o banco insere sempre à direita do índice em vez de fragmentar página.

O prefixo live ou test na chave existe para evitar o acidente mais caro que há: disparar uma campanha de teste contra a base real de clientes. Os dois prefixos são visíveis no painel e no log.

GET https://api.fluxoapi.com.br/health responde sem autenticação, com status, db, redis e version. Use no seu monitoramento; devolve 503 quando algo abaixo está fora.

Assinando em outras linguagens

A receita é a mesma em qualquer lugar: seis linhas unidas por quebra de linha, HMAC-SHA256 com o segredo, hexadecimal, prefixo v1=. O corpo entra pelo hash, e precisa ser exatamente os bytes que você vai enviar.

Requisição sem corpo usa o sha256 da string vazia: e3b0c442…7852b855. E o caminho assinado inclui a query string — /v1/messages?limit=10, não /v1/messages.

Node do n8n

Pacote oficial: n8n-nodes-fluxo. Instale em Configurações → Community nodes e informe o nome do pacote. Ele resolve a assinatura, a paginação e a janela de 24 h por você.

São 36 ações, e a credencial pede só dois campos: API Key (fxk_…) e HMAC Secret (fxs_…). O segredo nunca sai do n8n — só a assinatura calculada vai na requisição.

Nem toda ação é um endpoint. Enviar Texto Longo divide em partes de 4096 caracteres e envia em série (em paralelo, a fila entregaria a parte 2 antes da 1). Pré-Visualizar, Validar Preenchimento e Validar Número resolvem dentro do node, sem chamar a Meta — conferir antes de gastar um envio cobrado é o ponto. Contar Por Status consulta status a status, com teto de 200 por consulta: ao bater o teto, a resposta marca amostra_limitada em vez de mentir um total. Baixar Mídia recebe o message_id do gatilho e devolve o arquivo como binário, pronto para Google Drive, S3 ou transcrição.

Servidor MCP — para agentes de código

A FluxoAPI expõe um servidor MCP em https://mcp.fluxoapi.com.br. Ele serve para um agente de código ajudar você a integrar: ler a especificação, achar o instance_id, montar a assinatura, explicar um erro que apareceu ontem.

É somente leitura, e de propósito. O MCP não é caminho para um agente conversar com o seu cliente final — quem envia mensagem é a API pública, com chave e segredo, onde o dono da conta assina cada chamada.

A autorização é OAuth 2.1 com PKCE obrigatório (S256), audiência ligada ao recurso (RFC 8707) e registro dinâmico de cliente (RFC 7591) — o cliente se cadastra sozinho, e o acesso só existe depois que você entra e aprova numa tela que mostra exatamente o que ele vai ler. Nenhuma senha chega ao agente.

Você revoga quando quiser em Configurações → MCP. Revogar derruba os tokens na hora.

Saúde da plataforma

Feito para o seu monitoramento. Responde 200 quando banco e Redis respondem, e 503 quando algum deles está fora.

Um 503 aqui significa que os envios estão parados — e que o recebimento também. É o primeiro lugar para olhar antes de abrir chamado.

Métricas

Formato de exposição do Prometheus. Exige Authorization: Bearer com o token de métricas da instalação.

Sem token configurado, a rota responde 404 em produção — e não 401. As métricas contam mensagens por conta, falhas de assinatura e profundidade de fila: é o mapa da operação, e um 401 já confirmaria que há algo do outro lado.

Metadata do Authorization Server

RFC 8414. Diz onde autorizar, onde trocar o código, onde revogar e onde se registrar.

É o primeiro lugar que um cliente MCP consulta. Cliente que não encontra registration_endpoint aqui aborta com does not support dynamic client registration — sem tentar mais nada.

Registrar um cliente

RFC 7591. É aberto por definição do protocolo: quem se registra ainda não tem conta aqui.

Registrar não concede nada. O cliente nasce sem dono, sem token e sem conta ligada. O que ele ganha é o direito de pedir — e o pedido só vira acesso depois que uma pessoa entra, lê a tela de consentimento e aprova.

redirect_uris aceita https://, ou http:// apenas em localhost, 127.0.0.1 e ::1. Sem essa trava, o registro aberto viraria uma máquina de redirecionamento assinada por nós.

Só emitimos cliente público com PKCE — não há client_secret. Limite de 10 registros por hora por origem; cliente que nunca vira token é apagado em 7 dias.

Tela de consentimento

Devolve HTML, não JSON: quem está do outro lado é uma pessoa. Sem sessão, redireciona para o login e volta para cá depois.

Nada é concedido aqui. O pedido fica guardado por 5 minutos e só vira código depois do clique em Permitir — sem isso, bastaria um site levar o navegador logado até esta URL para um cliente qualquer receber um código que ninguém autorizou.

PKCE com S256 é obrigatório; plain é recusado. O redirect_uri é comparado por igualdade exata com os registrados — prefixo permitiria roubar o código com https://legitimo.com.evil.com.

resource (RFC 8707) é obrigatório e vira a audiência do token: token emitido para outro recurso não vale no nosso servidor MCP.

Trocar o código por token

Aceita application/x-www-form-urlencoded. Dois fluxos.

authorization_code — troca o código, conferindo o code_verifier do PKCE em tempo constante. Código reutilizado revoga todos os tokens daquele cliente: se alguém interceptou e chegou primeiro, o legítimo derruba a sessão do atacante ao tentar.

refresh_token — rotaciona, e o antigo morre no uso. Apresentar um refresh já rotacionado é sinal de vazamento, e revoga a linhagem inteira.

Limite de 30 requisições por minuto por origem.

Revogar um token

Aceita access token ou refresh token.

Responde 200 sempre, inclusive para token desconhecido — é o que a RFC 7009 manda, e a razão é a mesma de sempre: distinguir permitiria sondar quais tokens existem.

Metadata do recurso protegido

RFC 9728. É por aqui que o cliente descobre qual Authorization Server usar.

O 401 do servidor MCP aponta esta URL no cabeçalho WWW-Authenticate — junto, as duas coisas fazem a configuração ser automática: você informa só a URL do servidor.

Chamar o servidor MCP

JSON-RPC 2.0. Métodos: initialize, tools/list, tools/call.

É somente leitura, e de propósito. Serve para um agente de código ajudar você a integrar a API — ler a especificação, achar o instance_id, montar a assinatura, explicar um erro de ontem. Não é o caminho para um agente conversar com o seu cliente final: quem envia mensagem é a API pública, onde o dono da conta assina cada chamada.

A audiência do token é conferida contra o próprio endereço (RFC 8707). Cada ferramenta exige um escopo, e o erro diz qual falta.

Tabela de preços

Faixas e preço por número. Sem autenticação — é o que a página de planos consome.

Dados do link de conexão

O link que a empresa envia ao dono do número, para ele conectar o WhatsApp sem ter conta no painel.

Entrega só o necessário para a tela: nome da empresa, nome do número e a configuração do Embedded Signup. Nada de conversa, nada de identificador de outro número.

Vale uma vez e expira. Limite de 30 tentativas por minuto por origem — o token tem 43 caracteres aleatórios, mas força bruta barata é barata em qualquer tamanho de chave.

Enviar imagem

A URL precisa ser pública e responder Content-Type de imagem — a Meta busca o arquivo por conta dela, e não enxerga o que está atrás do seu login.

JPEG e PNG, até 5 MB. A legenda é opcional e vai junto, na mesma bolha.

Enviar documento

PDF, planilha, o que for — até 100 MB. Use a legenda para dizer o que é: sem ela o contato vê só o nome do arquivo.

O nome que aparece no WhatsApp é o de media.filename. Sem ele, a Meta usa o final da URL — .../arquivo?id=93 chegaria como arquivo.

Enviar áudio

Áudio não aceita legenda — a Meta ignora. Até 16 MB.

Para virar mensagem de voz (a bolha com a onda), o arquivo precisa ser .ogg com codec OPUS. Qualquer outro formato chega como arquivo de áudio anexado.

Enviar vídeo

MP4 ou 3GPP, até 16 MB. Aceita legenda.

O limite é da Meta, não nosso. Vídeo maior: hospede e mande o link como texto.

Enviar botões de resposta

Até 3 botões abaixo do texto. O contato toca em um e a escolha volta pelo webhook — é o jeito mais curto de fazer "confirmar ou remarcar" sem depender de a pessoa digitar certo.

Não precisa de modelo aprovado nem é cobrado à parte, mas só sai com a janela de 24 horas aberta.

Enviar lista

Um botão que abre um menu com até 10 opções, agrupadas em seções. Serve quando três botões não bastam: horários, unidades, planos.

O limite de 10 é de linhas somando todas as seções, não por seção — duas seções de 6 são recusadas.

Enviar botão de link

Um botão que abre um endereço no navegador do celular, no lugar de um link cru no meio do texto. Boleto, rastreio, pagamento.

Aceita header (texto ou mídia) e footer como os botões de resposta. Tocar no link não gera webhook — a Meta não avisa.

Enviar carrossel

De 2 a 10 cartões lado a lado, cada um com imagem ou vídeo, texto curto e botões. Sem modelo aprovado — dentro da janela de 24 horas. Fora dela, carrossel continua existindo, mas como modelo.

Cada cartão leva buttons (respostas rápidas) ou cta (um botão de link), nunca os dois. E todos os cartões precisam do mesmo formato: se o primeiro tem 2 respostas rápidas, todos têm 2.

Receber o clique

Quando o contato toca num botão de resposta, numa linha da lista ou numa resposta rápida do carrossel, chega um message.received com type: "interactive" e o objeto reply.

text traz o título escolhido — é o que aparece na Inbox. reply.id é o id que você definiu no envio. reply_to_wamid diz qual mensagem foi respondida.

Receber mídia

Quando o contato manda foto, áudio, vídeo, documento ou figurinha, o message.received chega com o objeto media. O mesmo vale para message.sent_from_phone quando o dono manda mídia pelo celular.

A Meta não entrega o arquivo no evento — só um identificador, e o endereço que ele gera expira em 5 minutos e exige o token do número. Por isso você baixa por aqui: um GET assinado em media.download_path devolve os bytes do arquivo, com Content-Type e Content-Disposition certos. Não é JSON.

text traz a legenda. Sem legenda vem vazio — exceto em documento, que traz o nome do arquivo. Para decidir o que fazer, olhe type, não text.

Com ?download=1 a resposta sai sempre como anexo. Tipos que o navegador executaria (HTML, SVG) saem como anexo mesmo sem o parâmetro.

Responder citando uma mensagem

Mande reply_to com o wamid da mensagem que você está respondendo — não com o nosso msg_….

O contato vê a citação acima da sua resposta, como no aplicativo. Num fio longo, é o que evita a pergunta "respondendo o quê?".

Enviar para vários contatos

Não existe envio em lote num único pedido — e isso é de propósito: janela fechada de um contato não pode derrubar a lista inteira.

Faça uma chamada por destinatário, tratando cada resposta. Use idempotency_key derivada do telefone: se o seu laço quebrar no meio e você reprocessar, quem já recebeu não recebe de novo.

Respeite o limite do plano — ao ver 429, espere o Retry-After em vez de insistir.

Enviar texto longo

O limite é 4096 caracteres por mensagem. Acima disso a chamada é recusada com 422 invalid_input.

Quebre o texto e envie em série, esperando cada resposta. Em paralelo, a fila pode entregar a parte 2 antes da 1 e o texto chega embaralhado.

Corte em parágrafo, depois em frase, depois em espaço — nunca no meio da palavra.

Acompanhar a entrega

O envio responde 202 com queued: nada foi entregue ainda. Quem diz o que aconteceu é o webhook message.status — ou esta consulta, se você preferir perguntar.

Filtre por status para achar o que falhou, e por since para não varrer o histórico inteiro. A janela máxima é de 90 dias.

Entender uma falha

Mensagem com status: failed traz error_code e error_message — os dois vêm da Meta, não de nós.

Os mais comuns: 131047 a janela de 24 h fechou (use modelo); 131026 o número não tem WhatsApp; 132000 o modelo tem número de variáveis diferente do aprovado; 130429 vazão estourada — a fila já reenvia sozinha.

Reenviar não é automático para falha definitiva: corrija a causa e mande de novo, com idempotency_key nova.

Ver quem ainda dá para responder

Cada conversa traz window_expires_at. No futuro, você responde livremente; no passado ou null, só modelo aprovado — e modelo é cobrado.

É a consulta que decide o custo do seu dia: responder dentro da janela é grátis.

Listar quem está esperando

unread conta as mensagens recebidas sem leitura. Maior que zero significa que alguém escreveu e ninguém respondeu.

Some com window_expires_at e você tem a fila de trabalho do dia, na ordem certa: quem espera há mais tempo e cuja janela fecha antes.

Achar conversas paradas

Use since ao contrário do habitual: em vez de pedir o que é novo, pegue a lista e separe o que não se mexe há horas.

Conversa aberta e parada é receita esfriando — e a janela de 24 h corre contra você.

Encontrar a conversa de um número

Não há busca por telefone no servidor: a lista vem por last_message_at e você filtra pelo campo phone.

Compare só os dígitos. O mesmo contato aparece como +55 11 99999-9999 na exibição e 5511999999999 no dado — normalizar os dois lados evita o falso "não encontrei".

Exportar o fio de uma conversa

Traz o histórico com direction, type, texto e horário. Use order=asc para ler de cima para baixo.

É o formato certo para jogar num modelo de linguagem, anexar num chamado ou arquivar: uma linha por mensagem, com quem falou.

Marcar como lida

Os dois traços azuis no celular do contato, e o unread da conversa zerado.

Sem isso, você responde pela API e a pessoa continua vendo a mensagem dela como não lida — o que parece defeito do WhatsApp e chega como reclamação para você.

Só vale para mensagem recebida que já tenha wamid.

Contar conversas

Não há endpoint de contagem: pagine e some. Com limit=100 e o cursor, cada volta traz cem.

Para número exibido em painel, guarde o resultado por alguns minutos — contar tudo a cada carregamento de tela gasta o limite do seu plano à toa.

Só o que mudou desde a última vez

since devolve apenas conversas com mensagem depois daquele instante. É o que transforma uma sincronização inteira numa consulta barata.

Guarde o last_message_at mais recente que você processou e mande de volta na próxima rodada. Prefira isso a repaginar tudo.

Se você recebe webhooks, esta consulta vira só a rede de segurança para quando o seu endpoint ficou fora do ar.

Descobrir o que um modelo pede

Cada modelo da resposta traz fields: exatamente o que precisa ser preenchido, já com exemplo.

É o que evita descobrir na Meta, em forma de código numérico, que faltava o parâmetro do botão de URL. Leia fields antes de montar o envio.

Filtrar o catálogo

status, category, language e name filtram a lista. Só APPROVED pode ser enviado.

O catálogo é cacheado por 5 minutos. refresh=true relê da Meta na hora — use quando você acabou de aprovar um modelo, e não a cada carregamento: essa chamada consome o orçamento da Graph API, que é compartilhado pela plataforma.

Preencher as variáveis do corpo

As variáveis do corpo são posicionais: {{1}}, {{2}}. Mande um objeto com a posição como chave.

Faltar uma, ou mandar a mais, faz a Meta recusar a mensagem inteira com 132000. Confira em fields quantas o modelo espera.

Cabeçalho com mídia

Modelo com cabeçalho de imagem, vídeo ou documento espera a mídia no envio — o desenho aprovado define o tipo, você fornece o arquivo.

Aceita link com URL pública, ou id de mídia já enviada à Meta. Documento aceita também filename, que é o nome que o contato vê.

Botões com trecho variável

Botão de URL dinâmica tem uma parte fixa, aprovada, e um trecho que você preenche. Mande em buttons, indexado pela posição do botão.

Botão de copiar código usa code, e oferta por tempo limitado usa offer_expiration_ms.

Esquecer o parâmetro de um botão recusa a mensagem inteira — não só o botão.

Carrossel

Modelo de carrossel leva vários cartões, cada um com o próprio cabeçalho de mídia, corpo e botões. Mande em cards, indexado pela posição.

A quantidade de cartões é a do modelo aprovado. Mandar menos, ou mais, é recusado.

Montar os components à mão

Se você já monta o array da Meta, mande template.components pronto e nós passamos adiante sem validar.

É escotilha de emergência: existe para não travar um recurso novo da Meta atrás de um deploy nosso. Em troca, você perde a conferência contra a definição do modelo — e o erro aparece como recusa da Meta, não como mensagem nossa.

Quando o modelo é cobrado

Sempre. Modelo abre conversa cobrada pela Meta mesmo que o contato nunca responda. A resposta traz billable: true para você saber antes da fatura.

Dentro da janela de 24 h, mensagem comum é grátis. Antes de disparar modelo, confira window_expires_at — se estiver aberta, use texto.

O preço varia por categoria (marketing, utilidade, autenticação) e por país. A tabela é da Meta.

Criar modelo

Submete um modelo novo à análise da Meta, no WABA deste número. Ele nasce PENDING e a Meta aprova, recusa ou muda a categoria em minutos ou horas — acompanhe por GET /templates?name=….

Você manda a receita, não os components da Meta. Ela passa pelo mesmo validador do painel: a Meta recusa criação com (#100) Invalid parameter sem dizer o quê, e aqui o erro volta em português, apontando o campo.

Subir mídia do cabeçalho

Para enviar um modelo, cabeçalho de imagem aceita link. Para criar, a Meta exige um handle — é esta rota que gera. Use-o em header.handle ou cards[].header.handle.

O arquivo vai em base64 dentro do JSON, até 5 MB. Não há busca por URL, de propósito. Com chave test, volta um handle SIMULADO_… que só vale para criação com chave test.