Externe Sitzungsereignisse

Mit der Funktion für externe Sitzungsereignisse können Sie Echtzeitdaten aus der CCAI Platform mithilfe von Webhooks in Ihre externen Systeme streamen. So erhalten Sie sofort Einblick in die Lebenszyklen von Sitzungen für benutzerdefinierte Berichte, Aktualisierungen von CRM-Einträgen oder automatisierte Workflows nach der Interaktion.

Externe Sitzungsereignisse bieten einen Push-basierten Mechanismus, um Ihren Server zu benachrichtigen, wenn sich der Status eines Chats oder Sprachanrufs ändert. Wenn Sie einen API-Endpunkt angeben, sendet die CCAI Platform JSON-formatierte Ereignisdaten per POST an Ihre Infrastruktur, wenn Übergänge stattfinden, z. B. „Anruf verbunden“, „Kundenservicemitarbeiter zugewiesen“ oder „Sitzung getrennt“.

Externe Sitzungsereignisse konfigurieren

So konfigurieren Sie externe Sitzungsereignisse:

  1. Klicken Sie im CCAI Platform-Portal auf Einstellungen > Entwicklereinstellungen. Wenn das Menü Einstellungen nicht angezeigt wird, klicken Sie auf Menü.

  2. Klicken Sie im Bereich Sitzungsdatenexport auf Einstellungen für den Datenexport verwalten. Die Seite Sitzungsdatenexport wird angezeigt.

  3. Gehen Sie zum Bereich Externe Sitzungsereignisse und klicken Sie auf die Schaltfläche, um sie zu aktivieren.

  4. Führen Sie einen oder beide der folgenden Schritte aus:

    • So konfigurieren Sie externe Anrufsitzungsereignisse:

      1. Aktivieren Sie das Kästchen Anrufereignisse – Ereignis für Anrufsitzungen senden.

      2. Geben Sie im Feld API-Endpunkt die vollständige HTTPS-URL Ihrer Ziel-API ein.

      3. Geben Sie den Nutzernamen und das Passwort ein. Die Plattform verwendet diese für die Basisauthentifizierung.

    • So konfigurieren Sie externe Chatsitzungsereignisse:

      1. Aktivieren Sie das Kästchen Chatereignisse – Ereignis für Chatsitzungen senden.

      2. Geben Sie im Feld API-Endpunkt die vollständige HTTPS-URL Ihrer Ziel-API ein.

      3. Geben Sie den Nutzernamen und das Passwort ein. Die Plattform verwendet diese für die Basisauthentifizierung.

  5. Klicken Sie auf Speichern.

Ereignislebenszyklus und Statuslogik

Im Laufe einer Sitzung sendet die CCAI Platform mehrere Aktualisierungen. Mit jeder Aktualisierung werden dem item-Objekt weitere Metadaten hinzugefügt, sobald sie verfügbar sind.

Tabelle zur Statusentwicklung

Ereignisreihenfolge Bundesland Teilnahmestatus Wichtige Datenpunkte hinzugefügt
1. Starten connected Extern: connected call_id, Kundentelefonnummer dn.
2. Routing connected Extern: connected queue_path_names, initiator (virtueller Kundenservicemitarbeiter).
3. Zugewiesen connected Kundenservicemitarbeiter: accepted Name und ID des Kundenservicemitarbeiters werden hinzugefügt.
4. Sportarmband connected Kundenservicemitarbeiter: connected Media-Stream eingerichtet (Unterhaltung beginnt).
5. Beenden disconnected Beide: disconnected Der Zeitstempel ends_at wird ausgefüllt.
6. Finale disconnected Kundenservicemitarbeiter: dispositionSubmitted dispositions-Objekt mit Abschlusscodes.

Referenz zum Ereignisdatenschema

Ereignisse werden in einem Objekt an den Webhook gesendet. Jedes Webhook-Ereignis hat dieselbe Struktur, die in der folgenden Tabelle dargestellt ist:

Root-Objekt

Feld Typ Beschreibung
count Ganzzahl Anzahl der Ereignisobjekte in der aktuellen Nutzlast.
events Array Eine Sammlung von Ereignisobjekten mit Sitzungsdetails.

Wichtige Sitzungsfelder

  • event_id: Eine UUID für die Ereignisbenachrichtigung.
  • timestamp: Epochenzeit in Millisekunden für den Zeitpunkt, zu dem das Ereignis generiert wurde.
  • connected_at und ends_at: ISO 8601-Zeitstempel für die Sitzungsdauer.
  • initiator: Gibt die Entität an, die die Statusänderung vorgenommen hat, z. B. virtual_agent_15 oder agent_1.
  • dispositions: Ein verschachteltes Objekt mit code, custom_code_id und einer beliebigen note des Kundenservicemitarbeiters.

Sicherheit

Alle Anfragen werden mit einem Standardautorisierungsheader gesendet: Authorization: Basic <base64_encoded_credentials>

Sendeanforderungen

  • Methode:POST
  • Inhaltstyp:application/json
  • Zeitlimit:Ihr Server sollte innerhalb von fünf Sekunden antworten.
  • Bestätigung:Ihr Endpunkt muss den Statuscode 200 OK zurückgeben. Die Plattform kann exponentielle Backoff-Wiederholungen verwenden, wenn ein anderer Code als 200 empfangen wird.

Beispielnutzlasten

Im Folgenden finden Sie Beispielnutzlasten, die in Ereignisnachrichten an den Webhook gesendet werden.

Aktive Unterhaltung (Media verbunden)

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

Abschließende Disposition (Anrufnachbereitung)

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