Começo rápido

O primeiro dia

O caminho inteiro numa página só: o que você compra, as quatro telas da ativação, a credencial, a primeira mensagem enviada, a primeira mensagem recebida, e o que fazer quando cada coisa dá errado. Você precisa de um terminal e de um celular com WhatsApp por perto.

O que você compra, e o que recebe

Você compra um número de WhatsApp conectado à Cloud API da Meta, no nome da sua própria empresa, mais o painel que cuida dele. A Zera é provedora de tecnologia da Meta, e não intermediária: a credencial é gerada pela própria Meta dentro da sua conta de negócio, e as suas chamadas vão direto para graph.facebook.com. Nenhuma requisição sua passa por um servidor nosso.

O que chega na sua mão, ao fim da ativação, são seis valores. Três deles você usa todo dia:

O que não vem junto, e é bom saber antes: o custo das mensagens é da Meta e é cobrado direto de você, no preço da tabela pública dela, pelo meio de pagamento que está na sua conta de negócio. Esse valor não passa pela Zera. Não existe ambiente de teste. E o cabeçalho X-Hub-Signature-256 dos eventos recebidos você não consegue validar, pelo motivo explicado em Receber mensagens.

Os quatro passos da ativação

Se você já tem o número no painel, pule para Pegue a credencial. Se ainda não, este é o caminho, com o nome que cada tela usa e o endereço dela. A própria tela mostra em qual dos quatro você está.

Depois disso, o painel. Entrar é em hub.zeracompany.com/auth/login, com o e-mail do cadastro. A lista dos seus números fica em app.zeracompany.com/painel/canais, e é para lá que o login leva. Os dois endereços conversam: digitar um caminho do painel no hub. redireciona para o app., e digitar app.zeracompany.com sozinho cai direto em Canais. Esta documentação mora em docs.zeracompany.com/docs.

Antes de começar

• O número já precisa estar conectado. Se ele ainda não passou pela conexão com a Meta, a credencial nem existe: ela é criada pela Meta no momento em que você conecta. Se ele ainda estiver em Rascunho ou em Pronto para conectar, o caminho é abrir o número no painel, aba Começar, botão Ir para a ativação, e o passo a passo está em O painel.
• Na hora de conectar, autorize tudo que a Meta pedir. Nada do lado da Zera confere se o seu token carrega o escopo de envio, então um token sem ele conecta verde e só falha no passo 4. O detalhe está no passo 5.
• Você precisa de acesso ao painel com o e-mail do cadastro. A credencial não é entregue por outro caminho, e nunca por telefone nem por mensagem.
• Tenha um celular com WhatsApp à mão, que não seja o número da API. É dele que sai a mensagem que abre a conversa.

