Dos Modalidades de Integración: Puente API Directo o Flujos en CLink Panel

¿Dónde obtener sus claves de API Directa y cómo resetearlas si las extravía?

Si su empresa ya cuenta con su propio software, ERP, sistema de turnos o motor conversacional y solo necesita que CLink sea el puente oficial de alta disponibilidad entre Meta y su servidor receptor, puede autenticarse directamente contra nuestro Gateway REST mediante una llave de servidor (X-Service-Key).

Cómo enviar mensajes salientes desde su sistema (POST /v1/messages)

Envíe una petición POST /v1/messages con la cabecera X-Service-Key y opcionalmente Idempotency-Key (para evitar duplicados en reintentos de red). El campo to debe ir en formato internacional E.164 con signo más (ej. +573001234567). Seleccione el tipo de mensaje (kind) para ver el JSON exacto:

// POST /v1/messages
// Headers:
//   X-Service-Key: <su_service_key>
//   Idempotency-Key: msg-orden-9821 (opcional)
{
  "phoneNumberId": "10592837465001",
  "to": "+573001234567",
  "kind": "text",
  "reference": "ORD-9821",
  "content": {
    "text": "Hola Camila, su pedido #9821 ya salió a reparto y llegará en 20 minutos."
  }
}

{
  "messageId": "01964a90-4f1c-7b2a-8a11-901234567890",
  "status": "queued"
}

Cómo recibe su servidor los mensajes entrantes y estados de WhatsApp

Cuando un cliente escribe a su línea de WhatsApp, pulsa un botón interactivo, envía un archivo o cambia el estado de un mensaje enviado (kind: "status"), el puente de CLink realiza un POST hacia el CallbackUrl configurado en su canal:

// POST hacia el CallbackUrl de su servidor
// Cabecera de seguridad enviada por CLink Gateway:
//   X-ChainSoft-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
{
  "eventId": "01964a92-1b80-7d10-9c44-001122334455",
  "phoneNumberId": "10592837465001",
  "displayNumber": "+573237818144",
  "from": "+573001234567",
  "kind": "text",
  "reference": "CITA-4410",
  "receivedAt": "2026-10-18T19:20:15.0000000+00:00",
  "payload": {
    "id": "wamid.HBgMNTczMDAxMjM0NTY3FQIAEhgg...",
    "from": "573001234567",
    "timestamp": "1760815215",
    "type": "text",
    "text": {
      "body": "Sí, confirmo mi asistencia para mañana."
    }
  }
}

Consulta de Estado, Plantillas Meta, Descarga de Multimedia y Linki LLM Directo

Cómo disparar llamadas telefónicas individuales o por lote desde su propio sistema

Si su cuenta tiene una línea de voz asignada y el plan CLink + Linki IA Premium, puede iniciar llamadas salientes con POST /v1/voice/calls o programar un grupo de llamadas a una lista con POST /v1/voice/batches. Si omite el campo mission, Linki sigue automáticamente el guion del flujo de voz activo en su cuenta.

// POST /v1/voice/calls
// Header: X-Service-Key: <su_service_key>
{
  "toPhone": "573001234567",
  "person": "Camila Gómez",
  "mission": "Saluda en nombre de Clínica Aurora, confirma su cita de dermatología para mañana a las 10:30 a. m. y pregunta si podrá asistir.",
  "metadata": {
    "citaId": "CITA-4410",
    "sede": "Chicó Norte",
    "whatsappFallbackTemplate": "recordatorio_cita_medica",
    "whatsappFallbackLanguage": "es",
    "whatsappFallbackParamCount": 2
  },
  "idempotencyKey": "call-cita-4410"
}

// POST /v1/voice/batches
// Header: X-Service-Key: <su_service_key>
{
  "audienceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Confirmación de citas viernes",
  "mission": "Saluda con amabilidad, confirma la cita programada y pregunta si asistirá o necesita reprogramar.",
  "metadata": {
    "whatsappFallbackTemplate": "recordatorio_cita_medica",
    "whatsappFallbackLanguage": "es",
    "whatsappFallbackParamCount": 2
  },
  "scheduledAt": "2026-10-30T14:00:00-05:00"
}

