Módulo 21 · Integraciones

Read in English: Module 21 · Integrations.

Objetivo: conectar la plataforma con tus propios sistemas sin escribir código: llaves de API para tus scripts, webhooks que avisan a tu CRM, el widget del agente dentro de tu CRM y el click-to-call en tu web. Tiempo: ~10 minutos · Necesitas: acceso a la sección Seguridad del menú lateral. Todas las pantallas de este módulo viven ahí.

Cada parte termina con un enlace a la guía de desarrollador (en inglés) para quien tenga que programar el otro lado. Tú, como administrador, decides qué se conecta y a quién se le da la credencial; el equipo técnico se encarga del cómo.

Dos de estas cosas vienen apagadas

El acceso de los agentes al widget y el click-to-call están apagados por defecto y no se encienden desde tu cuenta: los enciende el founder de la plataforma, cliente por cliente (en el catálogo de banderas son widget_auth_enabled y click_to_call_enabled, con escritura reservada al founder). Si los necesitas, pídeselo a tu contacto de Dialer Digital antes de prometérselos a tu equipo o a tus visitantes.

1. Llaves de API: crear y revocar

Las claves de API (la consola las llama así) son para integraciones — scripts y servidores — que llaman a la API. Cada una es una credencial completa de tu agencia. La consola en sí no se abre con una clave: entra con tu correo y contraseña, o con el SSO de tu organización.

En Seguridad, sección Claves de API:

1. Escribe una Etiqueta que diga para qué es (el ejemplo de la pantalla es «Integración con CRM»).
2. Pulsa Crear clave.
3. Aparece el aviso «Copia esta clave ahora — no se volverá a mostrar.» Pulsa Copiar, guárdala en el gestor de secretos de quien la va a usar y pulsa Listo.

La tabla Claves muestra la etiqueta, el estado y cuándo se creó, con un resumen del tipo «N activas · N en total». Para quitar una, pulsa Revocar en su fila:

• La revocación es inmediata y permanente.
• Las claves nunca se borran: quedan en la lista, revocadas, para que las referencias antiguas de auditoría sigan resolviendo.
• De cada clave solo se guarda su SHA-256, así que nadie puede volver a mostrártela. Si se pierde, revócala y crea otra.

Una clave por integración

Crea una clave con su propia etiqueta para cada sistema. Así, si uno se compromete, revocas solo esa y no tumbas las demás.

Detalle técnico: Authentication (en inglés), sección «Managing keys».

2. Webhooks: avisar a tu CRM

Un webhook saliente empuja cada evento a tu propio sistema en el momento en que ocurre, firmado para que tu lado pueda comprobar que salió de nosotros. En Seguridad, la tarjeta Webhooks para tu CRM tiene el enlace Gestionar webhooks (en el menú: Webhooks).

Dar de alta un endpoint

