---
title: "Consultar mensagem"
method: GET
path: "/v1/messages/{id}"
tags: ["Mensagens"]
---

# Consultar mensagem

`GET /v1/messages/{id}`

## Request

- Base URL: `https://api.ararahq.com`
- URL: `https://api.ararahq.com/v1/messages/{id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ararahq/apis/ararahq-api/docs/v1/messages/:id/get.ts> (a function with typed inputs; its response is checked against the schema)

Devolve a mensagem no mesmo formato do envio, com `status` e `reason`
atualizados. Em produção, prefira o webhook `message.status_updated` a
consultar em laço.

Só devolve mensagens enviadas pelo mesmo usuário dono da chave. Mensagem de
outro membro da organização responde `403` sem corpo, e ID inexistente
responde `404` sem corpo. Para qualquer mensagem da organização, use
`GET /dashboard/messages/{id}`.

Permissão: `READ`.

## Path parameters

- `id` string, required

## Response `200`

Mensagem

- MessageResponse
  - `id` string, nullable: ID público da mensagem. Use para consultar e para casar com o webhook.
  - `status` 'PENDING' | 'SCHEDULED' | 'PROCESSING' | 'SENT' | 'DELIVERED' | 'READ' | 'FAILED' | 'CANCELED', required: Estado atual, sempre em maiúsculas: - `PENDING`: criada, na fila. - `SCHEDULED`: agendada. - `PROCESSING`: em processamento. - `SENT`: aceita pelo provedor. - `DELIVERED`: entregue no aparelho. - `READ`: lida. - `FAILED`: falhou. Veja `reason`. - `CANCELED`: cancelada antes do envio. O webhook `message.status_updated` usa os mesmos estados em minúsculas, com `PENDING` virando `queued`.
  - `mode` 'LIVE', required: Todo envio por chave de API é `LIVE`.
  - `sender` string, required: Número que enviou.
  - `receiver` string, required: Número do destinatário.
  - `body` string, nullable: Conteúdo final enviado, com as variáveis aplicadas. Pode vir `null`.
  - `cost` number, nullable: Custo em reais. Pode vir `null`. Os valores dos exemplos são ilustrativos.
  - `reason` string, nullable: Motivo da falha quando `status` é `FAILED`.

## Other responses

- `401`: Chave inexistente, revogada, expirada, com prefixo errado (`ara_` sem `ara_live_`) ou vinda de IP fora da allowlist. O corpo é o JSON padrão do Spring, sem `error.code`.
- `403`: Mensagem de outro usuário (sem corpo) ou chave sem permissão.
- `404`: Mensagem não encontrada (sem corpo).
- `429`: `RATE_LIMIT_EXCEEDED`: limite geral da API (1.200 leituras ou 3.000 escritas por minuto, por usuário da chave).

---

[API](https://skmtc.dev/ararahq/apis/ararahq-api.md) - [All operations](https://skmtc.dev/ararahq/apis/ararahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ararahq/apis/ararahq-api/revisions/d576cd28afc0?raw)