Skip to main content
POST
Enviar mensagem

Autorizações

x-api-key
string
header
obrigatório

Sua chave de API ps_

Corpo

application/json
templateId
string

Id ou nome do template (exclusivo com text).

Exemplo:

"boas_vindas"

text
string

Texto livre (exclusivo com templateId).

Exemplo:

"Olá! Sua entrega chegou."

destinationNumber
string

Destino (exatamente um destino). Aceita telefone E.164 OU um BSUID — o userId durável do contato (ex.: BR.13491208655302741918), retornado por GET /api/v1/conversations. Use o BSUID para responder a contatos que usam username do WhatsApp (sem telefone). Templates de autenticação one-tap/zero-tap/copy-code exigem telefone.

Exemplo:

"5511988887777"

groupId
string

JID de grupo. NOT_SUPPORTED_FOR_META.

Exemplo:

"123456789-987654321@g.us"

newsletterId
string

JID de canal/newsletter. NOT_SUPPORTED_FOR_META.

Exemplo:

"120363000000000000@newsletter"

variables
object

Variáveis do template (padrão {}).

Exemplo:
media
string

URL pública http(s) OU data URI base64 (ex.: data:audio/ogg;base64,AAAA…). Base64 funciona na Meta Cloud API e na Evolution v2; na Evolution GO use uma URL pública http(s) (GO não aceita base64). Usado no modo template ou no modo mídia direta (media + mediaType, sem templateId e sem text).

Exemplo:

"https://cdn.acme.com/img.png"

mediaType
enum<string>

Tipo da mídia. No modo mídia direta (sem templateId/text) envie media + mediaType: caption opcional para image/video/document (não para audio/voice); botões/header/footer/variáveis não permitidos. "audio" entrega como nota de voz (PTT) sem waveform; "voice" entrega como nota de voz com waveform/ondinha (Meta renderiza a ondina quando voice: true). Ambos são normalizados no servidor (OGG/Opus mono, metadados removidos, start_time zero). Na Evolution v2 e GO um indicador "gravando áudio" é mostrado antes da nota de voz. "sticker" envia uma figurinha do WhatsApp: só no modo mídia direta (nunca com templateId), sem caption, e o arquivo precisa ser image/webp com exatamente 512x512 pixels — estática até 100 KB, animada até 500 KB. Qualquer outra dimensão é recusada pelo WhatsApp (erro 131053 da Meta, META_MEDIA_UPLOAD_ERROR) depois que esta API já respondeu 202. Na Meta Cloud API a figurinha é enviada como type "sticker"; na Evolution v2 e GO ela sai pela rota de sticker dedicada de cada servidor.

Opções disponíveis:
image,
video,
document,
audio,
voice,
sticker
Exemplo:

"image"

mediaFilename
string

Nome com que o documento chega no WhatsApp. Apenas envios diretos de documento (exige mediaType: document). Sem ele, o nome vem do final da URL. Separadores de caminho são removidos. Retorna 400 se enviado sem media, em um envio de template, ou com mediaType diferente de document.

Exemplo:

"Nota Fiscal 123.pdf"

caption
string

Legenda que acompanha um envio direto de mídia. Vale para image, video e document; recusada com 400 para audio, voice e sticker (nota de voz e figurinha não carregam texto). Máximo de 1024 caracteres. Não é usada no modo template — lá o texto vem do corpo do template.

Exemplo:

"Segue seu comprovante"

buttons
object[]

Até 3 botões interativos. Cada item tem type + displayText mais um campo específico do tipo.

  • reply — botão de resposta rápida; funciona em texto livre e em template. Defina id (valor seu; não volta no toque — case as respostas por rótulo + quotedMessageId).
  • url — abre um link; defina url (https). Em texto livre, no máximo um botão URL por mensagem, e ele pode ser combinado com botões reply.
  • call — liga para um número; defina phoneNumber (E.164, ex.: +5511999999999). Somente em templates — em texto livre retorna 400 (BUTTON_PHONE_NUMBER_TEMPLATE_ONLY).
  • copy — copia um código; defina copyCode. Somente em templates — em texto livre retorna 400 (BUTTON_COPY_CODE_TEMPLATE_ONLY).

Em um template, os botões substituem os botões do próprio template.

Exemplo:
list
object

Lista interativa de seleção única — um botão que abre um menu de até 10 linhas. Requer text (o corpo da mensagem acima do botão); exclusiva com templateId, buttons e mídia direta. 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.

Exemplo:

Carrossel de sessão — uma tira horizontal e arrastável de 2–10 cards anexada a um envio livre. Requer text (o corpo da mensagem acima dos cards); exclusivo com templateId, list, buttons e mídia direta, e não aceita header (a mídia fica em cada card). Funciona nos dois tipos de número: números Meta Cloud API só enviam dentro da janela de atendimento de 24h (fora dela, use um template de carrossel aprovado); números não oficiais (Pilot Status web) enviam no avulso. Botões do carrossel de sessão são QUICK_REPLY na Meta (um botão URL ali exige um template de carrossel aprovado); em números não oficiais um botão URL também funciona no avulso. O toque num botão de resposta rápida chega como um webhook de entrada normal.

Exemplo:
header
object

Cabeçalho de uma mensagem interativa de texto livre. Requer buttons. type é text (até 60 chars em content) ou image / video / document (URL pública em content).

Exemplo:

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

deliverAt
string

Agendar a entrega para um instante futuro.

Exemplo:

"2026-06-21T09:00:00Z"

deliverUntil
string

Janela máxima de entrega.

Exemplo:

"2026-06-21T18:00:00Z"

labels
string[]

Labels a aplicar à conversa de destino.

Exemplo:

Resposta

Enviar template