Anleitung zur API-Einbindung für Chatplattformen

In dieser Anleitung erfahren Sie, wie Sie eine serverseitige Chat-Integration mit der Apps API erstellen. Am Ende kann Ihre Integration Folgendes:

  • Bei der Apps API authentifizieren

  • Endnutzer erstellen oder aktualisieren

  • Starten Sie einen Chat für diesen Endnutzer.

  • Webhook-Ereignisse von der Contact Center AI Platform empfangen und bestätigen.

  • Textnachrichten in den Chat senden

  • Optionale Zweige wie den Import von Pre-Chat-Transkripten, die Auswahl von Warteschlangen, das Routing von virtuellen Kundenservicemitarbeitern, die Eskalierung von Anfragen und Medienanhänge verarbeiten.

  • Beenden Sie den Chat, wenn die Unterhaltung abgeschlossen ist.

Dieser Leitfaden richtet sich an Entwickler, die einen Backend-Dienst erstellen, der eine vom Kunden bereitgestellte Chatoberfläche mit der CCAI Platform verbindet. Dabei wird davon ausgegangen, dass Sie API-Anmeldedaten in der CCAI-Plattform erstellen, einen HTTPS-Webhook-Endpunkt hosten, Geheimnisse sicher speichern und HTTP-Anfragen von Ihrem Server aus senden können.

Diese Anleitung ergänzt die Apps API-Chat-Endpunkte. Verwenden Sie die API-Referenz für das vollständige Anfrage- und Antwortschema und diesen Leitfaden für den empfohlenen End-to-End-Implementierungsablauf.

Terminologie

Die folgenden Definitionen gelten für dieses Dokument:

  • Kunde: Der CCAI Platform-Kunde, der die Chatintegration in seine eigene Software implementiert.

  • Consumer: Die serverseitige Anwendung des Kunden, die Anfragen an die Apps API sendet und CCAI Platform-Webhook-Ereignisse empfängt.

  • Endnutzer: Die Person, die die Software des Kunden verwendet, um einen Chat mit einem Kundenservicemitarbeiter oder virtuellen Kundenservicemitarbeiter zu starten oder fortzusetzen.

  • Chat: Die CCAI Platform-Konversationsressource, die von der Apps API erstellt wird.

  • Webhook-Endpunkt: Der HTTPS-Endpunkt in der Verbraucheranwendung, der Chat-Ereignisse von der CCAI-Plattform empfängt.

Hinweis

Bevor Sie beginnen, benötigen Sie Folgendes:

  • Apps API-Anmeldedaten

    • Erstellen Sie API-Anmeldedaten in der CCAI-Plattform unter Einstellungen > Entwicklereinstellungen > API-Anmeldedaten.

    • Speichern Sie das Secret für die Anmeldedaten sicher. Geben Sie ihn nicht im Browser- oder Mobilclientcode an.

  • Mandanten-URL-Details

    • CCAI Platform-Subdomain und -Domain ermitteln

    • Die Basis-URL der Apps API lautet: https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1

  • Webhook-Endpunkt

    • Hosten Sie einen öffentlichen HTTPS-Endpunkt, der POST-Anfragen von der CCAI-Plattform empfangen kann.

    • Konfigurieren Sie den Endpunkt in den Entwicklereinstellungen der CCAI Platform.

    • Generieren und speichern Sie die primären und sekundären Webhook-Secrets.

  • Warteschlangen- oder Menükonfiguration

    • Ermitteln Sie die Warteschlange oder das Menü, in die neue Chats eingehen.

    • Wenn Sie einen virtuellen Kundenservicemitarbeiter zur Auswahl von Warteschlangen verwenden, konfigurieren Sie diesen virtuellen Kundenservicemitarbeiter und weisen Sie ihn der Eingangs-Warteschlange zu, bevor Sie Chats über die API erstellen.

  • Identität des Endnutzers

    • Legen Sie fest, welche stabile Kennung Ihr System für jeden Endnutzer verwendet.

    • Speichern Sie die von der Apps API zurückgegebene CCAI Platform-Endnutzer-ID.

  • Umgang mit Ratenbegrenzungen

    • Die Apps API unterliegt Ratenbeschränkungen durch die CCAI Platform. Bauen Sie Wiederholungsversuche und Backoff in Ihre Integration ein und vermeiden Sie das Senden von Anfragen in kurzen Abständen für einen einzelnen Mandanten.

