Enviar uma mensagem de WhatsApp

POST https://pilotstatus.com.br/v1/messages/send

Este é o único endpoint de envio. Ele suporta três modos de nível superior mutuamente exclusivos:

Envio de template — templateId (+ variables opcional)
Envio de texto livre — text
Envio de mídia direta — media + mediaType (sem templateId, sem text)

Exatamente um modo deve ser usado por requisição. Não existem endpoints separados /messages/text, /messages/media ou /messages/interactive.

Página Mensagem do painel com seletor de template e pré-visualização, variáveis mapeadas para colunas da planilha, lista de destinatários com upload de Excel/CSV, ações Enviar e Agendar e o curl gerado automaticamente da chamada exata da API — A página Mensagem usa este mesmo endpoint — escolha um template, mapeie variáveis para colunas da planilha, suba destinatários e copie o curl gerado automaticamente.

Headers

Content-Type: application/json
x-api-key: ps_... (ou x-api-key-id: <api_key_id>) — uma chave com escopo de número

Destino (exatamente um)

string

Telefone de destino em E.164 com um + inicial (ex.: +5511999999999).

string

JID do grupo do WhatsApp terminando em @g.us.

JID do canal do WhatsApp terminando em @newsletter.

Campos de modo

string

Template do painel /templates. Mutuamente exclusivo com text e com o modo de mídia direta.

object

Mapa chave→valor para as variáveis do template. Variáveis obrigatórias ausentes produzem MISSING_TEMPLATE_VARIABLES.

string

Corpo de uma mensagem de texto livre. Obrigatório se templateId não for enviado (e não se tratar de um envio de mídia direta).

string

Uma URL http(s) pública ou um data URI base64 (ex.: data:audio/ogg;base64,AAAA...) para um arquivo de imagem, vídeo, documento ou áudio. Base64 é aceito para todos os tipos de mídia em números Meta Cloud API. Em números não oficiais (Pilot Status web), base64 não é aceito — use uma URL http(s) pública. Sobrescreve qualquer mediaUrl embutido no template.

string

image, video, document, audio, voice ou sticker. Defina explicitamente quando a extensão da URL não for óbvia (ex.: PDFs cuja URL não termina em .pdf). Quando mediaType é audio, o arquivo é entregue como uma nota de voz (PTT) do WhatsApp em todos os provedores. Um indicador de presença é exibido ao contato logo antes da entrega: números não oficiais (Pilot Status web) mostram “gravando áudio”; números Meta Cloud API mostram “digitando” — a Cloud API não tem variante de gravação, e ele só aparece quando a conversa tem uma mensagem recebida recente para ancorar. O “digitando” é mostrado antes de todo envio conversacional em números Meta e Evolution; você também pode dispará-lo de forma independente via Indicador de Digitando. sticker envia uma figurinha do WhatsApp — só em envio direto de mídia, nunca com templateId, nunca com caption, e o arquivo precisa ser image/webp com exatamente 512×512 pixels (estática até 100 KB, animada até 500 KB).

Envio de mídia direta

Envie mídia por conta própria fornecendo media + mediaType sem templateId e sem text. Nesse modo, buttons, header, footer e variables não são permitidos; um caption opcional é permitido para image, video e document, mas não para audio, voice ou sticker.

Envios de mídia estão disponíveis em todos os planos, incluindo o Free — eles contam na cota de mensagens do número como qualquer outra mensagem. Não há uma cobrança paga separada para enviar mídia.

Agendamento e janela de entrega

string

Data e hora ISO 8601 para agendar o envio.

string

Prazo ISO 8601 para a entrega. Se expirar, a mensagem falha (veja Códigos de erro de log).

Outros campos

string[]

Marque o destino com Labels (escopo do tenant). Processados de forma assíncrona. Com a chave de API retentionDays = 0, as Labels são criadas, mas a vinculação com o telefone/grupo pode não ser persistida (PII).

object

Apenas para templates MARKETING. aiRewriteEnabled: true habilita a variação automática do texto final da mensagem para reduzir padrões repetitivos (anti-spam) preservando a intenção. Se a variação não puder ser aplicada, o texto original é enviado. Envios MARKETING também recebem um atraso automático de fila variável (padrão 8–25 s) para espaçar o ritmo de envio.

array

Até 3 botões que sobrescrevem os botões do template. Cada botão possui type e displayText mais campos específicos do tipo:

