Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Chatplattform-API – Leitfaden

Auf dieser Seite wird beschrieben, wie Sie Chat-Endpunkte verwenden, wie in den API-Endpunkten der Chatplattform beschrieben.

Terminologie

Zur Klarheit finden Sie hier einige Definitionen, die bei der Verwendung dieses Dokuments wichtig sind.

Kunde:Der Contact Center AI Platform-Kunde (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 Agent zu führen.

Webhook-Authentifizierung

Die Chatplattform-API kommuniziert Ereignisse, die während des Chats stattfinden, an den Nutzer, indem sie Webhook-Anfragen an den Server des Nutzers sendet. 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 einer verketteten Zeichenfolge aus dem X-Signature-Timestamp-Header und der JSON-Nutzlast der Anfrage.

Im Folgenden finden Sie eine Beispielimplementierung der Autorisierung für die Webhook-Anfragen in einer Ruby on Rails-Beispiel-App:

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 Unterhaltung über die Chatplattform-API so aussehen: Die wichtigsten Punkte sind nummeriert und es werden Hinweise für zusätzlichen Kontext gegeben. Beachten Sie, dass der Kunde nur für die Implementierung der „Customer“-Seite des Diagramms verantwortlich ist, während die Contact Center AI Platform die Seiten „Our system“ und „Agent“ des Diagramms übernimmt. Ihre Aufnahme in das Diagramm dient nur dazu, dem Leser Kontext für den Gesamtfluss eines Chats zu 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 Attribut identifier identifiziert, das ein Stringwert ist, der vom Nutzer bereitgestellt wird. Es ist möglich, dass ein Endnutzer bereits im System vorhanden ist, wenn er die Web- oder mobilen SDKs verwendet hat. Der Endpunkt POST /end_users 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-Nutzlasten verarbeiten:Der Chat-Initialisierungsprozess erfolgt asynchron zur Anfrage POST /chats. Daher kann das Ereignis chat_created vor oder nach der API-Antwort vom Erstellungsendpunkt POST /chats empfangen werden. Es wird empfohlen, das Ereignis chat_created und die API-Antwort zur Chat-Erstellung idempotent zu verarbeiten, um Fehler im Nutzer zu vermeiden.
Chats mit Transkripten erstellen:Die Chatplattform-API unterstützt das Erstellen eines Chats mit einem Transkript einer vorhandenen Unterhaltung für ein Szenario, 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 Chat-Sitzung und der Endnutzer muss sich nicht wiederholen. Das Format der Transkript-Nutzlast finden Sie in chat_platform_openapi.yaml.

Der virtuelle Kundenservicemitarbeiter für die Warteschlangenauswahl

Um die Menüauswahl für API-Nutzer zu optimieren, ist die Chatplattform-API für die Verwendung in Verbindung mit einem virtuellen Dialogflow-Kundenservicemitarbeiter konzipiert, der bei der Warteschlangenplatzierung für neue Chats hilft.

Die folgenden Schritte sind erforderlich, um den virtuellen Kundenservicemitarbeiter einzurichten:

Erstellen Sie zu diesem Zweck einen bestimmten virtuellen Kundenservicemitarbeiter und weisen Sie ihn einer Warteschlange zu. Alle neuen Chats, die von der 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 Endpunkt POST oder chats erstellen, fügen Sie eine benutzerdefinierte Kontextnutzlast hinzu, die einige Informationen zum erstellten Chat enthält, mit denen der virtuelle Kundenservicemitarbeiter bestimmen kann, an welche Warteschlange der Chat weitergeleitet werden soll. Die Kontextnutzlast kann beliebige benutzerdefinierte Daten enthalten, die vom Kunden definiert werden. Sie muss jedoch das folgende Format haben, damit die Daten für den virtuellen Kundenservicemitarbeiter zugänglich sind, der der Warteschlange zugewiesen ist.
- Beispiel: "context": {"value": {"foo": "bar" } } kann dem virtuellen Agenten erlauben, $session.params.context.foo mit einem Wert von bar zu lesen.
Anhand der Daten im Feld „context“ leitet der virtuelle Kundenservicemitarbeiter den Chat an die ausgewählte Warteschlange weiter (je nach Konfiguration durch den Kunden). Wenn in der Zielwarteschlange kein Agent verfügbar ist (z. B. wenn eine Warteschlange außerhalb der Geschäftszeiten liegt oder überlastet ist), wird die Weiterleitung abgewiesen und der Nutzer erhält einen Webhook mit dem Grund für die Abweisung und den verfügbaren Abweisungsoptionen.

Abweisungen bei der Weiterleitung: Bei der Weiterleitung von Chats in der Chatplattform-API werden die folgenden Abweisungsoptionen unterstützt, 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 Kunde den Chat nach dem Senden der E-Mail mit dem PATCH /chats/:id Endpunkt mit den folgenden Parametern im Anfragetext als abgewiesen und beendet markieren: "status": "finished" , "escalation_id": <id of escalation> , und "deflection_channel": "email"
Mit dem virtuellen Kundenservicemitarbeiter fortfahren: Dies ist technisch gesehen eine gültige Abweisungsoption , aber sie ist nicht sinnvoll, wenn der virtuelle Kundenservicemitarbeiter für die Warteschlangenauswahl verwendet wird, da er nur versuchen würde, den Chat noch einmal weiterzuleiten.
Weiter auf einen menschlichen Agent warten: Diese Option kann nur für Weiterleitungen mit dem Grund over_capacity verwendet werden. Wenn der Endnutzer diese Option auswählt, aktualisieren Sie die Abweisung der Weiterleitung mit PATCH chats/:id/escalations/:id with deflection_channel=human_agent
- Externer Abweisungslink: Warnen Sie den Endnutzer, dass der Chat beendet wird, wenn er einen Link auswählt, der in der Abweisung angegeben ist. Wenn ein Link ausgewählt wird, 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 POST /chats/:id/message Endpunkt, wie in der API-Dokumentation definiert. Wenn Sie Nachrichten empfangen möchten, warten Sie auf das message_received Webhook-Ereignis. Beachten Sie, dass der API-Nutzer für alle Nachrichten, die über die API gesendet werden, ein message_received-Ereignis erhält, einschließlich Nachrichten, die vom Endnutzer gesendet wurden.
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. Vorab signierte URL abrufen: Rufen Sie eine vorab signierte Upload-URL von der Contact Center AI Platform mit den POST /v1/chats/:chat_id/photos/upload oder POST /v1/chats/:chat_id/videos/upload endpoints ab. Dieser Endpunkt gibt eine vorab signierte URL sowie eine Sammlung von Feldern zurück, die beim Hochladen der Datei an den Speicherdienst weitergeleitet werden müssen. Für vorab 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 Client 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, senden 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 Objekt „fields“ in der vorab signierten URL-Anfrage zurückgegeben werden.
3. Mediendatei zum Chat hinzufügen: Wenn Sie die Mediendatei zum Chat hinzufügen möchten, verwenden Sie den Endpunkt POST /chats/:id/photos oder POST /chats/:id/videos. Beachten Sie, dass der Endpunkt für Fotos das Senden eines Arrays von Fotos unterstützt, während der Endpunkt für Videos nur ein Video gleichzeitig unterstützt.
  - Der Anfragetextparameter s3_path sollte denselben Wert wie das Feld key der vorab signierten URL-Antwort haben.
  - Bei Erfolg gibt die Anfrage zwei Felder zurück. Es wird empfohlen, eine Zuordnung von media_id zu URL im API-Nutzer zu speichern oder zu cachen, 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 Mediendatei in der Contact Center AI Platform. Dies ist die ID, mit der auf die Medien in Chat-Nutzlasten verwiesen wird.
4. Mediendatei als Chatnachricht senden: Wenn Sie die Mediendatei als Chatnachricht senden möchten, senden Sie die folgende Nutzlast an den POST /chats/:id/message endpoint:
```
{
  "from_user_id": <id of end user>,
  "message": {
    "type": <"photo" or "video">,
    "media_id": < media_id returned as described in 2.c >
  }
}
```

Unerkannte JSON-Schlüssel in API-Antworten erwarten

Alle API-Updates sind abwärtskompatibel. Wir behalten uns das Recht vor, jederzeit neue JSON-Schlüssel in vorhandenen API-Antworten einzuführen. Wir empfehlen, Antworten defensiv zu verarbeiten, indem Sie alle nicht erkannten Schlüssel 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.