Skip to main content
A API de WhatsApp envia mensagens por modelo pela WhatsApp Cloud API. Cada mensagem pode ter um carimbo de tempo certificado RFC 3161 como prova legal.
Todos os endpoints de WhatsApp usam HTTP Basic Auth — usuário = e-mail da conta, senha = securityToken. Veja Autenticação.

​
Conceitos

  • Remetente (sender) — um número do WhatsApp Business que você conecta (ou um número de sistema fornecido pela Escrybe). Gerenciado em Remetentes.
  • Modelo (template) — uma estrutura de mensagem pré-aprovada (exige aprovação da Meta). Gerenciado em Modelos.
  • Mensagem — um envio vinculado a um modelo e a um destinatário.

​
Endpoints

Os schemas completos estão na aba Referência da API.

​
Enviando uma mensagem

A resposta retorna um message_id, um visual_id público e um status processing até o pagamento ser liquidado e a mensagem entrar na fila.
  • template_variables aceita três formas equivalentes: um objeto com o nome da variável como chave ({"codigo": "A1B2C3"} — os nomes estão em variable_names na resposta de templates/get), um objeto com a posição a partir de 1 ({"1": "A1B2C3"}, a numeração {{1}} da Meta) ou uma lista na ordem do modelo (["A1B2C3"]). Toda variável precisa de um valor não vazio — o WhatsApp recusa parâmetros vazios, então a API rejeita o pedido com 400 antes de cobrar, nomeando a variável que faltou.
  • O telefone do destinatário é verificado no WhatsApp — números que não estão no WhatsApp são rejeitados com 400.
  • Se o cabeçalho do modelo usa imagem ou documento, um entre media_url, media_file ou media_base64 é obrigatório.
  • Se uma mensagem parar com status 2 (créditos insuficientes), adicione créditos pelo painel — as mensagens na fila são reprocessadas automaticamente assim que o saldo cobre o envio.

​
Carimbos de tempo certificados

Cada mensagem pode produzir arquivos de atestação para as fases accepted, sent, delivered e read. Baixe todos em um ZIP:

​
Respostas do destinatário

Tudo que o destinatário manda de volta para o número que entregou a sua mensagem é registrado pela plataforma. A resposta é atribuída ao seu pedido só quando não há dúvida de qual pedido ela responde: Se mais de uma conta mandou mensagem para o mesmo número nesse período, a resposta fica guardada na plataforma mas nunca é atribuída a um pedido — não aparece no seu, e nunca no de outra pessoa. Respostas vinculadas voltam em GET /whatsapp/v1/get como replies[] (texto, tipo, nome do anexo, marca forwarded, hash de identidade do aparelho, carimbo certificado) e disparam o webhook tracking.updated com event_detail_type: "reply" — veja Webhooks. O dono da conta do pedido também recebe um e-mail quando as notificações de rastreamento estão ativas no painel. O relatório pericial lista cada resposta vinculada, o carimbo RFC 3161 dela e se a mensagem foi encaminhada ou veio de um aparelho diferente da resposta anterior. Aviso automático. Quem responde recebe uma mensagem automática por número de telefone (no máximo a cada 30 dias) dizendo que o número é um serviço automático de envio e que deve usar os dados de contato informados na notificação recebida. Ela sai só dos números da plataforma, nunca de um sender seu. auto_reply_sent_at, auto_reply_delivered_at e auto_reply_read_at na mensagem dizem se o aviso saiu e se foi lido.
A API oficial do WhatsApp não expõe foto de perfil de quem responde. O que identifica a pessoa é o número, o nome de perfil que o WhatsApp informa e, quando a verificação de identidade está ligada no número que recebeu, o hash da chave de identidade do aparelho dela.

​
Modelos

Modelos precisam ser aprovados pela Meta antes do uso. Crie um e consulte o status até ficar approved:
O nome final do modelo é normalizado e recebe o prefixo do seu id de usuário (ex.: user42_order_confirmation) — o campo name da resposta é o que você usa ao enviar; seu texto original fica em display_name. Um rodapé de identificação do remetente é adicionado automaticamente ao corpo, e modelos com cabeçalho de imagem/documento enviados sem mídia usam um arquivo de exemplo padrão da Escrybe para aprovação da Meta.