Externe Sitzungsereignisse

Mit der Funktion für externe Sitzungsereignisse können Sie Echtzeitdaten mithilfe von Webhooks von der CCAI-Plattform in Ihre externen Systeme streamen. So erhalten Sie sofort Einblick in die Sitzungslebenszyklen für benutzerdefinierte Berichte, CRM-Datensatzaktualisierungen 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, POSTET die CCAI-Plattform JSON-formatierte Ereignisdaten an Ihre Infrastruktur, wenn Übergänge stattfinden, z. B. Anruf verbunden, Kundenservicemitarbeiter zugewiesen, Sitzung getrennt.

Externe Sitzungsereignisse konfigurieren

So konfigurieren Sie externe Sitzungsereignisse:

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

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

  3. Rufen Sie den Bereich Externe Sitzungsereignisse auf und klicken Sie dann auf den Ein/Aus-Schalter, um ihn auf „Ein“ zu stellen.

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

    • So konfigurieren Sie Ereignisse für externe Anrufsitzungen:

      1. Aktivieren Sie das Kästchen Anrufe – 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 Ereignisse für externe Chatsitzungen:

      1. Wählen Sie das Kästchen Chat-Ereignisse – Ereignis „Chat-Sitzungen senden“ aus.

      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 CCAI Platform mehrere Updates. Bei jeder Aktualisierung werden dem item-Objekt weitere Metadaten hinzugefügt, sobald sie verfügbar sind.

Tabelle mit Statusübergängen

Ereignisreihenfolge Bundesland Teilnahmestatus Wichtige Datenpunkte hinzugefügt
1. Start connected Extern: connected call_id, Kundennummer dn (Telefonnummer).
2. Routing connected Extern: connected queue_path_names, initiator (Virtual Agent).
3. Zugewiesen connected KI-Agent: accepted Der Name und die ID des Kundenservicemitarbeiters werden hinzugefügt.
4. Aktiv connected KI-Agent: connected Medienstream wird eingerichtet (Unterhaltung beginnt).
5. Ende disconnected Beide: disconnected Der Zeitstempel für ends_at ist ausgefüllt.
6. Final disconnected KI-Agent: dispositionSubmitted dispositions-Objekt mit Wrap-up-Codes.

Referenz zum Schema für Ereignisdaten

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, zu der 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 verarbeitet hat, z. B. virtual_agent_15 oder agent_1.
  • dispositions: Ein verschachteltes Objekt, das code, custom_code_id und alle Agenten-note enthält.

Sicherheit

Alle Anfragen werden mit einem Standard-Autorisierungsheader gesendet: Authorization: Basic <base64_encoded_credentials>

Bereitstellungsanforderungen

  • Methode:POST
  • Content-Type:application/json
  • Zeitüberschreitung:Ihr Server sollte innerhalb von fünf Sekunden antworten.
  • Bestätigung:Ihr Endpunkt muss den Statuscode 200 OK zurückgeben. Die Plattform kann Wiederholungsversuche mit exponentiellem Backoff verwenden, wenn ein Code ungleich 200 empfangen wird.

Beispielnutzlasten

Nachfolgend finden Sie Beispielnutzlasten, die in Ereignisnachrichten an den Webhook empfangen werden.

Aktive Unterhaltung (Medien 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" }
        ]
      }
    }
  ]
}

Endgültige Disposition (Arbeit nach dem Anruf)

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