¿Cómo funciona CLink con WhatsApp Cloud API Oficial?

CLink conecta la línea oficial de WhatsApp de su empresa directamente a la infraestructura en la nube de Meta (WhatsApp Business Platform), eliminando el riesgo de bloqueos o desconexiones por escaneo de códigos QR no oficiales.

Flujo de Bienvenida, Flujo de Campaña y Flujo de Voz

En la pestaña «Flujos» de CLink usted puede crear tres clases de automatización según el canal y quién inicie la conversación:

Tipos de Paso en el Editor de Flujos

Arrastre y conecte pasos como un mapa. Cada uno hace una sola cosa: hablarle al cliente, pedirle datos, mostrar opciones, abrir un formulario, consultar su sistema o terminar la conversación.

Cómo usar un formulario nativo dentro del flujo

Un Formulario WhatsApp es una pantalla (o varias) que el cliente completa dentro de WhatsApp: datos de contacto, solicitud de cita, pedido, encuesta, etc. Usted lo diseña y publica en WhatsApp Manager → Flujos; en CLink solo lo enlaza a un paso.

Cómo usar Variables Dinámicas y Cargar Listas en Excel / CSV

Cuando una plantilla aprobada en Meta incluye variables como {{1}}, {{2}} o {{3}}, CLink las reemplaza automáticamente con las columnas de su archivo Excel o CSV cargado en «Audiencias»:

Bandeja Multi-Agente en Tiempo Real e Historial Auditable

• ▪ Tomar y devolver el control al Bot: Cuando un agente pulsa «Tomar chat», el flujo automático y Linki se pausan para ese contacto. Al pulsar «Devolver al bot», el flujo retoma el control.
• ▪ Bloqueo de colisiones en tiempo real: Si dos agentes intentan tomar el mismo chat en el mismo milisegundo, CLink garantiza mediante control de concurrencia que solo el primero lo tome y notifica al segundo al instante.
• ▪ Notas Internas y Respuestas Rápidas (/): Los agentes pueden dejar notas privadas que nunca se envían por WhatsApp, clasificar el chat con etiquetas y escribir /atajo para insertar respuestas rápidas preconfiguradas.
• ▪ Descanso post-cierre (24 horas): Cuando una conversación termina su flujo normal, entra en reposo durante 24 horas para no reiniciar el saludo de bienvenida si el cliente solo responde «¡Muchas gracias!». Si un agente cierra el chat manualmente, queda listo de inmediato para futuras consultas.

Cómo hacer que Linki llame por teléfono a una persona o a toda una lista de contactos

Desde el módulo «Llamada saliente» en CLink Panel, Linki puede realizar llamadas telefónicas en español natural para confirmar citas, recordar vencimientos de cartera, avisar entregas o realizar encuestas de atención:

Cómo entrenar el «Contexto del Negocio» en cada Flujo

En el panel izquierdo del editor de flujos encontrará el recuadro «Contexto del negocio (Linki IA)». Todo lo que escriba allí (hasta 8.000 caracteres por flujo) actúa como la Base de Conocimiento Oficial que Linki consulta cuando un cliente escribe una pregunta abierta en lugar de pulsar un botón.

Empresa: Clínica Dermatológica Aurora.
Horarios de atención: Lunes a Viernes de 8:00 AM a 6:00 PM, Sábados de 8:00 AM a 1:00 PM. Domingos y festivos cerrado.
Sedes:
- Sede Norte: Calle 100 #15-20, Consultorio 402 (Parqueadero gratuito por 1 hora).
- Sede Chapinero: Carrera 13 #54-10.
Tarifas vigentes:
- Consulta de valoración dermatológica: $120.000 COP.
- Limpieza facial profunda: $160.000 COP.
Medios de pago: PSE, Nequi, Daviplata, tarjetas débito/crédito y efectivo en sede.
Política de cancelación: Se puede reprogramar sin costo avisando con mínimo 4 horas de anticipación.

Cómo responde Linki sin inventar información y cómo usa la rama «Otra respuesta»

