> ## Documentation Index > Fetch the complete documentation index at: https://docs.routa.chat/llms.txt > Use this file to discover all available pages before exploring further. # Enviar mensagem > Envia uma mensagem de texto ou de template por um canal. A resposta é `202 Accepted`: a mensagem foi gravada de forma durável, mas **ainda não foi entregue**. Acompanhe `sent`, `delivered`, `read` e `failed` por [webhooks](/webhooks/overview) ou por `GET /v1/messages/{id}`. Informe **exatamente um** entre `text` e `template`. Envie o header `Idempotency-Key` para repetir a requisição com segurança. Veja [Idempotência](/reliability/idempotency). A validação do canal, do destinatário e do template acontece no aceite e retorna `422` imediatamente. ## OpenAPI ````yaml openapi.json POST /v1/messages openapi: 3.0.3 info: title: API da Routa description: >- API REST para enviar e receber mensagens de WhatsApp, acompanhar a entrega e receber eventos normalizados por webhook. version: '1' servers: - url: https://api.routa.chat description: Produção security: - bearerAuth: [] tags: - name: Mensagens description: Envie, consulte e liste mensagens. - name: Eventos description: Consulte o log de eventos normalizados. - name: Webhooks description: Gerencie endpoints de webhook, segredos e entregas. - name: Templates description: Submeta e consulte templates de WhatsApp. - name: Mídia description: Envie e obtenha arquivos de mídia. - name: Uso description: Consulte o uso medido do projeto. - name: Identidade description: Identifique a chave de API em uso. paths: /v1/messages: post: tags: - Mensagens summary: Enviar mensagem description: >- Envia uma mensagem de texto ou de template por um canal. A resposta é `202 Accepted`: a mensagem foi gravada de forma durável, mas **ainda não foi entregue**. Acompanhe `sent`, `delivered`, `read` e `failed` por [webhooks](/webhooks/overview) ou por `GET /v1/messages/{id}`. Informe **exatamente um** entre `text` e `template`. Envie o header `Idempotency-Key` para repetir a requisição com segurança. Veja [Idempotência](/reliability/idempotency). A validação do canal, do destinatário e do template acontece no aceite e retorna `422` imediatamente. operationId: sendMessage parameters: - name: Idempotency-Key in: header required: false description: >- Chave única por mensagem lógica (um UUID v4, por exemplo). Repetir a requisição com a mesma chave e o mesmo corpo devolve a resposta original, com o header `Idempotent-Replay: true`. Uma chave reutilizada com outro corpo retorna `409 idempotency_key_reuse`. O registro é mantido por 24 horas. schema: type: string example: 6f0a9d9e-3c1f-4e56-9a64-2b7f6a5c1d10 requestBody: required: true content: application/json: schema: type: object required: - channel - to properties: channel: description: Identificador do canal pelo qual enviar (`chan_...`). type: string example: chan_01J8ZK9M3Q7XABCDEFGHJKMNPQ to: pattern: ^\+?[1-9]\d{1,14}$ description: >- Destinatário em formato E.164, por exemplo `+5581999999999`. O `+` inicial é opcional. O formato é verificado aqui; se o número não pode existir no país indicado, a API retorna `invalid_recipient`. type: string example: '+5581999999999' text: description: >- Corpo da mensagem de texto. Não pode ser usado junto com `template`. type: string example: Olá! Seu pedido foi confirmado. template: type: object required: - id properties: id: description: >- Identificador do template (`tmpl_...`). O template precisa estar `approved`. type: string example: tmpl_01J8ZK9M3Q7XABCDEFGHJKMNPQ body_parameters: description: >- Valores posicionais para os placeholders `{{1}}`, `{{2}}`, … do corpo do template, na ordem. A quantidade precisa bater com a de variáveis do template. type: array items: type: string description: >- Template aprovado a enviar. Não pode ser usado junto com `text`. metadata: maxProperties: 20 description: >- Até 20 pares chave-valor de texto, de propriedade do cliente, com 1 KB no total. É devolvido na consulta e nos eventos. type: object additionalProperties: type: string example: channel: chan_01J8ZK9M3Q7XABCDEFGHJKMNPQ to: '+5581999999999' text: Olá! Seu pedido foi confirmado. metadata: order_id: '1234' responses: '202': description: Aceito. O processamento é assíncrono content: application/json: schema: $ref: '#/components/schemas/Message' '401': description: >- Chave de API ausente, inválida, revogada ou expirada (`api_key_invalid`) content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: >- Franquia ou limite do plano esgotado (`message_quota_exceeded`, `subscription_required`, `payment_failed`) content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: A chave não tem o escopo necessário (`insufficient_scope`) content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: O recurso não existe ou pertence a outro projeto content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflito de idempotência ou de estado content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Requisição inválida content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Limite de taxa excedido. Veja o header `Retry-After` content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: - messages:write components: schemas: Message: type: object properties: id: type: string description: Identificador da mensagem. example: msg_01J8ZK9M3Q7XABCDEFGHJKMNPQ channel: type: string description: Identificador do canal usado. example: chan_01J8ZK9M3Q7XABCDEFGHJKMNPQ direction: type: string enum: - outbound - inbound description: >- Direção da mensagem: `outbound` (enviada por você) ou `inbound` (recebida). from: type: string description: Endereço de origem, em E.164. example: '+5581988888888' to: type: string description: Endereço de destino, em E.164. example: '+5581999999999' content: oneOf: - type: object required: - type - body properties: type: type: string enum: - text body: type: string - type: object required: - type - media_id properties: type: type: string enum: - image media_id: type: string caption: type: string - type: object required: - type - media_id properties: type: type: string enum: - document media_id: type: string filename: type: string caption: type: string - type: object required: - type - media_id properties: type: type: string enum: - audio media_id: type: string - type: object required: - type - media_id properties: type: type: string enum: - video media_id: type: string caption: type: string - type: object required: - type - media_id properties: type: type: string enum: - sticker media_id: type: string - type: object required: - type - latitude - longitude properties: type: type: string enum: - location latitude: type: number longitude: type: number name: type: string address: type: string - type: object required: - type - target_message_id - emoji properties: type: type: string enum: - reaction target_message_id: type: string emoji: type: string - type: object required: - type - template_id - body_parameters properties: type: type: string enum: - template template_id: type: string body_parameters: type: array items: type: string - type: object required: - type properties: type: type: string enum: - unsupported description: Conteúdo da mensagem. O campo `type` indica o formato. status: type: string enum: - accepted - sent - delivered - read - failed description: Estado atual no ciclo de vida. O status nunca retrocede. metadata: type: object additionalProperties: type: string description: Até 20 pares chave-valor de texto, de propriedade do cliente. accepted_at: format: date-time type: string description: Quando a Routa aceitou a mensagem. example: '2026-09-04T13:22:41.031Z' sent_at: format: date-time type: string nullable: true description: Quando o provedor aceitou a mensagem. `null` se ainda não ocorreu. example: '2026-09-04T13:22:41.031Z' delivered_at: format: date-time type: string nullable: true description: Quando a entrega foi confirmada. `null` se ainda não ocorreu. example: '2026-09-04T13:22:41.031Z' read_at: format: date-time type: string nullable: true description: Quando o destinatário leu. `null` se ainda não ocorreu. example: null failed_at: format: date-time type: string nullable: true description: Quando a mensagem falhou. `null` se não falhou. example: null required: - id - channel - direction - from - to - content - status - metadata - accepted_at - sent_at - delivered_at - read_at - failed_at Error: type: object properties: error: type: object required: - type - code - message - request_id properties: type: type: string description: >- Categoria do erro: `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `conflict_error`, `rate_limit_error`, `billing_error` ou `api_error`. example: invalid_request_error code: type: string description: >- Código estável e legível por máquina. Veja [Códigos de erro](/errors/error-codes). example: channel_inactive message: type: string description: >- Texto para humanos, em inglês. Pode mudar, então não faça parse dele. example: Channel chan_01J8... is not active and cannot send messages. param: type: string description: O campo da requisição com problema, quando se aplica. doc_url: type: string description: Link para a documentação do código, quando disponível. details: type: object additionalProperties: oneOf: - type: string - type: number description: >- Valores acionáveis, como `limit`, `used` e `resets_at` em `message_quota_exceeded`. request_id: type: string description: Identificador da requisição. Informe-o ao falar com o suporte. example: req_01J8ZK9M3Q7XABCDEFGHJKMNPQ description: Detalhes do erro. required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chave de API do projeto, no formato `rt_live_...` ou `rt_test_...`, enviada como `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.