Authentifizierung und Webhook-Sicherheit

Ihre Integration verwendet zwei Authentifizierungspfade:

  • Apps API-Authentifizierung für Anfragen von Ihrem Server an die CCAI Platform.

  • Webhook-Signaturprüfung für Anfragen von der CCAI Platform an Ihren Server.

Apps API-Anfragen authentifizieren

Für Anfragen wird die HTTP-Basisauthentifizierung verwendet. Erstellen Sie in der CCAI-Plattform unter Einstellungen > Entwicklereinstellungen > API-Anmeldedaten ein API-Token und übergeben Sie es im Feld password (empfohlen). Wenn in Ihrem Mandanten der alte Authentifizierungspfad verwendet wird, können Sie stattdessen Ihren Unternehmensschlüssel als Nutzernamen und Ihr Unternehmensgeheimnis als Passwort übergeben. Die vollständige Einrichtung der Authentifizierung finden Sie in der Apps API-Referenz. Im folgenden Beispiel wird gezeigt, wie Sie eine Apps API-Anfrage mit der einfachen Authentifizierung authentifizieren:

curl -X GET \
  https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1/chats/{chat_id} \
  -u "YOUR_SUBDOMAIN:YOUR_API_TOKEN" \
  -H "Accept: application/json"

Speichern Sie Anmeldedaten in einem serverseitigen Secret Store, rotieren Sie sie gemäß Ihrer Sicherheitsrichtlinie und geben Sie sie niemals in Browser- oder mobilen Apps an.

Webhook-Anfragen bestätigen

CCAI Platform sendet Chat-Ereignisse an Ihren Webhook-Endpunkt. Jede Webhook-Anfrage enthält:

  • X-Signature

  • X-Signature-Timestamp

Der X-Signature-Header kann eine primäre Signatur, eine sekundäre Signatur oder beides enthalten:

primary=<primary_signature> secondary=<secondary_signature>

Jede Signatur ist ein Base64-codierter HMAC-SHA256-Digest. Der signierte Wert ist der Timestamp-Header, der mit dem JSON-Rohanfragetext verkettet wird:

X-Signature-Timestamp + raw_request_body

In Ihrem Webhook-Handler:

  1. Weitere Informationen finden Sie unter X-Signature und X-Signature-Timestamp.

  2. Lehnen Sie die Anfrage ab, wenn einer der beiden Header fehlt.

  3. Verwerfen Sie alte Zeitstempel, um das Risiko von Wiederholungsangriffen zu verringern.

  4. Lesen Sie den Roh-Anfragetext, bevor Sie JSON parsen.

  5. Berechnen Sie die erwartete Signatur mit jedem aktiven Webhook-Secret.

  6. Vergleichen Sie die empfangene Signatur und die erwartete Signatur mit einem Vergleich in konstanter Zeit.

  7. Die Anfrage wird akzeptiert, wenn ein aktives Secret übereinstimmt.

Das folgende Beispiel für die Ruby-Implementierung zeigt, wie UJET-Webhook-Signaturen überprüft werden:

require "base64"
require "openssl"
require "active_support/security_utils"

def parse_ujet_signature(header)
  header.to_s.split(/\s+/).each_with_object({}) do |part, result|
    key, value = part.split("=", 2)
    result[key] = value if key && value
  end
end

def expected_signature(secret, timestamp, raw_body)
  Base64.strict_encode64(
    OpenSSL::HMAC.digest(
      OpenSSL::Digest.new("sha256"),
      secret,
      "#{timestamp}#{raw_body}"
    )
  )
end

def secure_match?(received, expected)
  return false if received.nil? || expected.nil?
  return false unless received.bytesize == expected.bytesize

  ActiveSupport::SecurityUtils.secure_compare(received, expected)
end

