Skip to main content
POST
/
v1
/
whatsapp
/
messages
curl --request POST \
  --url https://api.superlead.app/v1/whatsapp/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "+5511999999999",
  "type": "text"
}
'
{
  "id": "msg_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "wamid": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjVGQjA3RDIzRkU3QzYxRjM5NQA=",
  "external_id": "pedido-8734",
  "to": "+5511999999999",
  "type": "text",
  "status": "accepted",
  "created_at": "2026-07-08T12:34:56.000Z"
}
{
"error": {
"code": "invalid_request",
"message": "The request body is invalid.",
"request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1",
"details": [
{
"path": "to",
"message": "Required"
}
]
}
}
{
"error": {
"code": "invalid_api_key",
"message": "Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'.",
"request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
}
}
{
"error": {
"code": "lead_not_found",
"message": "No lead matches this recipient in your company. The API only messages existing leads.",
"request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
}
}
{
"error": {
"code": "idempotency_conflict",
"message": "This Idempotency-Key was already used with a different request body, or the original request is still in progress.",
"request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
}
}
{
"error": {
"code": "outside_24h_window",
"message": "Free-form messages require the lead to have messaged you within the last 24 hours. Send an approved template instead.",
"request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1",
"upstream_code": 131047
}
}
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit for this API key exceeded. Retry after the time in the Retry-After header.",
"request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
}
}

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

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.

Maximum string length: 255

Body

application/json
to
string
required

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.

Example:

"+5511999999999"

type
enum<string>
required

Tipo da mensagem. Define qual objeto de conteúdo é obrigatório no body (ex.: text exige o objeto text).

Available options:
text,
template,
image,
video,
audio,
document,
sticker,
location,
contacts,
interactive,
reaction
Example:

"text"

external_id
string

Identificador do seu sistema (id do pedido, ticket...), para reconciliação. Volta na resposta, na consulta de status e nos webhooks.

Required string length: 1 - 255
Example:

"pedido-8734"

context
object

Responde (cita) uma mensagem anterior da conversa.

text
object

Conteúdo quando type: "text". Requer janela de 24h aberta.

template
object

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).

image
object

Conteúdo quando type: "image". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.

video
object

Conteúdo quando type: "video". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.

audio
object

Conteúdo quando type: "audio". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.

document
object

Conteúdo quando type: "document". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.

sticker
object

Conteúdo quando type: "sticker". Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio.

location
object

Conteúdo quando type: "location" — envia um pin de localização.

contacts
object[]

Conteúdo quando type: "contacts" — cartões de contato no formato contacts da Cloud API da Meta (name, phones, emails...).

Minimum array length: 1
Example:
[
{
"name": {
"formatted_name": "Maria Souza",
"first_name": "Maria"
},
"phones": [
{ "phone": "+5511988887777", "type": "CELL" }
]
}
]
interactive
object

Conteúdo quando type: "interactive" — botões e listas, no formato interactive da Cloud API da Meta.

reaction
object

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
string

Id da mensagem no Superlead (msg_...). Use em GET /v1/whatsapp/messages/{id}.

Example:

"msg_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f"

wamid
string | null

Id da mensagem na Meta. Os webhooks de status (whatsapp.message.updated) referenciam este valor.

Example:

"wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjVGQjA3RDIzRkU3QzYxRjM5NQA="

external_id
string | null

O external_id enviado no body, se houver.

Example:

"pedido-8734"

to
string | null

Destinatário, como resolvido pela API.

Example:

"+5511999999999"

type
enum<string>

Tipo da mensagem enviada.

Available options:
text,
template,
image,
video,
audio,
document,
sticker,
location,
contacts,
interactive,
reaction
status
enum<string>

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 em error.
Available options:
accepted,
held_for_quality_assessment,
paused,
sent,
delivered,
read,
failed
created_at
string<date-time>

Data de criação da mensagem (ISO 8601, UTC).

Example:

"2026-07-08T12:34:56.000Z"