Contactos

Busca, crea y gestiona los contactos de tu empresa. Cada persona que interactua con tu chatbot o agentes se convierte en un contacto.

En Cliengo, un contacto representa a una persona que interactuo con tu negocio a traves de cualquier canal: el chat web de tu sitio, WhatsApp, Facebook Messenger o Instagram. Cuando un visitante deja sus datos (nombre, email, telefono) en una conversacion, Cliengo crea automaticamente un contacto asociado. Tambien podes crear contactos manualmente via API para importar leads desde otras fuentes.

Los contactos son el eje central del CRM de Cliengo: podes asignarles agentes, etiquetarlos, cambiar su estado segun avancen en tu pipeline de ventas, y consultar todo su historial de interacciones.

Buscar contactos

El endpoint GET /v1/contacts soporta busqueda fuzzy y filtros avanzados. La busqueda fuzzy significa que no necesitas escribir el nombre exacto — con una parte o una aproximacion alcanza. Podes combinar cualquier cantidad de filtros para encontrar exactamente los contactos que necesitas.

Busqueda simple

curl "https://connect.cliengo.com/v1/contacts?search=juan" \
  -H "Authorization: Bearer TU_TOKEN"

Busca en nombre, email y telefono de forma fuzzy (no necesita match exacto).

Filtros avanzados

Ejemplo con filtros combinados

curl "https://connect.cliengo.com/v1/contacts?status=new&entryMethod=WHATSAPP&dateFrom=2026-03-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer TU_TOKEN"

Crear y actualizar contactos

Ademas de los contactos que Cliengo crea automaticamente desde las conversaciones, podes crear contactos via API. Esto es util para importar leads desde un CRM externo, un formulario de tu sitio, o cualquier otra fuente de datos.

Crear un contacto

curl -X POST https://connect.cliengo.com/v1/contacts \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteId": "TU_CHANNEL_ID",
    "name": "Maria Lopez",
    "email": "[email protected]",
    "phone": "+5491155551234",
    "status": "new"
  }'

Campos obligatorios: websiteId y name. Opcionalmente podes incluir email, phone, message, status, assignedTo, note, y customFields (campos personalizados como objeto).

Actualizar un contacto

curl -X PATCH https://connect.cliengo.com/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Lopez Garcia",
    "status": "client"
  }'

Solo se actualizan los campos enviados; el resto se mantiene.

Eliminar contactos

curl -X DELETE https://connect.cliengo.com/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer TU_TOKEN"

curl -X POST https://connect.cliengo.com/v1/contacts/bulk-delete \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contacts": ["CONTACT_ID_1", "CONTACT_ID_2"]}'

Tags y notas

Los tags son etiquetas libres que podes asignar a un contacto para clasificarlo (ej: "vip", "interesado-plan-premium", "requiere-seguimiento"). Las notas son comentarios internos visibles solo para tu equipo — ideales para dejar registro de llamadas, acuerdos, o cualquier contexto relevante sobre el contacto.

Agregar tag

curl -X POST https://connect.cliengo.com/v1/contacts/CONTACT_ID/tags \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag": "vip"}'

Agregar nota

curl -X POST https://connect.cliengo.com/v1/contacts/CONTACT_ID/notes \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Cliente interesado en plan premium"}'

Ver historial del contacto

curl https://connect.cliengo.com/v1/contacts/CONTACT_ID/history \
  -H "Authorization: Bearer TU_TOKEN"

Devuelve logs y notas combinados en orden cronologico.

Estados de un contacto

Cada contacto tiene un status que representa en que etapa del ciclo de vida comercial se encuentra. Esto permite a tu equipo priorizar la gestion y hacer seguimiento del avance de cada lead:

El cambio de estado dispara el evento contact/status_changed si tenes un webhook configurado.

Origen y atribucion de leads

Cada contacto y cada conversacion traen datos de origen y canal de adquisicion, para que puedas medir la efectividad de cada canal y distinguir el trafico organico del pago.

Campos disponibles

Filtrar conversaciones por campaña

El listado de conversaciones permite filtrar por los parametros UTM:

curl "https://connect.cliengo.com/v1/conversations?utmSource=facebook&utmMedium=cpc" \
  -H "Authorization: Bearer TU_TOKEN"

Distinguir organico vs pago

