Referência · envio

Enviar mensagens

Envie texto livre na janela de atendimento ou use um template aprovado, com os anexos e botões previstos no modelo.

POST/public/v1/messages

Escolha text ou template, nunca os dois. Os modelos dos exemplos são ilustrativos: consulte os templates do seu número e use os nomes e campos retornados.

Enviar um template (link para esta seção)

Este exemplo usa um modelo com duas variáveis numeradas: nome da pessoa e número do pedido. Pode ser enviado dentro ou fora da janela de atendimento.

cURL · enviar template

curl -X POST https://api.patrociniotech.com/public/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: aviso-pedido-8421-v1" \
  -d '{
  "to": "5521999999999",
  "phone_number_id": "SEU_NUMERO_ID",
  "template": "aviso_entrega",
  "language": "pt_BR",
  "variables": [

15 linhas

Resposta de envio aceito (link para esta seção)

JSON · HTTP 200

{
  "success": true,
  "data": {
    "message_id": "wamid.EXEMPLO",
    "status": "sent",
    "to": "5521999999999",
    "client_ref": "pedido-8421"
  }
}

sent confirma que a Meta aceitou o envio. Guarde message_id e acompanhe message.status no webhook para confirmar entrega, leitura ou falha.

Repetir a operação com segurança (link para esta seção)

Gere uma Idempotency-Key por mensagem e salve-a antes de enviar. Em falha de conexão ou 5xx, repita com a mesma chave e o mesmo corpo.

Resultado	Como agir
200 · idempotent_replay: true	A resposta é de uma operação já aceita. Use o message_id retornado; a repetição não dispara outro envio.
409 · idempotency_in_flight	A operação está em andamento ou sem confirmação. Aguarde e repita com a mesma chave. Se persistir, confira os eventos antes de iniciar outro envio.
409 · idempotency_conflict	A chave pertence a outro conteúdo. Confira a operação original; use outra chave somente para uma nova mensagem intencional.
409 · idempotency_legacy_unverified	O registro antigo não permite comparar o conteúdo. Verifique o envio original e os eventos antes de outra tentativa.

Não gere outra chave para contornar uma tentativa sem confirmação. A reserva não é liberada automaticamente após cinco minutos. A proteção dura pelo período de retenção; mantenha o histórico da operação também no seu sistema.

Dados recusados antes do envio podem ser corrigidos. Para tratar limites e indisponibilidade, use a política de novas tentativas.

Enviar texto livre (link para esta seção)

O contato precisa ter escrito para o mesmo número da empresa nas últimas 24 horas. Confirme a janela de atendimento quando necessário; ela não determina a gratuidade.

cURL · enviar texto livre

curl -X POST https://api.patrociniotech.com/public/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: texto-pedido-8421-v1" \
  -d '{
  "to": "5521999999999",
  "phone_number_id": "SEU_NUMERO_ID",
  "text": "Seu pedido saiu para entrega.",
  "client_ref": "pedido-8421"
}'

Enviar um template com PDF (link para esta seção)

O cabeçalho DOCUMENT exige o arquivo em cada envio. Este exemplo combina um PDF, variáveis nomeadas e um botão de link dinâmico.

cURL · enviar template com PDF

curl -X POST https://api.patrociniotech.com/public/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bilhete-pedido-8421-v1" \
  -d '{
  "to": "5521999999999",
  "phone_number_id": "SEU_NUMERO_ID",
  "template": "entrega_pedido_documento",
  "language": "pt_BR",
  "variable_names": [

26 linhas

A Meta precisa acessar o link sem uma sessão de navegador. Use HTTPS e mantenha o arquivo disponível durante o envio. A amostra da aprovação não substitui o documento do pedido; para enviar sem PDF, selecione um template sem esse cabeçalho.

Enviar um código de autenticação (link para esta seção)

Use um modelo AUTHENTICATION com botão OTP. A API preenche o corpo e o botão nativo com o mesmo otp_code. O índice suportado é 0.

cURL · autenticação

curl -X POST https://api.patrociniotech.com/public/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: verificacao-operacao-1234-v1" \
  -d '{
  "to": "5521999999999",
  "phone_number_id": "SEU_NUMERO_ID",
  "template": "codigo_verificacao",
  "language": "pt_BR",
  "otp_code": "123456",
  "otp_index": 0,
  "client_ref": "operacao-1234"
}'

Gere o código no seu servidor e valide prazo, destinatário, operação, uso único e tentativas. O texto de expiração do template não invalida o código nem apaga a mensagem. Veja validade do código e prazo de entrega.

