> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # 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.** ## OpenAPI ````yaml openapi.pt.json POST /v1/messages/send openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/messages/send: post: tags: - Messages summary: Enviar mensagem description: >- 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.** operationId: post_messages_send parameters: - name: Idempotency-Key in: header required: false description: >- **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. schema: type: string maxLength: 255 example: order-48213-+5511999999999 requestBody: required: false content: application/json: schema: type: object properties: templateId: type: string description: Id ou nome do template (exclusivo com text). example: boas_vindas text: type: string description: Texto livre (exclusivo com templateId). example: Olá! Sua entrega chegou. destinationNumber: type: string description: >- 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. example: '5511988887777' groupId: type: string description: JID de grupo. NOT_SUPPORTED_FOR_META. example: 123456789-987654321@g.us newsletterId: type: string description: JID de canal/newsletter. NOT_SUPPORTED_FOR_META. example: 120363000000000000@newsletter variables: type: object description: >- 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_`, 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. additionalProperties: type: string example: nome: Ana media: type: string description: >- 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. example: https://cdn.acme.com/img.png mediaType: type: string enum: - image - video - document - audio - voice - sticker description: >- 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. example: image mediaFilename: type: string description: >- 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). example: Nota Fiscal 123.pdf caption: type: string description: >- 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. example: Segue seu comprovante buttons: type: array description: >- 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**. Defina `id` (valor seu; **não** volta no toque — case as respostas por rótulo + `quotedMessageId`). - `url` — abre um link; defina `url` (https). Em texto livre, **no máximo um botão URL por mensagem**, e ele **pode** ser combinado com botões `reply`. - `call` — liga para um número; defina `phoneNumber` (E.164, ex.: `+5511999999999`). **Somente em templates** — em texto livre retorna 400 (`BUTTON_PHONE_NUMBER_TEMPLATE_ONLY`). - `copy` — copia um código; defina `copyCode`. **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_` 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ão em `copyCode`. items: type: object properties: type: type: string enum: - reply - url - call - copy description: Tipo do botão. displayText: type: string description: Rótulo visível do botão. id: type: string description: >- Só `reply` — identificador que você define (não é devolvido no toque). url: type: string description: Só `url` — link https a abrir. phoneNumber: type: string description: Só `call` — telefone a discar, E.164. copyCode: type: string description: Só `copy` — código que o usuário copia. required: - type - displayText example: - type: reply displayText: Confirmar id: confirmar - type: url displayText: Ver detalhes url: https://exemplo.com/pedido/123 list: type: object description: >- **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. properties: buttonText: type: string description: Rótulo do botão que abre a lista (1–20 caracteres). sections: type: array description: >- De 1 a 10 seções. Máx. **10 linhas no total** somando todas as seções. items: type: object properties: title: type: string description: Título opcional da seção. rows: type: array description: Linhas da seção (pelo menos 1). items: type: object properties: id: type: string description: >- Id opcional da linha, até 200 caracteres (gerado quando ausente). title: type: string description: Título da linha (1–24 caracteres). description: type: string description: >- Descrição opcional da linha (até 72 caracteres). required: - title required: - rows required: - buttonText - sections example: buttonText: Ver áreas sections: - title: Atendimento rows: - id: clientes title: Clientes description: Consultar e cadastrar clientes carousel: type: object description: >- **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. properties: cardTemplate: type: object description: >- **Esqueleto** compartilhado que todo card deve seguir — uma decisão `hasBody` e uma lista de botões (tipos e ordem). Cada card só preenche a própria mídia, corpo e valores dos botões. properties: hasBody: type: boolean description: >- Se todos os cards têm corpo. Tudo-ou-nada entre os cards. buttons: type: array description: >- Esqueleto de botões (até 2): o tipo e a ordem que todo card repete. items: type: object properties: type: type: string enum: - QUICK_REPLY - URL description: >- Tipo do botão. `QUICK_REPLY` funciona em todos; `URL` sai no avulso só em números não oficiais (na Meta um botão URL exige template de carrossel aprovado). required: - type required: - hasBody cards: type: array description: >- **2–10 cards**. Todo card deve seguir o `cardTemplate` na presença de corpo e no tipo/ordem dos botões. items: type: object properties: media: type: object description: >- Mídia de cabeçalho do card (**obrigatória**). A `url` deve ser uma URL `https` pública terminada em `.png`, `.jpg`, `.jpeg` ou `.webp`, sem query string — uma URL inalcançável é recusada antes do despacho. properties: url: type: string description: >- URL de mídia https pública, terminada em .png/.jpg/.jpeg/.webp, sem query string. format: type: string enum: - IMAGE - VIDEO description: >- Formato da mídia. `IMAGE` em todos os provedores; `VIDEO` só na Meta. Padrão `IMAGE`. required: - url body: type: string description: >- Texto do corpo do card, até **160** caracteres. Obrigatório quando `cardTemplate.hasBody` é true, proibido quando false. buttons: type: array description: >- Botões do card (até **2**), seguindo o `cardTemplate` no tipo e na ordem. items: type: object properties: type: type: string enum: - QUICK_REPLY - URL description: >- Deve ser igual ao tipo do botão do `cardTemplate` no mesmo índice. text: type: string description: Rótulo do botão (1–20 caracteres). payload: type: string description: >- Id de payload do QUICK_REPLY devolvido no toque (até 256 caracteres; cai no `text`). url: type: string description: >- Destino do botão URL (obrigatório num botão `URL`). required: - type - text required: - media required: - cardTemplate - cards example: 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: type: object description: >- **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. properties: flowId: type: string description: >- O id do Flow **na Meta** (`meta_flow_id`), não o id da linha no Pilot Status. Precisa ser desta conta, da mesma WABA do número remetente, e estar publicado (ou use `mode: "draft"`). example: '1973196646685107' cta: type: string description: Rótulo do botão que abre o Flow. Até 30 caracteres. example: Abrir formulário action: type: string enum: - navigate - data_exchange description: >- `navigate` (padrão) abre uma tela do Flow. `data_exchange` entrega o controle ao seu endpoint, que responde cada tela. example: navigate screen: type: string description: >- Id da tela de entrada. **Só em `navigate`** — a Meta recusa o envio quando ela vem junto de `data_exchange`, e o Pilot Status responde `FLOW_PAYLOAD_NOT_ALLOWED` antes disso. Omita num envio `navigate` e a primeira tela do Flow é resolvida por você. example: WELCOME_SCREEN data: type: object description: >- Dados iniciais da tela de entrada. **Só em `navigate`**, pelo mesmo motivo do `screen`: um Flow `data_exchange` recebe os dados iniciais pela requisição INIT que a Meta faz ao seu endpoint. example: nome: Ana mode: type: string enum: - published - draft description: >- `published` (padrão) envia a última versão publicada. `draft` envia o rascunho atual — serve para testar sem publicar, e expõe trabalho inacabado a um cliente real se usado sem cuidado. example: published required: - flowId - cta header: type: object description: >- 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`). example: type: text content: Título do cabeçalho properties: type: type: string enum: - text - image - video - document description: Tipo do cabeçalho. content: type: string description: >- Texto (type=text, ≤60 chars) ou URL pública de mídia (image/video/document). footer: type: string description: >- Rodapé da mensagem (máx. 60 caracteres). Requer `buttons` ou `list`. example: Responda SAIR para não receber mais deliverAt: type: string description: Agendar a entrega para um instante futuro. example: '2026-06-21T09:00:00Z' deliverUntil: type: string description: Janela máxima de entrega. example: '2026-06-21T18:00:00Z' markRead: type: boolean description: >- 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`. example: false labels: type: array description: Labels a aplicar à conversa de destino. items: type: string example: - pedido - vip responses: '202': headers: Idempotent-Replayed: description: >- `true` quando esta resposta reproduz uma requisição anterior aceita com a mesma `Idempotency-Key`; nada foi enviado de novo. schema: type: string enum: - 'true' description: Enviar template content: application/json: example: id: msg_01HZX... correlationId: corr_01HZX... status: QUEUED createdAt: '2026-06-20T10:00:00.000Z' origin: Suporte sourceNumber: '5511999999999' '400': description: >- Payload ou parâmetros inválidos (inclui `IDEMPOTENCY_KEY_INVALID`: `Idempotency-Key` com mais de 255 caracteres ou com caractere de controle) — ou `INVALID_BODY` quando o corpo não é um JSON válido content: application/json: schema: type: object properties: error: type: string code: type: string examples: validation: summary: Erro de validação value: error: Validation error invalidBody: summary: Corpo não é um JSON válido value: error: >- The request body is not valid JSON | O corpo da requisição não é um JSON válido code: INVALID_BODY '401': description: Header `x-api-key` / `x-api-key-id` ausente ou inválido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '403': description: Chave com escopo de tenant usada em endpoint com escopo de número content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Tenant-scoped keys cannot call number endpoints code: TENANT_SCOPE_NOT_ALLOWED '404': description: Template não encontrado ou sem versão aprovada content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Template not found '409': description: >- Conflito de idempotência: uma requisição com a mesma `Idempotency-Key` e o mesmo corpo ainda está em andamento (`IDEMPOTENCY_KEY_IN_USE`) — tente de novo com a mesma chave daqui a pouco; ou a chave já foi usada com um corpo diferente nas últimas 24 horas (`IDEMPOTENCY_KEY_REUSED`) — use uma chave nova content: application/json: schema: type: object properties: error: type: string code: type: string examples: inUse: summary: Chave ainda em uso value: error: >- A request with this Idempotency-Key is still being processed. Retry in a few seconds with the same key. | Uma requisição com esta Idempotency-Key ainda está em processamento. Tente de novo em alguns segundos com a mesma chave. code: IDEMPOTENCY_KEY_IN_USE reused: summary: Chave reutilizada com outro corpo value: error: >- This Idempotency-Key was already used with a different body in the last 24 hours. Use a new key for a new request. | Esta Idempotency-Key já foi usada com outro corpo nas últimas 24 horas. Use uma chave nova para uma nova requisição. code: IDEMPOTENCY_KEY_REUSED '422': description: >- Cobrança do tenant suspensa (`BILLING_SUSPENDED`); ou `mediaFilename` num template cujo cabeçalho aprovado não é DOCUMENT (`MEDIA_FILENAME_REQUIRES_DOCUMENT_HEADER`, com `details.templateName` e `details.headerType` — IMAGE, VIDEO, TEXT ou null) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Billing suspended code: BILLING_SUSPENDED '429': description: Limite de taxa excedido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Too many requests '503': description: >- Uma `Idempotency-Key` foi enviada e o armazenamento de idempotência está indisponível — nada foi enviado; é seguro tentar de novo com a mesma chave content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- The idempotency check is temporarily unavailable; nothing was sent. Retry with the same Idempotency-Key. | A verificação de idempotência está indisponível no momento; nada foi enviado. Tente de novo com a mesma Idempotency-Key. code: IDEMPOTENCY_UNAVAILABLE components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.