Documentação

API do WhatsApp pela Zera: o que você recebe e o que fazer com isso.

A referência de endpoint e de payload é a da Meta, e continua sendo. Esta página documenta a parte que é da Zera: como a credencial chega até você, o que a conexão faz com o seu número, quais erros aparecem e o que fazer em cada um.

O que não foi confirmado no código não está escrito aqui. Onde falta informação, esta página diz que falta e por quê. Documentação que preenche buraco com suposição custa mais caro do que documentação que não existe.

Entrar no painel Ver os planos da API

O que você recebe

A entrega é uma credencial da Cloud API da Meta, no seu número, dentro da conta do WhatsApp Business da sua empresa. São cinco campos, e a tela do painel devolve exatamente estes.

token texto	A autorização que a Meta gerou para a sua empresa quando você conectou o número. Vai no cabeçalho Authorization das suas chamadas. Não é chave da Zera, não é token de plataforma, não é segredo compartilhado.
phone_number_id texto	O identificador do seu número na Cloud API. É ele que entra na URL de envio da mensagem.
waba_id texto	O identificador da conta do WhatsApp Business da sua empresa na Meta. Serve para consultar números, modelos de mensagem e assinaturas.
webhook texto ou nulo	O endereço https que você informou para receber os eventos. Nulo quer dizer que você ainda não informou nenhum, e a tela diz isso em vez de esconder.
expira_em data ou nulo	O vencimento do token, quando existir. Nulo quer dizer que a Meta não devolveu prazo, e não que o token venceu. Por padrão o token do Embedded Signup não expira por tempo.

De quem é isso, na prática

A conta do WhatsApp Business é da sua empresa, e o token também. A Zera guarda cifrado para operar o seu número, e a posse continua sendo sua.
Só a Meta revoga esse token. A Zera não consegue revogar, e por isso não existe botão de gerar outra credencial no painel. Botão que promete o que o sistema não cumpre é pior do que a ausência dele.
Como não dá para girar a credencial, também não faz sentido exibir uma vez só: quem perdesse ficaria preso. A regra é a outra ponta: você vê quantas vezes precisar, e toda exibição faz barulho.

Como pegar a credencial

A credencial fica na tela do canal, dentro do painel. Ela não é enviada por WhatsApp nem por e-mail, e nunca viaja numa URL. As regras abaixo não são burocracia: cada uma fecha um caminho concreto, e a tela explica cada recusa com a frase dela.

Só no plano sem caixa de entrada

No plano de API a credencial é o produto. Num plano com caixa de atendimento, o ZeraSync usa essa mesma credencial, e girar ou vazar ela derrubaria o seu próprio atendimento. Nesses planos a tela explica isso e não mostra nada.

Sessão de menos de dez minutos

Estar logado não basta. O cookie de sessão dura trinta dias, e a credencial sobrevive a ele. Se a sua sessão for mais velha que dez minutos, a tela pede um link novo e oferece o botão que envia, em vez de dar erro seco.

Três exibições por dia, por conta

A contagem inclui a tentativa em curso e conta tentativa, não sucesso. Estourou, a tela diz que você pediu demais hoje, e não finge que a falha foi nossa.

Toda exibição avisa o dono da conta

Sai um e-mail na hora, com data, hora e origem, e uma linha aparece na aba Atividade do canal. Se o e-mail não for aceito pelo provedor, a credencial não é exibida. O aviso é a trava, não o enfeite: sem poder revogar, a única defesa é você ficar sabendo rápido.

Token vencido não é entregue

Se o token já venceu, a tela diz isso e oferece reconectar o número. Entregar uma credencial morta faria você perder meia hora depurando o seu sistema por um problema que é nosso de avisar.

A conexão do seu número

A conexão acontece na janela oficial da Meta, no seu navegador. O que muda de caminho é a situação em que o número está hoje, e cada caminho executa passos diferentes do lado do servidor.

Número novo	Número sem WhatsApp, ou chip novo. Você precisa receber SMS ou ligação nesse número para a verificação.
Número no WhatsApp comum	A conta precisa ser apagada no aparelho antes, e o histórico local se perde. Isso está dito na tela antes do clique, não depois.
Número no WhatsApp Business	É a coexistência. O número continua funcionando no celular e o histórico é preservado. É a rota mais usada, e ela tem uma lista própria de mudanças, logo abaixo.
Número em outra plataforma de API	Não tem botão hoje, e a ausência é deliberada. A migração depende de a plataforma antiga desligar a verificação em duas etapas, e a Zera não destrava isso sozinha. Esse caso entra em fila com uma pessoa, com instrução na tela. Prometer botão aqui seria vender o que não existe.