1. Pegue a credencial no painel

   Entre em hub.zeracompany.com com o e-mail do cadastro. No painel, abra Canais, clique no seu número e fique na aba Detalhes.

   No cartão Ajustes de API já estão, na tela, o Identificador do número, que é o phone_number_id das chamadas, e a Conta WABA, que é o waba_id. A tela usa o nome em português e o comando usa o nome da API: são os mesmos dois valores. Eles não são segredo e não exigem clique nenhum.

   Logo abaixo aparece o cartão Credencial da Cloud API, e nele o botão Mostrar a credencial revela o token.

   Esse cartão existe em todo plano, desde 06 de setembro de 2026, inclusive no que inclui a caixa de entrada da Zera. A mesma credencial serve para as duas coisas de propósito: o seu sistema envia por ela, e a caixa de entrada recebe por ela. O que muda no plano com caixa é o recebimento: os eventos daquele número continuam indo para a plataforma da Zera, e o bloco de endereço de webhook não aparece.

   Só o dono da conta exibe a credencial.

   É a trava que mais pega desenvolvedor, porque o normal é o cliente convidar quem vai integrar. Quem entrou por convite recebe so_o_dono, HTTP 403, mesmo com acesso ao painel e mesmo com uma sessão recém-feita. Se você é o desenvolvedor, peça os valores ao dono da conta, ou combine de estar junto na hora. O painel já trata o convidado assim em outros lugares: ele também não troca de plano, não convida ninguém e não vê o telefone completo.

   Com o cartão na tela, seis coisas acontecem quando você clica no botão, e todas são de propósito:

   • Só o dono da conta. Quem entrou por convite recebe so_o_dono, 403.
   • O painel exige um acesso recente: uma sessão com menos de dez minutos de vida, seja pelo link que chega no e-mail, seja entrando com a senha. Sessão aberta há dias não serve, recebe sessao_velha, 403, e a tela oferece o link novo.
   • O dono da conta recebe um e-mail no mesmo minuto, toda vez. Esse aviso não pode ser desligado, e se o e-mail não sair a credencial não sai junto.
   • São três exibições a cada 24 horas, por conta e não por número, e conta a tentativa; a que falha por problema nosso é devolvida. A janela corre a partir de cada exibição, e não vira à meia-noite. A quarta recebe teto_do_dia, 429.
   • A credencial some da tela assim que você troca de aba ou recarrega a página. Ela não fica guardada no navegador.
   • Não existe botão de gerar outra, nem de revogar. Quem revoga é a Meta, no Gerenciador de Negócios da sua empresa, e a Zera não consegue fazer isso por você.

   Três exibições a cada 24 horas corridas, com sessão de dez minutos e só para o dono, é pouco de propósito. Copie os seis valores de uma vez e guarde onde o seu time guarda segredo. O detalhe de cada trava, e o que fazer quando o botão recusa, está em A sua credencial.

2. Separe os dois valores que o comando usa

   Dos seis valores descritos lá em cima, e um a um em Referência, o envio usa dois: o token, que vai no cabeçalho Authorization: Bearer, e o phone_number_id, que vai no caminho da chamada.

   Os outros quatro não entram neste comando. O waba_id serve para modelos e saúde do número; webhook e webhook_verify_token são do recebimento, que é o passo 6; e expira_em é informação.

3. Abra a janela de 24 horas

   Pegue o seu celular e mande qualquer mensagem, um oi serve, do seu WhatsApp pessoal para o número da API.

   Isso não é formalidade. A Meta só deixa você escrever texto livre para alguém que falou com você nas últimas 24 horas. Quem abre essa janela é a pessoa, nunca a empresa. Enquanto ela está aberta, você responde o que quiser; depois que ela fecha, só passa um modelo aprovado antes.

   É a causa número um de mandei e não chegou. O detalhe do que reabre a janela e do que conta como resposta está em A janela de 24 horas.

