API oficial do WhatsApp passo a passo: do zero à primeira mensagem

O que você precisa antes de começar?

Três coisas, as mesmas que o painel lista em "Antes de conectar": login do Facebook e um portfólio empresarial, que dá para criar na hora; um número que receba SMS ou ligação, fora do WhatsApp comum e de outra API; e, para manter o número no celular, o app WhatsApp Business 2.24.17 ou mais novo.

Além disso, tenha à mão:

• Uma URL HTTPS que aceite POST: um nó Webhook no n8n, um endpoint do seu sistema ou de um CRM. É para onde cada mensagem vai.
• Um segundo celular com WhatsApp, para mandar a mensagem de teste para o número conectado.
• O número livre: se ele está no WhatsApp comum, a Meta exige apagar a conta antes; se está numa API não oficial, desconecte de lá.

Se ainda tem dúvida sobre o que a Meta exige do número e da empresa, veja como conseguir a API oficial do WhatsApp.

Passo 1: como criar a conta no Omnique?

Abra a página de cadastro e preencha nome, e-mail, país e uma senha de pelo menos 8 caracteres, ou use o botão "Criar conta com Google". No cadastro por e-mail chega um link de confirmação que abre o painel. O teste grátis libera uma instância por 3 dias, sem pedir cartão.

Ao entrar, o painel mostra o bloco "Primeiros passos" com três itens: "Conectar seu número", "Apontar o webhook" e "Receber o primeiro evento". Eles se marcam sozinhos conforme você avança, e são exatamente os próximos passos deste guia. Criar a conta agora.

Passo 2: como conectar o número pelo Cadastro Incorporado?

Em Conexões, clique em "Conectar nova instância", escolha WhatsApp e preencha o "Nome da conexão", por exemplo "Atendimento Principal". Depois escolha entre "Já uso no app WhatsApp Business", para manter o número no celular, e "Conectar número novo", para um número só da API. A janela oficial da Meta abre em seguida.

A janela é da Meta, não do Omnique: é o Cadastro Incorporado, o fluxo que a Meta oferece para provedores conectarem o número de uma empresa. Dentro dela, você:

1. Entra com o login do Facebook.
2. Aceita os termos da Cloud API e do WhatsApp Business.
3. Escolhe um portfólio empresarial existente ou cria um novo.
4. Escolhe ou cria a conta do WhatsApp Business.
5. Informa o número e confirma com o código que chega por SMS ou ligação.
6. Define o nome de exibição, que aparece no perfil do WhatsApp.
7. Autoriza o acesso aos ativos do WhatsApp.

Na coexistência o caminho muda num ponto: depois de informar o número do app, a janela mostra um código, e no app WhatsApp Business do celular chega uma mensagem da conta oficial do Facebook Business. Você toca para conectar à plataforma, confirma se quer compartilhar o histórico de conversas e cola o código. O resto do fluxo é igual.

Ao fechar a janela, o painel avisa "Instância conectada". Se a Meta ainda estiver analisando a conta, o aviso é "Conexão em análise pela Meta", e o repasse começa quando ela aprovar. Na coexistência, o painel lembra que contatos e histórico do app só podem ser pedidos à Meta nas 24 horas seguintes. Mais sobre esse modo em coexistência: app e API no mesmo número.

Passo 3: onde cadastrar o webhook de destino?

Abra a instância em Conexões: ela abre na aba "Webhook de destino". Clique em "Adicionar webhook", dê um nome, cole a URL de destino, que precisa começar com https://, e mantenha marcados os eventos que quer receber. Ao salvar, o painel mostra o secret do webhook uma única vez. Copie e guarde.

Mensagens recebidas e mudanças de status do que você envia já vêm marcadas. Os outros eventos são opcionais e cada um tem a explicação ao lado:

• Receber mensagens enviadas pelo celular: o eco do que você responde pelo app. Vem ligado e só chega em número de coexistência.
• Receber avisos da Meta sobre a conta: limite de envio, vazão, restrição ou violação de política. Desligado por padrão.
• Receber o histórico de conversas do app e Receber os contatos do app: só para coexistência, desligados por padrão.