Con estos campos podes clasificar el origen del lado del cliente y cruzarlo con la etapa de conversion (status), oportunidades y ventas. Heuristica simple:

Conversaciones y Mensajes

Las conversaciones son el nucleo de Cliengo. Cada interaccion con un visitante — por Web, WhatsApp, Facebook o Instagram — es una conversacion con su historial de mensajes.

Una conversacion en Cliengo representa un hilo de comunicacion entre un visitante y tu equipo. Puede originarse en el chat web de tu sitio, en WhatsApp, Facebook Messenger o Instagram Direct. Cada conversacion tiene participantes (el visitante, agentes humanos, y/o el chatbot), un historial de mensajes, y un estado (abierta o cerrada).

Las conversaciones se pueden asignar a agentes especificos, transferir entre operadores, clasificar con tags, y organizar en fases de un pipeline visual (como un CRM tipo kanban). Cuando un visitante deja datos de contacto en la conversacion, Cliengo asocia automaticamente un contacto.

Listar y filtrar conversaciones

curl "https://connect.cliengo.com/v1/conversations?status=opened&channel=WHATSAPP&limit=20" \
  -H "Authorization: Bearer TU_TOKEN"

Filtros disponibles

Conversaciones de un contacto

curl https://connect.cliengo.com/v1/conversations/contact/CONTACT_ID \
  -H "Authorization: Bearer TU_TOKEN"

Conversaciones por fase

curl https://connect.cliengo.com/v1/conversations/by-phase \
  -H "Authorization: Bearer TU_TOKEN"

Agrupa las conversaciones por fase del pipeline. Util para dashboards tipo kanban.

Metricas de asignacion e intervencion

Connect expone los datos necesarios para medir quien atiende cada conversacion y construir metricas de SLA (tiempos de gestion, primera respuesta humana, seguimiento por agente) sin interpretar logs manualmente.

Asignacion vs. intervencion

Son dos conceptos distintos y cada uno tiene su propio campo y filtro:

Listar conversaciones por agente

# Conversaciones INTERVENIDAS por un agente
curl "https://connect.cliengo.com/v1/conversations?agent=AGENT_ID" \
  -H "Authorization: Bearer TU_TOKEN"

# Conversaciones ASIGNADAS a un agente
curl "https://connect.cliengo.com/v1/conversations?preAssigned=AGENT_ID" \
  -H "Authorization: Bearer TU_TOKEN"

# Solo las que tuvieron intervencion humana (cualquier agente)
curl "https://connect.cliengo.com/v1/conversations?condition=intervened" \
  -H "Authorization: Bearer TU_TOKEN"

Fecha y hora de intervencion humana

Cada conversacion trae el array participants, donde cada participante incluye firstMessageAt y lastMessageAt. Los participantes humanos tienen type igual a user (operador interno) o externalOperator (operador externo). De ahi se derivan los dos datos clave para SLA:

// conversation = un item del listado de /v1/conversations
const humano = conversation.participants
  .filter(p => p.type === 'user' || p.type === 'externalOperator');

// Fecha y hora de la primera intervencion humana
const intervencionHumanaAt = humano
  .map(p => p.firstMessageAt)
  .filter(Boolean)
  .sort()[0];

// Fecha y hora del ultimo mensaje del agente que intervino
const ultimoMsgAgente = humano
  .map(p => p.lastMessageAt)
  .filter(Boolean)
  .sort()
  .at(-1);

Mensajes

Cada conversacion tiene un historial de mensajes ordenado cronologicamente. Los mensajes pueden ser de texto plano, imagenes, o notas internas. Podes leer todo el historial y enviar nuevos mensajes en nombre de un agente o un bot.

Leer mensajes

curl https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer TU_TOKEN"

Enviar un mensaje

curl -X POST https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "TU_USER_ID",
    "fromType": "user",
    "type": "text/plain",
    "body": "Hola, gracias por contactarnos!"
  }'

Tipos de mensaje

Enviar imagen

curl -X POST https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "TU_USER_ID",
    "fromType": "user",
    "type": "image",
    "message": {
      "url": "https://ejemplo.com/foto.jpg",
      "caption": "Foto del producto"
    }
  }'

Asignar, cerrar y notas

Estas operaciones son las que tu equipo de atencion usa dia a dia: asignar conversaciones a agentes especificos, transferirlas cuando otro miembro del equipo puede resolver mejor, cerrarlas cuando se completo la gestion, y dejar notas internas con contexto para el equipo.