4. Mande a mensagem

   Troque os três valores destacados: SEU_PHONE_NUMBER_ID, SEU_TOKEN e o número de destino, que é o celular de onde você acabou de mandar o oi.

   Enviar uma mensagem de texto Copiar

   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",
       "recipient_type": "individual",
       "to": "5511987654321",
       "type": "text",
       "text": {
         "preview_url": false,
         "body": "Primeira mensagem pela API."
       }
     }'

   O número de destino vai no formato internacional, sem o sinal de mais e sem pontuação: um celular de São Paulo fica 5511987654321. Nada de espaço, parêntese ou traço.

   As barras invertidas no fim das linhas são a continuação de linha do terminal do Linux e do macOS. No Windows, o comando acima roda igual dentro do Git Bash ou do WSL.

   No PowerShell do Windows, use este

   O comando acima não roda no Windows PowerShell 5.1, que é a versão que vem instalada no Windows. Se você digitar $PSVersionTable.PSVersion e o número começar com 5, é o seu caso. No PowerShell 7, que é instalado à parte, o comando acima roda.

   São duas coisas no 5.1, e nenhuma delas se resolve escrevendo tudo em uma linha só:

   • curl, ali, é apelido de Invoke-WebRequest, que é outro comando com outros parâmetros. A resposta é uma reclamação sobre o parâmetro Headers, que manda você olhar para o lugar errado. No PowerShell 7 esse apelido não existe mais, e curl chama o programa de verdade.
   • Mesmo chamando curl.exe pelo nome inteiro, o 5.1 tira as aspas de dentro do corpo antes de entregar o texto ao programa: o JSON chega como { messaging_product: whatsapp } e a Meta recusa um corpo que na sua tela está correto. O 7 entrega as aspas intactas.

   Este bloco desvia dos dois e roda igual nas duas versões, então serve sem você precisar descobrir qual tem. Ele grava o corpo num arquivo, que é o caminho por onde o texto passa inteiro, e imprime a resposta da Meta como ela vem, no sucesso e no erro.

   O mesmo envio, no PowerShell do Windows Copiar

   $corpo = '{"messaging_product":"whatsapp","recipient_type":"individual","to":"5511987654321","type":"text","text":{"preview_url":false,"body":"Primeira mensagem pela API."}}'
   [System.IO.File]::WriteAllText("$PWD\corpo.json", $corpo, (New-Object System.Text.UTF8Encoding($false)))
   $url = "https://graph.facebook.com/v25.0/SEU_PHONE_NUMBER_ID/messages"
   $aut = "Authorization: Bearer SEU_TOKEN"
   curl.exe -X POST $url -H $aut -H "Content-Type: application/json" -d "@corpo.json"

   Cada linha é uma instrução inteira, de propósito: coladas de uma vez, elas rodam uma a uma, sem deixar o console esperando o resto de um comando. A segunda grava corpo.json na pasta em que você está, sem a marca invisível de início de arquivo que o Set-Content do PowerShell coloca e que a Meta lê como caractere estranho no começo do JSON. As cinco linhas foram exercitadas no Windows PowerShell 5.1 e no PowerShell 7, das duas formas, com resposta de sucesso e com resposta de erro.

5. Confira a resposta

   Deu certo, a Meta responde assim:

   Resposta da Meta Copiar

   {
     "messaging_product": "whatsapp",
     "contacts": [ { "input": "5511987654321", "wa_id": "5511987654321" } ],
     "messages": [ { "id": "wamid.HBgN...", "message_status": "accepted" } ]
   }

   200 quer dizer aceita, não entregue. A Meta recebeu a sua mensagem e devolveu um identificador. Entrega e leitura acontecem depois, e aparecem no webhook.

   Enquanto o seu servidor não estiver recebendo eventos, o wamid desta resposta é o único retorno que você tem. Guarde ele: é por ele que você liga a mensagem enviada ao aviso de entrega, quando o recebimento estiver de pé.

   A mensagem deve aparecer no celular em segundos. Se não aparecer, o próximo lugar é Erros.

   Se voltou erro em vez de accepted, comece pelo escopo, e não pelo token. A conexão do número confere se o seu token carrega whatsapp_business_management, que é o escopo de gerenciar. Ela não confere whatsapp_business_messaging, que é o escopo que faz este envio funcionar, e nada mais do lado da Zera confere depois. Por isso existe o desencontro mais confuso do produto: a conexão termina verde, o painel mostra o número, o estado na Meta lê bem, e o primeiro envio recusa. O caminho é reconectar o número autorizando tudo que a Meta pedir, e o detalhe está em O escopo que ninguém confere.

