> ## 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. # Envia uma mensagem WhatsApp para um lead ## OpenAPI ````yaml /openapi.json post /v1/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 sl_live_...` (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/messages \ -H "Authorization: Bearer sl_live_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/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/messages/{id}` ou pelo webhook `whatsapp.message.status`. ## 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.status`) ou por `GET /v1/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 sl_live_...'. | | 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. | | 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/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/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 security: [] paths: /v1/messages: post: summary: Envia uma mensagem WhatsApp para um lead parameters: - schema: type: string required: false name: Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: to: type: string external_id: type: string minLength: 1 maxLength: 255 type: type: string enum: - text - template - image - video - audio - document - sticker - location - contacts - interactive - reaction context: type: object properties: message_id: type: string minLength: 1 required: - message_id text: type: object properties: body: type: string minLength: 1 maxLength: 4096 preview_url: type: boolean required: - body template: type: object properties: name: type: string minLength: 1 language: type: object properties: code: type: string minLength: 2 required: - code components: type: array items: type: object additionalProperties: {} required: - name - language image: type: object properties: link: type: string format: uri caption: type: string maxLength: 1024 filename: type: string maxLength: 240 required: - link video: type: object properties: link: type: string format: uri caption: type: string maxLength: 1024 filename: type: string maxLength: 240 required: - link audio: type: object properties: link: type: string format: uri caption: type: string maxLength: 1024 filename: type: string maxLength: 240 required: - link document: type: object properties: link: type: string format: uri caption: type: string maxLength: 1024 filename: type: string maxLength: 240 required: - link sticker: type: object properties: link: type: string format: uri caption: type: string maxLength: 1024 filename: type: string maxLength: 240 required: - link location: type: object properties: latitude: type: number longitude: type: number name: type: string address: type: string required: - latitude - longitude contacts: type: array items: type: object additionalProperties: {} minItems: 1 interactive: type: object properties: type: type: string minLength: 1 required: - type reaction: type: object properties: message_id: type: string minLength: 1 emoji: type: string minLength: 1 required: - message_id - emoji required: - to - type additionalProperties: false responses: '201': description: Mensagem aceita pelo canal content: application/json: schema: type: object properties: id: type: string wamid: type: - string - 'null' external_id: type: - string - 'null' to: type: - string - 'null' type: type: string enum: - text - template - image - video - audio - document - sticker - location - contacts - interactive - reaction status: type: string enum: - accepted - held_for_quality_assessment - paused - sent - delivered - read - failed created_at: type: string required: - id - wamid - external_id - to - type - status - created_at '400': description: invalid_request content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string request_id: type: string upstream_code: type: number details: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message - request_id required: - error '401': description: invalid_api_key content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string request_id: type: string upstream_code: type: number details: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message - request_id required: - error '404': description: lead_not_found | message_not_found content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string request_id: type: string upstream_code: type: number details: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message - request_id required: - error '409': description: idempotency_conflict content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string request_id: type: string upstream_code: type: number details: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message - request_id required: - error '422': description: Regras de negócio (ver catálogo) content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string request_id: type: string upstream_code: type: number details: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message - request_id required: - error '429': description: rate_limit_exceeded | channel_rate_limit content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string request_id: type: string upstream_code: type: number details: type: array items: type: object properties: path: type: string message: type: string required: - path - message required: - code - message - request_id required: - error security: - apiKey: [] components: securitySchemes: apiKey: type: http scheme: bearer description: Chave de API (sl_live_...) ````