Historial del chat

POST

api

chat

history

:instance

Historial del chat

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

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({number: '<string>', count: 123, from: '<string>', to: '<string>'})
};

fetch('https://api.example.com/api/chat/history/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/chat/history/:instance"

payload = {
    "number": "<string>",
    "count": 123,
    "from": "<string>",
    "to": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: sí

Descripción

Devuelve los mensajes almacenados de un chat específico, ordenados del más reciente al más antiguo. Puedes controlar la cantidad con count y filtrar por una ventana de fechas con from/to.

No hay cursor de paginación. Para paginar, ajusta los filtros from y to. El campo hasMore es una heurística: es true cuando la cantidad de mensajes devueltos == count (probablemente hay más).

Ejemplos

Últimos 50

Forma mínima: pasa solo number y usa el count predeterminado de 50 mensajes, devolviendo los más recientes del chat ordenados del más nuevo al más antiguo.

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

Con ventana de fechas

Recupera hasta 200 mensajes enviados entre el 20 y el 28 de abril de 2026 (from/to en ISO 8601). Útil para extraer historial de un intervalo específico o paginar usando to como 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)
}

Grupo

La misma lógica, pero con number apuntando a un JID de grupo (@g.us) y count de 100. Cada item en messages[] lleva senderJid con el autor del mensaje dentro del grupo.

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

Respuesta exitosa

messages lleva los mensajes en orden cronológico inverso (más nuevos primero). count indica cuántos items vinieron en esta página y hasMore es true cuando alcanzaste exactamente el count solicitado, señalando que puede haber más mensajes, pagina usando los from/to del último mensaje devuelto. chat_jid es el JID resuelto del chat solicitado.

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
}

Cada elemento en messages[] trae la identidad del remitente resuelta, senderJid (número cuando se conoce), senderLid y senderName. Los campos de media (mediaUrl, mediaMimeType, mediaSize, mediaDuration) aparecen solo en mensajes de media. El chat_name en la raíz trae el nombre del grupo o del contacto.

La identidad del remitente y el chat_name se leen de los datos locales de la instancia, los mismos que alimentan los eventos en tiempo real, sin consultar servidores externos. Para miembros de grupo que la instancia nunca vio, o cuando la instancia está desconectada, senderName puede venir vacío y senderJid puede permanecer en formato @lid. Los números ocultados por WhatsApp mantienen el valor @lid en senderJid.

Parámetros de ruta

string

requerido

Nombre de la instancia.

Cabeceras

Nombre	Requerido	Ejemplo	Descripción
`Content-Type`	sí	`application/json`	,
`token`	sí (o `Authorization`)	`a1b2c3d4-...`	TokenAccount o TokenInstance.

Cuerpo de la solicitud

string

requerido

Número de teléfono, JID privado (...@s.whatsapp.net o ...@lid), JID de grupo (...@g.us) o newsletter.

int

predeterminado:"50"

Cantidad máxima de mensajes a devolver. Sin límite superior interno.

string

ISO 8601 / RFC3339. Mensajes a partir de esta fecha (inclusive).

string

ISO 8601 / RFC3339. Mensajes hasta esta fecha (inclusive).

Notas y precauciones

Funciona incluso cuando la instancia está desconectada, lee directamente de la base de datos de ingestión.
Para paginar de forma segura, define to = timestamp del mensaje más antiguo ya recibido en la llamada anterior.
hasMore=true no garantiza al 100% que existan más mensajes, es solo una heurística basada en el count solicitado.

Respuestas de error

HTTP	`error.message`	Cuándo ocurre
400	`Instance name is required`	,
400	`Invalid request body: <...>`	JSON malformado.
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" }
}

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Historial del chat

Descripción

Ejemplos

Últimos 50

Con ventana de fechas

Grupo

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas y precauciones

Respuestas de error

Relacionados

Buscar mensaje

Media en base64

​Descripción

​Ejemplos

​Últimos 50

​Con ventana de fechas

​Grupo

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas y precauciones

​Respuestas de error

​Relacionados

Buscar mensaje

Media en base64

Descripción

Ejemplos

Últimos 50

Con ventana de fechas

Grupo

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas y precauciones

Respuestas de error

Relacionados