1. En Dirección del endpoint escribe la dirección donde escucha tu CRM (por ejemplo https://crm.ejemplo.com/hooks/dialerdigital). Debe ser https en el puerto estándar 443 y resolver a un host público: se rechaza cualquier dirección interna y se vuelve a comprobar en el momento de enviar.
2. En Eventos a enviar marca al menos uno. La lista es fija. Según la pantalla, disposition.event lleva name, disposition, debt_id y campaign_id; carrier.health_changed avisa de un cambio de estado (up, down o unknown) de una troncal propia; y anomaly.detected avisa cuando se abre una anomalía de insights (la resolución no se avisa).
3. Pulsa Registrar endpoint.
4. Aparece el secreto de firma: «Copia ahora este secreto de firma — no se volverá a mostrar.» Pásaselo a quien programa tu lado, que lo usa para verificar cada entrega. Pulsa Listo.

En la tabla Endpoints, el estado es Entregando o Desactivado, y el secreto solo se ve como «termina en …». Los endpoints nunca se borran: Desactivar conserva el registro de qué estaba suscrito y desde cuándo, y Reactivar lo devuelve. Si tu servidor responde 410 Gone, lo apagamos nosotros y la pantalla te lo dice: corrige la dirección y reactívalo. Editar cambia la dirección (con las mismas comprobaciones que al registrarla).

Límite: 20 endpoints habilitados por cuenta. Sólo cuentan los habilitados. Si ya tienes 20, registrar uno nuevo — o pulsar Reactivar en uno desactivado — se rechaza (422, «the tenant has too many enabled webhook endpoints»): desactiva antes uno que ya no uses. Una cuenta que ya está por encima de 20 conserva todos los que tiene y siguen recibiendo; sólo se rechaza uno nuevo o reactivado. Puedes registrar la misma dirección dos veces. Base técnica: lib/dialer/webhooks.ex de core.

Rotar el secreto

Si el secreto se pierde o sale de quien debía tenerlo, pulsa Rotar secreto y confirma con Rotar ahora. Te damos uno nuevo, una sola vez. El anterior sigue funcionando durante una ventana de solape (la pantalla indica hasta cuándo: «Rotado hace poco: el secreto anterior sigue funcionando hasta …») para que tu CRM pueda cambiarse sin perder nada. La guía de desarrollador fija esa ventana en 24 h por defecto.

Leer el historial de entregas

Pulsa Entregas en la fila de un endpoint. Verás, lo más reciente primero, cada envío con su Evento, cuándo Ocurrió, el Código de respuesta y el Resultado:

Resultado en pantalla	Qué significa
Aún sin intentar	Está en cola, todavía no se ha enviado.
Reintentando	El último intento falló y habrá otro. La pantalla cuenta «N intentos hasta ahora».
Entregado	Tu servidor contestó con éxito.
Se abandonó	Se agotaron los intentos y ya no se reintenta.
Endpoint apagado	El endpoint estaba desactivado.

Para una entrega concreta, Reenviar → Enviar de nuevo encola otro intento; no se puede mientras el endpoint esté desactivado (reactívalo primero). Ver más antiguas pagina hacia atrás. Este registro nunca se edita: es lo que le enseñas a un CRM que dice que jamás lo llamamos.

Quién puede registrar y cambiar endpoints

Hay una bandera, webhook_admin_role_enforced, apagada por defecto: con ella apagada, cualquier usuario de la consola puede registrar o cambiar un endpoint; encendida, solo el rol account_admin (un member recibe 403). Encenderla es decisión del founder, que mide antes el efecto. Las lecturas y el historial siguen abiertos a cualquier usuario de tu cuenta.

Detalle técnico: Outbound webhooks (en inglés): el sobre JSON, cómo verificar la firma, la escalera de reintentos y la deduplicación.

3. El widget dentro de tu CRM

El widget del agente se incrusta en tu propio CRM, para que tus agentes llamen sin salir de él. Hay dos listas de control, y conviene no confundirlas:

• Dónde puede mostrarse el widget: los sitios permitidos (esta sección).
• Quién puede entrar en él: el acceso de agentes (más abajo).

Sitios permitidos

En el menú, Embebido del widget (título de la pantalla: Sitios permitidos):

1. En Origen del sitio escribe el sitio de tu CRM exactamente como aparece en la barra de direcciones: solo esquema, host y puerto, sin ruta. El ejemplo de la pantalla es https://crm.example.com.
2. Si quieres, ponle una Etiqueta (opcional), como «CRM de ventas».
3. Pulsa Añadir sitio. La pantalla confirma «Añadido — el widget ya puede incrustarse en este sitio.» y te enseña la forma exacta en que se guardó: esa es la que cuenta.

En la tabla Sitios, Desactivar impide la incrustación en ese sitio; Activar la devuelve. Desactivar no cierra la sesión de nadie ni revoca nada. Los sitios nunca se borran y la dirección no se edita: para cambiarla, desactiva la vieja y añade la nueva.

Acceso de los agentes

En Seguridad, Acceso de agentes al widget fija el correo y la contraseña propios de cada agente (la columna Login de widget dice si lo tiene; Cambiar contraseña la fija). Así, cada acción de llamada queda atribuida a esa persona y no a una clave compartida. Rotar o desactivar la contraseña termina de inmediato la sesión viva del agente en el widget. Fijar o quitar la contraseña de un asiento exige un administrador (o el propio agente, sobre su asiento): un inicio de sesión member sobre el asiento de otro agente recibe 403 role_forbidden. Los asientos se crean antes, en el roster de asientos.

Guardar una contraseña no enciende el acceso

El acceso al widget está apagado por defecto (widget_auth_enabled, que enciende el founder) y no está activado en todos los entornos. Donde sí lo está, un acceso se rechaza salvo que la petición venga del host publicado del widget. Ninguna de las dos cosas se cambia desde la lista de sitios permitidos ni desde esa pantalla, y la pantalla no puede confirmar su estado: consúltanos antes de prometerle a un agente que podrá entrar.

Tokens del widget

Al pie de la pantalla Sitios permitidos, Tokens del widget lista la sesión que cada agente abre al entrar (agente, etiqueta, Sitio fijado, estado vivo / caducado / revocado y cuándo Caduca). Los tokens no se emiten desde ahí: nacen cuando el agente inicia sesión. Si hay que echar a alguien, Revocar → Confirmar revocación cierra su sesión en el widget. Desactivar un sitio no revoca ningún token: son dos cosas separadas.

Detalle técnico: Agent widget (embed) (en inglés): el iframe, el puente postMessage y la seguridad del widget.

4. Click-to-call en tu web

El click-to-call deja que un visitante de tu sitio pida que lo llamen: publicas un formulario de solicitud en un sitio permitido, y cada solicitud queda ligada a la campaña, los modos y los topes que tú configuras. En Seguridad, tarjeta Click-to-call para tu sitio web → Gestionar sitios click-to-call.

Apagado por defecto

Mientras click_to_call_enabled esté apagado para tu cuenta —y viene apagado—, las dos rutas públicas del formulario responden 404 y no se guarda nada. Las solicitudes que ya existieran no se tocan: son evidencia. Lo enciende el founder; pídeselo a tu contacto antes de publicar nada.

Crear un sitio con el interruptor apagado también se rechaza: la consola muestra «La función de click-to-call no está activada en tu cuenta. Pide a tu administrador de cuenta que la active.» (la API responde 403 click_to_call_not_enabled) y no se crea ningún sitio. El siguiente paso es el mismo: pídele a tu contacto que lo encienda.

Crear un sitio

En Crear un sitio click-to-call:

1. Etiqueta del sitio: cómo lo reconocerás en la lista.
2. Campaña destino: elige una campaña (es obligatoria).
3. Llamar ahora y/o Programar llamada: marca al menos un modo.
4. Los topes: Solicitudes de la cuenta por día, Solicitudes por número al día y Solicitudes del sitio por hora.
5. Declaración del visitante: el texto exacto que el visitante debe reconocer («Reconozco: …») antes de pulsar Solicitar llamada. Cambiarlo crea la siguiente versión inmutable y se registra su SHA-256. Mientras no haya texto configurado, el formulario permanece cerrado («Sin configurar — el frame permanece cerrado»).
6. Pulsa Crear sitio y clave.

Aparece el Snippet de embebido. Cópialo ahora con Copiar snippet: la clave publicable del sitio se muestra una sola vez y no puede recuperarse desde la consola. Pásalo a quien mantiene tu web.

Gestionar y revocar

La tabla Sitios click-to-call muestra el sitio, sus modos, la versión de la declaración y el estado (Activo o «Revocado» con fecha). Configurar cambia campaña, topes o declaración. Revocar → Confirmar revocación mata la clave publicable; los registros de solicitudes existentes permanecen como evidencia.

Más abajo, Orígenes de embebido permitidos es la misma lista de la sección 3: la lista del tenant controla qué sitios pueden enmarcar el widget del agente y este formulario. Puedes añadir un origen desde ahí (Añadir origen) o abrir la lista completa con Gestionar la lista completa de orígenes.

Lo que ve el visitante

El visitante teclea su número en formato internacional (por ejemplo +13125550100), elige cuándo llamar si hay más de un modo, reconoce la declaración y pulsa Solicitar llamada. Recibe «Solicitud recibida.» sin que la confirmación revele si el número pertenece a un cliente: recibirla no garantiza que se vaya a llamar; la plataforma aplica después sus compuertas de cumplimiento y su horario.

Detalle técnico: Agent widget (embed) (en inglés). Esa guía indica, a la fecha de esta página, que el frame y su snippet de carga aún no están publicados: consúltala antes de fijar una fecha con tu equipo web.

Lo que te llevas

• Una llave de API se ve una vez; si se pierde, se revoca y se crea otra.
• Un secreto de webhook también se ve una vez; se rota con ventana de solape, y el historial de Entregas es tu prueba.
• Los sitios permitidos deciden dónde se muestra el widget; el acceso de agentes decide quién entra. Son listas distintas.
• Widget de agentes y click-to-call vienen apagados: los enciende el founder, cliente por cliente.