Webhooks para la plataforma de la API de chat

Con los webhooks, la API de Apps envía a tu aplicación una notificación en tiempo real cada vez que se produce un evento relevante durante una sesión de chat, por ejemplo, cuando se crea un chat, se recibe un mensaje o se transfiere o deriva un chat. Usa webhooks para reaccionar a la actividad del chat a medida que sucede en lugar de sondear la API.

Los webhooks se limitan a las sesiones de chat en la API de Apps. Contact Center AI Platform entrega todos los eventos de webhook de chat de la API de las apps compatibles como solicitudes HTTP POST a una sola URL de webhook que configures. No hay suscripciones por evento.

Antes de comenzar

  • Para configurar webhooks, debes ser administrador (o tener un rol con permiso para editar la configuración del desarrollador).
  • Prepara un extremo que pueda recibir solicitudes POST HTTP. La URL del webhook debe usar HTTPS.

Cómo activar los webhooks

Cuando activas los webhooks, Contact Center AI Platform entrega eventos de webhook a la URL que configuraste, y aparecen los campos de URL y secreto. Cuando los webhooks están desactivados, no se envían eventos.

Para activar los webhooks, sigue estos pasos:

  1. En el portal de la Plataforma de CCAI, haz clic en Configuración > Configuración del desarrollador. Si no ves el menú Configuración, haz clic en Menú.
  2. Ve al panel Webhooks y, luego, haz clic en el botón de activación Webhooks para activarlo.

Configura la URL del webhook

  1. En URL, ingresa el extremo de tu webhook.
  2. Confirma que el extremo use HTTPS y pueda recibir solicitudes POST. Contact Center AI Platform envía todos los eventos admitidos a esta única URL.

Genera secretos de firma

Contact Center AI Platform firma cada solicitud de webhook para que tu aplicación pueda confirmar que la solicitud provino de Contact Center AI Platform. Envía la firma en el encabezado de la solicitud X-Signature y la marca de tiempo de la firma en X-Signature-Timestamp. Puedes configurar hasta dos secretos de firma:

  • Secreto principal: Es el token principal que se usa para firmar solicitudes de webhook.
  • Secondary secret: Es un segundo token opcional. Cuando se establece un secreto secundario, Contact Center AI Platform firma cada solicitud con ambos secretos, lo que te permite rotar los secretos sin perder eventos.

Genera cada secreto por separado. Para generar un secreto, sigue estos pasos:

  1. En el portal de la Plataforma de CCAI, haz clic en Configuración > Configuración del desarrollador. Si no ves el menú Configuración, haz clic en Menú.
  2. Ve al panel Webhooks.
  3. En la sección Primary Secret, haz clic en Generate. Haz clic en Copiar para copiar un secreto y almacenarlo de forma segura. El secreto completo solo se muestra inmediatamente después de generarlo. Luego, se enmascara.
  4. Opcional: En la sección Secondary Secret, haz clic en Generate. Haz clic en Copiar para copiar un secreto y almacenarlo de forma segura.
  5. Confirma la acción en el cuadro de diálogo de advertencia. Un nuevo secreto entra en vigencia de inmediato, por lo que falla todo lo que aún use un secreto reemplazado.

Rota los secretos de firma

Cuando existe un secreto principal, se encuentra disponible la acción Rotate Secrets. Rotar tus secretos periódicamente es una práctica recomendada de seguridad. Dado que Contact Center AI Platform firma cada solicitud con los secretos principal y secundario, puedes rotar los secretos sin interrumpir la entrega:

  1. En el portal de la Plataforma de CCAI, haz clic en Configuración > Configuración del desarrollador. Si no ves el menú Configuración, haz clic en Menú.
  2. Asegúrate de que se establezcan un secreto principal y uno secundario.
  3. Haz clic en Rotar secretos para intercambiar los secretos principal y secundario.
  4. Actualiza tu aplicación para verificar las firmas con el nuevo secreto activo. Durante la superposición, Contact Center AI Platform firma cada solicitud con los dos secretos configurados, por lo que se acepta cualquiera de ellos y no se interrumpe la entrega.

Guarda la configuración

Selecciona Guardar para aplicar el estado habilitado y la URL del webhook. La generación o rotación de un secreto se aplica de inmediato y no requiere una operación de guardado. Contact Center AI Platform comienza a entregar eventos después de que se habilitan los webhooks y se configuran una URL de webhook y un secreto principal.

Qué recibe tu aplicación

Después de habilitar los webhooks, Contact Center AI Platform envía una solicitud HTTP POST para cada evento de chat admitido, como cambios en el ciclo de vida, actividad de los participantes, mensajes, transferencias, derivaciones, formularios web y advertencias de descarte. Cada cuerpo de solicitud es un sobre JSON con event_type, timestamp, chat_id y un body específico del evento.