Chats

Métodos para gestionar chats y mensajes de WhatsApp.

  • {session} — nombre de la sesión que creaste con POST /api/sessions.
  • {chatId} — ID del chat en formato 123123123123@c.us (directo) o 123123123123@g.us (grupo).

Obtener todos los chats

http
GET /api/{session}/chats

Parámetros de consulta:

http
GET /api/{session}/chats?limit=100&offset=0&sortBy=messageTimestamp&sortOrder=desc
  • limit=100 — limita el número de chats a devolver.
  • offset=0 — omite N chats desde el inicio.
  • sortBy — ordena por campo: messageTimestamp (último mensaje), id o name.
  • sortOrder — desc (nuevos primero) o asc (antiguos primero).

Obtener resumen de chats

La API que casi todo cliente de interfaz de chat necesita.

http
GET /api/{session}/chats/overview?limit=20&offset=0
  • limit / offset — paginación.
  • ids=11111&ids=9999@c.us — filtra por ID o número de teléfono.

Usa POST si tienes muchos chats (>400) en el filtro ids:

http
POST /api/{session}/chats/overview
jsonBody
{
  "pagination": { "limit": 20, "offset": 0 },
  "filter": { "ids": ["5215551234567@c.us"] }
}
jsonResponse
[
  {
    "id": "5215551234567@c.us",
    "name": "Juan Pérez",
    "picture": "https://ejemplo.com/foto.jpg",
    "lastMessage": {
      "id": "true_5215551234567@c.us_AAAA",
      "timestamp": 1667561485,
      "from": "5215551234567@c.us",
      "fromMe": true,
      "body": "Hola"
    }
  }
]

Obtener foto del chat

http
GET /api/{session}/chats/{chatId}/picture?refresh=true
jsonResponse
{ "url": "https://ejemplo.com/foto.jpg" }

url puede ser null si el chat no tiene foto. refresh=true fuerza el refresco (cacheado 24 h).

Archivar / desarchivar chat

http
POST /api/{session}/chats/{chatId}/archive
http
POST /api/{session}/chats/{chatId}/unarchive

Marcar chat como no leído

http
POST /api/{session}/chats/{chatId}/unread

Eliminar chat

http
DELETE /api/{session}/chats/{chatId}

Marcar mensajes como leídos

Marca todos los mensajes no leídos del chat como leídos (doble check azul).

http
POST /api/{session}/chats/{chatId}/messages/read
jsonBody
{ "messages": 30, "days": 7 }
jsonBody
{
  "ids": [
    "false_5215551234567@c.us_AAAA",
    "true_5215551234567@c.us_BBBB"
  ]
}
  • messages — cuántos mensajes leer (default 30 en chats directos, 100 en grupos).
  • days — cuántos días leer (default 7).

Obtener mensajes

http
GET /api/{session}/chats/{chatId}/messages?limit=10

Parámetros disponibles:

  • downloadMedia=true — descargar archivos multimedia.
  • limit / offset — paginación.
  • filter.timestamp.gte / filter.timestamp.lte — filtrar por timestamp.
  • filter.fromMe=false — excluir mensajes propios.
  • filter.ack — filtrar por estado de confirmación:ERROR (-1), PENDING (0), SERVER (1), DEVICE (2), READ (3), PLAYED (4).
jsonResponse
[
  {
    "id": "false_5215551234567@c.us_AAAAAA",
    "timestamp": 1727745026,
    "from": "5215551234567@c.us",
    "fromMe": false,
    "body": "¡Hola!",
    "hasMedia": false,
    "ack": 3,
    "ackName": "READ",
    "replyTo": null
  }
]

Obtener mensaje por id

http
GET /api/{session}/chats/{chatId}/messages/{messageId}?downloadMedia=true

Fijar / desfijar mensaje

http
POST /api/{session}/chats/{chatId}/messages/{messageId}/pin
jsonBody
{
  "duration": 86400
}

Duración: 24 horas = 86400, 7 días = 604800, 30 días = 2592000.

http
POST /api/{session}/chats/{chatId}/messages/{messageId}/unpin

Editar mensaje

http
PUT /api/{session}/chats/{chatId}/messages/{messageId}
jsonBody
{ "text": "Mensaje editado" }

Eliminar mensaje

http
DELETE /api/{session}/chats/{chatId}/messages/{messageId}

Eliminar todos los mensajes

http
DELETE /api/{session}/chats/{chatId}/messages

Eventos

Recibe eventos de chats mediante Eventos. El evento chat.archive se dispara cuando un chat se archiva o desarchiva (consulta el detalle del payload en la página de Eventos).