Buscar chats

Lista los chats de la cuenta vinculada de WhatsApp actual, con la opción de filtrarlos mediante parámetros de búsqueda.

API de WhatsApp y CRM

Necesitas una clave de API. Pídela a nuestro equipo de soporte o créala desde la plataforma.

GET https://api.getincloud.ai/v1/chat/{deviceId}/chats

Lista los chats de la cuenta vinculada de WhatsApp actual, con la opción de filtrarlos mediante parámetros de búsqueda.

Prueba este endpoint en el probador de API en vivo

>¿Necesitas ayuda? Explora todos los tutoriales, más de 100 ejemplos de casos de uso y juega con el probador de API en vivo con ejemplos de código listos para usar en más de 15 lenguajes de programación, incluidos JavaScript/Node.js, PHP, Python, C#, Java, Ruby, Swift, Kotlin, Powershell, cURL y más.

Autenticación

Envía tu API key en el encabezado Token en cada petición.

Parámetros

Campo	Dónde	Tipo	Obligatorio	Descripción
`status`	query	array	No	Filtra los chats por estado. Se permiten varios estados separados por comas. - `pending` = chats sin asignar y sin responder. - `active` = chat asignado y respondido. - `resolved` = chats cerrados. `default: pending,active,resolved`
`unread`	query	boolean	No	Filtra los chats con mensajes sin leer (`true`) o sin mensajes sin leer (`false`). Los chats sin leer pueden tener cualquier estado (pending, active, resolved)
`active`	query	boolean	No	Filtra solo los chats, grupos o canales activos. Los chats no activos incluyen chats eliminados y grupos de solo lectura que no pueden aceptar mensajes nuevos. Un chat de grupo es de solo lectura cuando tu número ya no es participante del grupo.
`canSend`	query	boolean	No	Filtra solo los chats, grupos o canales a los que puedes enviar mensajes, a diferencia de los chats de solo lectura.
`readOnly`	query	boolean	No	Filtra los chats, grupos o canales que son de solo lectura y no pueden aceptar mensajes. Un chat de grupo es de solo lectura cuando tu número ya no es participante del grupo.
`type`	query	array	No	Filtra los chats por tipo. Nota: el tipo `broadcast` está obsoleto y se eliminará en el futuro.
`agent`	query	array	No	Filtra los chats asignados a uno o varios agentes de usuario por ID (ID de usuario hexadecimal de 24 caracteres). Se permiten varios IDs de agente separados por comas.
`ids`	query	array	No	Filtra los chats por ID de WhatsApp del chat. Ej: `1234567890@c.us`. Se permiten varios IDs separados por comas.
`lid`	query	array	No	Filtra los chats por LID (identificador privado de WhatsApp). Ej: `1234567890123@lid`. Se permiten varios LIDs separados por comas.
`chat`	query	array	No	Filtra los mensajes por ID de WhatsApp del chat. Este filtro funciona para chats de usuario, grupos y canales. Ej: `1234567890@c.us`, `123456789000000000@g.us`, `123000098765421000@newsletter`
`phone`	query	array	No	Filtra los chats por números de teléfono o WIDs. Ej: +1234567890 o 1234567890@c.us
`group`	query	array	No	Filtra los chats por WIDs de grupo. Ej: 123456789000000000@g.us
`channel`	query	array	No	Filtra los chats por WIDs de canal. Ej: 123000098765421000@newsletter
`search`	query	string	No	Busca chats mediante texto libre que coincida parcialmente con el número de teléfono, el ID de WhatsApp, el nombre del grupo o chat, el nombre del contacto, el correo electrónico, el nombre de la empresa, el sitio web, los metadatos o las notas privadas `maxLength: 150`
`labels`	query	array	No	Filtra los chats que contengan al menos una de las etiquetas indicadas. Si se definen varias etiquetas, al menos una debe coincidir por chat. Para incluir los chats que tengan cualquier etiqueta asignada, usa `` como valor, por ejemplo: `labels=`. Este filtro no se puede usar junto con `labelsExclude`.
`labelsExclude`	query	array	No	Excluye los chats que tengan ciertas etiquetas. Si se definen varias etiquetas, ninguna de ellas debe coincidir. Para excluir los chats que no tienen etiquetas asignadas, usa `` como valor, por ejemplo: `labelsExclude=`. Este filtro no se puede usar junto con `labels`.
`include`	query	array	No	Incluye opcionalmente subdocumentos relacionados por cada chat
`includeChats`	query	array	No	Incluye siempre en la búsqueda documentos de chats adicionales por ID de WhatsApp, sin excluir los chats que coincidan según los filtros de búsqueda. Ej: 1234567890@c.us
`excludeChats`	query	array	No	Excluye de la búsqueda chats específicos por ID de WhatsApp. Ej: 1234567890@c.us
`excludeType`	query	array	No	Excluye chats por tipo.
`metadataKey`	query	array	No	Busca chats que tengan al menos una de las claves de metadatos indicadas. Se permiten varios valores separados por comas.
`metadataValue`	query	array	No	Busca chats que tengan al menos uno de los valores de metadatos indicados. Se permiten varios valores separados por comas.
`after`	query	string	No	Chats creados después de la fecha indicada `format: date-time`
`before`	query	string	No	Chats creados antes de la fecha indicada `format: date-time`
`lastMessageAfter`	query	string	No	Chats con último mensaje posterior a la fecha indicada, ya sea entrante o saliente `format: date-time`
`lastMessageBefore`	query	string	No	Chats con último mensaje anterior a la fecha indicada, ya sea entrante o saliente `format: date-time`
`lastMessageInboundAfter`	query	string	No	Chats con último mensaje entrante posterior a la fecha indicada `format: date-time`
`lastMessageInboundBefore`	query	string	No	Chats con último mensaje entrante anterior a la fecha indicada `format: date-time`
`lastMessageOutboundfter`	query	string	No	Chats con último mensaje saliente posterior a la fecha indicada `format: date-time`
`lastMessageOutboundBefore`	query	string	No	Chats con último mensaje saliente anterior a la fecha indicada `format: date-time`
`firstMessageBefore`	query	string	No	Chats con primer mensaje saliente anterior o igual a la fecha indicada `format: date-time`
`firstMessageAfter`	query	string	No	Chats con primer mensaje saliente posterior o igual a la fecha indicada `format: date-time`
`firstInboundMessageBefore`	query	string	No	Chats con primer mensaje entrante anterior o igual a la fecha indicada `format: date-time`
`firstInboundMessageAfter`	query	string	No	Chats con primer mensaje entrante posterior o igual a la fecha indicada `format: date-time`
`page`	query	number	No	Número de página de resultados (empezando en 0) `minimum: 0` · `maximum: 300` · `default: 0` · `format: integer`
`size`	query	number	No	Tamaño de página de resultados `minimum: 1` · `maximum: 500` · `default: 20` · `format: integer`
`sort`	query	string	No	Define cómo ordenar los chats `enum: ['date:asc', 'date:desc', 'lastMessage:asc', 'lastMessage:desc', 'inbound:asc']`
`assigned`	query	boolean	No	Filtra solo los chats que están actualmente asignados a algún agente de usuario (es decir, `owner.agent` tiene valor). No se puede combinar con `unassigned`.
`unassigned`	query	boolean	No	Filtra solo los chats que no están asignados a ningún agente de usuario (es decir, `owner.agent` está vacío). No se puede combinar con `assigned`.
`department`	query	array	No	Filtra los chats asignados a uno o varios departamentos por ID (24 caracteres hexadecimales). Se permiten varios IDs de departamento separados por comas.
`favorite`	query	boolean	No	Filtra solo los chats marcados como favoritos.
`pinned`	query	boolean	No	Filtra solo los chats fijados en la plataforma o en la aplicación de WhatsApp.
`spam`	query	boolean	No	Filtra solo los chats marcados como spam.
`excludeApi`	query	boolean	No	Excluye los chats cuya última actividad es un mensaje saliente en un chat sin asignar, que es la aproximación a nivel de chat de "el último mensaje se envió a través de la API". Conserva los chats que están asignados a un agente, no tienen mensajes salientes o cuyo último mensaje entrante es más reciente que el último saliente.

