Verwenden des Schritts „API-Aufruf durchführen“ in einem Konversations-Bot

Achtung: Die Zendesk-Bot-Funktionen wurden umbenannt. Answer Bot heißt jetzt Zendesk-Bots, Flow Builder heißt jetzt Bot Builder und Beitragsempfehlungen heißen jetzt Automatische Antworten. Bei einigen älteren Funktionen wird noch die alte Terminologie verwendet, was sich auch in der Dokumentation widerspiegelt. Weitere Informationen zu dieser Änderungen finden Sie in dieser Ankündigung.

Mit dem Schritt API-Aufruf durchführen können Sie einen API-Aufruf an ein internes CRM- oder ERP-System o. ä. konfigurieren oder Details zur Konversation an einen externen Endpunkt wie Amazon Event Bridge oder Google Analytics übertragen.

In diesem Beitrag erfahren Sie, wie Sie diesen Schritt in einen Konversations-Bot einbinden und konfigurieren.

Allgemeine Informationen zum Schritt API-Aufruf durchführen und den entsprechenden Konfigurationsregeln finden Sie im Beitrag Überblick über die Schrittarten im Bot-Konversationsfluss: API-Aufruf durchführen.

Dieser Beitrag enthält die folgenden Abschnitte:

• Hinzufügen des Schritt „API-Aufruf durchführen“ zu einem Bot
• Hinzufügen von API-Details
• Speichern von Variablen aus der API-Antwort
• Überblick über die Schrittverzweigungen

Hinzufügen des Schritt „API-Aufruf durchführen“ zu einem Bot

Um den Schritt API-Aufruf durchführen zu einem Bot hinzuzufügen, sind mehrere Aufgaben erforderlich.

Bei den unten stehenden Anweisungen wird vorausgesetzt, dass Sie bereits einen Konversations-Bot erstellt haben, dem Sie diesen Schritt hinzufügen möchten.

So fügen Sie den Schritt „API-Aufruf durchführen“ hinzu

1. Öffnen Sie den Bot im Bot Builder.
2. Klicken Sie an der Stelle, an der Sie den Schritt einfügen möchten, auf das Symbol Neu hinzufügen: entweder am Ende einer Verzweigung oder zwischen zwei vorhandenen Schritten.
3. Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
4. Geben Sie aussagekräftige Informationen zu diesem Schritt ein. Die hier eingegebenen Informationen sind nur für Ihr Team sichtbar, nicht für Kunden.
   • Name: Ein Name, an dem Ihr Team den Aufruf leicht erkennt.
   • Beschreibung (optional): Eine kurze Beschreibung der durch den Anruf ausgelösten Aktion.
5. Fahren Sie wie im nächsten Abschnitt unter Hinzufügen von API-Details beschrieben fort.

Hinzufügen von API-Details

Konfigurieren Sie im Abschnitt „API-Details“ den gewünschten HTTP-Aufruf, indem Sie die HTTP-Anfragemethode und den Standort der externen Ressource angeben sowie bei Bedarf weitere Header hinzufügen. Die folgenden Schritte sind eine Fortsetzung des im vorherigen Abschnitt beschriebenen Verfahrens.

So fügen Sie die API-Details hinzu

1. Klicken Sie im Konfigurationsfenster auf API-Details.
2. Klicken Sie in der Dropdownliste auf eine Anfragemethode:
   • GET ruft Daten von einem Server bei der externen Ressource ab. Dies ist die am häufigsten verwendete Methode.
   • POST sendet Daten, um eine Ressource in einem externen System zu erstellen oder zu aktualisieren. Wenn die Ressource bereits vorhanden ist, wird sie durch die gesendeten Daten geändert.
   • PUT sendet Daten, um eine Ressource zu aktualisieren oder zu erstellen. Wenn die Ressource bereits vorhanden ist, wird sie durch die gesendeten Daten ersetzt.
   • PATCH sendet Daten, um eine Ressource an einem externen Standort zu aktualisieren. Mit dieser Methode werden Teile der Ressource verändert.
   • DELETE entfernt die Ressource am externen Standort.
3. Geben Sie eine Endpunkt-URL ein. Die Endpunkt-URL ist der Standort der externen Ressource, zu der eine Verbindung hergestellt werden soll. Die Endpunkt-URL unterstützt das https://-Protokoll. Sie können Variablen in den Pfad oder die Query-String einer URL einfügen. Weitere Informationen finden Sie unter Übergeben von Variablen in einem API-Aufruf.
4. Wählen Sie optional eine Verbindung zur Authentifizierung des API-Aufrufs.
   Hinweis: Sie müssen eine Verbindung erstellen, bevor Sie sie im Schritt API-Aufruf durchführen verwenden können.