def verify_ujet_webhook!(request, primary_secret:, secondary_secret:)
  signature_header = request.headers["X-Signature"]
  timestamp = request.headers["X-Signature-Timestamp"]

  return false if signature_header.nil? || timestamp.nil?

  # Optional but recommended: reject stale requests.
  return false if (Time.now.utc - Time.at(timestamp.to_i).utc).abs > 5.minutes

  raw_body = request.body.read
  signatures = parse_ujet_signature(signature_header)

  expected = [
    expected_signature(primary_secret, timestamp, raw_body),
    expected_signature(secondary_secret, timestamp, raw_body)
  ].compact

  received = [
    signatures["primary"],
    signatures["secondary"]
  ].compact

  received.any? do |received_signature|
    expected.any? do |expected_signature_value|
      secure_match?(received_signature, expected_signature_value)
    end
  end
end

Wenn die Bestätigung erfolgreich ist, geben Sie schnell eine Erfolgsantwort zurück und verarbeiten Sie das Ereignis idempotent. Webhook-Übermittlungen und API-Antworten können in unterschiedlicher Reihenfolge eingehen. Entwickeln Sie Ihre Integration daher so, dass sie dieselbe Statusänderung mehrmals empfangen kann, ohne doppelte Datensätze zu erstellen.

Integrationsablauf

Im folgenden Ablauf wird ein Endnutzer erstellt, ein Chat gestartet, CCAI Platform-Ereignisse empfangen, Nachrichten ausgetauscht und der Chat beendet.

Endnutzer erstellen oder aktualisieren

Ziel:Stellen Sie sicher, dass CCAI Platform einen Endnutzerdatensatz hat, bevor Sie den Chat erstellen.

Endpunkt

Verwenden Sie den folgenden Endpunkt, um einen Endnutzer zu erstellen oder zu aktualisieren:

POST /apps/api/v1/end_users

Beispielanfrage

Das folgende Beispiel zeigt einen Anfragetext zum Erstellen oder Aktualisieren eines Endnutzers:

{
  "identifier": "customer-user-12345",
  "email": "customer.user@example.com",
  "name": "Customer User",
  "phone": "+15551234567"
}

Was speichern?

Speichern Sie die CCAI Platform-Endnutzer-ID aus der Antwort in Ihrem System. Verwenden Sie diese ID, wenn Sie einen Chat erstellen.

Ablauf

  • Wenn der Endnutzer nicht vorhanden ist, wird in der CCAI-Plattform ein neuer Datensatz erstellt.

  • Wenn bereits ein Endnutzer mit derselben Kennung vorhanden ist, aktualisiert die CCAI Platform den Datensatz und gibt die Informationen des vorhandenen Endnutzers zurück.

Chat erstellen

Ziel:Einen neuen CCAI Platform-Chat für den Endnutzer starten.

Endpunkt

Verwenden Sie den folgenden Endpunkt, um einen neuen Chat zu starten:

POST /apps/api/v1/chats

Beispielanfrage

Das folgende Beispiel zeigt einen Anfragetext zum Erstellen eines Chats:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en"
  }
}

Optionaler Kontext für das Routing von virtuellen Kundenservicemitarbeitern

Wenn Ihr virtueller Agent zur Auswahl der Warteschlange Kontext aus Ihrer Anwendung benötigt, fügen Sie beim Erstellen des Chats eine Kontextnutzlast ein, wie im folgenden Beispiel gezeigt:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en",
    "context": {
      "value": {
        "customer_tier": "gold",
        "issue_type": "billing"
      }
    }
  }
}

Ein virtueller Kundenservicemitarbeiter kann Werte aus diesem Kontext verwenden, um zu entscheiden, in welche Warteschlange der Chat weitergeleitet wird.

Ablauf

  • Die Apps API gibt die Chat-Ressource zurück.

  • CCAI Platform sendet ein chat_created-Webhook-Ereignis an den konfigurierten Webhook-Endpunkt.

  • Die API-Antwort und das Webhook-Ereignis können in beliebiger Reihenfolge eintreffen. Behandeln Sie beide als Aktualisierungen desselben Chatdatensatzes, der über die Chat-ID identifiziert wird.

Chat-Webhook-Ereignisse verarbeiten

Ziel:Die Verbraucheranwendung soll mit dem Chatstatus der CCAI Platform synchronisiert werden.