Respuestas

Código	Descripción
`200`	Chats
`400`	Datos de consulta o cuerpo de la solicitud no válidos
`401`	No autorizado - Token de API no válido o ausente
`403`	Faltan los permisos necesarios
`404`	Recurso no encontrado
`409`	Conflicto
`429`	Demasiadas solicitudes - Inténtalo de nuevo más tarde
`500`	Error inesperado
`501`	No implementado
`503`	Servicio no disponible temporalmente - Inténtalo de nuevo más tarde

// This code example requires you to have installed curl package
// Installation instructions here: https://curl.haxx.se/download.html

// Get most recent 50 chats
curl --request GET \
  --url 'https://api.getincloud.ai/v1/chat/{deviceId}/chats?size=50&page=0' \
  --header 'Token: <api token goes here>'


// Get group chats up to 30
curl --request GET \
  --url 'https://api.getincloud.ai/v1/chat/{deviceId}/chats?type=group&size=30&page=0' \
  --header 'Token: <api token goes here>'


// Search chat by phone number 
curl --request GET \
  --url 'https://api.getincloud.ai/v1/chat/{deviceId}/chats?phone=%2B123456789' \
  --header 'Token: <api token goes here>'

AnteriorAsignar chat SiguienteBuscar estados

¿Te sirvió esta página?