Cómo consultar contactos, tickets y mensajes en tiempo real vía API

Cuándo usar

• Quieres leer datos actuales de Cloud Chat sin modificar nada (consultar un contacto, ver los tickets de un cliente, leer los mensajes de una conversación)

• Estás integrando Cloud Chat con otro sistema (CRM, portal interno) que necesita mostrar datos en vivo

• Quieres evitar la duplicación de contactos antes de crear un ticket

Requisitos previos

• API Key de administrador — ver Cómo encontrar tu API Key en Cloud Chat

• CLOUDCHAT_DOMAIN y ACCOUNT_ID

Sobre este artículo

Las APIs de Consulta en Tiempo Real permiten leer datos actuales de Cloud Chat, directamente desde la base de producción, sin modificar nada. Son ideales para integraciones, automatizaciones y pantallas internas que necesitan responder preguntas como:

• "¿Este contacto ya existe?"

• "¿Qué tickets tiene este cliente?"

• "¿Cuál es el estado actual de este ticket?"

• "¿Qué mensajes se intercambiaron en esta conversación?"

Sobre el namespace /api/client/

Para qué sirven estas APIs

Úsalas cuando necesites:

• Leer datos ahora

• Integrar datos de Cloud Chat con otro sistema

• Mostrar información en una aplicación

• Tomar decisiones basadas en el estado actual de la atención

Para qué no sirven

Autenticación

Todos los endpoints exigen:

• {CLOUDCHAT_DOMAIN} — dominio de tu cuenta (ej.: cloudchat.cloudhumans.com)

• {ACCOUNT_ID} — ID de la cuenta

• api_access_token — para los endpoints /api/client/ (secciones 1, 2 y 3), el token debe ser de administrador — los tokens de supervisor o agente reciben 403 Forbidden. La búsqueda por texto libre (sección 1b, namespace /api/v1/) acepta tokens de cualquier perfil de agente

1. Buscar contacto por correo electrónico o teléfono

Cuándo usar

• Antes de crear un ticket (para saber si el contacto ya existe)

• Para asociar datos externos a un contacto

• Para evitar duplicación

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts?email=EMAIL&phone_number=PHONE

Reglas

• Al menos uno de los parámetros (email o phone_number) es obligatorio

• Si se envían ambos, la API intenta el match más preciso posible

Qué devuelve

• ID del contacto, nombre, correo electrónico, teléfono

• Campos personalizados

• Fechas de creación y última actividad

1b. Buscar contactos por texto libre (Search)

Cuándo usar

Para buscar un contacto por cualquier campo de texto (nombre, correo electrónico, teléfono, identificador, empresa) sin saber exactamente cuál contiene la información.

A diferencia del endpoint anterior, este realiza una búsqueda ILIKE (sin distinción de mayúsculas, parcial) en múltiples campos simultáneamente.

Endpoint

GET /api/v1/accounts/{account_id}/contacts/search?q={termo}

Parámetros

Campos consultados

• name — nombre del contacto (siempre se busca)

• email — correo electrónico (a partir de 3 caracteres con dígito)

• identifier — identificador externo (a partir de 3 caracteres con dígito)

• phone_number — teléfono, con y sin el prefijo + (a partir de 3 caracteres con dígito)

• company_name — nombre de la empresa (a partir de 3 caracteres con dígito)

Respuesta

• payload[] — array de contactos encontrados

• meta — contiene solo la página actual

Ejemplo

GET /api/v1/accounts/1/contacts/search?q=maria&page=1

Devuelve todos los contactos cuyo nombre, correo electrónico, teléfono, identifier o empresa contengan maria.

Límite de uso (rate limit)

Diferencia entre los dos endpoints de búsqueda

2. Listar los tickets de un contacto

Cuándo usar

Ya tienes el CONTACT_ID y quieres listar los tickets de ese cliente:

• Mostrar el historial de atenciones

• Ver tickets abiertos o resueltos

• Integrar con un CRM o portal interno

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/conversations?page=1&limit=10

Parámetros

• page — obligatorio

• limit — opcional (por defecto: 10)

Qué devuelve

• IDs de los tickets

• Estado (open, resolved, etc.)

• Prioridad

• Inbox

• Fechas de creación

• Si fue iniciado por una campaña

3. Listar los mensajes de un ticket

Cuándo usar

Para recuperar el historial de mensajes de un ticket:

• Auditoría en tiempo real

• Mostrar la conversación en otra interfaz

• Depurar integraciones

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/messages?page=1&limit=10

Qué devuelve

• Contenido del mensaje

• Tipo (incoming / outgoing)

• Pública o privada

• Fecha de creación

• Estado del mensaje

• Enlaces de los adjuntos (si existen)

Cómo se conectan estas APIs (flujo típico)

1. Buscar el contacto por correo electrónico o teléfono

2. Obtener el CONTACT_ID

3. Listar los tickets de ese contacto

4. Elegir un ticket

5. Listar los mensajes del ticket

Nivel de riesgo

Riesgo medio — no modifican datos, pero consultan la base de producción en tiempo real.

Errores comunes

Etiquetas (labels) de la conversación y cómo encontrar el contact_id

Las etiquetas aplicadas a la conversación tienen su propio endpoint (en Chatwoot, la base de Cloud Chat, se llaman labels):

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/labels

Para encontrar el contact_id a partir del CONVERSATION_ID no se necesita un endpoint separado — el propio detalle de la conversación ya lo devuelve:

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}

En la respuesta, meta.sender.id es el contact_id del contacto dueño de la conversación. El mismo objeto meta.sender incluye nombre, correo electrónico, teléfono y otros identificadores.

Ambos endpoints exigen un api_access_token de un usuario con el permiso adecuado.

Observaciones

• Para cambiar estado, prioridad o equipo: Cómo actualizar y actuar en tickets vía API

• Para reportes y BI (extracción histórica): Cómo extraer datos en lote vía API

• Visión general de las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API