Cuando una conversación se encuentra en un paso de tipo «Pregunta con opciones» y el cliente escribe texto libre que no coincide con ninguno de los botones:

1. Memoria de Conversación (Transcript): Linki recibe automáticamente los últimos turnos de la charla junto con la pregunta actual, las opciones válidas y el Contexto del Negocio (aiContext) del flujo.
2. Regla Cero-Alucinaciones: Si el cliente pregunta por un dato que está en el Contexto del Negocio (ej. «¿A qué hora cierran los sábados y cuánto vale la valoración?»), Linki le responde con precisión en 2 a 4 oraciones y le recuerda amablemente elegir una de las opciones del paso actual para continuar.
3. Si preguntan algo no incluido en el contexto: Linki tiene estrictamente prohibido adivinar precios, descuentos, stock o políticas no escritas. Le indicará con calidez que no dispone de ese dato exacto y lo invitará a elegir una opción o hablar con un asesor.

Requisitos Técnicos para Conectar su Servidor o API con CLink

Estructura del JSON que CLink envía a su API en un paso «Conectar sistema»

Cuando la conversación llega a un paso de integración (webhook), CLink realiza una petición POST con Content-Type: application/json. Si la cuenta tiene Linki IA Premium, el campo data contiene el objeto JSON limpio extraído por Linki según las instrucciones del paso:

{
  "version": "v1",
  "id": "8f14e45f-ceea-467a-a8e4-5c19b4a28910",
  "sentAt": "2026-10-18T19:30:00.0000000+00:00",
  "flow": {
    "id": "3c91a720-6f12-4b88-911e-77a2c8910211",
    "name": "Agendamiento y Pedidos"
  },
  "step": {
    "id": "step-webhook-orden",
    "title": "Conectar con ERP"
  },
  "contact": {
    "phone": "573001234567",
    "name": "Camila Gómez",
    "reference": "CLI-9021"
  },
  "data": {
    "especialidad": "Dermatología",
    "fecha_deseada": "2026-10-20",
    "jornada": "mañana",
    "documento": "1020304050"
  },
  "replies": [
    {
      "stepId": "step-ask-servicio",
      "title": "Especialidad",
      "prompt": "¿Para qué especialidad desea consultar disponibilidad?",
      "answer": "Necesito cita de Dermatología para el martes por la mañana, mi cédula es 1020304050",
      "optionId": null
    }
  ]
}

Cómo hacer que Linki consulte su API y le responda al cliente en WhatsApp

En planes CLink + Linki IA Premium, el paso «Conectar con otro sistema» es bidireccional: CLink lee el cuerpo JSON o texto que su API devuelve en la respuesta HTTP 200 OK (hasta 8.000 caracteres) y decide automáticamente entre dos modos:

{
  "disponible": true,
  "profesional": "Dra. Laura Martínez",
  "sede": "Sede Chicó - Calle 94 #15-32",
  "horarios_disponibles": ["09:00 AM", "10:30 AM", "11:15 AM"],
  "valor_consulta": "$130.000 COP",
  "preparacion": "Asistir 15 minutos antes con documento de identidad."
}

{
  "ok": true,
  "status": "received"
}

Qué recibe su API cuando el formulario pregunta la siguiente pantalla (purpose: "flow_data_exchange")

Solo aplica si en el paso Formulario WhatsApp activó «Actualizar datos mientras el cliente lo llena» y eligió un webhook en Conectar con mi sistema (Premium). CLink hace un POST síncrono a su URL. Su respuesta debe ser un objeto JSON con al menos screen (nombre de la pantalla en Meta) y, si aplica, data (valores para rellenar esa pantalla).

{
  "version": "v1",
  "purpose": "flow_data_exchange",
  "flow": {
    "id": "3c91a720-6f12-4b88-911e-77a2c8910211",
    "name": "Captura de cita"
  },
  "step": {
    "id": "step-formulario",
    "title": "Formulario WhatsApp",
    "metaFlowId": "1516739540503594"
  },
  "contact": {
    "phone": "573001234567",
    "name": "Camila Gómez",
    "reference": "CLI-9021"
  },
  "conversationId": "8f2a1c90-4b11-4e20-9c5d-1a2b3c4d5e6f",
  "meta": {
    "action": "INIT",
    "flow_token": "…",
    "data": {}
  }
}