Ihr Webhook-Endpunkt verarbeitet Chat-Lebenszyklus- und Nachrichtenereignisse von der CCAI Platform. Mindestens speichern:

  • Chat-ID.

  • Ereignistyp.

  • Zeitstempel des Ereignisses.

  • Absender, Typ und Inhalt der Nachricht, wenn das Ereignis eine Nachricht enthält.

  • Alle Eskalierungs- oder Umleitungsdaten, wenn das Ereignis das Routing-Verhalten beschreibt.

Empfohlenes Verhalten

  • Überprüfen Sie jede Webhook-Signatur, bevor Sie das Ereignis verarbeiten.

  • Speichern Sie verarbeitete Ereignis-IDs oder einen deterministischen Ereignisschlüssel, damit bei Wiederholungsversuchen keine Duplikate erstellt werden.

  • Geben Sie nach dem Annehmen des Ereignisses eine 2xx-Antwort zurück.

  • Nachgelagerte Nebeneffekte nach Möglichkeit asynchron verarbeiten.

Ablauf

Ihre Anwendung aktualisiert ihren Chatstatus, wenn die CCAI Platform Ereignisse wie die Erstellung von Chats, eingehende Nachrichten, Agent-Nachrichten, Eskalierungsänderungen und den Abschluss von Chats sendet.

SMS senden

Ziel:Eine Endnutzernachricht aus der Verbraucheranwendung in den CCAI Platform-Chat senden.

Endpunkt

Verwenden Sie den folgenden Endpunkt, um eine Nachricht in den Chat zu senden:

POST /apps/api/v1/chats/{chat_id}/message

Beispielanfrage

Das folgende Beispiel zeigt einen Anfragetext zum Senden einer Nachricht:

{
  "from_user_id": 456,
  "message": {
    "type": "text",
    "content": "Hello, I need help with my order."
  }
}

Ablauf

  • CCAI Platform akzeptiert die Nachricht.

  • Die Nachricht wird in der Unterhaltung mit dem KI-Agenten oder virtuellen Kundenservicemitarbeiter angezeigt.

  • Ihr Webhook-Endpunkt empfängt ein Nachrichtenereignis für die Nachricht, einschließlich Nachrichten, die von Ihrer eigenen Anwendung über die Apps API gesendet wurden.

Nachrichten von der CCAI Platform empfangen und anzeigen

Ziel:Nachrichten von Kundenservicemitarbeitern oder virtuellen Kundenservicemitarbeitern im Chat des Kunden anzeigen.

Wenn Ihr Webhook-Endpunkt ein Nachrichtenereignis empfängt, gilt Folgendes:

  1. Webhook-Signatur überprüfen

  2. Prüfen Sie, ob das Ereignis neu ist.

  3. Identifizieren Sie den Chat anhand der Chat-ID.

  4. Identifizieren Sie den Absender und den Nachrichtentyp.

  5. Rendern Sie die Nachricht in der Chat-Benutzeroberfläche des Kunden.

  6. Speichern Sie das Ereignis, damit der Unterhaltungsverlauf bei Aktualisierungen oder Wiederholungen nicht verloren geht.

Ablauf

In der Chat-UI des Kunden werden Nachrichten, die von Kundenservicemitarbeitern, virtuellen Kundenservicemitarbeitern und dem Endnutzer gesendet wurden, in der richtigen Reihenfolge angezeigt. Wenn Ereignisse in falscher Reihenfolge eintreffen, können Sie die Anzeigereihenfolge mithilfe von Ereigniszeitstempeln und Ihrer eigenen Persistenzebene abstimmen.

Von einem virtuellen Kundenservicemitarbeiter an einen menschlichen Kundenservicemitarbeiter eskalieren

Ziel:Den Chat von der Bearbeitung durch den virtuellen Kundenservicemitarbeiter in eine Warteschlange für Kundenservicemitarbeiter verschieben, wenn der Endnutzer Unterstützung durch einen Kundenservicemitarbeiter benötigt.

Wenn in Ihrer Integration ein virtueller Kundenservicemitarbeiter zur Auswahl von Warteschlangen verwendet wird, konfigurieren Sie ihn so, dass Chats an die Zielwarteschlange weitergeleitet werden. Wenn Ihr Server die Eskalierung direkt initiiert, verwenden Sie den Eskalierungs-Endpunkt der Apps API.

