Chatplattform-API – Leitfaden

Auf dieser Seite wird beschrieben, wie Sie Chat-Endpunkte verwenden, wie unter Chat-Plattform-API-Endpunkte beschrieben.

Terminologie

Zur besseren Verständlichkeit finden Sie hier einige Definitionen, die Sie bei der Verwendung dieses Dokuments beachten sollten.

Kunde:Der Kunde der Contact Center AI Platform (CCAI Platform), der die Chatplattform-API in seiner Software implementiert.
Nutzer:Die Software, die Anfragen an die Chatplattform-API sendet.
Endnutzer:Der Nutzer der Software des Kunden, der versucht, einen Chat mit einem Agenten zu führen.

Webhook-Authentifizierung

Die Chatplattform-API kommuniziert Ereignisse, die während des Chats stattfinden, an den Verbraucher, indem Webhook-Anfragen an den Server des Verbrauchers gesendet werden. Webhook-Nutzlasten und -Typen sind in der API-Spezifikation definiert. Jede Webhook-Anfrage enthält zwei Header: X-Signature und X-Signature-Timestamp.

X-Signature enthält eine Webhook-Signatur im folgenden Format: primary=<primary_signature> secondary=<secondary_signature>

Primäre und sekundäre Signaturen sind ein base64-codierter SHA256-Digest der primären bzw. sekundären Webhook-Secrets mit einem verketteten String aus dem X-Signature-Timestamp-Header und der JSON-Nutzlast der Anfrage.

Im Folgenden finden Sie ein Beispiel für die Implementierung der Autorisierung für die Webhook-Anfragen in einer Ruby on Rails-Beispielanwendung:

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

Übersicht

Im Allgemeinen sollte der grundlegende Ablauf einer API-Unterhaltung auf einer Chatplattform so aussehen: Die wichtigsten Punkte sind nummeriert und es werden Hinweise für zusätzlichen Kontext gegeben. Der Kunde ist nur für die Implementierung der „Customer“-Seite des Diagramms verantwortlich, während Contact Center AI Platform die System- und Kundenservicemitarbeiterseite des Diagramms übernimmt. Sie sollen dem Leser lediglich einen Kontext für den allgemeinen Ablauf eines Chats geben.

Der Ablauf einer Unterhaltung mit einer Chatplattform-API wird dargestellt.

Endnutzer erstellen

Für Chats ist beim Erstellen eine gültige Endnutzer-ID erforderlich. Das bedeutet, dass ein Endnutzer im Contact Center AI Platform-System vorhanden sein muss, bevor ein Chat erstellt wird.
Endnutzer werden eindeutig durch ihr identifier-Attribut identifiziert, das ein vom Verbraucher bereitgestellter Stringwert ist. Es ist möglich, dass ein Endnutzer bereits im System vorhanden ist, wenn er die Web- oder Mobile-SDKs verwendet hat. Der POST /end_users-Endpunkt wird als idempotenter Upsert implementiert. Wenn Sie also versuchen, einen vorhandenen Endnutzer noch einmal zu erstellen, werden alle geänderten Daten aktualisiert und die Informationen des Endnutzers zurückgegeben.

Chats erstellen

So erstellen Sie Chats mit der Chatplattform-API:

Neue Chat-Payloads verarbeiten:Die Chat-Initialisierung erfolgt asynchron zur POST /chats-Anfrage. Daher kann das chat_created-Ereignis vor oder nach der API-Antwort vom POST /chats-Erstellungs-Endpunkt empfangen werden. Es wird empfohlen, das chat_created-Ereignis und die API-Antwort für die Chaterstellung auf idempotente Weise zu verarbeiten, um Fehler im Consumer zu vermeiden.
Chats mit Transkripten erstellen:Die Chatplattform-API unterstützt das Erstellen eines Chats mit einem Transkript einer bestehenden Unterhaltung. Dies ist z. B. in einem Szenario möglich, in dem ein Chat auf der Plattform eines Kunden stattfindet, z. B. mit einem Chatbot, bevor er an die Contact Center AI Platform gesendet wird. So erhält der Agent, der den Chat beantwortet, zusätzliche Informationen zur Chatsitzung und der Endnutzer muss sich nicht wiederholen. Informationen zum Format der Transkript-Nutzlast finden Sie in chat_platform_openapi.yaml.