{ "type": "reply", "displayText": "Yes", "id": "yes" } — resposta rápida
{ "type": "url", "displayText": "Site", "url": "https://example.com" } — botão de URL
{ "type": "call", "displayText": "Call", "phoneNumber": "+5511999999999" } — botão de chamada
{ "type": "copy", "displayText": "Code", "copyCode": "ABC123" } — botão de copiar

buttons pode ser combinado com qualquer mediaType. A API não rejeita botões com mediaType: "video" ou mediaType: "document" (números não oficiais os aceitam); observe que a Meta Cloud API pode rejeitar algumas combinações de botões com vídeo/documento no momento da entrega.

object

Header para uma mensagem interativa de texto livre. Requer buttons. Tipos: { "type": "text", "content": "Header title" } (até 60 caracteres), ou image / video / document com uma URL pública como content.

string

Rodapé da mensagem (máximo 60 caracteres). Requer buttons.

object

Lista interativa de seleção única para um envio de texto livre. Requer text; exclusiva com templateId, buttons, header e mídia direta (footer é permitido). Veja Listas abaixo.

Restrições de texto livre

media e mediaType não podem ser usados com text (texto livre).
header e footer só são suportados quando buttons está presente (limitação da Meta Cloud API).
Em números Meta, mensagens de texto livre só funcionam dentro da janela de conversa de 24h do WhatsApp. Fora da janela, um erro META_OUTSIDE_24H_WINDOW é retornado no webhook message.failed — use um template aprovado em vez disso. Verifique se a janela está aberta antes de enviar com GET /v1/service-window.

Botões

buttons adiciona até 3 botões interativos — em um envio de texto livre, ou para sobrescrever os botões de um template em um envio de template. Cada item precisa de type + displayText e um campo específico do tipo:

`type`	Campo extra	Comportamento
`reply`	`id` (string)	Resposta rápida. O toque chega como webhook de entrada normal cujo `content` é o rótulo do botão — o `id`não é devolvido.
`url`	`url` (https)	Abre um link.
`call`	`phoneNumber` (E.164)	Liga para o número.
`copy`	`copyCode` (string)	Copia um código para a área de transferência.

{
  "text": "Confirmar seu agendamento?",
  "destinationNumber": "+5511999999999",
  "buttons": [
    { "type": "reply", "displayText": "Confirmar", "id": "confirmar" },
    { "type": "url", "displayText": "Detalhes", "url": "https://exemplo.com/pedido/123" }
  ]
}

header e footer só são permitidos junto com buttons (limitação da Meta Cloud API).
Case os toques de resposta pelo rótulo em content + quotedMessageId — não existe campo button_id nem evento button_reply.
Em números Meta Cloud API, botões de texto livre só funcionam dentro da janela de atendimento de 24 horas. Fora dela, envie um template aprovado. Botões de template usam um vocabulário diferente — QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, PAYMENT_REQUEST — definidos na criação do template; veja Templates.

Listas

list adiciona uma lista interativa de seleção única a um envio de texto livre: text vira o corpo da mensagem e buttonText é o rótulo do botão que abre o menu de linhas. Exclusiva com templateId, buttons e mídia direta:

{
  "text": "Como podemos ajudar hoje?",
  "destinationNumber": "+5511999999999",
  "list": {
    "buttonText": "Ver áreas",
    "sections": [
      {
        "title": "Atendimento",
        "rows": [
          { "id": "clientes", "title": "Clientes", "description": "Consultar e cadastrar clientes" },
          { "title": "Pedidos", "description": "Acompanhar um pedido existente" }
        ]
      }
    ]
  }
}

Limites (da Meta, aplicados de forma uniforme em todos os tipos de número): buttonText 1–20 caracteres, 1–10 seções, máx. 10 linhas no total somando todas as seções, title da linha 1–24 caracteres, description da linha até 72 caracteres, id da linha até 200 caracteres (gerado quando ausente). O title da seção é opcional.
Funciona em ambos os tipos de número com a mesma requisição: números Meta Cloud API enviam a lista interativa oficial; números não oficiais (Pilot Status web) enviam a lista nativa.
A seleção do destinatário chega como mensagem/webhook de entrada normal.

