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.

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.

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

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. Podes programar el envio para una fecha futura o lanzarlo inmediatamente. Cliengo se encarga de enviar los mensajes respetando los limites de la linea de WhatsApp y te da un reporte detallado con el estado de cada mensaje (enviado, entregado, leido, fallido).

Crear lista de contactos

curl -X POST https://connect.cliengo.com/v1/whatsapp/CHANNEL_ID/contact-lists \
  -H "Authorization: Bearer TU_TOKEN" \
  -F "[email protected]"

Subi un archivo Excel con los contactos. La API devuelve un contactListId.

Crear campana

curl -X POST https://connect.cliengo.com/v1/whatsapp/CHANNEL_ID/campaigns \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "170",
    "contactListId": "CONTACT_LIST_ID",
    "scheduledAt": "2026-04-01T10:00:00Z"
  }'

Si omitis scheduledAt, la campana se envia inmediatamente.

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.

Cancelar campana programada

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

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",
  "webhookId": "60a1b2c3d4e5f6a7b8c9d0e1",
  "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",
  "webhookId": "60a1b2c3d4e5f6a7b8c9d0e1",
  "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.