Chat history

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"}'

await fetch(`https://ryzeapi.cloud/api/chat/history/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ number: "5511999999999" })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/history/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={"number": "5511999999999"}
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{"number":"5511999999999"}`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/history/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
  }'

await fetch(`https://ryzeapi.cloud/api/chat/history/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511999999999",
    count:  200,
    from:   "2026-04-20T00:00:00Z",
    to:     "2026-04-28T23:59:59Z"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/history/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "5511999999999",
        "count":  200,
        "from":   "2026-04-20T00:00:00Z",
        "to":     "2026-04-28T23:59:59Z"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "count":  200,
        "from":   "2026-04-20T00:00:00Z",
        "to":     "2026-04-28T23:59:59Z"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/history/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/chat/history/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "120363123456789@g.us",
    count:  100
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/chat/history/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "120363123456789@g.us",
        "count":  100
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "120363123456789@g.us",
        "count":  100
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/history/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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": "120363036972484891@g.us",
  "chat_name": "Nodejs - Whatsapp APIS",
  "messages": [
    {
      "id": "A50E17E1B504F5F9EC439A24B4A8AD68",
      "fromMe": false,
      "timestamp": "2026-04-28T14:30:00Z",
      "content": "Me mandaram a API em um pdf",
      "type": "text",
      "chatJid": "120363036972484891@g.us",
      "senderJid": "557398631289@s.whatsapp.net",
      "senderLid": "95967336501274@lid",
      "senderName": "Impa 365"
    },
    {
      "id": "B72F00AA13C4D5E6F7A80912",
      "fromMe": false,
      "timestamp": "2026-04-28T14:29:55Z",
      "content": "olha o print",
      "type": "image",
      "chatJid": "120363036972484891@g.us",
      "senderJid": "5511988887777@s.whatsapp.net",
      "senderLid": "84770001111223@lid",
      "senderName": "Carlos Dev",
      "mediaUrl": "https://ryzeapi.cloud/media/Orion/B72F00AA13C4D5E6F7A80912.jpg",
      "mediaMimeType": "image/jpeg",
      "mediaSize": 184320
    }
  ],
  "count": 2,
  "hasMore": false
}

Each item in messages[] carries the resolved sender identity, senderJid (phone number when known), senderLid and senderName. Media fields (mediaUrl, mediaMimeType, mediaSize, mediaDuration) appear only on media messages. The root chat_name carries the group name or the contact name.

Sender identity and chat_name are read from the instance’s local data, the same data that powers real-time events, without querying external servers. For group members the instance has never seen, or when the instance is disconnected, senderName may come empty and senderJid may stay in the @lid format. Numbers hidden by WhatsApp keep the @lid value in senderJid.

Path parameters

string

required

Instance name.

Headers

Name	Required	Example	Description
`Content-Type`	yes	`application/json`	,
`token`	yes (or `Authorization`)	`a1b2c3d4-...`	TokenAccount or TokenInstance.

Request body

string

required

Phone number, private JID (...@s.whatsapp.net or ...@lid), group JID (...@g.us), or newsletter.

int

default:"50"

Maximum number of messages to return. No internal upper limit.

string

ISO 8601 / RFC3339. Messages starting from this date (inclusive).

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

HTTP	`error.message`	When it happens
400	`Instance name is required`	,
400	`Invalid request body: <...>`	Malformed JSON.
400	`Number is required`	,
400	`invalid 'from' date format. Use ISO 8601 format (e.g., '2026-02-16T18:32:39Z')`	,
400	`invalid 'to' date format. Use ISO 8601 format (e.g., '2026-02-16T18:32:39Z')`	,
401	`Invalid token`	,
404	`Instance 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.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Last 50

With a date window

Group

Success response

Path parameters

Headers

Request body

Notes and gotchas

Error responses

Find message

Media as base64

​Description

​Examples

​Last 50

​With a date window

​Group

​Success response

​Path parameters

​Headers

​Request body

​Notes and gotchas

​Error responses

​Related

Find message

Media as base64

Description

Examples

Last 50

With a date window

Group

Success response

Path parameters

Headers

Request body

Notes and gotchas

Error responses

Related