Cada instância aceita um webhook de destino. A URL que a Meta chama e o token de verificação dela são configurados pelo Omnique na conexão, então o seu lado não precisa tratar o hub.challenge. No n8n, use a URL de produção do nó Webhook com o método POST; o roteiro completo está em API oficial do WhatsApp no n8n.

Passo 4: como testar se o webhook está recebendo?

Na linha do webhook, clique em "Testar". O Omnique manda um POST assinado, com o evento "test", para a sua URL e mostra o código HTTP que voltou, como "Teste enviado. HTTP 200". Depois mande uma mensagem de outro celular para o número conectado: ela chega no seu sistema e aparece na aba "Logs".

O teste conta como sucesso quando a sua URL responde com um código da faixa 200. Se voltar outro código, o problema está no destino: a URL não aceita POST, exige autenticação ou o fluxo está desligado.

A mensagem real chega com este formato no primeiro nível:

• event: message, status, template, echo ou account.
• origin: quem originou, como inbound para o cliente final.
• delivery_id: o identificador estável da entrega.
• data.message com o objeto da Meta e data.channel com o Phone Number ID e o nome da instância.

Quando a mensagem aparece no seu sistema, o item "Receber o primeiro evento" fica marcado no painel. Se ela não aparecer, a aba "Logs" mostra se houve tentativa e qual código o seu servidor devolveu.

Passo 5: como validar a assinatura e evitar duplicidade?

Toda entrega vem com o header X-Omnique-Signature-256 no formato sha256= seguido do HMAC-SHA256 do corpo cru, calculado com o secret do webhook. Confira antes de processar. Para não tratar a mesma mensagem duas vezes, guarde o delivery_id, que também vem no header X-Omnique-Delivery, e ignore o que já viu.

Em Node.js, o cálculo é uma linha:

crypto.createHmac("sha256", SECRET).update(corpoCru).digest("hex")

Compare o resultado com o que vem depois de sha256= no header, em tempo constante. Três detalhes evitam dor de cabeça:

• Calcule sobre o corpo cru, antes de qualquer parse de JSON.
• A ordem de chegada não é garantida: um status read pode chegar antes do delivered. Para ordenar, use o timestamp de dentro de data, que é o horário da Meta.
• Trocar o secret vale na hora, sem janela de graça. Atualize o seu lado antes de rotacionar.

Passo 6: como responder pela API?

Gere a chave da instância no bloco "Identidade da instância", em "Gerar chave", ou crie chaves com escopo em "Chaves de API". A chave começa com zpk_ e aparece uma vez só. Para responder, faça um POST no endpoint chat-send com o header Authorization: Bearer e um corpo com to, type e text.

O corpo mínimo de uma resposta de texto:

{"to": "5511999999999", "type": "text", "text": "Olá! Recebemos sua mensagem."}

O endereço completo do endpoint e os outros tipos (template, mídia, botões, listas) estão na documentação da API. Duas regras da Meta valem aqui:

• Texto livre só dentro da janela de 24 horas, que abre e se renova a cada mensagem do cliente. Fora dela, só template aprovado; o Omnique cria e acompanha os templates na aba "Templates" da instância.
• Desde 1º de outubro de 2026, as primeiras 1.000 respostas do mês dentro da janela são grátis em cada número, e da 1.001ª em diante cada uma custa R$ 0,035 na Meta; template de marketing custa R$ 0,3217. A cobrança sai no cartão da sua conta do WhatsApp Business, não no Omnique.

Para não mandar a mesma mensagem duas vezes quando o seu fluxo repete uma chamada, envie uma idempotency_key; um bom valor é o próprio delivery_id da mensagem que você está respondendo.

O que fazer se algo não funcionar?

Os tropeços mais comuns têm causa conhecida. Janela da Meta aberta por muito tempo ou fechada no meio expira o código e pede conectar de novo. Número ainda no WhatsApp comum ou em outra API não registra. URL sem https é recusada. E envio fora da janela de 24 horas sem template volta erro da Meta.

O webhook também se desliga sozinho depois de uma sequência de falhas, e o painel avisa. Para os casos em que a mensagem não chega e você não sabe por quê, veja webhook do WhatsApp Cloud API. Para entender o contexto antes de conectar, comece pelo guia da API oficial do WhatsApp, e para o custo total por número, veja preços.