Virtueller Kundenservicemitarbeiter für die Auswahl der Warteschlange

Um die Menüauswahl für API-Nutzer zu vereinfachen, ist die Chatplattform-API für die Verwendung in Verbindung mit einem virtuellen Dialogflow-Agenten konzipiert, um die Warteschlangenplatzierung für neue Chats zu unterstützen.

Für die Einrichtung des virtuellen Kundenservicemitarbeiters sind die folgenden Schritte erforderlich:

Erstellen Sie zu diesem Zweck einen dedizierten virtuellen Kundenservicemitarbeiter und weisen Sie ihn einer Warteschlange zu. Alle neuen Chats, die über die Chatplattform-API erstellt werden, sollten in dieser Warteschlange erstellt werden. Das Erstellen und Konfigurieren eines neuen virtuellen Kundenservicemitarbeiters wird in diesem Dokument nicht behandelt.
Wenn Sie einen neuen Chat mit dem POST- oder Chats-Endpunkt erstellen, fügen Sie eine benutzerdefinierte Kontextnutzlast ein, die einige Informationen zum erstellten Chat enthält. Der virtuelle Kundenservicemitarbeiter kann anhand dieser Informationen ermitteln, an welche Warteschlange der Chat weitergeleitet werden soll. Die Kontext-Nutzlast kann beliebige benutzerdefinierte Daten enthalten, die vom Kunden definiert werden. Damit die Daten jedoch für den der Warteschlange zugewiesenen virtuellen Kundenservicemitarbeiter zugänglich sind, muss sie das folgende Format haben.
- Beispiel: "context": {"value": {"foo": "bar" } } würde es dem virtuellen Kundenservicemitarbeiter ermöglichen, $session.params.context.foo mit dem Wert bar zu lesen.
Anhand der Daten im Kontextfeld eskaliert der virtuelle Kundenservicemitarbeiter den Chat (je nach Konfiguration durch den Kunden) an die ausgewählte Warteschlange. Wenn in der Zielwarteschlange kein Kundenservicemitarbeiter verfügbar ist (z. B. wenn eine Warteschlange außerhalb der Geschäftszeiten oder überlastet ist), wird die Eskalierung abgewiesen und der Kunde erhält einen Webhook mit dem Grund für die Ablehnung und den verfügbaren Ablehnungsoptionen.

Eskalierungsabweichungen: Chat-Eskalierungen in der Chat-Plattform-API unterstützen die folgenden Abweichungsoptionen, sofern sie im Contact Center AI Platform-Portal konfiguriert sind:

E-Mail: Der Endnutzer sendet eine E-Mail an den Support und beendet den Chat. Wenn ein Endnutzer diese Option auswählt, muss der Kundenservicemitarbeiter nach dem Senden der E-Mail den Chat als umgeleitet und beendet markieren. Dazu muss er den PATCH /chats/:id-Endpunkt mit den folgenden Parametern im Anfragetext verwenden: "status": "finished" , "escalation_id": <id of escalation> , und "deflection_channel": "email".
Mit dem virtuellen Kundenservicemitarbeiter fortfahren: Dies ist technisch gesehen eine gültige Option zur Ablenkung, aber sie ist nicht sinnvoll, wenn der virtuelle Kundenservicemitarbeiter zur Auswahl der Warteschlange verwendet wird, da er nur versuchen würde, den Chat noch einmal zu eskalieren.
Auf Kundenservicemitarbeiter warten: Diese Option kann nur für Eskalierungen mit dem Grund over_capacity verwendet werden. Wenn der Endnutzer diese Option auswählt, aktualisiere die Eskalierungsumleitung mit PATCH chats/:id/escalations/:id with deflection_channel=human_agent.
- Externer Link zur Weiterleitung: Warnen Sie den Endnutzer, dass durch Auswahl eines Links in der Weiterleitung der Chat beendet wird. Wenn ein Link ausgewählt ist, beenden Sie den Chat und verwenden Sie external_link für den Parameter deflection_channel.

Nachrichten senden und empfangen

