> ## 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.

# POST /v1/messages/read — Marcar Mensagens como Lidas

> Envie um recibo de leitura (tique azul) para a última mensagem recebida de um contato, sem enviar mensagem.

# Marcar Mensagens como Lidas

```text theme={null}
POST https://pilotstatus.com.br/v1/messages/read
```

Envia um **recibo de leitura** (tique azul duplo) para a **última mensagem recebida** da conversa com `to` — marcando essa e todas as anteriores como lidas **sem enviar mensagem**.

<Note>
  Melhor-esforço: a requisição é aceita (`200`) mesmo quando não há o que confirmar — verifique o campo `acked` na resposta.
</Note>

## Cabeçalhos

* `Content-Type: application/json`
* `x-api-key: ps_...` (ou `x-api-key-id: <api_key_id>`) — uma chave com **escopo de número**

## Corpo

<ParamField body="to" type="string" required>
  Telefone do contato em **E.164** ou só dígitos (ex.: `+5511999999999` ou `5511999999999`) — cujas mensagens recebidas marcar como lidas.
</ParamField>

## Exemplo

```bash theme={null}
curl -X POST "https://pilotstatus.com.br/v1/messages/read" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_sua_chave_aqui" \
  -d '{ "to": "5511999999999" }'
```

## Resposta (200)

```json theme={null}
{ "ok": true, "acked": true }
```

<ResponseField name="ok" type="boolean">
  Sempre `true` quando a requisição foi aceita.
</ResponseField>

<ResponseField name="acked" type="boolean">
  `true` quando um recibo de leitura foi despachado ao provedor; `false` quando não havia o que confirmar — veja `reason`.
</ResponseField>

<ResponseField name="reason" type="string">
  Presente apenas quando `acked` é `false`:

  * `NO_INBOUND_MESSAGE` — a conversa não tem mensagem recebida para confirmar.
  * `PII_RELAY_ONLY` — o modo de privacidade do número é RELAY\_ONLY, então nenhum id de entrada é armazenado.
</ResponseField>

## Comportamento por provedor

| Provedor                              | Como funciona                                                                                                         |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Meta Cloud API**                    | `status:"read"` da Cloud API na última mensagem recebida (marca essa e todas as anteriores).                          |
| **Evolution (Pilot Status web / GO)** | `POST /message/markread` nativo por uma instância conectada. Evolution V2 não tem endpoint de recibo → `acked:false`. |

## Erros comuns

| Status | Significado                                                                                       |
| ------ | ------------------------------------------------------------------------------------------------- |
| `400`  | JSON inválido, `to` ausente, ou a chave não está vinculada a um número (`code: NUMBER_NOT_FOUND`) |
| `401`  | Header de API key ausente/inválido (`x-api-key` / `x-api-key-id`)                                 |
| `403`  | Chave com escopo de tenant usada em endpoint por número                                           |
| `404`  | Nenhuma conversa com `to` (`code: CONVERSATION_NOT_FOUND`)                                        |