> ## Documentation Index > Fetch the complete documentation index at: https://docs.superlead.app/llms.txt > Use this file to discover all available pages before exploring further. # Enviar Mensagem > Envia uma mensagem WhatsApp para um **lead existente** da sua empresa. - O destinatário `to` aceita telefone E.164 ou BSUID. O envio **nunca cria leads** — para contatos novos, crie antes com `POST /v1/leads` (veja o fluxo recomendado em [Leads](/guias/leads)). - O campo `type` define qual objeto de conteúdo acompanha o body: `type: "text"` exige o objeto `text`, `type: "image"` exige `image`, 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 em `GET /v1/whatsapp/templates`. Detalhes em [Envio de mensagens](/guias/envio-de-mensagens). - Um `201` significa **aceita**, não entregue: a Meta pode falhar o envio de forma assíncrona segundos depois (janela de 24h, mídia inválida...). Acompanhe por `GET /v1/whatsapp/messages/{id}` ou pelo webhook `whatsapp.message.updated` — veja [Webhooks](/guias/webhooks). - Recomendado: envie o header `Idempotency-Key` para poder repetir a requisição com segurança em timeouts — veja [Idempotência](/guias/idempotencia). ## OpenAPI ````yaml /openapi.json post /v1/whatsapp/messages openapi: 3.1.0 info: title: Superlead API version: 1.0.0 description: > API oficial do Superlead para envio de mensagens WhatsApp aos **seus leads**. ## Autenticação Toda chamada exige `Authorization: Bearer sk_...` (crie a chave no painel Superlead em Integrações → API). A chave é escopada à sua empresa. ## Início rápido ```bash curl -X POST https://api.superlead.app/v1/whatsapp/messages \ -H "Authorization: Bearer sk_SUACHAVE" \ -H "Idempotency-Key: pedido-8734" \ -H "Content-Type: application/json" \ -d '{"to":"+5511999999999","type":"text","text":{"body":"Olá!"}}' ``` No n8n: nó **HTTP Request**, método POST, header Authorization como acima. ## Endereçamento O campo `to` aceita **telefone E.164** (`+5511999999999`) ou **BSUID** (`BR.13491208655302741918` — o `fromUserId` entregue nos webhooks quando o contato usa username do WhatsApp; usernames nunca endereçam). O destinatário precisa ser um lead existente da sua empresa — o envio nunca cria leads. Para outreach, crie antes com `POST /v1/leads`. Use `external_id` para reconciliar com o seu sistema. ## Janela de 24h (regra da Meta) Mensagens de formato livre (text, image, ...) só são entregues se o lead falou com você nas últimas 24 horas. Fora da janela, use `type: "template"` com um template aprovado (liste-os em `GET /v1/whatsapp/templates`). Fora da janela a Meta pode rejeitar o envio na hora (`outside_24h_window`) OU aceitá-lo (201, status `accepted`) e falhá-lo de forma assíncrona segundos depois — a mensagem passa ao status `failed`. Confirme em `GET /v1/whatsapp/messages/{id}` ou pelo webhook `whatsapp.message.updated`. ## Idempotência Envie o header `Idempotency-Key` (recomendado). Retries com a mesma chave e mesmo body retornam a resposta original sem reenviar. Validade: 24h. ## Rate limit 60 requisições/min por chave (headers `X-RateLimit-*`; `429` inclui `Retry-After`). ## Status da mensagem A resposta traz o status inicial. Acompanhe `sent → delivered → read` (ou `failed`) pelos webhooks do Superlead (evento `whatsapp.message.updated`) ou por `GET /v1/whatsapp/messages/{id}`. O evento de status identifica a mensagem pelo `wamid` retornado na resposta do envio. ## Erros Envelope estável `{ "error": { "code", "message", "request_id" } }`. Trate códigos desconhecidos pelo HTTP status (novos códigos são mudança aditiva). | HTTP | code | Meaning | |---|---|---| | 400 | `invalid_request` | The request body is invalid. Check the details field and the API reference. | | 401 | `invalid_api_key` | Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'. | | 404 | `lead_not_found` | No lead matches this recipient in your company. The API only messages existing leads. | | 404 | `message_not_found` | No message with this id exists in your company. | | 404 | `stage_not_found` | No funnel stage with this id exists in your company. List valid stages with GET /v1/funnel/stages. | | 409 | `idempotency_conflict` | This Idempotency-Key was already used with a different request body, or the original request is still in progress. | | 409 | `lead_already_exists` | A lead with this phone number already exists in your company. You can message it directly via POST /v1/whatsapp/messages. | | 422 | `funnel_not_configured` | Your company has no funnel stages configured. Set up the funnel in the Superlead panel first. | | 422 | `no_active_connection` | Your company has no active WhatsApp connection. Connect a number in the Superlead panel first. | | 422 | `connection_expired` | Your WhatsApp connection is no longer authorized. Reconnect it in the Superlead panel. | | 422 | `channel_capability_unsupported` | Your company's WhatsApp connection type does not support this operation. | | 422 | `outside_24h_window` | Free-form messages require the lead to have messaged you within the last 24 hours. Send an approved template instead. | | 422 | `template_not_found` | Template not found. Check the exact name and language with GET /v1/whatsapp/templates. | | 422 | `template_params_invalid` | Template parameters do not match the approved template. Check count, format and language. | | 422 | `recipient_unavailable` | The recipient cannot receive this message on WhatsApp right now. | | 422 | `media_unsupported` | WhatsApp could not fetch or process the media. Check that the link is public and direct, the format is supported and the file is within the size limit for its type. | | 422 | `message_blocked` | Meta blocked this message (spam or ecosystem limits). Reduce volume to this recipient and review quality. | | 429 | `rate_limit_exceeded` | Rate limit for this API key exceeded. Retry after the time in the Retry-After header. | | 429 | `channel_rate_limit` | WhatsApp is throttling your number. Slow down and retry later. | | 502 | `channel_error` | The messaging provider returned an unexpected error. Our team was notified; retry later. | | 500 | `internal_error` | Internal error. Our team was notified; retry later. | ## Versionamento Caminho `/v1/`. Mudanças incompatíveis só em `/v2/`. Campos novos opcionais podem aparecer a qualquer momento — ignore campos desconhecidos. servers: - url: https://api.superlead.app description: Produção security: [] paths: /v1/whatsapp/messages: post: summary: Enviar Mensagem description: >- Envia uma mensagem WhatsApp para um **lead existente** da sua empresa. - O destinatário `to` aceita telefone E.164 ou BSUID. O envio **nunca cria leads** — para contatos novos, crie antes com `POST /v1/leads` (veja o fluxo recomendado em [Leads](/guias/leads)). - O campo `type` define qual objeto de conteúdo acompanha o body: `type: "text"` exige o objeto `text`, `type: "image"` exige `image`, 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 em `GET /v1/whatsapp/templates`. Detalhes em [Envio de mensagens](/guias/envio-de-mensagens). - Um `201` significa **aceita**, não entregue: a Meta pode falhar o envio de forma assíncrona segundos depois (janela de 24h, mídia inválida...). Acompanhe por `GET /v1/whatsapp/messages/{id}` ou pelo webhook `whatsapp.message.updated` — veja [Webhooks](/guias/webhooks). - Recomendado: envie o header `Idempotency-Key` para poder repetir a requisição com segurança em timeouts — veja [Idempotência](/guias/idempotencia). operationId: sendWhatsAppMessage parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- 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`. example: pedido-8734 requestBody: required: true content: application/json: schema: type: object required: - to - type additionalProperties: false properties: to: type: string description: >- 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' external_id: type: string minLength: 1 maxLength: 255 description: >- Identificador do **seu** sistema (id do pedido, ticket...), para reconciliação. Volta na resposta, na consulta de status e nos webhooks. example: pedido-8734 type: type: string enum: - text - template - image - video - audio - document - sticker - location - contacts - interactive - reaction description: >- Tipo da mensagem. Define qual objeto de conteúdo é obrigatório no body (ex.: `text` exige o objeto `text`). example: text context: type: object required: - message_id description: Responde (cita) uma mensagem anterior da conversa. properties: message_id: type: string minLength: 1 description: >- Id da mensagem citada: o `id` (`msg_...`) retornado no envio ou o `wamid` recebido nos webhooks. example: msg_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f text: type: object required: - body description: 'Conteúdo quando `type: "text"`. Requer janela de 24h aberta.' properties: body: type: string minLength: 1 maxLength: 4096 description: >- Texto da mensagem, até 4096 caracteres. Aceita a formatação do WhatsApp: `*negrito*`, `_itálico_`, `~tachado~`. example: Olá! Seu orçamento está pronto 🎉 preview_url: type: boolean default: false description: >- Gera pré-visualização do primeiro link contido no `body`. template: type: object required: - name - language description: >- 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`). properties: name: type: string minLength: 1 description: Nome exato do template aprovado. example: confirmacao_consulta language: type: object required: - code description: Idioma do template. properties: code: type: string minLength: 2 description: Código do idioma, como aprovado na Meta. example: pt_BR components: type: array description: >- Parâmetros do template (variáveis do body, mídia do header, botões), no formato de `components` da Cloud API da Meta. Obrigatório quando o template tem variáveis — quantidade e formato precisam bater com o template aprovado. items: type: object additionalProperties: {} example: - type: body parameters: - type: text text: João - type: text text: quinta, 10h image: type: object required: - link description: >- Conteúdo quando `type: "image"`. Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio. properties: link: type: string format: uri description: >- URL **pública e direta** do arquivo — sem autenticação, token ou página intermediária; o servidor deve responder com o Content-Type real. Limite do WhatsApp: 5 MB. Formatos: JPEG, PNG (WebP não — use `sticker`). example: https://seusite.com/arquivos/orcamento.jpg caption: type: string maxLength: 1024 description: Legenda exibida junto à mídia (até 1024 caracteres). example: Seu orçamento video: type: object required: - link description: >- Conteúdo quando `type: "video"`. Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio. properties: link: type: string format: uri description: >- URL **pública e direta** do arquivo — sem autenticação, token ou página intermediária; o servidor deve responder com o Content-Type real. Limite do WhatsApp: 16 MB. Formatos: MP4/3GPP (vídeo H.264, áudio AAC). example: https://seusite.com/videos/demo.mp4 caption: type: string maxLength: 1024 description: Legenda exibida junto à mídia (até 1024 caracteres). example: Seu orçamento audio: type: object required: - link description: >- Conteúdo quando `type: "audio"`. Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio. properties: link: type: string format: uri description: >- URL **pública e direta** do arquivo — sem autenticação, token ou página intermediária; o servidor deve responder com o Content-Type real. Limite do WhatsApp: 16 MB. Formatos: AAC, MP3, M4A, AMR, OGG (opus). example: https://seusite.com/audios/boas-vindas.mp3 document: type: object required: - link description: >- Conteúdo quando `type: "document"`. Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio. properties: link: type: string format: uri description: >- URL **pública e direta** do arquivo — sem autenticação, token ou página intermediária; o servidor deve responder com o Content-Type real. Limite do WhatsApp: 100 MB. Formatos: PDF, Office, texto e afins. example: https://seusite.com/arquivos/contrato.pdf caption: type: string maxLength: 1024 description: Legenda exibida junto à mídia (até 1024 caracteres). example: Seu orçamento filename: type: string maxLength: 240 description: >- Nome do arquivo exibido no WhatsApp, com extensão. Relevante principalmente para `document`. example: orcamento.pdf sticker: type: object required: - link description: >- Conteúdo quando `type: "sticker"`. Mídia é enviada por link: você hospeda o arquivo e o WhatsApp baixa da URL no momento do envio. properties: link: type: string format: uri description: >- URL **pública e direta** do arquivo — sem autenticação, token ou página intermediária; o servidor deve responder com o Content-Type real. Limite do WhatsApp: 100 KB (500 KB animado). Formatos: WebP. example: https://seusite.com/stickers/logo.webp location: type: object required: - latitude - longitude description: >- Conteúdo quando `type: "location"` — envia um pin de localização. properties: latitude: type: number description: Latitude em graus decimais. example: -23.5613 longitude: type: number description: Longitude em graus decimais. example: -46.6565 name: type: string description: Nome do local exibido no pin. example: Escritório Superlead address: type: string description: Endereço exibido abaixo do nome. example: Av. Paulista, 1000 - São Paulo, SP contacts: type: array minItems: 1 description: >- Conteúdo quando `type: "contacts"` — cartões de contato no formato `contacts` da Cloud API da Meta (`name`, `phones`, `emails`...). items: type: object additionalProperties: {} example: - name: formatted_name: Maria Souza first_name: Maria phones: - phone: '+5511988887777' type: CELL interactive: type: object required: - type description: >- Conteúdo quando `type: "interactive"` — botões e listas, no formato `interactive` da Cloud API da Meta. properties: type: type: string minLength: 1 description: >- Formato interativo da Cloud API (ex.: `button`, `list`). Os demais campos do objeto seguem o formato da Meta para o tipo escolhido. example: button reaction: type: object required: - message_id - emoji description: >- Conteúdo quando `type: "reaction"` — reage a uma mensagem existente da conversa. properties: message_id: type: string minLength: 1 description: >- Id da mensagem que recebe a reação: `id` (`msg_...`) ou `wamid`. example: msg_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f emoji: type: string minLength: 1 description: Emoji da reação. example: 👍 examples: texto: summary: Texto simples value: to: '+5511999999999' type: text text: body: Olá! Seu orçamento está pronto 🎉 template: summary: Template com variáveis (fora da janela de 24h) value: to: '+5511999999999' type: template template: name: confirmacao_consulta language: code: pt_BR components: - type: body parameters: - type: text text: João - type: text text: quinta, 10h imagem: summary: Imagem com legenda value: to: '+5511999999999' type: image image: link: https://seusite.com/arquivos/orcamento.jpg caption: Seu orçamento documento: summary: Documento PDF value: to: '+5511999999999' type: document document: link: https://seusite.com/arquivos/contrato.pdf filename: contrato.pdf resposta: summary: Resposta citando outra mensagem value: to: '+5511999999999' type: text context: message_id: msg_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f text: body: 'Sobre a sua pergunta: sim!' com_external_id: summary: Com external_id e reconciliação value: to: '+5511999999999' external_id: pedido-8734 type: text text: body: Pedido confirmado! Chega em 3 dias úteis. responses: '201': description: >- Mensagem **aceita** pelo canal. Aceita ≠ entregue: acompanhe o status por `GET /v1/whatsapp/messages/{id}` ou pelo webhook `whatsapp.message.updated`. content: application/json: schema: type: object properties: id: type: string description: >- Id da mensagem no Superlead (`msg_...`). Use em `GET /v1/whatsapp/messages/{id}`. example: msg_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f wamid: type: - string - 'null' description: >- Id da mensagem na Meta. Os webhooks de status (`whatsapp.message.updated`) referenciam este valor. example: >- wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjVGQjA3RDIzRkU3QzYxRjM5NQA= external_id: type: - string - 'null' description: O `external_id` enviado no body, se houver. example: pedido-8734 to: type: - string - 'null' description: Destinatário, como resolvido pela API. example: '+5511999999999' type: type: string enum: - text - template - image - video - audio - document - sticker - location - contacts - interactive - reaction description: Tipo da mensagem enviada. status: type: string enum: - accepted - held_for_quality_assessment - paused - sent - delivered - read - failed description: >- 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`. created_at: type: string format: date-time description: Data de criação da mensagem (ISO 8601, UTC). example: '2026-07-08T12:34:56.000Z' example: 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' '400': description: >- `invalid_request` — o body ou os parâmetros da requisição são inválidos. O campo `details` aponta cada campo com problema. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: The request body is invalid. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 details: - path: to message: Required '401': description: >- `invalid_api_key` — chave de API ausente, malformada ou revogada. Envie `Authorization: Bearer sk_...`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: >- Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 '404': description: >- `lead_not_found` — o destinatário não é um lead da sua empresa. O envio nunca cria leads: registre-o antes com `POST /v1/leads`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: lead_not_found message: >- No lead matches this recipient in your company. The API only messages existing leads. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 '409': description: >- `idempotency_conflict` — a `Idempotency-Key` já foi usada com um body diferente, ou a requisição original ainda está em andamento. content: application/json: schema: $ref: '#/components/schemas/Error' example: 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 '422': description: >- Regra de negócio impediu o envio: `outside_24h_window`, `template_not_found`, `template_params_invalid`, `media_unsupported`, `no_active_connection`, `connection_expired`, `channel_capability_unsupported`, `recipient_unavailable` ou `message_blocked`. Veja o [catálogo de erros](/guias/erros). content: application/json: schema: $ref: '#/components/schemas/Error' example: 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 '429': description: >- `rate_limit_exceeded` — limite de 60 requisições/min da chave excedido (aguarde o `Retry-After`). `channel_rate_limit` — o WhatsApp está limitando o seu número; reduza o ritmo. content: application/json: schema: $ref: '#/components/schemas/Error' example: 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 security: - apiKey: [] components: schemas: Error: type: object properties: error: type: object properties: code: type: string description: >- Código estável do erro (ex.: `lead_not_found`). Novos códigos podem surgir a qualquer momento — trate códigos desconhecidos pelo HTTP status. example: lead_not_found message: type: string description: >- Descrição legível do erro, em inglês. O texto pode mudar — não faça parsing dele; use `code`. request_id: type: string description: >- Id único desta requisição. Inclua ao reportar um problema ao suporte. example: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 upstream_code: type: number description: >- Código numérico original da Meta, presente quando o erro veio do WhatsApp (ex.: `131047` para fora da janela de 24h). example: 131047 details: type: array description: >- Erros de validação campo a campo. Presente em respostas `400 invalid_request`. items: type: object properties: path: type: string description: 'Caminho do campo inválido no body (ex.: `text.body`).' message: type: string description: O que está errado com o campo. securitySchemes: apiKey: type: http scheme: bearer description: >- 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](/guias/autenticacao). ````