6. Receba o que o cliente responde

   Você já sabe enviar. Enquanto o seu servidor não estiver recebendo, o wamid da resposta é o único retorno que existe: entrega e leitura só aparecem no webhook. Este passo resolve isso, e o painel faz a parte difícil.

   Antes de tudo, deixe o seu servidor no ar, em https, respondendo a um GET de verificação. Quando o endereço é apontado, a Meta bate nele com três parâmetros de consulta (se no mesmo instante ou depois, a Zera ainda não mediu), e o seu servidor precisa devolver 200 com o valor de hub.challenge no corpo, em texto puro. Sem isso a Meta não fecha a assinatura e nenhum evento chega depois, sem erro em lugar nenhum. O formato exato está em Receber mensagens.

   Na primeira vez, o seu servidor ainda não tem como conferir o código de verificação, porque ele nasce na primeira tentativa de apontar, que normalmente é o salvamento logo abaixo. Então ele responde ao GET sem conferir o hub.verify_token até o código aparecer, e passa a conferir assim que você acrescentar o código à lista de códigos aceitos: todo GET com um valor fora da sua lista de códigos recebe 403. Guarde como lista desde o primeiro número, porque o código é de cada número, e não da conta: a ficha do segundo número já vem com o mesmo endereço, e o apontamento dele gera um código novo. Essa janela é um risco, curto e real: o que ele significa, e o jeito de fazer o primeiro apontamento sem ela, estão em Em ordem, do zero. O que fazer antes de ligar o número seguinte está em Para o número seguinte no mesmo endereço.

   Com o servidor de pé, o caminho é o painel: Canais, o seu número, aba Detalhes, cartão Ajustes de API, bloco O endereço para onde os eventos deste número devem ir. Você informa o endereço e salva. Desde 23 de setembro de 2026 esse salvamento aponta a sobreposição na Meta, no seu número. O código que faz isso existe desde 15 de setembro, e até o dia 22 ficou desligado: nesse intervalo, salvar só guardava. Você não precisa fazer chamada nenhuma.

   Com uma condição: a conexão do número vem primeiro. Enquanto o número não concluiu a conexão com a Meta, salvar o endereço só guarda: nenhum e-mail sai, a Meta não é chamada, e a linha de estado diz Guardado aqui, ainda não apontado na Meta. Mesmo sem a conexão, o salvamento pede a sessão de dez minutos. Conclua a conexão e salve de novo.

   Depois que a conexão fecha, um endereço guardado antes dela, pela ficha do número ou por um salvamento, também pode ser apontado pela rotina de operação da Zera, sem e-mail ao dono e sem mostrar o código na tela. Nesse caso, o código está no campo webhook_verify_token da exibição da credencial, que a tela desenha logo abaixo do token, com botão de copiar próprio. Por isso o servidor de pé vem antes da conexão, e não só antes do salvamento.

   O que acontece por baixo do salvamento, nesta ordem: o endereço é conferido (https, com host, no máximo 200 caracteres), o dono da conta recebe um e-mail avisando da troca antes de a Meta ser tocada, o endereço é gravado, a sobreposição é escrita com POST /{phone_number_id}, e o painel relê na Meta para mostrar o estado verdadeiro. Se o e-mail não for aceito, a Meta não é tocada naquele salvamento, e o endereço gravado pode ser apontado depois pela rotina de operação, sem outro e-mail. Salvar aqui exige a mesma sessão de dez minutos da credencial, porque este salvamento redireciona o recebimento do número.

   O código de verificação aparece uma vez, na resposta do salvamento que o gera.

   Você não inventa mais esse valor: ele é gerado por nós, com 32 bytes aleatórios, e volta num bloco com botão de copiar logo depois de salvar, quando o mesmo salvamento que o gerou fecha o apontamento. Acrescente à lista de códigos do seu servidor naquele momento. Se a Meta recusar a primeira tentativa, ele foi gerado e não aparece; se a primeira tentativa foi da rotina de operação da Zera, ele também não aparece. Nesses casos, e se você perder o valor, ele volta no campo webhook_verify_token da exibição da credencial, com as travas daquela rota, e a tela o mostra logo abaixo do token. Trocar o endereço do mesmo número depois não gera um código novo: o mesmo valor é reusado, justamente para não quebrar o que já está no seu servidor. Um número novo, mesmo no mesmo endereço, ganha o código dele, e o seu servidor precisa aceitar os dois: acrescente o novo à lista, sem tirar o primeiro (veja o número seguinte no mesmo endereço).

   Confira a linha de estado que nasce embaixo do campo. Com a conexão concluída, ela tem de dizer Apontado na Meta, com data e hora, e ela vem da releitura, não da resposta da escrita. Se disser Guardado aqui, ainda não apontado na Meta, A Meta está entregando em outro endereço ou A Meta não confirmou este endereço, o que fazer em cada caso está em Receber mensagens, junto com o caminho manual para destravar.

   Feito isso, mande de novo uma mensagem do seu celular para o número da API e confira que o corpo chegou no seu servidor.

   Duas honestidades sobre este passo.

   Nenhum número passou por ele de ponta a ponta em produção até hoje. A escrita está construída, tem prova em código e está ligada. O que não existe é medição com um número real. Se você for o primeiro, escreva para a Zera ao terminar, dando certo ou dando errado.

   Você não consegue validar a assinatura dos eventos. O cabeçalho X-Hub-Signature-256 é calculado com o segredo do aplicativo, que é da Zera e é o mesmo para todos os clientes. Ele não vai na credencial e não vai passar a ir. As quatro defesas que restam estão em Receber mensagens, e vale ler antes de escrever o servidor.