Asignar a un agente

curl -X POST https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/assign \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"assignedTo": "AGENT_USER_ID"}'

Transferir a otro agente

curl -X POST https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/transfer \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transferTo": "OTRO_AGENT_ID"}'

Cerrar conversacion

curl -X POST https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/close \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isLead": true}'

El campo isLead indica si la conversacion genero un contacto valido.

Reabrir conversacion

curl -X POST https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/open \
  -H "Authorization: Bearer TU_TOKEN"

Agregar nota interna

curl -X POST https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/notes \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "El cliente pregunto por el plan enterprise"}'

Las notas son internas — visibles solo para el equipo, no para el visitante.

Fases del pipeline

Cliengo incluye un pipeline visual donde las conversaciones se organizan en fases (columnas tipo kanban). Cada empresa configura sus propias fases — por ejemplo: "Nuevo", "En negociacion", "Propuesta enviada", "Cerrado ganado", "Cerrado perdido". Mover una conversacion de fase es la forma principal de hacer seguimiento comercial.

Asignar fase

curl -X PATCH https://connect.cliengo.com/v1/conversations/CONVERSATION_ID/phases/PHASE_ID \
  -H "Authorization: Bearer TU_TOKEN"

Ver fases disponibles

curl https://connect.cliengo.com/v1/phases \
  -H "Authorization: Bearer TU_TOKEN"

Cada fase tiene id, name, order, y type (progress, success, lost).

Inbox: datos y conceptos para reportes

El Inbox es donde tu equipo gestiona las conversaciones. Si vas a construir reportes (por ejemplo con una IA generadora de apps), conviene entender qué significa cada concepto y dónde vive cada dato, porque algunos están en la conversación y otros en el contacto asociado.

Glosario

Etiquetas: de usuario/bot vs. internas de Cliengo

Esta es la confusión más común. El array tags (formato plano, legacy) mezcla tus etiquetas de negocio con etiquetas internas/sistémicas de Cliengo. Las internas siguen patrones reconocibles:

• Prefijos posted_ (ej. posted_email, posted_phone, posted_international_phone) y fired_ (ej. fired_new_lead).
• Flags de estado: is_intervened, was_intervened, automatic_transfer, external_robot, post_lead, no_lead.

Recomendado: usá operatorTags en vez de tags. Cada item trae tagName y source (human = agente, chatbot = flujo del bot, ai = auto-etiquetado), y no incluye las internas. Si necesitás usar tags, filtrá las internas:

// Opción A (recomendada): etiquetas de negocio desde operatorTags
const etiquetas = (conversation.operatorTags || []).map(t => t.tagName);

// Opción B: limpiar el array legacy `tags`
const INTERNAS = /^(posted_|fired_|is_intervened|was_intervened|automatic_transfer|external_robot|post_lead|no_lead)/;
const tags = Array.isArray(conversation.tags) ? conversation.tags : [];
const etiquetasUsuario = tags.filter(t => !INTERNAS.test(t));

Valor monetario por etapa

El monto del negocio está en amount de cada conversación (puede ser null o 0 si no se cargó). Para sumarlo por etapa, agrupá por phaseId y resolvé el nombre con /v1/phases:

// phases = GET /v1/phases  → { id: name }
const nombreEtapa = Object.fromEntries(phases.map(p => [p.id, p.name]));
const montoPorEtapa = {};
for (const c of conversaciones) {
  const etapa = nombreEtapa[c.phaseId] || 'Sin etapa';
  montoPorEtapa[etapa] = (montoPorEtapa[etapa] || 0) + (Number(c.amount) || 0);
}

Puntuación (estrellas) del lead

El rating (1–5 estrellas, 0 = sin puntuar) vive en el contacto, no en la conversación. Traé el contacto de la conversación por su contactId:

# el rating viene en el contacto
curl "https://connect.cliengo.com/v1/contacts?limit=100" \
  -H "Authorization: Bearer TU_TOKEN"
# cruzá conversation.contactId con contact.id y leé contact.rating

WhatsApp Templates (HSM)

Envia mensajes proactivos a tus clientes via WhatsApp usando templates pre-aprobados por Meta. Ideal para seguimiento, recordatorios y campañas.

WhatsApp tiene reglas estrictas sobre que mensajes pueden enviar las empresas. Existen dos tipos de comunicacion:

Mensajes dentro de la ventana de 24 horas: Cuando un cliente te escribe, tenes 24 horas para responder libremente con cualquier mensaje. Pasadas las 24 horas, la ventana se cierra.

Mensajes fuera de la ventana (templates/HSM): Para contactar a un cliente despues de las 24 horas, necesitas usar un template pre-aprobado por Meta. Estos templates tienen un formato fijo con variables reemplazables y deben pasar un proceso de revision antes de poder usarlos.

Templates

Los templates de WhatsApp (tambien llamados HSM — Highly Structured Messages) son mensajes con un formato aprobado por Meta. Cada template pertenece a una categoria que determina su uso permitido, y puede incluir variables ({{1}}, {{2}}) que se reemplazan con datos reales al momento del envio.

Categorias

Listar canales WhatsApp

curl https://connect.cliengo.com/v1/whatsapp \
  -H "Authorization: Bearer TU_TOKEN"

Devuelve los canales de tu cuenta que tienen WhatsApp configurado. Necesitas el channelId para las operaciones siguientes.

Listar templates

curl https://connect.cliengo.com/v1/whatsapp/CHANNEL_ID/templates \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta:

{
  "result": [
    {
      "id": 170,
      "elementName": "promo_belleza_personalizada",
      "status": "APPROVED",
      "category": "MARKETING",
      "text": "Hola {name}, tenemos una oferta especial para vos!",
      "language": "es_AR",
      "components": [...]
    }
  ]
}

Crear template

curl -X POST https://connect.cliengo.com/v1/whatsapp/CHANNEL_ID/templates \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "seguimiento_venta",
    "language": "es_AR",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hola {{1}}, tu pedido #{{2}} esta en camino."
      }
    ]
  }'

El template se envia a Meta para aprobacion. El proceso puede tardar de minutos a horas.

Enviar mensajes

Una vez que tenes un template aprobado, podes enviar mensajes a contactos existentes de Cliengo (usando su ID) o directamente a un numero de telefono. En ambos casos necesitas el channelId de tu linea de WhatsApp.

A contactos de Cliengo

curl -X POST https://connect.cliengo.com/v1/whatsapp/CHANNEL_ID/messages \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "170",
    "contacts": ["CONTACT_ID_1", "CONTACT_ID_2"]
  }'

A un numero directo (notificacion)

curl -X POST https://connect.cliengo.com/v1/whatsapp/CHANNEL_ID/notifications \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "170",
    "destination": "+5491155551234",
    "variables": {
      "1": "Maria",
      "2": "ORD-5678"
    }
  }'

Las variables reemplazan los placeholders {{1}}, {{2}} del template.

Campañas

Las campañas permiten enviar un template masivamente a una lista de contactos. Connect expone las campañas en modo solo lectura: podes consultar su estado y su reporte detallado de envios (enviado, entregado, leido, fallido).

Estados de campana

Ver reporte de campana

curl https://connect.cliengo.com/v1/whatsapp/CHANNEL_ID/campaigns/CAMPAIGN_ID/full \
  -H "Authorization: Bearer TU_TOKEN"

Devuelve el detalle de la campana con contadores por estado (sent, delivered, read, failed) y el detalle de cada mensaje individual. Tambien disponible en version resumida con /simple en lugar de /full.

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tus conversaciones y contactos.

Que son los webhooks

Los webhooks permiten que tu servidor reciba notificaciones automaticas cuando ocurren eventos en Cliengo. En vez de hacer polling periodico a la API, Cliengo envia un POST HTTP a una URL que vos configuras cada vez que pasa algo relevante — por ejemplo, cuando se crea una conversacion nueva o un contacto cambia de estado.

Configuracion rapida

1. Crear un endpoint en tu servidor

Tu servidor necesita un endpoint HTTP que acepte POST y responda 200 OK:

app.post('/webhook', (req, res) => {
  const { event, data, test } = req.body;

  // Ignorar eventos de prueba si queres
  if (test) {
    return res.status(200).json({ received: true, test: true });
  }

  console.log(`Evento recibido: ${event}`, data);

  // Responder 200 inmediatamente
  res.status(200).json({ received: true });

  // Procesar el evento de forma asincrona
  processEvent(event, data).catch(console.error);
});

2. Crear el webhook via API