Endpunkt

Verwenden Sie den folgenden Endpunkt, um einen Chat von einem virtuellen Kundenservicemitarbeiter an einen menschlichen Kundenservicemitarbeiter zu eskalieren:

POST /apps/api/v1/chats/{chat_id}/escalations

Beispielanfrage

Das folgende Beispiel zeigt einen Anfragetext für die Eskalierung eines Chats:

{
  "reason": "by_end_user_ask",
  "force_escalate": false
}

Ablauf

  • Wenn die Zielwarteschlange verfügbar ist, wird der Chat an einen Kundenservicemitarbeiter weitergeleitet.

  • Wenn die Warteschlange aufgrund von Inaktivität oder Überlastung nicht verfügbar ist, kann die CCAI Platform über den Chatflow Optionen zur Umleitung zurückgeben oder senden.

  • Ihre Integration rendert die verfügbaren Umleitungsoptionen für den Endnutzer.

Auswahl für die Eskalierungsabweichung aufzeichnen

Ziel:CCAI Platform mitteilen, welche Ablenkungsoption der Endnutzer ausgewählt hat.

Wenn die CCAI-Plattform Optionen zur Vermeidung von Eskalierungen anbietet, erfassen Sie die Auswahl des Endnutzers mit dem Endpunkt für Eskalierungsupdates.

Endpunkt

Verwenden Sie den folgenden Endpunkt, um einen Eskalierungsdatensatz mit einer Auswahl für die Abwendung zu aktualisieren:

PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}

Unterstützte deflection_channel-Werte:

  • email: Der Endnutzer wählt die Option zur E-Mail-Weiterleitung aus.

  • virtual_agent: Der Endnutzer entscheidet sich, mit einem virtuellen Kundenservicemitarbeiter fortzufahren.

  • human_agent: Der Endnutzer möchte weiterhin auf einen Kundenservicemitarbeiter warten. Dieser Wert gilt nur für Umleitungen aufgrund von Überkapazität.

Beispielanfrage

Das folgende Beispiel zeigt einen Anfragetext zum Aufzeichnen einer Auswahl für die Umleitung:

{
  "deflection_channel": "email"
}

Senden Sie nur einen unterstützten deflection_channel-Wert an diesen Endpunkt. external_link ist kein gültiger Wert für den Endpunkt für Eskalierungsupdates. Wenn der Endnutzer einem externen Link zur Ablenkung folgt, wird der Chat stattdessen beendet.

Ablauf

CCAI Platform aktualisiert den Eskalierungsdatensatz und leitet den Chat entsprechend der ausgewählten Option weiter.

Chat beenden

Ziel:Schließen Sie den Chat, wenn die Unterhaltung abgeschlossen ist.

Endpunkt

Verwenden Sie den folgenden Endpunkt, um einen aktiven Chat zu beenden:

PATCH /apps/api/v1/chats/{chat_id}/end

Beispielanfrage

Das folgende Beispiel zeigt einen Anfragetext zum Beenden eines Chats:

{
  "ended_by_user_id": 456
}

Ablauf

  • Die CCAI Platform beendet den Chat.

  • Ihr Webhook-Endpunkt empfängt das endgültige Chatstatusereignis.

  • Ihre Anwendung markiert den Chat als abgeschlossen und akzeptiert keine neuen Endnutzernachrichten mehr für diesen Chat.

Erweiterte Abläufe

Die folgenden Zweige sind optional. Implementieren Sie nur die Abläufe, die für Ihre Integration gelten.

Vorab-Chat-Transkript importieren

Verwenden Sie diesen Ablauf, wenn der Endnutzer bereits eine Unterhaltung in Ihrem System geführt hat, bevor Sie den CCAI Platform-Chat erstellt haben, z. B. eine Chatbot-Unterhaltung.

Fügen Sie die Transkript-Payload hinzu, wenn Sie den Chat erstellen. Das Transkript liefert dem Kundenservicemitarbeiter Kontext, sodass der Endnutzer Informationen nicht wiederholen muss.

Die genauen Transkriptschemata finden Sie in der Apps API-Referenz.