Por que o exemplo é assim

Seis detalhes deste comando são a diferença entre funcionar e passar a tarde depurando. Eles valem para toda chamada, não só para esta.

• O phone_number_id vai no caminho, nunca no corpo. É a diferença de fundo em relação à documentação de um intermediário: lá a chave identifica o canal e o caminho é só /messages. Aqui a credencial não identifica o número, o caminho identifica.
• O cabeçalho é Authorization: Bearer. Não existe cabeçalho proprietário da Zera, não existe chave em parâmetro de URL, e não existe endereço nosso no meio.
• "messaging_product": "whatsapp" é obrigatório. É o campo mais esquecido por quem chegou copiando exemplo de outro fornecedor. A documentação da Meta registra 400 para a falta dele, e a Zera não mediu esse status: nenhuma rota nossa faz este envio.
• O destino vai em formato internacional, sem o sinal de mais. Número do Brasil leva o 55 na frente.
• Isto só chega dentro da janela de 24 horas. Fora dela, texto livre é recusado, e o caminho é "type": "template" com um modelo que a Meta aprovou antes. Veja Modelos de mensagem.
• 200 é aceita pela Meta, não entregue no celular. A entrega tem outro caminho, e ele passa pelo webhook.

Quando dá errado, com o código ao lado

Duas origens, e são duas listas. O painel da Zera responde com uma chave em português dentro de { "ok": false, "erro": "..." }. A Graph da Meta responde com um error.code numérico. Procurar um na lista do outro é o jeito mais rápido de perder a tarde. A lista completa das duas está em Erros; aqui ficam as que aparecem no primeiro dia.

O painel recusou

A Meta recusou

Não deu erro nenhum, e a mensagem não chegou

• A janela de 24 horas está fechada. É a causa número um. Texto livre só passa para quem falou com você nas últimas 24 horas, e quem abre a janela é a pessoa, nunca a empresa. Fora dela, só modelo aprovado antes. Veja A janela de 24 horas. Esta documentação não publica o código de erro desse caso porque a Zera não o mediu.
• Você leu accepted como entregue. A resposta do envio diz que a Meta aceitou, e nada mais. Entrega e leitura só existem no webhook.
• O webhook foi apontado no nível da conta, e não no do número. Funciona e some na próxima reconexão, porque a Zera reassina o aplicativo sem corpo, e assinar sem corpo apaga a sobreposição da conta. Aponte pelo painel, que escreve no nível do número.
• O seu servidor não respondeu ao GET de verificação. Sem o hub.challenge de volta em 200 e em texto puro, a Meta não fecha a assinatura, e o painel pode dizer Apontado na Meta com o seu servidor ainda mudo.

Funcionou. E agora?

Você sabe enviar e recebe o que chega. Falta uma coisa para um sistema de verdade:

• Falar primeiro com alguém. Fora da janela de 24 horas só passa modelo aprovado, e aprovar leva tempo. Comece por Modelos de mensagem antes de precisar.