curl -X POST https://connect.cliengo.com/v1/webhooks \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/webhook",
    "eventTypes": ["conversation/created", "contact/created"],
    "retryCount": 5
  }'

Respuesta:

{
  "id": "60a1b2c3d4e5f6a7b8c9d0e1",
  "url": "https://tu-servidor.com/webhook",
  "eventTypes": ["conversation/created", "contact/created"],
  "isActive": true,
  "secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
  "retryCount": 5,
  "customHeaders": {},
  "createdAt": "2026-03-29T12:00:00.000Z",
  "updatedAt": "2026-03-29T12:00:00.000Z"
}

3. Verificar conectividad

Antes o despues de crear el webhook, podes probar que tu URL es accesible:

curl -X POST https://connect.cliengo.com/v1/webhooks/ping \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tu-servidor.com/webhook"}'

Eventos disponibles

Los eventos siguen el formato categoria/accion. Podes suscribirte a cualquier combinacion.

Conversaciones (11 eventos)

Contactos (6 eventos)

Payload de eventos

Cada entrega es un POST HTTP con los siguientes headers y body:

Headers

Body

{
  "event": "conversation/created",
  "timestamp": "2026-03-29T12:00:00.000Z",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "companyId": "507f191e810c19729de860ea",
    "websiteId": "507f191e810c19729de860eb",
    "visitorName": "Juan Perez",
    "visitorEmail": "[email protected]",
    "channel": "WEBSITE",
    "status": "ACTIVE",
    "assignedTo": null,
    "createdAt": "2026-03-29T12:00:00.000Z"
  }
}

{
  "event": "contact/status_changed",
  "timestamp": "2026-03-29T14:30:00.000Z",
  "data": {
    "id": "507f1f77bcf86cd799439012",
    "companyId": "507f191e810c19729de860ea",
    "name": "Juan Perez",
    "email": "[email protected]",
    "status": "client",
    "previousStatus": "new",
    "changes": {
      "status": { "before": "new", "after": "client" }
    }
  }
}

Eventos de prueba

Los eventos enviados con el endpoint /test incluyen "test": true:

{
  "event": "conversation/created",
  "webhookId": "60a1b2c3d4e5f6a7b8c9d0e1",
  "timestamp": "2026-03-29T12:00:00.000Z",
  "test": true,
  "data": {
    "id": "test-1711713600000",
    "message": "This is a test event from Cliengo"
  }
}

Seguridad

Verificar el secret

Cada webhook tiene un secret unico (formato whsec_...) que se envia en el header X-Webhook-Secret de cada entrega. Verificalo en tu servidor para asegurarte de que la request viene de Cliengo:

app.post('/webhook', (req, res) => {
  const secret = req.headers['x-webhook-secret'];

  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Invalid secret' });
  }

  // Procesar evento...
  res.status(200).json({ received: true });
});

Reintentos

Si tu servidor no responde o devuelve un error, Cliengo reintenta la entrega automaticamente:

Historial de entregas

Consulta el historial de entregas de un webhook para debugging:

curl https://connect.cliengo.com/v1/webhooks/WEBHOOK_ID/logs \
  -H "Authorization: Bearer TU_TOKEN"

Cada entrada del log incluye:

Gestion de webhooks

Actualizar eventos suscritos

curl -X PUT https://connect.cliengo.com/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypes": ["conversation/created", "conversation/archived", "contact/status_changed"]
  }'

Desactivar temporalmente

curl -X PATCH https://connect.cliengo.com/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'

Eliminar

curl -X DELETE https://connect.cliengo.com/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer TU_TOKEN"

Buenas practicas

1. Responde 200 inmediatamente — procesa el evento de forma asincrona. Si tu servidor tarda mas de 10 segundos, Cliengo lo interpreta como timeout y reintenta.
2. Implementa idempotencia — por los reintentos, es posible que recibas el mismo evento mas de una vez. Usa el webhookId + timestamp como clave para deduplicar.
3. Verifica el secret — siempre compara el header X-Webhook-Secret con el secret de tu webhook para evitar requests falsas.
4. Usa HTTPS — tu endpoint debe usar HTTPS para proteger los datos en transito.
5. Monitorea los logs — revisa periodicamente el historial de entregas para detectar fallos.
6. Maneja eventos de prueba — los eventos con "test": true se envian desde el boton "Probar" del dashboard. Podes ignorarlos o procesarlos como quieras.