Integraciones: proveedores, credenciales, OAuth, webhooks y API

Visión general

Las Integraciones conectan ConversaLabs con el resto de tu ecosistema. Desde el área de integraciones activas conexiones listas y creas tus propios puntos de extensión:

• Slack: refleja conversaciones en un canal de Slack y responde desde allí.
• Dialogflow: conecta un bot de Dialogflow para respuestas automáticas.
• Notion y Linear: lleva el contexto de la conversación a tus herramientas de productividad y desarrollo.
• Shopify: trae datos de pedidos/cliente de tu tienda a la atención.
• Llamadas de video y voz (Cloudflare RealtimeKit): el agente inicia una llamada con el cliente dentro de la propia conversación. Esta integración antes se llamaba Dyte y ahora funciona con Cloudflare RealtimeKit — las credenciales cambiaron.
• Proveedores por credencial: conecta traducción, video, CRM, IA, voz y búsqueda con tus propias claves o cuentas de servicio.
• Webhooks: recibe eventos de la plataforma en tu propio endpoint, en tiempo real.
• Aplicaciones de panel (Dashboard Apps): incrusta tu aplicación web en la conversación o barra lateral de la cuenta, con audiencia, orden y compatibilidad nativos cuando están habilitados.
• API: automatiza e integra mediante tokens de acceso.

Requisitos previos

• Rol de Administrador o un rol nativo con el permiso Gestionar integraciones para configurar conexiones de la cuenta.
• Credenciales/cuentas de las herramientas que vas a conectar (por ejemplo, workspace de Slack, proyecto de Dialogflow, tienda Shopify).
• Para webhooks/API: un endpoint accesible y/o un token de acceso generado en la cuenta.
• Para llamadas de video/voz: una cuenta de Cloudflare con una aplicación RealtimeKit creada y un token de API con permiso Realtime Admin. Conectar y desconectar esta integración pide el mismo acceso que las demás: Administrador o un rol nativo con Gestionar integraciones.
• Para verificar la firma de los webhooks de Slack: el Signing Secret de tu aplicación de Slack, aplicado en la instalación (no por cuenta) — ver más abajo.

Paso a paso

1. Abre el área de Integraciones en Configuración.
2. Elige la integración. En los formularios por credencial, los accesos directos sobre los campos incluyen el nombre del proveedor:
   • Obtener credenciales de proveedor abre la página oficial de claves o cuentas de servicio;
   • Abrir la consola de proveedor abre la API o consola que debe habilitarse, cuando aplique;
   • Ver documentación de configuración de proveedor abre la guía oficial correspondiente.
3. Completa los campos con datos del mismo proyecto/cuenta y finaliza la creación.
4. Para webhooks, registra la URL de tu endpoint y selecciona los eventos de interés; valida la recepción en tu sistema.
5. Para la API, genera un token de acceso (perfil/agente) y úsalo en las llamadas autenticadas.
6. Prueba la integración con una conversación real antes de ponerla en producción.

Configurar llamadas de video con Cloudflare RealtimeKit

1. En Cloudflare, crea (o localiza) la aplicación RealtimeKit y anota su ID de aplicación.

2. Anota también el ID de cuenta de Cloudflare y genera un token de API con permiso Realtime Admin para esa cuenta.

3. En ConversaLabs, abre Integraciones y elige la integración de video — en español la tarjeta todavía puede aparecer con el nombre Dyte. Completa los tres campos:

   • Cloudflare Account ID
   • RealtimeKit App ID
   • Cloudflare API Token

   En esta integración, los accesos directos sobre los campos siguen apuntando a las páginas del proveedor anterior (dev.dyte.io y docs.dyte.io). Ignóralos: los tres valores salen del panel de Cloudflare.

4. Guarda. La plataforma valida las credenciales al instante: comprueba que el token esté activo y que el RealtimeKit App ID exista en esa cuenta de Cloudflare. Si algo no coincide, la conexión no se crea y el mensaje de error indica exactamente qué campo revisar.

5. Abre una conversación e inicia la llamada. La plataforma publica en la conversación un mensaje con la invitación; quien participa usa Haga clic aquí para unirse y termina con Abandonar la sala.

Si ya usabas la integración anterior (Dyte): sigue registrada, pero ya no puede abrir llamadas. Al intentar iniciar una reunión aparece el mensaje "Las credenciales de Cloudflare RealtimeKit son requeridas. Elimina la integración existente de Dyte y vuelve a crearla con las credenciales Cloudflare RealtimeKit." — y ese es exactamente el camino: eliminar la conexión antigua y crear una nueva con los tres campos de arriba. La pantalla de esta integración solo ofrece Conectar y Desconectar, así que no hay formulario para cambiar los campos antiguos (organization ID y API key) en su lugar.

Activar la verificación de firma de los webhooks de Slack

1. En el panel de tu aplicación de Slack, copia el Signing Secret.
2. Aplica el valor en la instalación, de una de estas formas:
   • en Super Admin, en el grupo de configuración de Slack, en el campo Slack Signing Secret; o
   • en la variable de entorno SLACK_SIGNING_SECRET del servidor.
3. Vuelve a enviar un evento desde Slack y confirma que la conversación sigue llegando con normalidad.

Mientras el secreto no esté configurado, la plataforma no rechaza el webhook: solo escribe un aviso en el log y procesa el evento — las instalaciones existentes siguen funcionando sin cambios. La verificación empieza a aplicarse cuando completas el secreto, y eso es lo que protege el endpoint frente a llamadas falsificadas.

