# Listar mensagens

Fonte: https://apiwpp.com/docs/api/registros/listar-mensagens
Seção: Registros
Atualizado em: 2026-09-28

`GET /messages`

Lista as mensagens registradas do projeto, das mais novas para as mais antigas: os envios feitos pela API (`POST /connections/{id}/send`) e as mensagens recebidas. Cada linha traz o estado atual da mensagem e o histórico de mudanças em `events`. `counts` aplica todos os filtros menos `direction`, para mostrar quantas há em cada direção de uma vez. Escopo necessário: `logs:read`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |

## Parâmetros de consulta

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `direction` | `string` | não | Só os envios (`out`) ou só as mensagens recebidas (`in`). Não muda `counts`. Valores: `"in"`, `"out"`. |
| `status` | `string` | não | Só as mensagens neste estado: `queued` (na fila), `sent` (enviada), `delivered` (entregue), `read` (lida), `failed` (falhou) ou `received` (recebida). Valores: `"queued"`, `"sent"`, `"delivered"`, `"read"`, `"failed"`, `"received"`. |
| `tenantId` | `string` | não | Filtra por projeto (`tenantId`). Com uma chave de API, a lista já cobre só o projeto da chave, então este filtro só aceita esse mesmo projeto; outro responde `404`. |
| `connectionId` | `string` | não | Só as mensagens de uma conexão (o número). Uma conexão que não é do projeto da chave não dá erro: a lista vem vazia. |
| `q` | `string` | não | Busca, sem diferenciar maiúsculas de minúsculas, em `contact`, `body`, `jobId`, `clientRef` e `messageId`. Um telefone formatado (`+55 (11) 98888-7777`) também encontra o contato guardado só com dígitos. |
| `limit` | `integer` | não | Quantas linhas trazer, das mais novas para as mais antigas. Padrão 60; um valor acima de 200 é tratado como 200. Não há paginação: para ver linhas mais antigas, estreite os filtros. (mínimo 1; padrão: 60) |

## Exemplo de requisição

### cURL

```bash
curl "https://api.apiwpp.com/messages?direction=out&status=failed&limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/messages?direction=out&status=failed&limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->get("https://api.apiwpp.com/messages", [
        'direction' => 'out',
        'status' => 'failed',
        'limit' => '20',
    ]);
```

### Python

```python
import requests

response = requests.get(
    "https://api.apiwpp.com/messages",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "direction": "out",
        "status": "failed",
        "limit": "20",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | `messages`, as linhas das mais novas para as mais antigas (cada uma com `id`, `tenantId`, `connectionId`, `direction`, `contact`, `type`, `body`, `status`, `jobId`, `clientRef`, `messageId`, `error`, `events`, `createdAt` e `updatedAt`), e `counts`, com o total de linhas que atendem aos filtros (`all`) e quantas são recebidas (`in`) e enviadas (`out`). Sem nada registrado, a lista vem vazia. |
| 400 | `FST_ERR_VALIDATION` | Um filtro não segue o schema da operação: `direction` ou `status` fora da lista, ou `limit` que não é um inteiro maior que zero; `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é `{"error": "Unauthorized"}`. |
| 403 |  | A chave não tem o escopo `logs:read`; a mensagem cita o escopo (`This credential lacks the logs:read scope`). |
| 404 |  | O filtro `tenantId` aponta para um projeto que não é da chave (`{"error": "Tenant not found"}`): o projeto de outra pessoa responde exatamente como um que não existe. |
| 429 |  | Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "messages": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
      "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
      "direction": "out",
      "contact": "5511988887777",
      "type": "text",
      "body": "Sua consulta está confirmada para amanhã às 10h.",
      "status": "delivered",
      "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
      "clientRef": "crm-msg-1",
      "messageId": "3EB0C767D26A1D8A3F52",
      "error": null,
      "events": [
        {
          "status": "queued",
          "at": "2026-09-24T11:59:55.000Z"
        },
        {
          "status": "sent",
          "at": "2026-09-24T12:00:00.000Z"
        },
        {
          "status": "delivered",
          "at": "2026-09-24T12:00:02.000Z"
        }
      ],
      "createdAt": "2026-09-24T11:59:55.000Z",
      "updatedAt": "2026-09-24T12:00:02.000Z"
    }
  ],
  "counts": {
    "all": 1,
    "in": 0,
    "out": 1
  }
}
```

## Detalhes

**O que entra no registro.** Um envio entra como `queued` no momento em que é aceito na fila e avança para `sent`, `delivered` e `read` conforme as confirmações do WhatsApp chegam; uma mensagem recebida entra como `received`. Mensagens digitadas no próprio celular não aparecem aqui (para acompanhá-las, use o evento [message.outgoing](https://apiwpp.com/docs/webhooks/message-outgoing)).

**O status só avança.** Uma confirmação que chega fora de ordem (um `read` antes do `delivered`) nunca faz a linha voltar. `failed` vale sempre, e uma linha `failed` ainda pode passar para `sent`, `delivered` ou `read` se o WhatsApp confirmar a mensagem depois. `events` guarda cada mudança aplicada, com o horário em `at`.

**Os campos de cada linha.** `direction` é `out` (envio) ou `in` (recebida). `contact` é o telefone só com dígitos ou, quando o endereço não é um telefone, a parte antes do `@` do JID (um LID ou o id de um grupo). `type` é `text`, `image`, `video`, `audio`, `document`, `sticker`, `location` ou, num envio por template, `template`. `body` é uma prévia de até 1000 caracteres: o texto, a legenda da mídia, o nome do arquivo ou o nome do local, e `null` quando não há nada disso. `jobId` e `clientRef` só existem nos envios; `messageId` é o id do WhatsApp, preenchido quando o envio sai ou na mensagem recebida.

**Por que falhou.** Numa linha `failed`, `error` explica o motivo, em português: `Número não está no WhatsApp`, `Número temporariamente restrito pelo WhatsApp para iniciar conversas`, `Falhou após 3 tentativas`, `Tempo de processamento esgotado`, `Cancelado via API` ou `Falha ao enfileirar`. Para reagir a falhas no seu sistema, use os eventos [message.send_failed](https://apiwpp.com/docs/webhooks/message-send-failed) e [message.delivery](https://apiwpp.com/docs/webhooks/message-delivery); este registro serve para consulta.

**Retenção.** Os registros ficam guardados por 7 dias por padrão; depois disso, saem da lista e das contagens.

Guia: [Uso e registros](https://apiwpp.com/docs/guias/uso-e-registros).