O que muda no seu número depois da coexistência

Esta lista é a da tabela oficial da Meta sobre a integração de usuários do aplicativo Business, e não uma lembrança de quem já fez. Ela está aqui porque a diferença entre um desenvolvedor informado e um chamado de suporte é ler isso antes.

Os aparelhos vinculados ao número são desvinculados.
Listas de transmissão são desativadas. Não dá para criar novas, e as existentes ficam somente para leitura.
Grupos não sincronizam. Eles continuam funcionando só no aplicativo.
Mensagens temporárias são desativadas nas conversas de uma pessoa para outra.
Ver uma vez é desativado nas mesmas conversas.
Localização ao vivo é desativada.
Chamadas de voz e de vídeo continuam só no aplicativo.
Catálogo, pedidos e status continuam só no aplicativo.
A vazão fica em vinte mensagens por segundo, fixa.

Na coexistência o número já está registrado na Cloud API, então o passo de registro é pulado de propósito: chamá-lo assim mesmo queimaria uma das dez chamadas que a Meta permite por número a cada 72 horas. E a lista de números da sua conta pode voltar vazia por alguns minutos depois de o diálogo terminar. Nesse caso a conexão espera em vez de falhar. Honestidade sobre a fonte: esse atraso não é documentado pela Meta em lugar nenhum, é relato de quem opera. O que a documentação dela sustenta é outra coisa, e é o que baseia a decisão: o evento de fim prova que o diálogo terminou, não que todo passo de servidor deu certo.

O primeiro envio

Um endpoint, uma chave, um minuto. O endereço é o da Meta, e a mensagem vai do seu servidor direto para lá. A Zera não fica no meio.

curl -X POST https://graph.facebook.com/v25.0/SEU_PHONE_NUMBER_ID/messages \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5545999999999",
    "type": "text",
    "text": { "body": "Olá!" }
  }'

A versão v25.0 é a que a conexão usa hoje, e ela vale até 29 de julho de 2028. Mandar a versão sempre na URL é proposital: chamada sem versão usa a que estiver marcada no painel do aplicativo, e quando uma versão expira a Meta encaminha em silêncio para a próxima, mudando comportamento sem avisar.

O webhook

O que está confirmado

A Zera assina o aplicativo dela na conta do WhatsApp Business da sua empresa, e relê a assinatura depois para conferir que ela existe mesmo. Sem essa assinatura, nenhum evento do seu número sai da Meta.
Você informa um endereço https na ficha de contratação. O https é obrigatório: a Meta recusa endereço em http, e descobrir isso na hora da configuração joga você para o fim da fila.
O endereço é opcional na contratação. Metade de quem compra a credencial ainda está desenvolvendo e não tem endereço para dar, e travar a entrega por causa disso criaria fila humana à toa.

O que ainda não está documentado, e por quê

O apontamento do seu endereço é feito hoje por uma pessoa da Zera, como um passo da fila de entrega, e não por um código que possa ser citado aqui.
Enquanto for assim, esta página não descreve o formato exato do que chega no seu endereço, nem os cabeçalhos, nem a assinatura. Não existe implementação nossa para conferir contra, e escrever isso de memória é como se publica endereço errado para quem vai construir um receptor em cima.
O contrato que vale é o da Meta: o corpo é o payload da Cloud API, no formato dela. Antes de escrever o seu receptor, confirme com a Zera qual é o apontamento em vigor no seu número.

Erros comuns

Estes são códigos da Meta, e aparecem tanto na conexão do seu número quanto nas suas próprias chamadas. A decisão sai sempre do código, nunca da frase da mensagem: a própria Meta recomenda não usar o texto como lógica, porque ela reescreve o texto sem avisar.

