# Buscar mensagens no formato legado

`POST /message/find`

Ordem mais recente primeiro. includeHistory=true por padrão; histórico nunca dispara automações novas. id ausente no store retorna messages=[].

## Autenticação

Header obrigatório: `token`. Use o token da instância.

Base URL: a API do servidor selecionado, como `https://1.atendro.cloud`. O domínio `wpp.atendro.cloud` hospeda a documentação e o console.

## Headers adicionais

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `X-Request-Id` | `string` | opcional | ASCII visível sem espaços, 1–128 caracteres. Inválido/ausente é substituído por UUID. Ecoado na resposta. Comprimento máximo: `128` |

## Corpo da requisição

Formato: `application/json`. Corpo opcional.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `id` | `string` | opcional | ID da mensagem guardada nesta instância. Nos corpos aceita também owner:id. Comprimento mínimo: `1` |
| `chatid` | `string` | opcional | Dígitos com DDI (8–15) ou identificador @s.whatsapp.net, @g.us ou @lid. Nunca inferir telefone de um LID. Comprimento mínimo: `1` |
| `limit` | `integer / string` | opcional | 0/ausente usa 100; máximo 200. Padrão: `100` |
| `offset` | `integer / string` | opcional | Deslocamento da página. |
| `includeHistory` | `boolean / string / integer / null` | opcional | Padrão: `true` |

## Resposta 200

Buscar mensagens no formato legado

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `messages` | `array<object>` | obrigatório | — |
| `messages[].id` | `string` | obrigatório | owner:messageid. |
| `messages[].messageid` | `string` | obrigatório | — |
| `messages[].chatid` | `string` | obrigatório | — |
| `messages[].sender` | `string` | opcional | — |
| `messages[].sender_pn` | `string` | opcional | — |
| `messages[].senderName` | `string` | opcional | — |
| `messages[].pushName` | `string` | opcional | — |
| `messages[].isGroup` | `boolean` | opcional | — |
| `messages[].fromMe` | `boolean` | obrigatório | — |
| `messages[].wasSentByApi` | `boolean` | opcional | — |
| `messages[].messageType` | `string` | opcional | Tipo legado PascalCase. |
| `messages[].type` | `string` | opcional | — |
| `messages[].messageTimestamp` | `integer` | opcional | Unix em milissegundos. Formato: `int64` |
| `messages[].timestamp` | `integer` | opcional | Unix em segundos. Formato: `int64` |
| `messages[].status` | `string` | opcional | Pending, Sent, Delivered, Read, Played, Failed, Received ou Deleted. |
| `messages[].text` | `string` | opcional | — |
| `messages[].content` | `object` | opcional | — |
| `messages[].buttonOrListid` | `string` | opcional | — |
| `messages[].reactions` | `array<object>` | opcional | — |
| `messages[].choices` | `any` | opcional | Opções armazenadas de menus/enquetes; estrutura depende do tipo e pode ser null. |
| `messages[].fileURL` | `string` | opcional | — |
| `messages[].mediaUrl` | `string` | opcional | — |
| `returnedMessages` | `integer` | obrigatório | — |
| `limit` | `integer` | obrigatório | — |
| `offset` | `integer` | obrigatório | — |
| `hasMore` | `boolean` | obrigatório | — |
| `nextOffset` | `integer` | opcional | — |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "hasMore": false,
  "limit": 0,
  "messages": [],
  "offset": 0,
  "returnedMessages": 0
}
```

## Resposta 400

invalid_limit ou invalid_chatid.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 401

unauthorized: header ausente, inválido ou duplicado. Bearer/query/instancekey não substituem admintoken/token.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "unauthorized"
}
```

## Resposta 502

storage_unavailable (Retry-After=5). Algumas rotas também retornam 502 por falha da conexão/mídia; consultar error.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "storage_unavailable"
}
```

## Resposta default

Falha; usar HTTP status e error. 404 rota inexistente; 405 método inválido com Allow. Ver catálogo no guia de integração.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Exemplos de requisição

Defina as variáveis no ambiente privado e substitua os dados sintéticos antes de usar. Os exemplos não executam operações nesta página.

### cURL

```sh
curl --request POST "$ATENDROZAP_URL/message/find" \
  --header "token: $ATENDROZAP_INSTANCE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "chatid": "12025550123",
  "limit": 20,
  "offset": 0
}'
```

### JavaScript

```javascript
const baseUrl = process.env.ATENDROZAP_URL;
let path = "/message/find";
const url = new URL(path, baseUrl);

const response = await fetch(url, {
  method: "POST",
  headers: {
    "token": process.env.ATENDROZAP_INSTANCE_TOKEN,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "chatid": "12025550123",
    "limit": 20,
    "offset": 0
  }),
});

if (!response.ok) {
  throw new Error(`AtendroZAP: HTTP ${response.status}`);
}
const result = await response.json();
```

## Relacionados

- [Conversas e consultas](https://wpp.atendro.cloud/docs/api/consultas.md)
- [Autenticação](https://wpp.atendro.cloud/docs/guias/autenticacao.md)
- [Erros e idempotência](https://wpp.atendro.cloud/docs/guias/erros-e-idempotencia.md)