# Solicitar histórico sob demanda

`POST /message/history-sync`

Pasta: **Ações na mensagem e Buscar**

## Autenticação

```http
token: {{token}}
```

## Descrição

# Solicitar histórico sob demanda

Pede aos seus próprios dispositivos WhatsApp mensagens **mais antigas** que uma mensagem-cursor. A resposta HTTP só confirma o pedido; as mensagens chegam depois via evento de History Sync (ON_DEMAND) e são gravadas no histórico.

## Endpoint

`POST {{baseUrl}}/message/history-sync`

## Autenticação

Header obrigatório: `token: {{token}}`.

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| chatid | string | Condicional | JID do chat. Aceita também `number` ou `jid` (mesmo valor) |
| number | string | Condicional | Alternativa a `chatid` |
| jid | string | Condicional | Alternativa a `chatid` |
| messageid | string | Sim | ID da mensagem-cursor (a mais antiga conhecida; prefixo `WAID:` é removido) |
| messageId | string | Não | Alias camelCase de `messageid` |
| fromMe | boolean | Condicional | Se a mensagem-cursor foi enviada por você. Obrigatório se ela **não** estiver no histórico local |
| timestamp | integer | Condicional | Unix (segundos ou ms) da mensagem-cursor. Obrigatório se ela **não** estiver no histórico local |
| count | integer | Não | Quantidade a pedir (padrão `50`, máximo `300`) |

Se a mensagem-cursor já existir no histórico, `chatid`/`fromMe`/`timestamp` podem ser inferidos (ou sobrescritos). Se não existir, informe `chatid` (ou `number`/`jid`) + `timestamp` (+ `fromMe` se for sua).

## Exemplo de Requisição

```bash
curl -X POST "{{baseUrl}}/message/history-sync" \
  -H "token: {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "chatid": "5511999999999@s.whatsapp.net",
    "messageid": "3EB01234567890ABCDEF",
    "fromMe": false,
    "timestamp": 1721200000,
    "count": 50
  }'
```

## Resposta de Sucesso

```json
{
  "success": true,
  "message": {
    "id": "3EB0PEERMSGID",
    "timestamp": "2026-07-17T06:45:00Z"
  }
}
```

(Em instâncias mobile o `id` do peer message pode vir vazio; o pedido ainda é enviado.)

## Erros comuns

- `400`/`500` — `messageid is required`
- `500` — `chatid is required when message is not in history`
- `500` — `timestamp is required when message is not in history`
- `500` — `chatid does not match stored message` (chat informado diverge do histórico)

## Observações

- Não existe campo `mode` (`history`/`exact`): o endpoint sempre pede mensagens anteriores ao cursor.
- Após o sucesso, acompanhe webhooks/SSE/histórico local — as mensagens não vêm no body desta resposta.
- Funciona em modo companion e mobile (peer HISTORY_SYNC_ON_DEMAND).

## Corpo (exemplo)

```json
{
  "chatid": "5511999999999@s.whatsapp.net",
  "messageid": "3EB01234567890ABCDEF",
  "fromMe": false,
  "timestamp": 1721200000,
  "count": 50
}
```

## cURL

```bash
curl -X POST "{{baseUrl}}/message/history-sync" \
  -H "token: {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
  "chatid": "5511999999999@s.whatsapp.net",
  "messageid": "3EB01234567890ABCDEF",
  "fromMe": false,
  "timestamp": 1721200000,
  "count": 50
}'
```

---

[Índice da pasta](./index.md) · [Índice geral](../index.md) · [UI](https://gozap.dev/docs?op=acoes-na-mensagem-e-buscar/solicitar-historico-sob-demanda)