Histórico do chat

POST

api

chat

history

:instance

Histórico do 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 ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim

Descrição

Retorna as mensagens armazenadas de um chat específico, ordenadas das mais novas para as mais antigas. Você pode controlar a quantidade com count e filtrar por janela de datas com from/to.

Não há cursor de paginação. Para paginar, ajuste os filtros from e to. O campo hasMore é uma heurística: vale true quando o número de mensagens retornadas == count (provavelmente há mais).

Exemplos

Últimas 50

Forma mínima: passa apenas number e usa o count padrão de 50 mensagens, retornando as mais recentes do chat ordenadas da mais nova para a mais antiga.

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

Com janela de datas

Recupera até 200 mensagens enviadas entre 20 e 28 de abril de 2026 (from/to em ISO 8601). Útil para extrair o histórico de um intervalo específico ou paginar usando o 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

Mesma lógica, mas com number apontando para um JID de grupo (@g.us) e count de 100. Cada item em messages[] traz senderJid preenchido com o autor da mensagem dentro do 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)
}

Resposta de sucesso

messages traz as mensagens em ordem cronológica decrescente (mais recente primeiro). count indica quantos itens vieram nesta página e hasMore é true quando você atingiu exatamente o count solicitado, sinalizando que pode haver mais mensagens, paginar usando o from/to da última mensagem retornada. chat_jid é o JID resolvido do 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 item em messages[] traz a identidade do remetente resolvida, senderJid (número quando conhecido), senderLid e senderName. Campos de mídia (mediaUrl, mediaMimeType, mediaSize, mediaDuration) aparecem apenas em mensagens de mídia. O chat_name na raiz traz o nome do grupo ou do contato.

A identidade do remetente e o chat_name são lidos dos dados locais da instância, os mesmos que alimentam os eventos em tempo real, sem consultar servidores externos. Para membros de grupo que a instância nunca viu, ou quando a instância está desconectada, senderName pode vir vazio e senderJid pode permanecer no formato @lid. Números ocultados pelo WhatsApp mantêm o valor @lid em senderJid.

Parâmetros de rota

string

obrigatório

Nome da instância.

Headers

Nome	Obrigatório	Exemplo	Descrição
`Content-Type`	sim	`application/json`	,
`token`	sim (ou `Authorization`)	`a1b2c3d4-...`	TokenAccount ou TokenInstance.

Request body

string

obrigatório

Telefone, JID privado (...@s.whatsapp.net ou ...@lid), JID de grupo (...@g.us) ou newsletter.

int

padrão:"50"

Quantidade máxima de mensagens a retornar. Sem limite superior interno.

string

ISO 8601 / RFC3339. Mensagens a partir desta data (inclusivo).

string

ISO 8601 / RFC3339. Mensagens até esta data (inclusivo).

Notas e gotchas

Funciona mesmo com a instância desconectada, lê direto do banco da ingestão.
Para paginar com segurança, use to = timestamp da mensagem mais antiga já recebida na chamada anterior.
hasMore=true não garante 100% que existam mais mensagens, é apenas uma heurística baseada no count solicitado.

Respostas de erro

HTTP	`error.message`	Quando ocorre
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`	,

Erro 400

{
  "success": false,
  "error": { "message": "Number is required" }
}

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Histórico do chat

Descrição

Exemplos

Últimas 50

Com janela de datas

Grupo

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas e gotchas

Respostas de erro

Relacionados

Buscar mensagem

Mídia em base64

​Descrição

​Exemplos

​Últimas 50

​Com janela de datas

​Grupo

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas e gotchas

​Respostas de erro

​Relacionados

Buscar mensagem

Mídia em base64

Descrição

Exemplos

Últimas 50

Com janela de datas

Grupo

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas e gotchas

Respostas de erro

Relacionados