Mensagens
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. O header opcional Idempotency-Key torna as novas tentativas seguras (24 h; a reprodução traz Idempotent-Replayed: true).
Requer uma chave com escopo de número.
POST
/
v1
/
messages
/
send
Enviar mensagem
curl --request POST \
--url https://pilotstatus.com.br/v1/messages/send \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"templateId": "boas_vindas",
"text": "Olá! Sua entrega chegou.",
"destinationNumber": "5511988887777",
"groupId": "123456789-987654321@g.us",
"newsletterId": "120363000000000000@newsletter",
"variables": {
"nome": "Ana"
},
"media": "https://cdn.acme.com/img.png",
"mediaType": "image",
"mediaFilename": "Nota Fiscal 123.pdf",
"caption": "Segue seu comprovante",
"buttons": [
{
"type": "reply",
"displayText": "Confirmar",
"id": "confirmar"
},
{
"type": "url",
"displayText": "Ver detalhes",
"url": "https://exemplo.com/pedido/123"
}
],
"list": {
"buttonText": "Ver áreas",
"sections": [
{
"title": "Atendimento",
"rows": [
{
"id": "clientes",
"title": "Clientes",
"description": "Consultar e cadastrar clientes"
}
]
}
]
},
"carousel": {
"cardTemplate": {
"hasBody": true,
"buttons": [
{
"type": "QUICK_REPLY"
}
]
},
"cards": [
{
"media": {
"format": "IMAGE",
"url": "https://media.example.com/a.png"
},
"body": "Tênis — 30% off",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quero",
"payload": "SKU-1"
}
]
},
{
"media": {
"format": "IMAGE",
"url": "https://media.example.com/b.png"
},
"body": "Mochila — frete grátis",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quero",
"payload": "SKU-2"
}
]
}
]
},
"header": {
"type": "text",
"content": "Título do cabeçalho"
},
"footer": "Responda SAIR para não receber mais",
"deliverAt": "2026-06-21T09:00:00Z",
"deliverUntil": "2026-06-21T18:00:00Z",
"markRead": false,
"labels": [
"pedido",
"vip"
]
}
'import requests
url = "https://pilotstatus.com.br/v1/messages/send"
payload = {
"templateId": "boas_vindas",
"text": "Olá! Sua entrega chegou.",
"destinationNumber": "5511988887777",
"groupId": "123456789-987654321@g.us",
"newsletterId": "120363000000000000@newsletter",
"variables": { "nome": "Ana" },
"media": "https://cdn.acme.com/img.png",
"mediaType": "image",
"mediaFilename": "Nota Fiscal 123.pdf",
"caption": "Segue seu comprovante",
"buttons": [
{
"type": "reply",
"displayText": "Confirmar",
"id": "confirmar"
},
{
"type": "url",
"displayText": "Ver detalhes",
"url": "https://exemplo.com/pedido/123"
}
],
"list": {
"buttonText": "Ver áreas",
"sections": [
{
"title": "Atendimento",
"rows": [
{
"id": "clientes",
"title": "Clientes",
"description": "Consultar e cadastrar clientes"
}
]
}
]
},
"carousel": {
"cardTemplate": {
"hasBody": True,
"buttons": [{ "type": "QUICK_REPLY" }]
},
"cards": [
{
"media": {
"format": "IMAGE",
"url": "https://media.example.com/a.png"
},
"body": "Tênis — 30% off",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quero",
"payload": "SKU-1"
}
]
},
{
"media": {
"format": "IMAGE",
"url": "https://media.example.com/b.png"
},
"body": "Mochila — frete grátis",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quero",
"payload": "SKU-2"
}
]
}
]
},
"header": {
"type": "text",
"content": "Título do cabeçalho"
},
"footer": "Responda SAIR para não receber mais",
"deliverAt": "2026-06-21T09:00:00Z",
"deliverUntil": "2026-06-21T18:00:00Z",
"markRead": False,
"labels": ["pedido", "vip"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
templateId: 'boas_vindas',
text: 'Olá! Sua entrega chegou.',
destinationNumber: '5511988887777',
groupId: '123456789-987654321@g.us',
newsletterId: '120363000000000000@newsletter',
variables: {nome: 'Ana'},
media: 'https://cdn.acme.com/img.png',
mediaType: 'image',
mediaFilename: 'Nota Fiscal 123.pdf',
caption: 'Segue seu comprovante',
buttons: [
{type: 'reply', displayText: 'Confirmar', id: 'confirmar'},
{
type: 'url',
displayText: 'Ver detalhes',
url: 'https://exemplo.com/pedido/123'
}
],
list: {
buttonText: 'Ver áreas',
sections: [
{
title: 'Atendimento',
rows: [
{
id: 'clientes',
title: 'Clientes',
description: 'Consultar e cadastrar clientes'
}
]
}
]
},
carousel: {
cardTemplate: {hasBody: true, buttons: [{type: 'QUICK_REPLY'}]},
cards: [
{
media: {format: 'IMAGE', url: 'https://media.example.com/a.png'},
body: JSON.stringify('Tênis — 30% off'),
buttons: [{type: 'QUICK_REPLY', text: 'Quero', payload: 'SKU-1'}]
},
{
media: {format: 'IMAGE', url: 'https://media.example.com/b.png'},
body: JSON.stringify('Mochila — frete grátis'),
buttons: [{type: 'QUICK_REPLY', text: 'Quero', payload: 'SKU-2'}]
}
]
},
header: {type: 'text', content: 'Título do cabeçalho'},
footer: 'Responda SAIR para não receber mais',
deliverAt: '2026-06-21T09:00:00Z',
deliverUntil: '2026-06-21T18:00:00Z',
markRead: false,
labels: ['pedido', 'vip']
})
};
fetch('https://pilotstatus.com.br/v1/messages/send', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://pilotstatus.com.br/v1/messages/send",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'templateId' => 'boas_vindas',
'text' => 'Olá! Sua entrega chegou.',
'destinationNumber' => '5511988887777',
'groupId' => '123456789-987654321@g.us',
'newsletterId' => '120363000000000000@newsletter',
'variables' => [
'nome' => 'Ana'
],
'media' => 'https://cdn.acme.com/img.png',
'mediaType' => 'image',
'mediaFilename' => 'Nota Fiscal 123.pdf',
'caption' => 'Segue seu comprovante',
'buttons' => [
[
'type' => 'reply',
'displayText' => 'Confirmar',
'id' => 'confirmar'
],
[
'type' => 'url',
'displayText' => 'Ver detalhes',
'url' => 'https://exemplo.com/pedido/123'
]
],
'list' => [
'buttonText' => 'Ver áreas',
'sections' => [
[
'title' => 'Atendimento',
'rows' => [
[
'id' => 'clientes',
'title' => 'Clientes',
'description' => 'Consultar e cadastrar clientes'
]
]
]
]
],
'carousel' => [
'cardTemplate' => [
'hasBody' => true,
'buttons' => [
[
'type' => 'QUICK_REPLY'
]
]
],
'cards' => [
[
'media' => [
'format' => 'IMAGE',
'url' => 'https://media.example.com/a.png'
],
'body' => 'Tênis — 30% off',
'buttons' => [
[
'type' => 'QUICK_REPLY',
'text' => 'Quero',
'payload' => 'SKU-1'
]
]
],
[
'media' => [
'format' => 'IMAGE',
'url' => 'https://media.example.com/b.png'
],
'body' => 'Mochila — frete grátis',
'buttons' => [
[
'type' => 'QUICK_REPLY',
'text' => 'Quero',
'payload' => 'SKU-2'
]
]
]
]
],
'header' => [
'type' => 'text',
'content' => 'Título do cabeçalho'
],
'footer' => 'Responda SAIR para não receber mais',
'deliverAt' => '2026-06-21T09:00:00Z',
'deliverUntil' => '2026-06-21T18:00:00Z',
'markRead' => false,
'labels' => [
'pedido',
'vip'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://pilotstatus.com.br/v1/messages/send"
payload := strings.NewReader("{\n \"templateId\": \"boas_vindas\",\n \"text\": \"Olá! Sua entrega chegou.\",\n \"destinationNumber\": \"5511988887777\",\n \"groupId\": \"123456789-987654321@g.us\",\n \"newsletterId\": \"120363000000000000@newsletter\",\n \"variables\": {\n \"nome\": \"Ana\"\n },\n \"media\": \"https://cdn.acme.com/img.png\",\n \"mediaType\": \"image\",\n \"mediaFilename\": \"Nota Fiscal 123.pdf\",\n \"caption\": \"Segue seu comprovante\",\n \"buttons\": [\n {\n \"type\": \"reply\",\n \"displayText\": \"Confirmar\",\n \"id\": \"confirmar\"\n },\n {\n \"type\": \"url\",\n \"displayText\": \"Ver detalhes\",\n \"url\": \"https://exemplo.com/pedido/123\"\n }\n ],\n \"list\": {\n \"buttonText\": \"Ver áreas\",\n \"sections\": [\n {\n \"title\": \"Atendimento\",\n \"rows\": [\n {\n \"id\": \"clientes\",\n \"title\": \"Clientes\",\n \"description\": \"Consultar e cadastrar clientes\"\n }\n ]\n }\n ]\n },\n \"carousel\": {\n \"cardTemplate\": {\n \"hasBody\": true,\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\"\n }\n ]\n },\n \"cards\": [\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/a.png\"\n },\n \"body\": \"Tênis — 30% off\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-1\"\n }\n ]\n },\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/b.png\"\n },\n \"body\": \"Mochila — frete grátis\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-2\"\n }\n ]\n }\n ]\n },\n \"header\": {\n \"type\": \"text\",\n \"content\": \"Título do cabeçalho\"\n },\n \"footer\": \"Responda SAIR para não receber mais\",\n \"deliverAt\": \"2026-06-21T09:00:00Z\",\n \"deliverUntil\": \"2026-06-21T18:00:00Z\",\n \"markRead\": false,\n \"labels\": [\n \"pedido\",\n \"vip\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://pilotstatus.com.br/v1/messages/send")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"templateId\": \"boas_vindas\",\n \"text\": \"Olá! Sua entrega chegou.\",\n \"destinationNumber\": \"5511988887777\",\n \"groupId\": \"123456789-987654321@g.us\",\n \"newsletterId\": \"120363000000000000@newsletter\",\n \"variables\": {\n \"nome\": \"Ana\"\n },\n \"media\": \"https://cdn.acme.com/img.png\",\n \"mediaType\": \"image\",\n \"mediaFilename\": \"Nota Fiscal 123.pdf\",\n \"caption\": \"Segue seu comprovante\",\n \"buttons\": [\n {\n \"type\": \"reply\",\n \"displayText\": \"Confirmar\",\n \"id\": \"confirmar\"\n },\n {\n \"type\": \"url\",\n \"displayText\": \"Ver detalhes\",\n \"url\": \"https://exemplo.com/pedido/123\"\n }\n ],\n \"list\": {\n \"buttonText\": \"Ver áreas\",\n \"sections\": [\n {\n \"title\": \"Atendimento\",\n \"rows\": [\n {\n \"id\": \"clientes\",\n \"title\": \"Clientes\",\n \"description\": \"Consultar e cadastrar clientes\"\n }\n ]\n }\n ]\n },\n \"carousel\": {\n \"cardTemplate\": {\n \"hasBody\": true,\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\"\n }\n ]\n },\n \"cards\": [\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/a.png\"\n },\n \"body\": \"Tênis — 30% off\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-1\"\n }\n ]\n },\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/b.png\"\n },\n \"body\": \"Mochila — frete grátis\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-2\"\n }\n ]\n }\n ]\n },\n \"header\": {\n \"type\": \"text\",\n \"content\": \"Título do cabeçalho\"\n },\n \"footer\": \"Responda SAIR para não receber mais\",\n \"deliverAt\": \"2026-06-21T09:00:00Z\",\n \"deliverUntil\": \"2026-06-21T18:00:00Z\",\n \"markRead\": false,\n \"labels\": [\n \"pedido\",\n \"vip\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://pilotstatus.com.br/v1/messages/send")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"templateId\": \"boas_vindas\",\n \"text\": \"Olá! Sua entrega chegou.\",\n \"destinationNumber\": \"5511988887777\",\n \"groupId\": \"123456789-987654321@g.us\",\n \"newsletterId\": \"120363000000000000@newsletter\",\n \"variables\": {\n \"nome\": \"Ana\"\n },\n \"media\": \"https://cdn.acme.com/img.png\",\n \"mediaType\": \"image\",\n \"mediaFilename\": \"Nota Fiscal 123.pdf\",\n \"caption\": \"Segue seu comprovante\",\n \"buttons\": [\n {\n \"type\": \"reply\",\n \"displayText\": \"Confirmar\",\n \"id\": \"confirmar\"\n },\n {\n \"type\": \"url\",\n \"displayText\": \"Ver detalhes\",\n \"url\": \"https://exemplo.com/pedido/123\"\n }\n ],\n \"list\": {\n \"buttonText\": \"Ver áreas\",\n \"sections\": [\n {\n \"title\": \"Atendimento\",\n \"rows\": [\n {\n \"id\": \"clientes\",\n \"title\": \"Clientes\",\n \"description\": \"Consultar e cadastrar clientes\"\n }\n ]\n }\n ]\n },\n \"carousel\": {\n \"cardTemplate\": {\n \"hasBody\": true,\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\"\n }\n ]\n },\n \"cards\": [\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/a.png\"\n },\n \"body\": \"Tênis — 30% off\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-1\"\n }\n ]\n },\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/b.png\"\n },\n \"body\": \"Mochila — frete grátis\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-2\"\n }\n ]\n }\n ]\n },\n \"header\": {\n \"type\": \"text\",\n \"content\": \"Título do cabeçalho\"\n },\n \"footer\": \"Responda SAIR para não receber mais\",\n \"deliverAt\": \"2026-06-21T09:00:00Z\",\n \"deliverUntil\": \"2026-06-21T18:00:00Z\",\n \"markRead\": false,\n \"labels\": [\n \"pedido\",\n \"vip\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "msg_01HZX...",
"correlationId": "corr_01HZX...",
"status": "QUEUED",
"createdAt": "2026-06-20T10:00:00.000Z",
"origin": "Suporte",
"sourceNumber": "5511999999999"
}
Autorizações
apiKeyapiKeyId
Sua chave de API ps_
Cabeçalhos
Opcional. Torna a nova tentativa segura. Durante 24 horas, no escopo do seu workspace + o número de WhatsApp da chave + o valor da chave: a mesma chave com o mesmo corpo devolve a resposta guardada da primeira chamada aceita (2xx) e não envia nada de novo (header de resposta Idempotent-Replayed: true); a mesma chave com corpo diferente é 409 IDEMPOTENCY_KEY_REUSED; a mesma chave enquanto a primeira chamada ainda está em andamento é 409 IDEMPOTENCY_KEY_IN_USE. Só respostas 2xx são guardadas — um erro libera a chave, então você pode corrigir o corpo e tentar de novo com a mesma chave. Até 255 caracteres, sem caracteres de controle (senão 400 IDEMPOTENCY_KEY_INVALID). Se o armazenamento de idempotência estiver indisponível, uma requisição com chave recebe 503 IDEMPOTENCY_UNAVAILABLE (é seguro tentar de novo com a mesma chave). Ausente, o comportamento não muda. Derive a chave de algo estável do seu lado (ex.: id do pedido + destinatário) ou de um UUID guardado antes da primeira tentativa.
Maximum string length:
255Corpo
application/json
Id ou nome do template (exclusivo com text).
Exemplo:
"boas_vindas"
Texto livre (exclusivo com templateId).
Exemplo:
"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.
Exemplo:
"5511988887777"
JID de grupo. NOT_SUPPORTED_FOR_META.
Exemplo:
"123456789-987654321@g.us"
JID de canal/newsletter. NOT_SUPPORTED_FOR_META.
Exemplo:
"120363000000000000@newsletter"
Variáveis do template (padrão {}). Para um template criado no painel da Meta cujo botão de URL dinâmica tem um placeholder numerado (ex.: https://ctlnk.io/{{1}}, que não é o {{1}} do body), passe o sufixo da URL desse botão como button_<N>, em que N é a posição do botão entre todos os botões do template, começando em 1. Num número oficial (Meta), a mesma chave também leva o código de um botão de copiar código cujo valor não tem {{variável}} (o código definido na criação é só a amostra da Meta), ex.: button_2 para os botões [QUICK_REPLY, COPY_CODE]; um envio sem ela é recusado com 400 MISSING_TEMPLATE_VARIABLES.
Show child attributes
Show child attributes
Exemplo:
{ "nome": "Ana" }
URL pública http(s) OU data URI base64 (ex.: data:audio/ogg;base64,AAAA…). Base64 é aceito em números Meta Cloud API e em números não oficiais (Pilot Status web); em números não oficiais a Pilot Status sobe o arquivo decodificado para o próprio armazenamento e envia uma URL ao provedor, e se esse upload falhar a mensagem falha com MEDIA_REHOST_FAILED. Para figurinhas em números não oficiais, use uma URL http(s) pública. Usado no modo template ou no modo mídia direta (media + mediaType, sem templateId e sem text). O base64 tem teto pelo tamanho decodificado: 50 MiB (52428800 bytes) quando mediaType é document, 16 MiB (16777216 bytes) nos demais tipos e quando mediaType é omitido; acima disso a requisição falha com 400 Validation error (details.fieldErrors.media). Envie arquivos maiores como URL http(s) pública. Uma URL (ou um redirecionamento que ela responda) que aponte para um endereço interno ou de rede privada nunca é baixada: a mensagem falha depois do 202 com MEDIA_DOWNLOAD_FAILED, em qualquer tipo de número.
Exemplo:
"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. "voice" entrega uma nota de voz (PTT) do WhatsApp em qualquer número. "audio" entrega um arquivo de áudio (não uma nota de voz) em números oficiais (Meta Cloud API) e uma nota de voz em números não oficiais (Evolution v2 e GO) — envie "voice" para uma nota de voz. Antes do envio, o áudio é convertido para AAC em MP4 (audio/mp4) em números oficiais e para Ogg/Opus em números não oficiais. Na Evolution v2 e GO um indicador "gravando áudio" é mostrado antes de um envio audio ou voice; na Meta Cloud API aparece um indicador "digitando" no lugar, quando a conversa tem uma mensagem recente do contato. "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"
Nome de arquivo que o destinatário vê num DOCUMENTO (1–240 caracteres; / e \ viram _). Aceito em dois casos: (1) envio direto de documento (media + mediaType: document, sem templateId/text) — sem ele, o nome vem do final da URL; (2) envio de template cujo template aprovado tem cabeçalho DOCUMENT — com media (o documento que substitui o exemplo do template) ou sem ele (renomeia o documento guardado no template); ali, se mediaType vier, precisa ser document. Sem ele, o documento do template chega sem título adequado em números oficiais (Meta) — o WhatsApp mostra o genérico "Documento" — e com um nome deduzido da URL em números não oficiais. Funciona na Meta Cloud API, na Evolution v2 e na Evolution GO. Retorna 400 num envio de texto livre, num envio sem template e sem media, ou com mediaType diferente de document; num template cujo cabeçalho é IMAGE, VIDEO, TEXT ou inexistente, 422 MEDIA_FILENAME_REQUIRES_DOCUMENT_HEADER (details.templateName, details.headerType).
Exemplo:
"Nota Fiscal 123.pdf"
Legenda que acompanha um envio direto de mídia. Vale para image, video e document; recusada com 400 para audio e sticker. Também não é suportada em voice: não é recusada, mas é descartada em números não oficiais e sua exibição em números oficiais não é garantida — não envie legenda. Máximo de 1024 caracteres. Não é usada no modo template — lá o texto vem do corpo do template.
Exemplo:
"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 — exceto em números Meta (oficiais), em que os botões do template aprovado são fixos: buttons não os substitui e não preenche variável de botão. Preencha um botão de URL dinâmica por variables (a chave nomeada, ou button_<N> para placeholder numerado em template criado no painel da Meta); o código de um botão de copiar código também vai em variables como button_<N>, não em copyCode.
Show child attributes
Show child attributes
Exemplo:
[ { "type": "reply", "displayText": "Confirmar", "id": "confirmar" }, { "type": "url", "displayText": "Ver detalhes", "url": "https://exemplo.com/pedido/123" } ]
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.
Show child attributes
Show child attributes
Exemplo:
{ "buttonText": "Ver áreas", "sections": [ { "title": "Atendimento", "rows": [ { "id": "clientes", "title": "Clientes", "description": "Consultar e cadastrar clientes" } ] } ] }
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.
Show child attributes
Show child attributes
Exemplo:
{ "cardTemplate": { "hasBody": true, "buttons": [{ "type": "QUICK_REPLY" }] }, "cards": [ { "media": { "format": "IMAGE", "url": "https://media.example.com/a.png" }, "body": "Tênis — 30% off", "buttons": [ { "type": "QUICK_REPLY", "text": "Quero", "payload": "SKU-1" } ] }, { "media": { "format": "IMAGE", "url": "https://media.example.com/b.png" }, "body": "Mochila — frete grátis", "buttons": [ { "type": "QUICK_REPLY", "text": "Quero", "payload": "SKU-2" } ] } ] }
Flow dinâmico — um botão que abre um WhatsApp Flow escolhido NO MOMENTO DO ENVIO, em vez de ficar preso a um template aprovado. Apenas números Meta Cloud API (os provedores não oficiais não têm Flows), exige text e exige a janela de 24h aberta: fora dela a Meta responde 200 com um wamid e descarta a mensagem em silêncio, por isso o Pilot Status recusa com FLOW_WINDOW_CLOSED em vez de deixá-la sumir. Mutuamente exclusivo com templateId, list, carousel, buttons, header e envio direto de mídia. O flow_token é gerado por mensagem pelo Pilot Status e não pode ser informado.
Show child attributes
Show child attributes
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).
Show child attributes
Show child attributes
Exemplo:
{ "type": "text", "content": "Título do cabeçalho" }
Rodapé da mensagem (máx. 60 caracteres). Requer buttons ou list.
Exemplo:
"Responda SAIR para não receber mais"
Agendar a entrega para um instante futuro.
Exemplo:
"2026-06-21T09:00:00Z"
Janela máxima de entrega.
Exemplo:
"2026-06-21T18:00:00Z"
Se este envio marca como lida (tiques azuis) a última mensagem recebida do contato e mostra o indicador "digitando" antes. Omitido: vale o settings.markReadOnSend do número (padrão true). false em número oficial (Meta Cloud API): sem "digitando" e a conversa continua não lida — a Cloud API só mostra o "digitando" como parte de uma confirmação de leitura, então as duas coisas não se separam. Use quando um agente automático responde e uma pessoa ainda precisa ver a conversa não lida. Sem efeito em número não-oficial (o envio nunca marca como lido ali; a leitura na chegada é a configuração readMessages do número). O contador de não lidas do painel não é zerado por um envio, em nenhum dos casos. POST /v1/messages/typing em número Meta também marca como lida. Valor não booleano é 400.
Exemplo:
false
Labels a aplicar à conversa de destino.
Exemplo:
["pedido", "vip"]
Resposta
Enviar template
Esta página foi útil?
⌘I
Enviar mensagem
curl --request POST \
--url https://pilotstatus.com.br/v1/messages/send \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"templateId": "boas_vindas",
"text": "Olá! Sua entrega chegou.",
"destinationNumber": "5511988887777",
"groupId": "123456789-987654321@g.us",
"newsletterId": "120363000000000000@newsletter",
"variables": {
"nome": "Ana"
},
"media": "https://cdn.acme.com/img.png",
"mediaType": "image",
"mediaFilename": "Nota Fiscal 123.pdf",
"caption": "Segue seu comprovante",
"buttons": [
{
"type": "reply",
"displayText": "Confirmar",
"id": "confirmar"
},
{
"type": "url",
"displayText": "Ver detalhes",
"url": "https://exemplo.com/pedido/123"
}
],
"list": {
"buttonText": "Ver áreas",
"sections": [
{
"title": "Atendimento",
"rows": [
{
"id": "clientes",
"title": "Clientes",
"description": "Consultar e cadastrar clientes"
}
]
}
]
},
"carousel": {
"cardTemplate": {
"hasBody": true,
"buttons": [
{
"type": "QUICK_REPLY"
}
]
},
"cards": [
{
"media": {
"format": "IMAGE",
"url": "https://media.example.com/a.png"
},
"body": "Tênis — 30% off",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quero",
"payload": "SKU-1"
}
]
},
{
"media": {
"format": "IMAGE",
"url": "https://media.example.com/b.png"
},
"body": "Mochila — frete grátis",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quero",
"payload": "SKU-2"
}
]
}
]
},
"header": {
"type": "text",
"content": "Título do cabeçalho"
},
"footer": "Responda SAIR para não receber mais",
"deliverAt": "2026-06-21T09:00:00Z",
"deliverUntil": "2026-06-21T18:00:00Z",
"markRead": false,
"labels": [
"pedido",
"vip"
]
}
'import requests
url = "https://pilotstatus.com.br/v1/messages/send"
payload = {
"templateId": "boas_vindas",
"text": "Olá! Sua entrega chegou.",
"destinationNumber": "5511988887777",
"groupId": "123456789-987654321@g.us",
"newsletterId": "120363000000000000@newsletter",
"variables": { "nome": "Ana" },
"media": "https://cdn.acme.com/img.png",
"mediaType": "image",
"mediaFilename": "Nota Fiscal 123.pdf",
"caption": "Segue seu comprovante",
"buttons": [
{
"type": "reply",
"displayText": "Confirmar",
"id": "confirmar"
},
{
"type": "url",
"displayText": "Ver detalhes",
"url": "https://exemplo.com/pedido/123"
}
],
"list": {
"buttonText": "Ver áreas",
"sections": [
{
"title": "Atendimento",
"rows": [
{
"id": "clientes",
"title": "Clientes",
"description": "Consultar e cadastrar clientes"
}
]
}
]
},
"carousel": {
"cardTemplate": {
"hasBody": True,
"buttons": [{ "type": "QUICK_REPLY" }]
},
"cards": [
{
"media": {
"format": "IMAGE",
"url": "https://media.example.com/a.png"
},
"body": "Tênis — 30% off",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quero",
"payload": "SKU-1"
}
]
},
{
"media": {
"format": "IMAGE",
"url": "https://media.example.com/b.png"
},
"body": "Mochila — frete grátis",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quero",
"payload": "SKU-2"
}
]
}
]
},
"header": {
"type": "text",
"content": "Título do cabeçalho"
},
"footer": "Responda SAIR para não receber mais",
"deliverAt": "2026-06-21T09:00:00Z",
"deliverUntil": "2026-06-21T18:00:00Z",
"markRead": False,
"labels": ["pedido", "vip"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
templateId: 'boas_vindas',
text: 'Olá! Sua entrega chegou.',
destinationNumber: '5511988887777',
groupId: '123456789-987654321@g.us',
newsletterId: '120363000000000000@newsletter',
variables: {nome: 'Ana'},
media: 'https://cdn.acme.com/img.png',
mediaType: 'image',
mediaFilename: 'Nota Fiscal 123.pdf',
caption: 'Segue seu comprovante',
buttons: [
{type: 'reply', displayText: 'Confirmar', id: 'confirmar'},
{
type: 'url',
displayText: 'Ver detalhes',
url: 'https://exemplo.com/pedido/123'
}
],
list: {
buttonText: 'Ver áreas',
sections: [
{
title: 'Atendimento',
rows: [
{
id: 'clientes',
title: 'Clientes',
description: 'Consultar e cadastrar clientes'
}
]
}
]
},
carousel: {
cardTemplate: {hasBody: true, buttons: [{type: 'QUICK_REPLY'}]},
cards: [
{
media: {format: 'IMAGE', url: 'https://media.example.com/a.png'},
body: JSON.stringify('Tênis — 30% off'),
buttons: [{type: 'QUICK_REPLY', text: 'Quero', payload: 'SKU-1'}]
},
{
media: {format: 'IMAGE', url: 'https://media.example.com/b.png'},
body: JSON.stringify('Mochila — frete grátis'),
buttons: [{type: 'QUICK_REPLY', text: 'Quero', payload: 'SKU-2'}]
}
]
},
header: {type: 'text', content: 'Título do cabeçalho'},
footer: 'Responda SAIR para não receber mais',
deliverAt: '2026-06-21T09:00:00Z',
deliverUntil: '2026-06-21T18:00:00Z',
markRead: false,
labels: ['pedido', 'vip']
})
};
fetch('https://pilotstatus.com.br/v1/messages/send', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://pilotstatus.com.br/v1/messages/send",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'templateId' => 'boas_vindas',
'text' => 'Olá! Sua entrega chegou.',
'destinationNumber' => '5511988887777',
'groupId' => '123456789-987654321@g.us',
'newsletterId' => '120363000000000000@newsletter',
'variables' => [
'nome' => 'Ana'
],
'media' => 'https://cdn.acme.com/img.png',
'mediaType' => 'image',
'mediaFilename' => 'Nota Fiscal 123.pdf',
'caption' => 'Segue seu comprovante',
'buttons' => [
[
'type' => 'reply',
'displayText' => 'Confirmar',
'id' => 'confirmar'
],
[
'type' => 'url',
'displayText' => 'Ver detalhes',
'url' => 'https://exemplo.com/pedido/123'
]
],
'list' => [
'buttonText' => 'Ver áreas',
'sections' => [
[
'title' => 'Atendimento',
'rows' => [
[
'id' => 'clientes',
'title' => 'Clientes',
'description' => 'Consultar e cadastrar clientes'
]
]
]
]
],
'carousel' => [
'cardTemplate' => [
'hasBody' => true,
'buttons' => [
[
'type' => 'QUICK_REPLY'
]
]
],
'cards' => [
[
'media' => [
'format' => 'IMAGE',
'url' => 'https://media.example.com/a.png'
],
'body' => 'Tênis — 30% off',
'buttons' => [
[
'type' => 'QUICK_REPLY',
'text' => 'Quero',
'payload' => 'SKU-1'
]
]
],
[
'media' => [
'format' => 'IMAGE',
'url' => 'https://media.example.com/b.png'
],
'body' => 'Mochila — frete grátis',
'buttons' => [
[
'type' => 'QUICK_REPLY',
'text' => 'Quero',
'payload' => 'SKU-2'
]
]
]
]
],
'header' => [
'type' => 'text',
'content' => 'Título do cabeçalho'
],
'footer' => 'Responda SAIR para não receber mais',
'deliverAt' => '2026-06-21T09:00:00Z',
'deliverUntil' => '2026-06-21T18:00:00Z',
'markRead' => false,
'labels' => [
'pedido',
'vip'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://pilotstatus.com.br/v1/messages/send"
payload := strings.NewReader("{\n \"templateId\": \"boas_vindas\",\n \"text\": \"Olá! Sua entrega chegou.\",\n \"destinationNumber\": \"5511988887777\",\n \"groupId\": \"123456789-987654321@g.us\",\n \"newsletterId\": \"120363000000000000@newsletter\",\n \"variables\": {\n \"nome\": \"Ana\"\n },\n \"media\": \"https://cdn.acme.com/img.png\",\n \"mediaType\": \"image\",\n \"mediaFilename\": \"Nota Fiscal 123.pdf\",\n \"caption\": \"Segue seu comprovante\",\n \"buttons\": [\n {\n \"type\": \"reply\",\n \"displayText\": \"Confirmar\",\n \"id\": \"confirmar\"\n },\n {\n \"type\": \"url\",\n \"displayText\": \"Ver detalhes\",\n \"url\": \"https://exemplo.com/pedido/123\"\n }\n ],\n \"list\": {\n \"buttonText\": \"Ver áreas\",\n \"sections\": [\n {\n \"title\": \"Atendimento\",\n \"rows\": [\n {\n \"id\": \"clientes\",\n \"title\": \"Clientes\",\n \"description\": \"Consultar e cadastrar clientes\"\n }\n ]\n }\n ]\n },\n \"carousel\": {\n \"cardTemplate\": {\n \"hasBody\": true,\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\"\n }\n ]\n },\n \"cards\": [\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/a.png\"\n },\n \"body\": \"Tênis — 30% off\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-1\"\n }\n ]\n },\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/b.png\"\n },\n \"body\": \"Mochila — frete grátis\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-2\"\n }\n ]\n }\n ]\n },\n \"header\": {\n \"type\": \"text\",\n \"content\": \"Título do cabeçalho\"\n },\n \"footer\": \"Responda SAIR para não receber mais\",\n \"deliverAt\": \"2026-06-21T09:00:00Z\",\n \"deliverUntil\": \"2026-06-21T18:00:00Z\",\n \"markRead\": false,\n \"labels\": [\n \"pedido\",\n \"vip\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://pilotstatus.com.br/v1/messages/send")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"templateId\": \"boas_vindas\",\n \"text\": \"Olá! Sua entrega chegou.\",\n \"destinationNumber\": \"5511988887777\",\n \"groupId\": \"123456789-987654321@g.us\",\n \"newsletterId\": \"120363000000000000@newsletter\",\n \"variables\": {\n \"nome\": \"Ana\"\n },\n \"media\": \"https://cdn.acme.com/img.png\",\n \"mediaType\": \"image\",\n \"mediaFilename\": \"Nota Fiscal 123.pdf\",\n \"caption\": \"Segue seu comprovante\",\n \"buttons\": [\n {\n \"type\": \"reply\",\n \"displayText\": \"Confirmar\",\n \"id\": \"confirmar\"\n },\n {\n \"type\": \"url\",\n \"displayText\": \"Ver detalhes\",\n \"url\": \"https://exemplo.com/pedido/123\"\n }\n ],\n \"list\": {\n \"buttonText\": \"Ver áreas\",\n \"sections\": [\n {\n \"title\": \"Atendimento\",\n \"rows\": [\n {\n \"id\": \"clientes\",\n \"title\": \"Clientes\",\n \"description\": \"Consultar e cadastrar clientes\"\n }\n ]\n }\n ]\n },\n \"carousel\": {\n \"cardTemplate\": {\n \"hasBody\": true,\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\"\n }\n ]\n },\n \"cards\": [\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/a.png\"\n },\n \"body\": \"Tênis — 30% off\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-1\"\n }\n ]\n },\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/b.png\"\n },\n \"body\": \"Mochila — frete grátis\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-2\"\n }\n ]\n }\n ]\n },\n \"header\": {\n \"type\": \"text\",\n \"content\": \"Título do cabeçalho\"\n },\n \"footer\": \"Responda SAIR para não receber mais\",\n \"deliverAt\": \"2026-06-21T09:00:00Z\",\n \"deliverUntil\": \"2026-06-21T18:00:00Z\",\n \"markRead\": false,\n \"labels\": [\n \"pedido\",\n \"vip\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://pilotstatus.com.br/v1/messages/send")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"templateId\": \"boas_vindas\",\n \"text\": \"Olá! Sua entrega chegou.\",\n \"destinationNumber\": \"5511988887777\",\n \"groupId\": \"123456789-987654321@g.us\",\n \"newsletterId\": \"120363000000000000@newsletter\",\n \"variables\": {\n \"nome\": \"Ana\"\n },\n \"media\": \"https://cdn.acme.com/img.png\",\n \"mediaType\": \"image\",\n \"mediaFilename\": \"Nota Fiscal 123.pdf\",\n \"caption\": \"Segue seu comprovante\",\n \"buttons\": [\n {\n \"type\": \"reply\",\n \"displayText\": \"Confirmar\",\n \"id\": \"confirmar\"\n },\n {\n \"type\": \"url\",\n \"displayText\": \"Ver detalhes\",\n \"url\": \"https://exemplo.com/pedido/123\"\n }\n ],\n \"list\": {\n \"buttonText\": \"Ver áreas\",\n \"sections\": [\n {\n \"title\": \"Atendimento\",\n \"rows\": [\n {\n \"id\": \"clientes\",\n \"title\": \"Clientes\",\n \"description\": \"Consultar e cadastrar clientes\"\n }\n ]\n }\n ]\n },\n \"carousel\": {\n \"cardTemplate\": {\n \"hasBody\": true,\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\"\n }\n ]\n },\n \"cards\": [\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/a.png\"\n },\n \"body\": \"Tênis — 30% off\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-1\"\n }\n ]\n },\n {\n \"media\": {\n \"format\": \"IMAGE\",\n \"url\": \"https://media.example.com/b.png\"\n },\n \"body\": \"Mochila — frete grátis\",\n \"buttons\": [\n {\n \"type\": \"QUICK_REPLY\",\n \"text\": \"Quero\",\n \"payload\": \"SKU-2\"\n }\n ]\n }\n ]\n },\n \"header\": {\n \"type\": \"text\",\n \"content\": \"Título do cabeçalho\"\n },\n \"footer\": \"Responda SAIR para não receber mais\",\n \"deliverAt\": \"2026-06-21T09:00:00Z\",\n \"deliverUntil\": \"2026-06-21T18:00:00Z\",\n \"markRead\": false,\n \"labels\": [\n \"pedido\",\n \"vip\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "msg_01HZX...",
"correlationId": "corr_01HZX...",
"status": "QUEUED",
"createdAt": "2026-06-20T10:00:00.000Z",
"origin": "Suporte",
"sourceNumber": "5511999999999"
}