So senden oder empfangen Sie Nachrichten:

Textinhalte: Wenn Sie Textnachrichten senden möchten, verwenden Sie den Endpunkt POST /chats/:id/message, wie in der API-Dokumentation beschrieben. Wenn Sie Nachrichten empfangen möchten, achten Sie auf das Webhook-Ereignis message_received. Der API-Nutzer erhält ein message_received-Ereignis für alle Nachrichten, die über die API gesendet werden, einschließlich der Nachrichten, die vom Endnutzer gesendet werden.
Foto- und Videoinhalte: Foto- und Videoinhalte werden gesendet, indem eine vorab signierte Upload-URL für einen konfigurierten Cloud Storage-Dienst von der Contact Center AI Platform abgerufen, in den Speicherdienst hochgeladen und dann die Speicher-URL in einer Nachrichtennutzlast an die Contact Center AI Platform gesendet wird.
1. Vorsignierte URL abrufen: Rufen Sie eine vorsignierte Upload-URL von der Contact Center AI Platform mit POST /v1/chats/:chat_id/photos/upload oder POST /v1/chats/:chat_id/videos/upload endpoints ab. Dieser Endpunkt gibt eine vorab signierte URL zusammen mit einer Sammlung von Feldern zurück, die beim Hochladen der Datei an den Speicherdienst weitergeleitet werden müssen. Für signierte Uploads gelten die folgenden Einschränkungen:
  - Der Inhaltstyp ist image/jpeg für Fotos und video/mp4 für Videos.
  - Die maximale Fotogröße beträgt 2 MB. Die maximale Videogröße beträgt 20 MB.
  - Die Ablaufzeit beträgt 5 Minuten.
  - Der Kunde muss die Größe und Ausrichtung des Fotos vor dem Hochladen anpassen.
  - Jede vorab signierte URL gilt für ein einzelnes Foto oder Video. Wenn Sie mehrere Anhänge senden möchten, müssen Sie für jeden Anhang eine vorab signierte URL anfordern.
2. Mediendatei hochladen: Wenn Sie die Mediendatei hochladen möchten, stellen Sie eine POST-Anfrage an die in Schritt 2a abgerufene vorab signierte URL mit Folgendem im Anfragetext:
  - "file": die hochzuladende Datei
  - Alle Felder, die im Feldobjekt in der Anfrage für die vorab signierte URL zurückgegeben werden.
3. Mediendatei dem Chat hinzufügen: Verwenden Sie den Endpunkt POST /chats/:id/photos oder POST /chats/:id/videos, um die Mediendatei dem Chat hinzuzufügen. Der Endpunkt „photos“ unterstützt das Senden eines Arrays von Fotos, während der Endpunkt „video“ jeweils nur ein Video unterstützt.
  - Der Parameter s3_path im Anfragetext sollte denselben Wert wie das Feld key in der Antwort der vorab signierten URL haben.
  - Bei erfolgreicher Ausführung werden zwei Felder zurückgegeben. Es wird empfohlen, eine Zuordnung von media_id zu URL im API-Nutzer zu speichern oder im Cache zu speichern, da alle Medien in Chatnachrichten nur über media_id referenziert werden.
    - url: Die schreibgeschützte S3- oder Cloud Storage-URL, unter der sich die Datei befindet.
    - media_id: Die ID der Media-Datei in der Contact Center AI Platform. Das ist die ID, mit der in Chat-Payloads auf die Medien verwiesen wird.
4. Mediendatei als Chatnachricht senden: Wenn Sie die Mediendatei als Chatnachricht senden möchten, senden Sie die folgende Nutzlast an POST /chats/:id/message endpoint:
```
{
  "from_user_id": <id of end user>,
  "message":
    "type": <"photo" or "video">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}
```

Unerkannte JSON-Schlüssel in API-Antworten

Alle API-Updates sind abwärtskompatibel. Wir behalten uns das Recht vor, jederzeit neue JSON-Schlüssel in bestehende API-Antworten einzuführen. Wir empfehlen, Antworten defensiv zu verarbeiten und alle nicht erkannten Schlüssel zu ignorieren, um die Funktionalität aufrechtzuerhalten.

Chatplattform-API – Leitfaden Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.