{
  "screen": "CONFIRM_SCREEN",
  "data": {
    "servicio": "Consulta general",
    "horarios": ["10:00", "11:30", "15:00"]
  }
}

• ▪ meta.action suele ser INIT (al abrir) o el evento de avance del formulario.
• ▪ Si su API falla o no devuelve screen, CLink cierra el formulario de forma segura para no dejar al cliente trabado.
• ▪ El resultado final del formulario también llega al chat cuando el cliente lo envía; el flujo sigue por «Qué sigue después».

Cómo devolver Productos o Servicios Dinámicos (purpose: "catalog")

Cuando utiliza un paso de tipo «Productos» (catalog), CLink envía un POST a su endpoint con "purpose": "catalog". Su API debe responder con un arreglo items (o directamente un arreglo JSON) de entre 1 y 10 opciones. Cada opción admite id (hasta 200 caracteres) y title o name (hasta 24 caracteres por requisito oficial de listas en WhatsApp):

{
  "version": "v1",
  "purpose": "catalog",
  "flow": {
    "id": "3c91a720-6f12-4b88-911e-77a2c8910211",
    "name": "Catálogo de servicios"
  },
  "step": {
    "id": "step-catalogo",
    "title": "Productos disponibles"
  },
  "contact": {
    "phone": "573001234567",
    "name": "Camila Gómez",
    "reference": ""
  },
  "replies": []
}

{
  "items": [
    { "id": "SRV-001", "title": "Consulta general" },
    { "id": "SRV-002", "title": "Valoración presencial" },
    { "id": "SRV-003", "title": "Seguimiento / control" },
    { "id": "SRV-004", "title": "Servicio a domicilio" }
  ]
}

Código Listo para Copiar en su Servidor (Node.js, .NET 8 y Python)

Seleccione el lenguaje de su backend para copiar un endpoint que valida la clave, atiende catálogo, formularios con datos al momento (flow_data_exchange) y respuestas bidireccionales a Linki IA:

import express from 'express';

const app = express();
app.use(express.json());

// Endpoint conectado en CLink -> Paso "Conectar con otro sistema"
app.post('/api/clink/webhook', async (req, res) => {
  // 1. Validar API Key configurada en CLink
  const auth = req.headers['authorization'];
  if (auth !== `Bearer ${process.env.CLINK_WEBHOOK_KEY}`) {
    return res.status(401).json({ error: 'No autorizado' });
  }

  // 2. Clave de idempotencia única por conversación + paso
  const idempotencyKey = req.headers['idempotency-key'];
  const { purpose, contact, data, replies } = req.body;

  // Caso A: Paso "Productos" (lista dinámica, máx. 10 ítems, título <= 24 chars)
  if (purpose === 'catalog') {
    return res.status(200).json({
      items: [
        { id: 'CITA-GEN', title: 'Consulta general' },
        { id: 'CITA-SEG', title: 'Seguimiento' },
        { id: 'CITA-DOM', title: 'Visita a domicilio' }
      ]
    });
  }

  // Caso B: Formulario WhatsApp con datos al momento (responde screen + data)
  if (purpose === 'flow_data_exchange') {
    const action = req.body?.meta?.action;
    if (action === 'INIT') {
      return res.status(200).json({
        screen: 'WELCOME_SCREEN',
        data: {}
      });
    }
    return res.status(200).json({
      screen: 'CONFIRM_SCREEN',
      data: {
        horarios: ['10:00', '11:30', '15:00']
      }
    });
  }

  // Caso C: Paso "Conectar con otro sistema" (JSON extraído por Linki en 'data')
  console.log('Cliente:', contact.phone, 'Datos extraídos por Linki:', data);

  // Si devuelve datos del negocio, Linki IA (Premium) le redacta la respuesta en WhatsApp:
  return res.status(200).json({
    estado_pedido: 'En preparación',
    responsable: 'Carlos Pérez',
    tiempo_estimado: '20 minutos',
    total_pagar: '$54.900 COP'
  });
});

app.listen(3000);