Eventos de sesión externos

La capacidad de eventos de sesión externos permite la transmisión de datos en tiempo real desde la plataforma de CCAI a tus sistemas externos a través de webhooks. Esto proporciona visibilidad inmediata de los ciclos de vida de las sesiones para la generación de informes personalizados, las actualizaciones de registros de CRM o los flujos de trabajo automatizados posteriores a la interacción.

Los eventos de sesión externos proporcionan un mecanismo basado en envíos para notificar a tu servidor cada vez que cambia el estado de un chat o una llamada de voz. Si proporcionas un extremo de API, la plataforma de CCAI enviará datos de eventos con formato JSON a tu infraestructura a medida que se produzcan transiciones (por ejemplo, llamada conectada, agente asignado, sesión desconectada).

Configura eventos de sesión externos

Para configurar eventos de sesión externos, 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. En el panel Exportación de datos de sesión, haz clic en Administrar la configuración de exportación de datos. Aparecerá la página Exportación de datos de sesión.

  3. Ve al panel External Session Events y, luego, haz clic en el botón de activación para habilitarlo.

  4. Realiza una o ambas de las siguientes acciones:

    • Para configurar eventos de sesión de llamadas externas, haz lo siguiente:

      1. Selecciona la casilla de verificación Eventos de llamadas: Envía el evento de sesiones de llamadas.

      2. En el campo API Endpoint, ingresa la URL HTTPS completa de tu API de destino.

      3. Ingresa el nombre de usuario y la contraseña. La plataforma los usa para la autenticación básica.

    • Para configurar eventos de sesión de chat externos, haz lo siguiente:

      1. Selecciona la casilla de verificación Eventos de chat: Enviar evento de sesiones de chat.

      2. En el campo API Endpoint, ingresa la URL HTTPS completa de tu API de destino.

      3. Ingresa el nombre de usuario y la contraseña. La plataforma los usa para la autenticación básica.

  5. Haz clic en Guardar.

Ciclo de vida del evento y lógica de estado

A medida que avanza la sesión, CCAI Platform envía varias actualizaciones. Cada actualización enriquece el objeto item con más metadatos a medida que están disponibles.

Tabla de progresión del estado

Orden de eventos Estado Estado del participante Se agregaron puntos de datos clave
1. Comenzar connected Externo: connected call_id, Cliente dn (número de teléfono).
2. Enrutamiento connected Externo: connected queue_path_names, initiator (Agente virtual).
3. Asignadas connected Agente: accepted Se agregan el nombre y el ID del agente en vivo.
4. Activo connected Agente: connected Se estableció la transmisión de medios (comienza la conversación).
5. Finalizar disconnected Ambos: disconnected Se propaga la marca de tiempo ends_at.
6. Final disconnected Agente: dispositionSubmitted Objeto dispositions que contiene códigos de resumen.

Referencia del esquema de datos de eventos

Los eventos se envían al webhook en un objeto. Cada evento de webhook tiene la misma estructura, que se muestra en la siguiente tabla:

Objeto raíz

Campo Tipo Descripción
count Número entero Es la cantidad de objetos de evento en la carga útil actual.
events Arreglo Es una colección de objetos de eventos que contienen detalles de la sesión.

Campos clave de la sesión

  • event_id: Es un UUID para la notificación del evento.
  • timestamp: Es la hora de la época en milisegundos en la que se generó el evento.
  • connected_at y ends_at: Marcas de tiempo ISO 8601 para la duración de la sesión.
  • initiator: Identifica la entidad que controló el cambio de estado, por ejemplo, virtual_agent_15 o agent_1.
  • dispositions: Es un objeto anidado que contiene code, custom_code_id y cualquier note del agente.

Seguridad

Todas las solicitudes se envían con un encabezado de autorización estándar: Authorization: Basic <base64_encoded_credentials>

Requisitos de la entrega

  • Método: POST
  • Content-Type: application/json
  • Tiempo de espera: Tu servidor debe responder en un plazo de cinco segundos.
  • Confirmación: Tu extremo debe devolver un código de estado 200 OK. La plataforma podría usar reintentos de retirada exponencial si se recibe un código que no es 200.

Cargas útiles de ejemplo

A continuación, se muestran ejemplos de cargas útiles que se reciben en los mensajes de eventos del webhook.

Conversación activa (medios conectados)

{
  "count": 1,
  "events": [
    {
      "event_id": "fc066edb-d99f-4db4-ba04-fb5dfea0e86a",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "connected",
        "queue_path_names": "Test/Talk to Andrew/English",
        "participants": [
          { "state": "connected", "type": "external", "dn": "+15555555555" },
          { "state": "connected", "type": "agent", "name": "Joe Smith", "agent_number": "528431" }
        ]
      }
    }
  ]
}

Disposición final (trabajo posterior a la llamada)

{
  "count": 1,
  "events": [
    {
      "event_id": "479798ff-b1ed-4a5c-a910-17a7edb3f283",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "disconnected",
        "participants": [
          {
            "type": "agent",
            "state": "dispositionSubmitted",
            "dispositions": {
              "code": "Call completed",
              "custom_code_id": "callComplete",
              "note": "none"
            }
          }
        ]
      }
    }
  ]
}