Configuración y opciones

• Conexiones por autorización (Slack, Shopify, etc.): siguen el login de la herramienta externa.
• Conexiones por clave/proyecto (Dialogflow, Google Translate, Cloudflare RealtimeKit, LeadSquared y proveedores de IA, voz o búsqueda): requieren credenciales del proveedor.
• Webhooks por evento: tú eliges qué eventos quieres recibir.
• Tokens de API: trátalos como contraseñas; revócalos si se filtran o quedan en desuso.

Campos de Cloudflare RealtimeKit

Los tres campos son obligatorios y el formulario no acepta ningún campo adicional. La columna "Visible después de guardar" aplica a los administradores; el token de API nunca lo devuelve la plataforma a nadie. Como la integración solo tiene Conectar y Desconectar, cambiar cualquiera de los tres valores significa desconectar y volver a conectar.

Dónde vive el Slack Signing Secret

El secreto pertenece a la instalación, no a una cuenta. La plataforma busca el valor en este orden:

1. la configuración de instalación Slack Signing Secret (Super Admin);
2. la variable de entorno SLACK_SIGNING_SECRET.

Si el campo del panel existe pero está vacío, la variable de entorno se sigue usando — así una instalación que ya configuraba el secreto por el entorno continúa protegida después de la actualización.

La verificación usa la firma que Slack envía en las cabeceras X-Slack-Signature y X-Slack-Request-Timestamp, con HMAC-SHA256 sobre el cuerpo bruto de la solicitud. Un webhook se rechaza con 401 cuando falta alguna de esas cabeceras, cuando la marca de tiempo está a más de 5 minutos del reloj del servidor, o cuando la firma no coincide.

Casos de uso

• Notificar a un canal de Slack cuando llega una nueva conversación.
• Triaje automático con un bot de Dialogflow antes de llegar al agente.
• Crear un ticket en Linear a partir de un error reportado por el cliente.
• Mostrar datos del pedido de Shopify directamente en la pantalla de la conversación.
• Sincronizar eventos con tu CRM o ERP mediante webhooks.
• Resolver en el momento un caso complejo abriendo una llamada de video con el cliente, sin sacarlo del canal en el que ya estaba.
• Blindar el endpoint de webhooks de Slack frente a llamadas falsificadas activando el signing secret.

Consejos, límites y buenas prácticas

• Empieza por una integración, valida el flujo y luego añade otras.
• Para webhooks, implementa idempotencia y responde rápido (procesa en segundo plano).
• Guarda los tokens en variables de entorno de tu sistema — nunca en el código fuente público.
• Revisa integraciones y tokens periódicamente; elimina lo que ya no se usa.
• Da al token de Cloudflare el menor alcance posible que aún incluya Realtime Admin: es el permiso que exigen tanto la validación como las llamadas.
• Confirma que los tres campos de RealtimeKit pertenecen a la misma cuenta de Cloudflare. Un App ID válido en otra cuenta se rechaza con el mensaje de aplicación no encontrada.
• La ventana de 5 minutos de la firma de Slack depende del reloj del servidor: mantén la sincronía horaria (NTP) al día, o webhooks legítimos empezarán a rechazarse.
• Al rotar el Signing Secret en Slack, actualiza el valor en la plataforma en la misma ventana — entre el cambio y la actualización, los eventos se rechazan.

Solución de problemas

• La integración no conecta: revisa credenciales/permisos e intenta reautorizar.
• El webhook no llega: verifica que la URL sea pública, responda con éxito (2xx) y esté suscrita a los eventos correctos.
• Error 401 en la API: el token es incorrecto, expiró o fue revocado — genera uno nuevo.
• No veo la integración que quiero: puede depender del plan o de una habilitación específica.
• Shopify requiere atención: consulta la guía dedicada antes de reconectar la tienda.
• "El token de la API de Cloudflare no es válido o está inactivo": el token no pasó la verificación de Cloudflare. Crea un token nuevo con permisos de Realtime Admin.
• "El ID de cuenta de Cloudflare no es válido, o el token de la API no tiene acceso de Administrador de tiempo real a esta cuenta": el token es válido pero no alcanza esa cuenta. Revisa el ID de cuenta y el alcance del token.
• "El ID de la aplicación RealtimeKit no se ha encontrado en esta cuenta Cloudflare": la aplicación no existe en esa cuenta. Comprueba que copiaste el App ID del entorno correcto.
• "No se han podido verificar las credenciales de Cloudflare RealtimeKit en este momento": Cloudflare no respondió a tiempo o devolvió un error temporal. Intenta guardar de nuevo.
• La llamada de video no abre y pide credenciales de RealtimeKit: la conexión sigue siendo la antigua de Dyte. Elimínala y crea la integración de nuevo con los tres campos de Cloudflare RealtimeKit.
• Los eventos de Slack se detuvieron con 401: el secreto configurado no coincide con el de la aplicación de Slack, o el reloj del servidor está fuera de la ventana de 5 minutos. Compara el Signing Secret y revisa la hora del servidor.

Ver también

• Dashboard Apps: superficies nativas, audiencia y seguridad
• Custom Scripts: inyectar JS/CSS
• Roles personalizados y gobernanza (RBAC)
• Registros de auditoría
• Visión general de Administración