Enviar mensagem
Enfileira o envio de uma mensagem pelo número vinculado à API key. Use exatamente um de templateId (envio por template, com variables) ou text (texto livre); e exatamente um destino: destinationNumber (E.164), groupId (…@g.us) ou newsletterId (…@newsletter). Requer key escopada a número (403 para key de tenant). Efeito real: entrega de verdade e pode custar. NOT_SUPPORTED_FOR_META para groupId/newsletterId em números Meta.
Requer uma chave com escopo de número.
Autorizações
Sua chave de API ps_
Corpo
Id ou nome do template (exclusivo com text).
"boas_vindas"
Texto livre (exclusivo com templateId).
"Olá! Sua entrega chegou."
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.
"5511988887777"
JID de grupo. NOT_SUPPORTED_FOR_META.
"123456789-987654321@g.us"
JID de canal/newsletter. NOT_SUPPORTED_FOR_META.
"120363000000000000@newsletter"
Variáveis do template (padrão {}).
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).
"https://cdn.acme.com/img.png"
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.
image, video, document, audio, voice, sticker "image"
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.
"Nota Fiscal 123.pdf"
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.
"Segue seu comprovante"
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. Definaid(valor seu; não volta no toque — case as respostas por rótulo +quotedMessageId).url— abre um link; definaurl(https). Em texto livre, no máximo um botão URL por mensagem, e ele pode ser combinado com botõesreply.call— liga para um número; definaphoneNumber(E.164, ex.:+5511999999999). Somente em templates — em texto livre retorna 400 (BUTTON_PHONE_NUMBER_TEMPLATE_ONLY).copy— copia um código; definacopyCode. 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.
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.
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 só 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.
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).
Rodapé da mensagem (máx. 60 caracteres). Requer buttons.
Agendar a entrega para um instante futuro.
"2026-06-21T09:00:00Z"
Janela máxima de entrega.
"2026-06-21T18:00:00Z"
Labels a aplicar à conversa de destino.
Resposta
Enviar template