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 report personalizzati, aggiornamenti dei record CRM o flussi di lavoro post-interazione automatizzati.

Gli eventi di sessione esterni forniscono un meccanismo basato sul push per notificare al 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 dei dati di sessione, fai clic su Gestisci impostazioni di esportazione dei dati. Viene visualizzata la pagina Esportazione dati sessione.

  3. Vai al riquadro Eventi di sessione esterni e poi fai clic sul pulsante di attivazione/disattivazione per attivarlo.

  4. Esegui una o entrambe le seguenti operazioni:

    • Per configurare gli eventi della sessione di chiamata esterna:

      1. Seleziona la casella di controllo Eventi di chiamata - Invia evento 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 della sessione di chat esterna:

      1. Seleziona la casella di controllo Eventi di chat - Invia evento 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.

Logica di stato e ciclo di vita degli eventi

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 dell'evento Stato Stato partecipante Punti dati chiave aggiunti
1. Inizia connected Esterno: connected call_id, cliente dn (numero di telefono).
2. Routing connected Esterno: connected queue_path_names, initiator (agente virtuale).
3. Assegnata 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. Fine disconnected Entrambi: disconnected Il timestamp ends_at viene compilato.
6. Finale disconnected Agente: dispositionSubmitted Oggetto dispositions contenente i codici di chiusura.

Riferimento allo schema dei dati sugli eventi

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

Oggetto principale

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 dell'epoca in millisecondi in cui è stato generato l'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 agente note.

Sicurezza

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

Requisiti di pubblicazione

  • 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 di backoff esponenziale se viene ricevuto un codice diverso da 200.

Payload di esempio

Di seguito sono riportati esempi di payload ricevuti nei messaggi di eventi inviati al webhook.

Conversazione attiva (contenuti multimediali 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"
            }
          }
        ]
      }
    }
  ]
}