Enviar Mensagem
Envia uma mensagem WhatsApp para um lead existente da sua empresa.
- O destinatário
toaceita telefone E.164 ou BSUID. O envio nunca cria leads — para contatos novos, crie antes comPOST /v1/leads(veja o fluxo recomendado em Leads). - O campo
typedefine qual objeto de conteúdo acompanha o body:type: "text"exige o objetotext,type: "image"exigeimage, e assim por diante. - Janela de 24h: mensagens de formato livre (texto, mídia) só são entregues se o lead falou com você nas últimas 24 horas. Fora da janela, apenas
type: "template"com template aprovado — liste-os emGET /v1/whatsapp/templates. Detalhes em Envio de mensagens. - Um
201significa aceita, não entregue: a Meta pode falhar o envio de forma assíncrona segundos depois (janela de 24h, mídia inválida…). Acompanhe porGET /v1/whatsapp/messages/{id}ou pelo webhookwhatsapp.message.updated— veja Webhooks. - Recomendado: envie o header
Idempotency-Keypara poder repetir a requisição com segurança em timeouts — veja Idempotência.
Authorizations
Chave de API da sua empresa (sk_...). Crie no painel Superlead em Integrações → API e envie em toda chamada como Authorization: Bearer sk_.... Veja Autenticação.
Headers
Chave única que torna o envio idempotente por 24h: retries com a mesma chave e o mesmo body retornam a resposta original sem reenviar a mensagem. A mesma chave com body diferente retorna 409 idempotency_conflict.
255Body
Destinatário: telefone E.164 (+5511999999999) ou BSUID (BR.13491208655302741918 — o fromUserId dos webhooks, para leads que chegaram por username do WhatsApp). Precisa ser um lead existente da sua empresa. Números brasileiros: a variação do nono dígito é resolvida automaticamente.
"+5511999999999"
Tipo da mensagem. Define qual objeto de conteúdo é obrigatório no body (ex.: text exige o objeto text).
text, template, image, video, audio, document, sticker, location, contacts, interactive, reaction "text"
Identificador do seu sistema (id do pedido, ticket...), para reconciliação. Volta na resposta, na consulta de status e nos webhooks.
1 - 255"pedido-8734"
Responde (cita) uma mensagem anterior da conversa.
Conteúdo quando type: "text". Requer janela de 24h aberta.
Conteúdo quando type: "template" — o único tipo entregue fora da janela de 24h. Nome e idioma precisam bater exatamente com o template aprovado na Meta (liste-os em GET /v1/whatsapp/templates).
Conteúdo quando type: "image". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.
Conteúdo quando type: "video". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.
Conteúdo quando type: "audio". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.
Conteúdo quando type: "document". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.
Conteúdo quando type: "sticker". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.
Conteúdo quando type: "location" — envia um pin de localização.
Conteúdo quando type: "contacts" — cartões de contato no formato contacts da Cloud API da Meta (name, phones, emails...).
1[
{
"name": {
"formatted_name": "Maria Souza",
"first_name": "Maria"
},
"phones": [
{ "phone": "+5511988887777", "type": "CELL" }
]
}
]Conteúdo quando type: "interactive" — botões e listas, no formato interactive da Cloud API da Meta.
Conteúdo quando type: "reaction" — reage a uma mensagem existente da conversa.
Response
Mensagem aceita pelo canal. Aceita ≠ entregue: acompanhe o status por GET /v1/whatsapp/messages/{id} ou pelo webhook whatsapp.message.updated.
Id da mensagem no Superlead (msg_...). Use em GET /v1/whatsapp/messages/{id}.
"msg_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
Id da mensagem na Meta. Os webhooks de status (whatsapp.message.updated) referenciam este valor.
"wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjVGQjA3RDIzRkU3QzYxRjM5NQA="
O external_id enviado no body, se houver.
"pedido-8734"
Destinatário, como resolvido pela API.
"+5511999999999"
Tipo da mensagem enviada.
text, template, image, video, audio, document, sticker, location, contacts, interactive, reaction Status atual da mensagem:
accepted— aceita pelo canal; entrega ainda não confirmada.held_for_quality_assessment— retida pela Meta para avaliação de qualidade.paused— envio pausado pela Meta.sent— entregue ao servidor do WhatsApp.delivered— entregue ao aparelho do lead.read— lida pelo lead.failed— falhou; o motivo fica emerror.
accepted, held_for_quality_assessment, paused, sent, delivered, read, failed Data de criação da mensagem (ISO 8601, UTC).
"2026-07-08T12:34:56.000Z"