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

Bei allen Suite-Plänen verfügbar

Diese Funktion ist Bestandteil von AI Agents.

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.

Hinweis: Wenn das angerufene System nicht innerhalb von 10 Sekunden antwortet, wird der Anruf wegen Zeitüberschreitung abgebrochen.

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

Klicken Sie in der Seitenleiste des Admin Centers auf Kanäle und dann auf AI Agents und Automatisierung > AI Agents.
Klicken Sie auf Konversations-Bots verwalten.
Klicken Sie auf den Namen des Bots, den Sie bearbeiten möchten.
Klicken Sie auf die Registerkarte Antworten und erstellen Sie eine neue Antwort bzw. öffnen Sie eine vorhandene Antwort.
Klicken Sie im Bot-Builder an der Stelle, an der Sie den Schritt einfügen möchten, auf das Symbol Schritt hinzufügen: entweder am Ende einer Verzweigung oder zwischen zwei vorhandenen Schritten.
Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
Geben Sie aussagekräftige Informationen zu diesem Schritt ein.
- Name: Ein Name, an dem Ihr Team den Aufruf leicht erkennt.
- Beschreibung (optional): Eine kurze Beschreibung der durch den Anruf ausgelösten Aktion.
Diese Informationen sind für Kunden nicht sichtbar.
Fahren Sie wie 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

Klicken Sie im Konfigurationsfenster auf API-Details.
Wählen Sie eine Anfragemethode:
- GET ruft eine externe Ressource vom API-Service ab. Dies ist die am häufigsten verwendete Methode.
- POST sendet Daten, um eine Ressource in einem externen System zu erstellen. Wenn die Ressource bereits vorhanden ist, wird sie durch die gesendeten Daten geändert.
- PUT sendet Daten, um eine Ressource zu aktualisieren.
- 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.
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 in die Query-Zeichenfolge einer URL einfügen. Weitere Informationen finden Sie unter Übergeben von Variablen in einem API-Aufruf.
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.
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.
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

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.

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 12 Variablen speichern. Es werden nur die ersten 280 Zeichen eines Variablenwerts gespeichert.

So erstellen Sie eine Variable anhand der Antwortdaten

Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
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.
Klicken Sie auf Speichern.
Legen Sie einen Namen für die neue Variable fest.
Variablennamen dürfen nur Kleinbuchstaben, Ziffern und Unterstriche enthalten.

Übergeben von Array-Variablen in einem API-Aufruf

Sie können Variablen an das externe System übergeben, indem Sie API-Aufruf durchführen verwenden und eine URL angeben. Das externe System muss über einen API-Endpunkt verfügen. Ein API-Endpunkt ist eine URL, über die die API Anfragen erhält und Antworten sendet, sodass zwei Systeme miteinander interagieren können. Antworten werden wie im folgenden Beispiel dargestellt im JSON-Format (JavaScript Object Notation) generiert.