Referência dos campos (link para esta seção)

Destinatário e conteúdo

Campo	Regra
to	Obrigatório. Telefone com país e DDD, somente dígitos. Ex.: 5521999999999.
phone_number_id	ID do seu número conectado. Sem ele, a API usa o número padrão da conta.
text	Texto livre de até 4.096 caracteres. Exige janela aberta e não pode ser combinado com campos de template.
template	Nome do modelo aprovado. Use em vez de text.
language	Idioma do modelo. Padrão: pt_BR.
reply_to_message_id	Opcional. ID da mensagem recebida que será citada na resposta.

Variáveis e cabeçalho

Campo	Regra
variables	Um valor por variável do corpo. Até 20 valores de 1.024 caracteres; a quantidade exigida vem do modelo.
variable_names	Nomes associados aos valores em variables, para modelos NAMED. Use a ordem da listagem ou mantenha cada par nome/valor correspondente.
header_media	Obrigatório se o modelo exigir mídia. Objeto com type (document, image ou video), link e filename opcional para documento.
header_text	Até 200 caracteres. Obrigatório se o cabeçalho de texto tiver uma variável; omita para cabeçalho fixo ou de mídia.

Botões e autenticação

Campo	Regra
button_url_param	Valor da parte variável de um botão de link. Até 200 caracteres; a API aceita um link dinâmico por template.
button_url_index	Posição do botão de link na lista, começando em zero. Padrão: 0.
coupon_code / coupon_index	Código de até 15 caracteres e posição do botão de cupom COPY_CODE. Não use para autenticação.
otp_code	Código de autenticação de até 15 caracteres, sem espaços ou caracteres de controle. variables pode ser omitido.
otp_index	Para autenticação, use 0 ou omita. Não combine OTP com anexo, cupom, link dinâmico ou PIX.
pix_order	Pedido para um template de cobrança, com botão ORDER_DETAILS. Veja o exemplo abaixo.

Valores de variáveis não aceitam quebras de linha, tabulações ou mais de quatro espaços consecutivos. Nenhum valor é cortado para caber: a API informa o erro para você corrigir.

Relacionar o envio ao seu pedido (link para esta seção)

client_ref é opcional, tem até 64 caracteres e volta nos eventos de status. Use um identificador da sua operação, como pedido-8421. Ele ajuda na conciliação, mas não substitui a Idempotency-Key.

Guarde também message_id e phone_number_id: um pedido pode ter várias mensagens e mais de um número de envio.

Cobrança PIX (link para esta seção)

Disponível para template de detalhes do pedido e conta com pagamentos habilitados na Meta. Os valores são inteiros em centavos; a API confere a soma dos itens e da taxa.

Ver exemplo de cobrança e campos de pagamento

cURL · cobrança PIX

curl -X POST https://api.patrociniotech.com/public/v1/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cobranca-pedido-8421-v1" \
  -d '{
  "to": "5521999999999",
  "phone_number_id": "SEU_NUMERO_ID",
  "template": "cobranca_emissao",
  "language": "pt_BR",
  "pix_order": {

26 linhas

Em pix_order	Uso
reference_id	Referência da cobrança no seu sistema. Até 64 caracteres.
pix_code	Copia e cola completo gerado pelo seu PSP para esta cobrança. Não use o texto ilustrativo acima.
merchant_name / key / key_type	Nome do recebedor, chave PIX e tipo: CNPJ, CPF, EMAIL, PHONE ou EVP.
items	Até 30 itens com name, amount unitário em centavos e quantity.
tax / total_amount	tax é opcional, com padrão 0. Se total_amount for informado, deve ser igual a Σ(amount × quantity) + tax.

Validar um telefone (link para esta seção)

POST/public/v1/validate

cURL · validar formato

curl -X POST https://api.patrociniotech.com/public/v1/validate \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to": "(21) 99999-9999", "country": "BR"}'

Use o to normalizado quando data.valid for true. Essa consulta valida o formato; não confirma existência no WhatsApp nem autorização para envio.

valid=true não significa que a mensagem será entregue. Um telefone digitado errado pode ter formato válido. A Cloud API não oferece uma consulta prévia para confirmar se o destinatário tem WhatsApp.

Após enviar, guarde message_id e client_ref. Considere a entrega confirmada apenas ao receber message.status com delivered ou read. O aceite inicial sent ainda pode terminar em failed.

Se chegar error.reason=recipient_unreachable com error.code=131026, registre a falha e confira o telefone com o cliente por outro canal. Esse código não comprova ausência de WhatsApp. Evite repetições automáticas e variações do número sem confirmação.