Exemplos

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "templateId": "onboarding-test",
    "destinationNumber": "+5511999999999",
    "variables": { "name": "John", "order_id": "123" }
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "templateId": "onboarding-test",
    "destinationNumber": "+5511999999999",
    "variables": { "name": "John" },
    "labels": ["vip", "customers"],
    "deliverAt": "2026-02-24T15:05:00.000Z"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "text": "Hi! Your delivery has been confirmed for tomorrow.",
    "destinationNumber": "+5511999999999"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "text": "Would you like to confirm your appointment?",
    "destinationNumber": "+5511999999999",
    "buttons": [
      { "type": "reply", "displayText": "Confirm", "id": "confirm" },
      { "type": "reply", "displayText": "Cancel", "id": "cancel" }
    ]
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "text": "Your reservation is confirmed!",
    "destinationNumber": "+5511999999999",
    "header": { "type": "image", "content": "https://example.com/reservation.png" },
    "footer": "Example Hotel",
    "buttons": [
      { "type": "url", "displayText": "View details", "url": "https://example.com/reservation/123" }
    ]
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "destinationNumber": "+5511999999999",
    "media": "https://cdn.example.com/voice.ogg",
    "mediaType": "audio"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "destinationNumber": "+5511999999999",
    "media": "data:image/png;base64,iVBORw0...",
    "mediaType": "image"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "templateId": "confirm-template",
    "destinationNumber": "+5511999999999",
    "variables": { "name": "John" },
    "media": "https://example.com/promo.png",
    "mediaType": "image",
    "buttons": [
      { "type": "reply", "displayText": "Yes", "id": "confirm" },
      { "type": "url", "displayText": "View offer", "url": "https://example.com/offer" }
    ]
  }'

Resposta (202)

{
  "id": "msg_abc",
  "correlationId": "corr_123",
  "status": "QUEUED",
  "createdAt": "2026-02-24T15:00:00.000Z",
  "origin": "My WhatsApp"
}

string

ID interno da mensagem. Persista este valor — é o valor a ser usado com GET /v1/messages/{id} e corresponde a internalMessageId nos webhooks.

string

Identificador de correlação para a requisição de envio.

string

Sempre QUEUED na aceitação.

Correlação com webhooks

O campo id na resposta é o mesmo campo id em message.sent, message.delivered, message.read e message.failed. Em message.reply, use quotedMessageId (o messageId do WhatsApp da sua mensagem original) e correlationId para vincular a resposta ao seu envio.
O messageId do WhatsApp (wamid) não está no corpo do 202; ele aparece pela primeira vez no webhook message.sent (e se repete nos eventos de status daquela mensagem).
Persista id quando receber o 202 e use GET /v1/messages/{id} com o mesmo valor.

Erros comuns

Status	Significado
`400`	Payload inválido (ex.: telefone fora do E.164, campos obrigatórios ausentes, `MISSING_TEMPLATE_VARIABLES`, ou texto livre não suportado pelo provedor: `code: FREE_FORM_NOT_SUPPORTED`)
`401`	Header de chave de API ausente/inválido (`x-api-key` / `x-api-key-id`)
`403`	Uma chave com escopo de tenant usada em um endpoint com escopo de número
`404`	Template não encontrado ou sem uma versão aprovada
`422`	Cobrança do tenant suspensa (`code: BILLING_SUSPENDED`) — inadimplência, ou saldo WALLET / de extras não pago; regularize seus créditos ou cartão para retomar os envios
`429`	Limite de taxa

Falhas de entrega assíncronas (ex.: META_OUTSIDE_24H_WINDOW, META_TEMPLATE_NOT_APPROVED, WHATSAPP_NOT_EXIST) aparecem via webhook message.failed e nos Logs — veja Códigos de erro de log.

Visão Geral

Mensagens

Modelos

Números

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

POST /v1/messages/send — Enviar uma mensagem de WhatsApp

Enviar uma mensagem de WhatsApp

Headers

Destino (exatamente um)

Campos de modo

Envio de mídia direta

Agendamento e janela de entrega

Outros campos

Restrições de texto livre

Botões

Listas

Exemplos

Resposta (202)

Correlação com webhooks

Erros comuns

​Enviar uma mensagem de WhatsApp

​Headers

​Destino (exatamente um)

​Campos de modo

​Envio de mídia direta

​Agendamento e janela de entrega

​Outros campos

​Restrições de texto livre

​Botões

​Listas

​Exemplos

​Resposta (202)

​Correlação com webhooks

​Erros comuns

Enviar uma mensagem de WhatsApp

Headers

Destino (exatamente um)

Campos de modo

Envio de mídia direta

Agendamento e janela de entrega

Outros campos

Restrições de texto livre

Botões

Listas

Exemplos

Resposta (202)

Correlação com webhooks

Erros comuns