Eventi di sessione esterni

La funzionalità degli eventi di sessione esterni consente lo streaming di dati in tempo reale dalla piattaforma CCAI ai tuoi sistemi esterni utilizzando i webhook. In questo modo, puoi visualizzare immediatamente i cicli di vita delle sessioni per la generazione di report personalizzati, gli aggiornamenti dei record CRM o i flussi di lavoro post-interazione automatizzati.

Gli eventi di sessione esterni forniscono un meccanismo basato sul push per inviare una notifica al tuo server ogni volta che lo stato di una chat o di una chiamata vocale cambia. Fornendo un endpoint API, la piattaforma CCAI invierà i dati degli eventi in formato JSON alla tua infrastruttura man mano che si verificano le transizioni, ad esempio chiamata connessa, agente assegnato, sessione disconnessa.

Configurare gli eventi di sessione esterni

Per configurare gli eventi di sessione esterni:

  1. Nel portale della piattaforma CCAI, fai clic su Impostazioni > Impostazioni sviluppatore. Se non vedi il menu Impostazioni, fai clic su Menu.

  2. Nel riquadro Esportazione dati sessione, fai clic su Gestisci impostazioni di esportazione dati. Viene visualizzata la pagina Esportazione dati sessione.

  3. Vai al riquadro Eventi di sessione esterni e fai clic sul pulsante di attivazione/disattivazione per attivare l'opzione.

  4. Esegui una o entrambe le seguenti operazioni:

    • Per configurare gli eventi di sessione di chiamata esterni:

      1. Seleziona la casella di controllo Eventi di chiamata - Invia evento di sessioni di chiamata.

      2. Nel campo Endpoint API, inserisci l'URL HTTPS completo dell'API di destinazione.

      3. Inserisci il nome utente e la password. La piattaforma li utilizza per l'autenticazione di base.

    • Per configurare gli eventi di sessione di chat esterni:

      1. Seleziona la casella di controllo Eventi di chat - Invia evento di sessioni di chat.

      2. Nel campo Endpoint API, inserisci l'URL HTTPS completo dell'API di destinazione.

      3. Inserisci il nome utente e la password. La piattaforma li utilizza per l'autenticazione di base.

  5. Fai clic su Salva.

Ciclo di vita degli eventi e logica di stato

Man mano che una sessione procede, la piattaforma CCAI invia più aggiornamenti. Ogni aggiornamento arricchisce l'oggetto item con altri metadati man mano che diventano disponibili.

Tabella di progressione dello stato

Ordine degli eventi Stato Stato partecipante Punti dati chiave aggiunti
1. Avvia connected Esterno: connected call_id, dn del cliente (numero di telefono).
2. Elaborazione del percorso connected Esterno: connected queue_path_names, initiator (agente virtuale).
3. Assegnato connected Agente: accepted Vengono aggiunti il nome e l'ID dell'agente live.
4. Attivo connected Agente: connected Flusso multimediale stabilito (la conversazione inizia).
5. Termina disconnected Entrambi: disconnected Viene compilato il timestamp ends_at.
6. Finale disconnected Agente: dispositionSubmitted Oggetto dispositions contenente i codici di riepilogo.

Riferimento allo schema dei dati degli eventi

Gli eventi vengono inviati al webhook in un oggetto. Ogni evento webhook ha la stessa struttura, mostrata nella tabella seguente:

Oggetto root

Campo Tipo Descrizione
count Numero intero Numero di oggetti evento nel payload corrente.
events Array Una raccolta di oggetti evento contenenti i dettagli della sessione.

Campi chiave della sessione

  • event_id: un UUID per la notifica dell'evento.
  • timestamp: ora Epoch in millisecondi per la generazione dell'evento.
  • connected_at e ends_at: timestamp ISO 8601 per la durata della sessione.
  • initiator: identifica l'entità che ha gestito la modifica dello stato, ad esempio virtual_agent_15 o agent_1.
  • dispositions: un oggetto nidificato contenente code, custom_code_id e qualsiasi note dell'agente.

Sicurezza

Tutte le richieste vengono inviate con un'intestazione Authorization standard: Authorization: Basic <base64_encoded_credentials>

Requisiti di recapito

  • Metodo: POST
  • Content-Type: application/json
  • Timeout: il server deve rispondere entro cinque secondi.
  • Riconoscimento: l'endpoint deve restituire un codice di stato 200 OK. La piattaforma potrebbe utilizzare i tentativi con backoff esponenziale se viene ricevuto un codice diverso da 200.

Payload di esempio

Di seguito sono riportati i payload di esempio ricevuti nei messaggi di eventi al webhook.

Conversazione attiva (media connessi)

{
  "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" }
        ]
      }
    }
  ]
}

Disposizione finale (attività successiva alla chiamata)

{
  "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"
            }
          }
        ]
      }
    }
  ]
}