Código	O que fazer
133016	O registro do número estourou o orçamento e ele fica trancado por 72 horas. Não insista: cada tentativa a mais empurra o prazo. Espere e leia o tempo em error_data.details.
133008 e 133009	Espera com prazo. O tempo vem escrito em error_data.details, na própria resposta. Leia de lá. A Meta não publica um número fixo para esses dois, e um valor chutado ou trava o seu número por tempo demais ou queima tentativa do orçamento.
133005	O número já tinha verificação em duas etapas, e o PIN é seu. A saída é desligar a verificação no WhatsApp Manager e conectar de novo. A Zera não consegue destravar isso do lado dela.
190	O token não é mais válido. Pegue a credencial de novo no painel, e reconecte o número se a tela pedir.
200	Falta permissão para o que foi pedido. Confira se o token é o do número certo.
368	Conta restrita por violação de política. Insistir não destrava, e ainda gera chamada numa conta já marcada. O caminho é resolver a restrição com a Meta.
100	Parâmetro inválido. Nas leituras costuma ser um campo pedido em fields que não existe naquela versão da Graph, e nesse caso você perde a lista inteira por causa de um campo opcional. Nas chamadas de autorização costuma ser parâmetro a mais.
4	Teto do aplicativo inteiro, não do seu número. Insistir não resolve. Se aparecer, todos os clientes daquele aplicativo pararam junto.
1 e 2	Indisponibilidade temporária da Meta. Tentar de novo mais tarde é a resposta certa.
17, 341, 80007, 80008, 131000, 133004 e 133015	A Zera trata como retentáveis: tentar de novo daqui a pouco tem chance de dar certo.
3, 10, 131031, 133006 e 133010	A Zera trata como definitivos: insistir não destrava e ainda gasta chamada.

As duas últimas linhas estão classificadas pelo que o código da Zera faz com elas. O significado exato de cada uma é da Meta e está na referência de códigos de erro dela. Repetir aqui o texto dela de memória seria inventar.
Chamada que morre no meio, ou 5xx sem corpo, não é recusa da Meta: é a Meta não tendo respondido. São coisas diferentes, e a segunda pede nova tentativa.
Código desconhecido é tratado como definitivo, de propósito. Insistir num erro que ninguém entende, num endpoint que cria conta de verdade, é como se descobre um limite depois de ter queimado ele.

Os limites que valem

O código do Embedded Signup vale 30 segundos

Ele é de uso único e a troca acontece dentro da própria requisição do navegador, e não numa fila. Enfileirar significaria acordar com ele já queimado.

Registro do número: 10 chamadas por 72 horas

É o teto da Meta, por número. A décima primeira tranca o número por três dias. A Zera para em 6 de propósito, para sobrar folga para um registro manual sem encostar no limite dela.

Coexistência: 20 mensagens por segundo

É fixo, e vem da própria tabela da Meta sobre a integração de usuários do aplicativo Business.

Alta capacidade não se compra, se solicita

A liberação de vazão maior é da Meta, número a número, com critérios dela. A Zera monta o pedido e acompanha. Se a Meta não aprovar, você não paga nada a mais.

O token não expira por tempo, por padrão

O campo expira_em nulo quer dizer que a Meta não devolveu prazo. Tratar ausência de prazo como vencimento tiraria a credencial de quem está com ela funcionando.

O que ainda não está documentado

Esta lista existe para você não perder tempo procurando o que não há. Cada item diz o motivo, porque ausência sem motivo parece esquecimento.

O formato do evento que chega no seu webhook: Pelo motivo da seção do webhook: o apontamento é passo humano hoje, e não existe implementação nossa para conferir contra. Confirme com a Zera antes de escrever o receptor.
Ambiente de teste: Não existe sandbox da Zera. Você testa no seu próprio número conectado, contra a Cloud API da Meta. Se um dia existir, entra aqui.
Biblioteca ou SDK da Zera: Não existe, e não vai existir. O que vale é a Cloud API da Meta, com os payloads dela. É por isso que o seu código continua funcionando se um dia você trocar de fornecedor.
Um endpoint da Zera para você chamar: Não existe, e isso não é falta: é o desenho. A sua mensagem vai do seu servidor para graph.facebook.com. A Zera conecta o número e mantém ele conectado.

A conexão é nossa. A API é da Meta, e continua sendo sua.

R$ 147 por número, por mês. Sem fidelidade, sem intermediário na sua mensagem.

Ver os planos da API

Ficou faltando alguma coisa nesta página? Fale com a Zera