Chats mit einem virtuellen Kundenservicemitarbeiter für die Auswahl von Warteschlangen weiterleiten

Verwenden Sie diesen Ablauf, wenn Ihre Anwendung alle neuen Chats in eine Warteschlange für den Eingang sendet und ein virtueller Kundenservicemitarbeiter die endgültige Zielwarteschlange festlegt.

  1. Erstellen Sie einen virtuellen Kundenservicemitarbeiter für die Auswahl der Warteschlange.

  2. Weisen Sie den virtuellen Kundenservicemitarbeiter der Eingangs-Queue zu.

  3. Geben Sie beim Erstellen des Chats Kontext an.

  4. Konfigurieren Sie den virtuellen Kundenservicemitarbeiter so, dass er den Kontext prüft und den Chat an die richtige Warteschlange eskaliert.

  5. Umgang mit Umleitungsoptionen, wenn die Zielwarteschlange nicht verfügbar ist.

Foto- oder Videoanhänge senden

Verwenden Sie diesen Ablauf, wenn der Endnutzer Medien über die Chat-Benutzeroberfläche des Kunden sendet.

Der Media-Ablauf umfasst vier Phasen.

Phase 1: Signierte Upload-URL anfordern

Verwenden Sie die folgenden Endpunkte, um eine signierte URL zum Hochladen eines Fotos oder Videos anzufordern:

POST /apps/api/v1/chats/{chat_id}/photos/upload
POST /apps/api/v1/chats/{chat_id}/videos/upload

Phase 2: Datei in die zurückgegebene Speicher-URL hochladen

Fügen Sie die Datei und alle Felder ein, die von CCAI Platform in der Antwort für den signierten Upload zurückgegeben werden.

Phase 3: Hochgeladene Datei dem Chat hinzufügen

Verwenden Sie die folgenden Endpunkte, um dem Chat ein hochgeladenes Foto oder Video hinzuzufügen:

POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos

Speichern Sie die media_id, die von CCAI Platform zurückgegeben wird. In Chatnachrichtennutzlasten wird auf Media anhand der Media-ID verwiesen.

Phase 4: Medien als Nachricht senden

Verwenden Sie den folgenden Endpunkt, um eine Mediennachricht in den Chat zu senden:

POST /apps/api/v1/chats/{chat_id}/message

Beispielanfrage

Das folgende Beispiel zeigt einen Anfragetext zum Senden einer Fotoanlage:

{
  "from_user_id": 456,
  "message": {
    "type": "photo",
    "content": {
      "media_id": 789
    }
  }
}

Verwende für Videonachrichten den Nachrichtentyp video und das Video media_id.

Benutzerdefinierte Daten während eines Chats senden

Verwenden Sie den folgenden Endpunkt, wenn in Ihrer Integration kundendefinierter Kontext an einen aktiven Chat angehängt werden muss:

POST /apps/api/v1/chats/{chat_id}/custom_data

In der Apps API-Referenz werden die genaue Nutzlastform und das Verhalten reservierter Schlüssel definiert.

Endnutzeridentität während eines Chats aktualisieren

Verwenden Sie den folgenden Endpunkt, wenn sich die Identität des Endnutzers ändert oder nach Beginn des Chats bekannt wird:

POST /apps/api/v1/chats/{chat_id}/end_user

Verwenden Sie diesen Endpunkt beispielsweise, wenn sich ein anonymer Endnutzer während eines aktiven Chats anmeldet und Ihre Integration CCAI Platform benötigt, um den Chat der aktualisierten Endnutzeridentität zuzuordnen.

Daten zur Kundenzufriedenheit oder Bewertungen erfassen

Verwenden Sie die folgenden Endpunkte für die CSAT- und Bewertungsfunktionen im Chat, wenn Ihre Integration für die Bewertungsfunktionen nach dem Chat verantwortlich ist:

GET /apps/api/v1/chats/{chat_id}/csat
GET /apps/api/v1/chats/{chat_id}/rating
PATCH /apps/api/v1/chats/{chat_id}/rating

Die genauen Zulassungsregeln und Nutzlasten für die Altersfreigabe finden Sie in der Apps API-Referenz.