{               
    "info": {   
        "count": 50,
        "pages": 2,
        "next": "https://mycompany.com/api/orders?page=2",
        "prev": null
    },      
    "results": [
        {   
            "id": 1052,
            "name": "Alexander Cummings",
            “address”: “123 MyStreet”,
            "Item": "belt",
            "price": "15.00",
            "image": "https://mycompany.com/api/orders/avatar/1.jpeg",
	…

Im Admin Center werden nur die ersten Elemente der Array-Variablen angezeigt, damit erkennbar ist, welche Daten zurückgegeben werden. In der oben stehenden JSON-Ausgabe werden beispielsweise die Elemente id, name, address, item, price und image angezeigt. Diese Daten werden in der Regel an ein Karussell übergeben, in dem allerdings maximal 10 Elemente angezeigt werden können.

Hinweis: In der Antwort werden nur die ersten 280 Zeichen eines Eigenschaftswerts angezeigt.

Verschachtelte JSON-Arrays lassen sich auch als Array-Variablen speichern. Im Fall der folgenden JSON-Ausgabe können beispielsweise lastname und firstname als separate Array-Variablen gespeichert werden.

"name": 
   {
      "lastname": "Cummings”,
      "firstname": “Alexander"
   },

Sie können das Array oder die Array-Werte nicht in der Karussellkonfiguration im Admin Center bearbeiten. Wenn Sie Daten ändern möchten, müssen Sie das Array im Admin Center löschen und ein neues Array erstellen.

Wenn die zurückgegebene Variable null ist, wird das Element im Karussell nicht angezeigt. Nehmen wir beispielsweise an, dass der Wert der Variablen {{customer.order}} im folgenden Szenario leer ist. In diesem Fall wird Karte 1 mit dem Teiltitel „Order number“ dargestellt. Der Titel von Karte 2 ist leer, weshalb Karte 2 nicht angezeigt wird.

Card 1
Title: Order number {{customer.order}}
Description: Here's your order {{product.description}}

Card 2
Title: {{customer.order}}
Description: Here's your order {{product.description}}

Beispiel

In diesem Beispiel wird eine Array-Variable mit einem API-Endpunkt erstellt, die ein Array von Bestellungen zurückgibt. Das Array „orders“ wird durch die Eigenschaft „results“ im folgenden API-Antwort-Snippet spezifiziert.


     {
  "info": {
   "count": 5,
   "pages": 1
  },
  "results": [
   {
    "createdAt": "July 10, 2023",
    "name": "Connie Stokes",
    "Shippingaddress": "123 Street, City, State",
    "order": {
      "Status": "Ordered",
      "Image": "https://images.pexels.com/photos/1484808/pexels-photo-1484808.jpeg"
    },
    "Quantity": 1,
    "Price": 45,
    "Item": "Shirt",
    "id": "1"
   },
…

In diesem Beispiel wird API-Aufruf durchführen verwendet, um die Array-Variable zu erstellen, und dann ein dynamisches Karussell, um die Ergebnisse einem Endbenutzer anzuzeigen.

So erstellen Sie das Array

Klicken Sie im Konfigurationsfenster auf API-Aufruf durchführen.
Geben Sie als Namen orders ein.
Klicken Sie im Konfigurationsfenster auf API-Details.
Klicken Sie auf das Dropdownmenü Anfragemethode und dann auf GET.
Geben Sie die Endpunkt-URL ein.
Wählen Sie unter Authentifizierung Ihre Authentifizierungsmethode aus.
Weitere Informationen finden Sie unter Erstellen von API-Verbindungen für Bot-Builder.
Klicken Sie auf API-Aufruf durchführen.
Klicken Sie neben den Ergebnissen auf Speichern.
Klicken Sie im Pulldownmenü Wert auf Order und dann auf Image.
Verwenden Sie den Standardvariablennamen („image“).
Klicken Sie auf Element hinzufügen und wiederholen Sie den obigen Schritt, um Elemente für Order Status und Element zu erstellen.
Sie können bis zu 12 Elemente (oder Schlüssel-Wert-Paare) hinzufügen.
Klicken Sie auf Speichern.

So erstellen Sie das dynamische Karussell

Klicken Sie im Bot-Builder unter API-Aufruf erfolgreich auf Schritt hinzufügen und dann auf Karussell hinzufügen.
Klicken Sie im Konfigurationsfenster auf In dynamische Nachricht umwandeln.
Klicken Sie im Dropdownmenü Array auf results. Das ist das Array, das Sie oben erstellt haben.
Klicken Sie für den Titel auf das Pluszeichen und wählen Sie results.item.
Sie können für den Titel und die Beschreibung bis zu 128 Zeichen eingeben.
Klicken Sie unter Button link auf das Pluszeichen und wählen Sie results.image.
Klicken Sie unter Button text auf das Pluszeichen und wählen Sie results.status.
Klicken Sie unter Image link auf das Pluszeichen und wählen Sie results.image.
Klicken Sie auf Fertig.

Hier ist ein Beispiel für ein dynamischen Karussell.

Ü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.

In den folgenden Fällen durchläuft der Bot die Verzweigung „Fehler“:

Die API gibt den Antwortcode 400 oder 500 zurück.
Die API gibt den Antwortcode 200 zurück (eine der gespeicherten Variablen fehlt oder weist den Wert null auf).

In allen anderen Fällen durchläuft der Bot die Verzweigung „Erfolg“.

Durch Verwendung des Schritts API-Aufruf durchführen erkennen Sie an, dass das externe 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.