5. Geben Sie bei Bedarf den Schlüssel und den Wert für einen optionalen Header ein.
   Wichtig: Verwenden Sie für Authentifizierungstypen keine HTTP-Header, sondern stattdessen API-Verbindungen.

   Wenn der Schritt API-Aufruf durchführen authentifizierungsbezogene Header wie authorization oder x-api-key enthält, schlägt er automatisch fehl. Wenn ein Schritt API-Aufruf durchführen fehlschlägt, folgt die Konversation den Schritten der Verzweigung API-Aufruf fehlgeschlagen.

6. Klicken Sie auf API-Aufruf durchführen, um den API-Aufruf zu testen. Wenn zur URL oder zum Header des Schritts Variablen hinzugefügt werden, können Sie optionale Testdaten für Ihren externen Service eingeben, um zu prüfen, ob der API-Aufruf wie erwartet funktioniert. Beachten Sie, dass hierbei eine HTTP-Anfrage an die konfigurierte Endpunkt-URL gesendet wird.

Übergeben von Variablen in einem API-Aufruf

Wenn Sie eine Endpunkt-URL für einen API-Aufruf eingeben, können Sie Variablen in den Pfad oder die Query-String einer URs einfügen. Damit können Sie Daten aus der Konversation an das externe System weitergeben.

So kann ein Messaging-Bot einen Kunden beispielsweise mit dem Schritt Details anfordern auffordern, eine Bestellnummer einzugeben. Der Bot kann dann über den Schritt API-Aufruf durchführen den Versandstatus für die Bestellung aus Ihrem Online-Shop abrufen.

Sie können keine Variablen in der Domäne oder Subdomäne einer Endpunkt-URL verwenden. Die folgende Tabelle enthält Beispiele für gültige und ungültige Werte für die Endpunkt-URL.

Gültige Endpunkt-URL	Ungültige Endpunkt-URL
https://myshopify.com/admin/api/orders/order_number.json Eine Bestellung anhand der Bestellnummer aus Shopify abrufen.	https://domain.com/api/search?input=value Variablen können nicht zur Domäne/Subdomäne hinzugefügt werden
https://maps.googleapis.com/maps/api/place?input=city_name Einen Ort per Schlüsselwortsuche aus der Google Places API abrufen.	https://example.com/api/search?key=value Variablen können nicht zum Query-Stringschlüssel hinzugefügt werden.

Wenn eine Variable ungültig oder leer ist, überspringt der Bot die Variable während einer Konversation.

Hinweis: Variablenwerte werden nicht automatisch übersetzt. Denken Sie daran, wenn Sie in Ihren Messaging-Konversationen automatische Übersetzung verwenden.

Speichern von Variablen aus der API-Antwort

Nachdem Sie die Details konfiguriert und den API-Aufruf getestet haben, können Sie die Werte aus der JSON-Antwort des API-Aufrufs als Variablen speichern. Im Schritt API-Aufruf durchführen können Sie bis zu acht Variablen speichern.

Hinweis: In der Messaging-Konversation werden in Antworten nur die ersten 280 Zeichen eines Variablenwerts angezeigt.

So erstellen Sie eine Variable anhand der Antwortdaten

1. Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
2. Erweitern Sie das Akkordeon und identifizieren Sie die Daten aus dem externen System, die Sie in eine Variable umwandeln möchten.
   Tipp: Die vom externen System zurückgegebene Rohdatenantwort können Sie in der Registerkarte „Antworttext“ einsehen.
3. Klicken Sie auf Speichern.
4. Legen Sie einen Namen für die neue Variable fest. Variablennamen dürfen nur Kleinbuchstaben, Ziffern und Unterstriche enthalten.

Überblick über die Schrittverzweigungen

Der Schritt API-Aufruf durchführen ist ein Verzweigungsschritt. Die weiteren Antworten des Bots hängen davon ab, ob die API erfolgreich ausgeführt wurde.

Wenn die API den Antwortcode 400, 500 oder 200 mit Daten zurückgibt, in denen eine der Variablen fehlt, verzweigt der Bot zur Fehlerbearbeitung.

Achtung: Durch Verwendung des Schritts API-Aufruf durchführen erkennen Sie an, dass das System, zu dem Sie eine Verbindung herstellen, laut dem Zendesk-Hauptdienstleistungsvertrag als Nicht-Zendesk-Dienst gilt. Die durch Verwendung der Bot-Builder-Erweiterungen aktivierten Nicht-Zendesk-Dienste werden nicht von Zendesk betrieben oder gesteuert. Zendesk übernimmt keine Verantwortung dafür, dass Sie oder die Nicht-Zendesk-Dienste die einschlägigen Gesetze oder Vorschriften einhalten.