Resposta curta: são três etapas, e nenhuma delas passa por aprovação da Meta. Você conecta o número em coexistência, escolhendo a opção de conectar um app do WhatsApp Business e escaneando um QR code, o que dá acesso à API "sem precisar passar por aprovações da Meta, sem ter que criar aplicativo da Meta e sem ter que se tornar um Tech Provider". Depois cadastra a URL do webhook e marca dois eventos, messages e smb_message_echoes. Por último, envia com um POST em https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages. A regra que decide se a mensagem chega: mensagem livre só vai para quem falou com você nas últimas 24 horas. E o detalhe que engana: fora da janela, a requisição volta com um ID igual ao envio que deu certo, e a falha só aparece depois, no webhook de status.
Principais pontos
- Coexistência. O número continua funcionando no aplicativo do celular e passa a funcionar na API, no mesmo número, com o mesmo histórico.
- O portfólio empresarial é obrigatório, verificado não é. "Não precisa ser verificado, se for verificado é melhor, mas apenas criar o portfólio já é suficiente."
- A escolha de compartilhar histórico é de uma vez só, feita no celular durante a conexão. Marcou errado? "É só fazer o processo novamente."
- Dois eventos, duas origens.
messagestraz o que o cliente manda e os status do que você envia.smb_message_echoestraz o que o atendente manda pelo celular. - Resposta com ID não é entrega. Israel Henrique, CTO da Datafy: "independente se a mensagem enviou ou não enviou ou se deu erro, ele vai retornar esse ID."
Antes de começar
| O que você precisa | Por quê |
|---|---|
| Um portfólio empresarial no Facebook | É onde o número fica cadastrado. Não precisa ser verificado |
| O celular em mãos | É nele que chega a mensagem do Facebook e é com ele que você escaneia o QR code |
Uma URL pública que receba POST |
O webhook: um nó do n8n ou o seu próprio servidor |
| Um número que já falou com você | Para o primeiro envio ser mensagem de serviço, sem template |
Passo 1: conectar o número em coexistência
No painel, clique em conectar número, dê um nome para a conexão (é um apelido interno, para identificar o número depois), preencha a descrição se quiser e clique em criar número. O teste é gratuito por 7 dias.
Na página do número, clique em conectar ao WhatsApp. Abre o Embedded Signup do Facebook, que é a conexão oficial. A partir daí:
- Continuar, e selecione o portfólio empresarial. Se você já tem um, ele costuma vir selecionado.
- Escolha conectar um app do WhatsApp Business. Essa é a opção da coexistência, para quem quer "utilizar o WhatsApp Business em conjunto com o teu celular". Avance.
- Informe o número com código do país e DDD, e avance duas vezes. Aparece o QR code na tela do computador.
- Olhe o seu WhatsApp. Chega uma mensagem do Facebook com um botão de conectar. Toque nele.
- No celular abre conectar-se à plataforma do WhatsApp Business. Toque em conectar.
- O celular pergunta se você quer compartilhar o histórico de conversas. Marcando a opção de compartilhar todas as conversas, depois dá para trazer seis meses de histórico e os contatos salvos na agenda.
- Confirmar. A câmera abre. Aponte para o QR code do computador.
- Não feche a janela. Avance e confirme até o fim: "não pode fechar a janela antes, tem que esperar até aparecer o botão de concluir."
- Concluir. A tela mostra o número conectado com sucesso.
O caso de chip novo e o cadastro da forma de pagamento estão em como conectar um número na API oficial.
Duas coisas que a documentação acrescenta aqui
A sincronização tem prazo e é de uma vez só. Marcar a opção no celular habilita o pedido, mas não sincroniza nada sozinho. É preciso chamar POST /v1/{phone_number_id}/smb_app_data com sync_type igual a history ou smb_app_state_sync, dentro de 24 horas contadas do Embedded Signup, e uma vez por tipo. Passou do prazo, só refazendo o onboarding. O histórico chega em fases, com duplicatas garantidas: deduplique por wamid e ordene por timestamp.
Desconectar não é operação de API. A saída é no aplicativo: configurações, conta, plataforma do WhatsApp Business, desconectar. "Não tem como desconectar via API, somente através do celular." A documentação da Meta diz o mesmo: a API de deregister não serve para esse caso.
Passo 2: cadastrar o webhook e escolher os eventos
No painel do número, abra webhooks e cadastre a URL que vai receber os eventos.
Se a sua URL vem do n8n, monte o gatilho antes: novo workflow, nó de webhook com método POST, e pelo menos um nó depois dele, senão não funciona. Publique e copie a URL de produção. A de teste só recebe com a escuta ligada.
Agora os eventos. Dois importam para começar, e a diferença entre eles é o que mais gera dúvida:
| Evento | O que ele notifica | O que ele não notifica |
|---|---|---|
messages |
Toda mensagem que alguém envia para o seu número, e os status das mensagens que você envia | O que você manda pelo celular |
smb_message_echoes |
Toda mensagem enviada pelo celular do número conectado | Mensagem enviada pela API |
A frase que resolve metade dos problemas em coexistência: "quando você envia mensagens direto pela API, não aparece, ele não notifica. Aliás, chega o status da mensagem." O que sai pela API volta como status, não como eco.
Clique em adicionar webhook. Você pode cadastrar mais de uma URL no mesmo número, cada uma com o seu filtro de eventos. E antes de existir tráfego real, use o testador: escolha o evento, clique em enviar, e um evento falso chega na sua URL.
A documentação acrescenta três coisas sobre a entrega que o painel não mostra. Toda entrega leva x-datafy-delivery-id, um UUID que serve como chave de idempotência. Com a assinatura ativada no número, vêm também x-datafy-timestamp e x-datafy-signature-256, um HMAC-SHA256 de {timestamp}.{corpo} que precisa ser conferido com o corpo cru. E a sua URL deve responder 200 em até 20 segundos: responda na hora e processe de forma assíncrona.
Passo 3: o que chega no payload
Mande um "olá" do seu celular para o número conectado e abra o payload. Ele tem três blocos:
O número conectado. display_phone_number e phone_number_id. São do seu número, não de quem mandou. Confundir os dois é erro clássico de primeira integração.
Quem mandou. Nome, telefone e o user_id, um código de identificação única já disponível na API oficial.
A mensagem. Quem enviou, o identificador da mensagem, o horário e o texto.
O payload que a Datafy entrega é idêntico ao da Meta. Sobre o user_id: ele é a relação entre aquela pessoa e aquela conta empresarial, não uma identidade global. O que muda quando o telefone para de vir no webhook tem página própria.
Passo 4: o primeiro envio
Se você ainda não sabe o identificador do número, pegue com o token:
GET https://cloud.datafyapi.com.br/me
Authorization: Bearer sk_live_xxx
{
"cliente_id": "uuid-do-cliente",
"phone_number_id": "106540352242922",
"waba_id": "366634483210360",
"business_id": "123456789"
}
E envie. Pela documentação, isso é escolher o tipo de mensagem, clicar em testar, colar o token, colar o phone_number_id no path e preencher o destinatário. O que acontece por baixo é isto:
POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "5511999999999",
"type": "text",
"text": { "preview_url": false, "body": "Olá! Tudo bem?" }
}
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
"messages": [{ "id": "wamid.HBgLMTY0Nj..." }]
}
Essa resposta "sempre vai ser essa resposta", e é exatamente por isso que ela engana. Guarde o id: é ele que aparece em todos os eventos de status daquela mensagem.
A regra que decide tudo: a janela de 24 horas
A mensagem que você acabou de enviar é uma mensagem de serviço. Ela só pode ir "para usuários que já enviaram mensagem para você nas últimas 24 horas".
O prazo conta do horário da última mensagem daquela pessoa, e só ela renova. Resposta da empresa, de atendente, de bot ou de automação, não aumenta o prazo. Cada cliente tem a própria janela.
| Quando | O que acontece | Até quando você responde sem template |
|---|---|---|
| Segunda, 9h | O cliente pergunta sobre a entrega | Terça, 9h |
| Segunda, 9h15 | A empresa informa o prazo | Continua até terça, 9h |
| Segunda, 16h | O cliente pede para confirmar o endereço | Muda para terça, 16h |
| Terça, 11h | A empresa confirma o endereço | Continua até terça, 16h |
| Terça, depois das 16h | Nenhuma mensagem nova do cliente | Janela fechada: só template |
Sobre a palavra "gratuita"
No primeiro envio é natural ouvir que mensagem de serviço é gratuita, e hoje isso é verdade. A documentação de custos é mais precisa, e a diferença importa para quem está dimensionando um SaaS:
| Período | Mensagem de serviço dentro da janela | Template de utilidade dentro da janela |
|---|---|---|
| Até 30 de setembro de 2026 | Sem cobrança da Meta | Sem cobrança da Meta |
| A partir de 1º de outubro de 2026 | 1.000 grátis por mês por número, e da 1.001ª entregue em diante a referência no Brasil é R$ 0,035 | Passa a ser cobrado, referência de R$ 0,035 |
A franquia é por número de telefone, não por cliente nem por conversa, renova todo dia 1º e não acumula. Marketing e autenticação não entram nela: são cobrados por mensagem entregue mesmo com a janela aberta, com referências de R$ 0,32 e R$ 0,035 no Brasil. E sempre: a Meta cobra a mensagem entregue, não a requisição aceita. Essa franquia foi comunicada pela Meta a parceiros e ainda não aparece na página de preços em português, então confira a tabela vigente.
O teste que ensina mais: enviar fora da janela
Agora escolha um número que não falou com você nas últimas 24 horas e mande a mesma mensagem de serviço. A requisição volta normal, com ID, e nada na resposta indica problema.
A falha chega depois, no webhook de status, com o mesmo ID, dizendo que o envio falhou porque já se passaram mais de 24 horas desde a última vez que aquele usuário entrou em contato. Enquanto isso, a mensagem anterior, a que estava dentro da janela, chega como delivered.
| Envio | Resposta da requisição | O que chega no webhook |
|---|---|---|
| Para quem escreveu nas últimas 24 horas | ID da mensagem | sent, depois delivered, e read quando disponível |
| Para quem não escreveu nas últimas 24 horas | ID da mensagem, idêntico | failed, com o motivo |
Os status possíveis são quatro: sent (enviada, ainda não é entrega), delivered (chegou ao destinatário), read (lida, quando a confirmação está disponível) e failed (falha, com o erro). O failed também aparece por outros motivos, e falha no pagamento é um deles.
A consequência para o seu código é uma só: não trate a resposta do POST como confirmação. Grave o id com o estado "aceita" e deixe o webhook mudar esse estado. Guardar o horário da última mensagem recebida de cada cliente resolve o problema na origem, inclusive quando um envio ficou esperando numa fila.
Fora da janela, o caminho é template
Para falar com quem não escreveu, é template aprovado, com a categoria definida pela finalidade. E o detalhe que muita gente descobre tarde: enviar template não abre a janela. Ela abre quando o cliente responde. Como enviar template pela API.
Marcar a mensagem recebida como lida
Para mostrar os dois tiques azuis a quem escreveu, existe uma rota simplificada que dispensa o identificador do número:
POST https://cloud.datafyapi.com.br/messages/read
Authorization: Bearer sk_live_xxx
Content-Type: application/json
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "wamid.HBgLMTY0Nj..."
}
Só funciona para mensagem recebida, e o recomendado é fazer isso em até 30 dias do recebimento.
Perguntas frequentes
Preciso de um portfólio empresarial verificado?
Não para começar. Basta ter um portfólio empresarial. Verificado é melhor, porque dá limites diários maiores para template, mas apenas criar já é suficiente para conectar.
Se eu recusar o compartilhamento de histórico, perco a chance?
Naquele onboarding, sim. A saída é refazer o processo: desconectar pelo celular e conectar de novo, marcando a opção. E a sincronização ainda precisa ser pedida por chamada, dentro de 24 horas.
Onde encontro o phone_number_id?
Na tela do número, com botão de copiar, ou com GET https://cloud.datafyapi.com.br/me. Ele também vem em todo payload de webhook, e não é o número de quem escreveu.
A resposta do envio garante que a mensagem chegou?
Não. O ID confirma que a requisição foi aceita. A entrega ou a falha chega depois, pelo webhook de status, com o mesmo ID.
Por que a mensagem que eu envio pela API não aparece em smb_message_echoes?
Porque esse evento é só para mensagem enviada pelo celular. O que sai pela API volta como status pelo evento messages.
Responder dentro de 24 horas custa quanto?
Até 30 de setembro de 2026, a Meta não cobra mensagem de serviço dentro da janela. A partir de 1º de outubro de 2026, cada número tem 1.000 grátis por mês e a referência no Brasil da 1.001ª em diante é R$ 0,035 por mensagem entregue.
Dá para testar o webhook antes de ter mensagem real?
Dá. O painel tem um testador: você escolhe o evento e clica em enviar, e um evento daquele tipo chega na sua URL.
Resumo para a sua integração
Faça na ordem: conecte o número, cadastre o webhook com os dois eventos, mande uma mensagem do seu celular para o número e leia o payload. Só depois envie pela API, primeiro para quem falou com você e em seguida para quem não falou. São dois envios que ensinam as duas regras que mais quebram integração: a janela de 24 horas e a diferença entre requisição aceita e mensagem entregue.
No código, três coisas resolvem a maior parte dos problemas futuros: guardar o horário da última mensagem recebida de cada cliente, guardar o wamid de cada envio, e usar o x-datafy-delivery-id como chave de idempotência.
Faça os dois envios de teste e compare os status
Responda pela API a uma mensagem que você mandou do celular, depois envie para um número que não falou com você nas últimas 24 horas. As duas requisições devolvem ID; só o webhook mostra que a segunda falhou.
Sem taxa de setup · Cancele quando quiser · Suporte por WhatsAppLeia também
- Como conectar um número na API oficial do WhatsApp
- A Datafy API é um espelho da Cloud API
- Como ver o payload das mensagens em tempo real
- Como enviar template pela API
Continue por aqui
- ImplementaçãoComo conectar um número na API oficial do WhatsApp em 5 minutos, sem burocracia
O passo a passo completo da conexão: criar o número no painel, escolher o portfólio empresarial, chip novo ou aplicativo existente, escanear o QR code e cadastrar a forma de pagamento na BM.
Ler mais - ImplementaçãoComo criar um template de WhatsApp passo a passo, no painel da Meta
Gerenciar modelos, categoria, cabeçalho com imagem, corpo com variáveis e exemplo obrigatório, botões e envio para análise. E o que a categoria faz no seu custo.
Ler mais - ImplementaçãoComo enviar imagem, documento e áudio pela API oficial do WhatsApp
Por link ou por identificador, no mesmo endpoint de mensagens. Legenda na imagem, nome no documento, e o que faz o áudio virar bolha de voz em vez de anexo.
Ler mais