Skip to main content
POST
/
api
/
chat
/
history
/
:instance
Chat history
curl --request POST \
  --url https://api.example.com/api/chat/history/:instance \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "<string>",
  "count": 123,
  "from": "<string>",
  "to": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: yes

​
Description

Returns the stored messages of a specific chat, ordered from newest to oldest. You can control the amount with count and filter by a date window with from/to.
There is no pagination cursor. To paginate, adjust the from and to filters. The hasMore field is a heuristic: it is true when the number of returned messages == count (likely there are more).

​
Examples

​
Last 50

Minimal form: pass only number and use the default count of 50 messages, returning the most recent ones in the chat ordered from newest to oldest. 
curl -X POST "https://ryzeapi.cloud/api/chat/history/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999"}'

​
With a date window

Retrieves up to 200 messages sent between April 20 and April 28, 2026 (from/to in ISO 8601). Useful to extract history for a specific interval or to paginate using to as a cursor. 
curl -X POST "https://ryzeapi.cloud/api/chat/history/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "count":  200,
    "from":   "2026-04-20T00:00:00Z",
    "to":     "2026-04-28T23:59:59Z"
  }'

​
Group

Same logic, but with number pointing to a group JID (@g.us) and count of 100. Each item in messages[] carries senderJid filled with the message author within the group. 
curl -X POST "https://ryzeapi.cloud/api/chat/history/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "120363123456789@g.us",
    "count":  100
  }'

​
Success response

messages carries the messages in reverse chronological order (newest first). count indicates how many items came in this page and hasMore is true when you reached exactly the requested count, signaling that there may be more messages, paginate by using the from/to from the last returned message. chat_jid is the resolved JID of the requested chat.
200 OK
{
  "success": true,
  "message": "Retrieved 2 messages from chat history",
  "chat_jid": "5511999999999@s.whatsapp.net",
  "messages": [
    {
      "id": "3EB08FCF27E532F1B0F5",
      "fromMe": true,
      "timestamp": "2026-04-28T14:30:00Z",
      "content": "Hi",
      "type": "text",
      "chatJid": "5511999999999@s.whatsapp.net",
      "senderJid": ""
    },
    {
      "id": "3EB08FCF27E532F1B0F4",
      "fromMe": false,
      "timestamp": "2026-04-28T14:29:55Z",
      "content": "Good morning!",
      "type": "text",
      "chatJid": "5511999999999@s.whatsapp.net",
      "senderJid": "5511999999999@s.whatsapp.net"
    }
  ],
  "count": 2,
  "hasMore": false
}

​
Path parameters

​
instance
string
required
Instance name.

​
Headers

NameRequiredExampleDescription
Content-Typeyesapplication/json—
tokenyes (or Authorization)a1b2c3d4-...TokenAccount or TokenInstance.

​
Request body

​
number
string
required
Phone number, private JID (...@s.whatsapp.net or ...@lid), group JID (...@g.us), or newsletter.
​
count
int
default:"50"
Maximum number of messages to return. No internal upper limit.
​
from
string
ISO 8601 / RFC3339. Messages starting from this date (inclusive).
​
to
string
ISO 8601 / RFC3339. Messages up to this date (inclusive).

​
Notes and gotchas

  • Works even when the instance is disconnected, reads directly from the ingestion database.
  • To paginate safely, set to = timestamp of the oldest message already received in the previous call.
  • hasMore=true does not guarantee 100% that more messages exist, it is just a heuristic based on the requested count.

​
Error responses

HTTPerror.messageWhen it happens
400Instance name is required—
400Invalid request body: <...>Malformed JSON.
400Number is required—
400invalid 'from' date format. Use ISO 8601 format (e.g., '2026-02-16T18:32:39Z')—
400invalid 'to' date format. Use ISO 8601 format (e.g., '2026-02-16T18:32:39Z')—
401Invalid token—
404Instance not found—
Error 400
{
  "success": false,
  "error": { "message": "Number is required" }
}

Find message

Retrieve a specific message from history.

Media as base64

Download a media item referenced in history.