Enviar mensagens

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 -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": [

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

{
  "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.

Guarde também o to da resposta: ele identifica o destinatário reconhecido pela Meta. Mantenha o status no seu sistema a partir dos eventos; para conferir uma mensagem já identificada, use a consulta abaixo.

Consultar um envio sem reenviar# (link para esta seção)

Informe o message_id devolvido no envio. A consulta lê o estado registrado na Patrocinio Tech, não envia uma mensagem nem consulta o telefone na Meta. Somente mensagens de saída da empresa autenticada são acessíveis.

curl "https://api.patrociniotech.com/public/v1/messages/wamid.EXEMPLO/status" \
  -H "Authorization: Bearer SUA_CHAVE"

{
  "success": true,
  "data": {
    "message_id": "wamid.EXEMPLO",
    "status": "delivered",
    "client_ref": "pedido-8421",
    "phone_number_id": "SEU_NUMERO_ID",
    "to": "5521999999999",
    "created_at": "2026-11-06T12:00:00Z",
    "message_at": "2026-11-06T12:00:00Z",
    "checked_at": "2026-11-06T12:01:00Z",
    "error": null
  }
}

404 message_not_found pode significar identificador incorreto, registro ainda não persistido, removido pela retenção ou pertencente a outra conta. Não comprova que a mensagem deixou de ser enviada nem autoriza reenvio automático. Sem message_id, preserve a operação e a chave de idempotência para recuperar o aceite original.

Consultar quando o envio ficou sem resposta# (link para esta seção)

Se o POST terminou em timeout ou 5xx antes de devolver o message_id, consulte com a Idempotency-Key original. A leitura encontra inclusive a reserva da tentativa, sem enviar outra mensagem nem liberar a chave.

curl "https://api.patrociniotech.com/public/v1/messages/status" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Idempotency-Key: aviso-pedido-8421-v1"

Para uma mensagem já registrada, também é possível consultar por client_ref, de até 64 caracteres. Informe apenas uma das opções por chamada. Use uma referência por operação; se houver duas tentativas com a mesma referência, a API retorna 409 ambiguous_client_ref e não escolhe uma delas.

curl --get "https://api.patrociniotech.com/public/v1/messages/status" \
  -H "Authorization: Bearer SUA_CHAVE" \
  --data-urlencode "client_ref=pedido-8421"

{
  "success": true,
  "data": {
    "lookup": "idempotency_key",
    "resolution": "unconfirmed",
    "message": null,
    "checked_at": "2026-11-06T12:01:00Z",
    "retention": {
      "idempotency_days": 2,
      "messages_days": 365,
      "measured_from": "created_at"
    }
  }
}

retention informa os prazos configurados no momento da consulta, contados da criação. São dois dias para a reserva e 365 dias para mensagens por padrão; a manutenção é periódica. Mantenha seu histórico de operações e não use o fim desse prazo como autorização para repetir um envio incerto.

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.

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 -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 -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": [

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 -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"
}'

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

Envie somente os campos documentados. Nomes desconhecidos, inclusive dentro de header_media e pix_order, retornam 422 invalid_request. Os detalhes indicam o campo a corrigir; ele não é ignorado para prosseguir com valores padrão.

Destinatário e conteúdo

Variáveis e cabeçalho

Botões e autenticação

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.

Marketing, consentimento e saída da lista# (link para esta seção)

A API permite enviar um template MARKETING a um contato com aceite pending ou sem cadastro local. Isso não registra consentimento como accepted. Conserve no seu sistema a origem da lista e a evidência de que a pessoa espera essa comunicação.

Uma recusa de promoções em qualquer número da mesma empresa, ou um bloqueio no número de envio, impede novos envios de marketing com 422 marketing_not_allowed. Não há parâmetro para ignorar essa exclusão. A consulta de janela e preferência permite conferir o bloqueio antes; a API verifica novamente ao enviar.

Uma saída de promoções não impede um aviso legítimo de pedido com template UTILITY ou um código solicitado com AUTHENTICATION. Use a categoria correspondente ao conteúdo; mudar a categoria não é uma forma de reenviar a promoção recusada.

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 único da operação, como pedido-8421-entrega-v1, para consultá-la depois. Ele ajuda na conciliação, mas não substitui a Idempotency-Key nem impede envios duplicados.

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 JSON em centavos; strings, decimais e booleanos são recusados. A API confere a soma dos itens e da taxa, sem arredondar valores.

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": {

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

Se o cadastro contém apenas DDD e telefone, informe o país em country (ISO de duas letras) nesta consulta antes de enviar. Para um telefone já internacional, use + e DDI, ou envie somente os dígitos e omita country. Não presuma que todos os clientes usam o DDI 55.

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.

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.