## 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

| Campo del formulario | Obligatorio | Qué es | Visible después de guardar |
|---|---|---|---|
| Cloudflare Account ID | Sí | ID de tu cuenta de Cloudflare | Sí |
| RealtimeKit App ID | Sí | ID de la aplicación RealtimeKit dentro de esa cuenta | Sí |
| Cloudflare API Token | Sí | Token de API con permiso **Realtime Admin** | No |

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](/hc/ajuda/articles/administration-shopify-es) 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](/hc/ajuda/articles/administration-dashboard-apps-native-surfaces-es)
- [Custom Scripts: inyectar JS/CSS](/hc/ajuda/articles/administration-custom-scripts-es)
- [Roles personalizados y gobernanza (RBAC)](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-es)
- [Registros de auditoría](/hc/ajuda/articles/administration-auditoria-es)
- [Visión general de Administración](/hc/ajuda/articles/administration-overview-es)