> ## 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. **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. **Requer uma chave com escopo de número.** operationId: post_messages_send 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: string description: Variáveis do template (padrão {}). example: '{ "nome": "Ana" }' media: type: string description: >- URL pública http(s) OU data URI base64 (ex.: data:audio/ogg;base64,AAAA…). Base64 funciona na Meta Cloud API e na Evolution v2; na Evolution GO use uma URL pública http(s) (GO não aceita base64). Usado no modo template ou no modo mídia direta (media + mediaType, sem templateId e sem text). example: https://cdn.acme.com/img.png mediaType: type: string 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); botões/header/footer/variáveis não permitidos. "audio" é entregue como nota de voz (PTT) na Meta Cloud API, Evolution v2 e Evolution GO; na Evolution v2 e GO um indicador de presença "gravando áudio" é mostrado ao destinatário antes da nota de voz (a Meta não tem API de presença de saída). example: image buttons: type: string description: Botões (QUICK_REPLY/URL/PHONE_NUMBER/COPY_CODE). header: type: string description: Header para texto livre (com botões). footer: type: string description: Rodapé para texto livre (com botões). 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' labels: type: string description: Labels a aplicar à conversa de destino. example: '["pedido", "vip"]' example: templateId: boas_vindas destinationNumber: '5511988887777' variables: nome: Ana responses: '202': 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 content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Validation error '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 '422': description: Cobrança do tenant suspensa 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 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) ````