Eventos de sesión externos

La capacidad de eventos de sesión externos permite la transmisión de datos en tiempo real desde CCAI Platform a tus sistemas externos mediante 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 la transmisión para notificar a tu servidor cada vez que cambia el estado de un chat o una llamada de voz. Al proporcionar un extremo de API, CCAI Platform enviará datos de eventos con formato JSON a tu infraestructura a medida que se produzcan las 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 CCAI Platform, haz clic en Configuración > Configuración para desarrolladores. 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 Eventos de sesión externos y, luego, haz clic en el botón de activación para colocarlo en la posición de activado.

  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: Enviar evento de sesiones de llamadas.

      2. En el campo Extremo de API, 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 Extremo de API, 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 una 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 de estado

Orden de eventos Estado Estado del participante Puntos de datos clave agregados
1. Iniciar connected Externo: connected call_id, dn del cliente (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 Cantidad de objetos de eventos 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: Son 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.
  • Acuse de recibo: Tu extremo debe mostrar un código de estado 200 OK. La plataforma puede usar reintentos de retirada exponencial si se recibe un código que no sea 200.

Cargas útiles de muestra

A continuación, se muestran cargas útiles de muestra que se reciben en mensajes de eventos en el 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"
            }
          }
        ]
      }
    }
  ]
}