API für SMS Gateway

Sie können das Verhalten von SMS Gateway und den Ablauf einer SMS-Sitzung steuern, indem Sie Aktionen und Statusvariablen mit dem IBM Watson™ Assistant-Service austauschen. Aktionstags leiten Aktionen ein, die SMS Gateway während einer Conversation-Sitzung ausführt, und Statusvariablen werden von SMS Gateway gesendet, um die Sitzungsmerkmale anzugeben.

Aktionstags

Wenn Sie Aktionen in SMS Gateway initiieren möchten, können Sie Aktionstags in einem Watson Assistant-Dialogknoten im JSON-Format über die Eigenschaft output definieren. Definieren Sie für jede Aktion eine smsAction-Eigenschaft, die sich aus der Eigenschaft command und einer optionalen Eigenschaft parameter zusammensetzt, um Attribute für Befehle zu definieren, die für diese Eigenschaften erforderlich sind.

Wenn beispielsweise ein Knoten, der die folgende Aktion enthält, ausgelöst wird, wird das Sitzungszeitlimit auf 200 Sekunden gesetzt. 

{
  "output": {
    "smsAction": {
      "command": "setSessionTimeoutCount",
      "parameters":{
            "count": 200
       }
    }
  }
}

Wenn ein Knoten ausgelöst wird, der smsActSendMedia enthält, wird das MMS-Messaging aktiviert.

{
  "output": {
    "smsAction": {
      "command": "smsActSendMedia",
          "parameters":{
            "mediaURL": [
              "https://exampleonly.com/media/l4JyRqcDU93S334KQ/first.gif",
              "https://exampleonly.com/media/tK9wGsGc72LcznCSeU/second.gif"
            ]
         }  
      }
   }   
}

In der folgenden Tabelle sind die Aktionen, die Sie im Watson Assistant-Dialog angeben können, sowie die für jede Aktion definierbaren Attribute aufgelistet.

Tabelle 1. Aktionen, die von Watson Assistant initiiert werden können
Aktionsbefehl Beschreibung Attribute
setSessionTimeoutCount Aktualisiert das Sitzungszeitlimit. count: Zeit in Sekunden
smsActForceNoInputTurn Erzwingt einen neuen Conversation-Turnus, ohne auf eine Eingabe vom Benutzer zu warten. SMS Gateway sendet eine Nachrichtenanforderung mit der Angabe smsNoInputTurn im Textfeld, sodass Sie diese Anforderung einem Intent in Ihrem Dialog zuordnen können. Ohne
smsActSetConversationConfig Gilt für eine Gruppe von Parametern, um einen Watson Assistant-Arbeitsbereich oder eine Serviceorchestrierungsengine zu konfigurieren. Weitere nformationen finden Sie unter Watson Assistant-Service oder Serviceorchestrierungsengine dynamisch konfigurieren. Alle der folgenden Parameter werden unterstützt. Weitere Informationen finden Sie unter Erweiterte JSON-Konfigurationseigenschaften für SMS Gateway.
  • url
  • workspaceID
  • username
  • password
  • convApiVersion
  • apikey
  • tokenAuthEnabled
    • tokenServiceProviderURL
  • conversationFailedReplyMessage
  • convConnectTimeout
  • convReadTimeout
  • convMaxRetryNo
  • convRetryInterval
terminateSession Beendet die zugeordnete Sitzung. Nicht zutreffend
smsActSendMedia Aktiviert MMS-Messaging. mediaURL: Gibt ein JSON-Array mit öffentlich zugänglichen Medien-URLs an, die an den Benutzer gesendet werden.

Von SMS Gateway gesendete Statusvariablen

Zur Angabe einer Statusänderung in der SMS-Sitzung sendet SMS Gateway mit jeder Nachrichtenanforderung Kontextvariablen an Watson Assistant. Da der Watson Assistant-Dialog statusunabhängig ist, werden alle Status in SMS Gateway beim Austausch mit Watson Assistant. Dies bedeutet, dass der Abschnitt context bei jedem Watson Assistant-Turnus innerhalb einer Chatsitzung an Watson Assistant weitergeleitet, vom Dialog verarbeitet oder aktualisiert und von Watson Assistant wieder empfangen wird.

Für einen Basisturnus in der SMS-Sitzung, die nur erforderliche Werte verwendet, sendet SMS Gateway beispielsweise das folgende context-Objekt. 

{
  "context": {
      "smsTenantPhoneNumber": "+12345556789",
    "smsUserPhoneNumber": "+18765554321",
    "smsSessionID": "a23de67h-e527-40d5-a867-5c0ce9e72d0d"
  }
}

Die folgenden Statusvariablen werden von SMS Gateway in der Nachrichtenanforderung gesendet. Die Werte smsTenantPhoneNumber, smsUserPhoneNumber, smsUserData und smsSessionTimeoutCount werden direkt aus der Sitzungs-REST-API extrahiert.

Tabelle 2. Von SMS Gateway gesendete Kontextvariablen
Statusvariable Beschreibung
smsTenantPhoneNumber Die SMS Gateway-Tenanttelefonnummer, die der Benutzer übermittelt.
smsUserPhoneNumber Die Telefonnummer des Benutzers, der Nachrichten mit SMS Gateway austauscht.
smsUserData Daten im JSON-Format, die an die Serviceorchestrierungsengine oder den Watson Assistant-Service übergeben werden sollen. Diese Variable wird nur gesendet, wenn die Sitzung über den SMS Gateway-Tenant gestartet wird und die Daten über die REST-API gesendet werden.
smsSessionTimeoutCount Der Wert für das Sitzungszeitlimit. Diese Variable wird nur gesendet, wenn der Zeitlimitwert über die REST-API definiert ist.
smsError Wenn SMS Gateway keine SMS-Nachricht senden kann, enthält diese Variable Details zu dem aufgetretenen Fehler.
smsSessionID Die GUID für die zugehörige SMS Gateway-Sitzung.
smsMedia Die arraylist von mediaURL und der entsprechende mediaContentType. Diese Kontextvariable wird am Ende von jedem Conversation-Turnus gelöscht.

Textschlüsselwörter

Bestimmte Ereignisse bewirken, dass SMS Gateway ein Textschlüsselwort in der Nachrichtenanforderung an Watson Assistant sendet. Sie können diese Textschlüsselwörter für die weitere Verarbeitung in einer Serviceorchestrierungsengine oder Analyse verwenden.

In der folgenden Tabelle ist der genaue Textwert, der von SMS Gateway gesendet wird, und das auslösende Ereignis aufgeführt.

Tabelle 3. Von SMS Gateway gesendete Textwerte
Textwert Ereignis
smsError Wird gesendet, wenn beim Senden einer abgehenden SMS-Nachricht an den SMS-Provider ein Fehler auftritt.
smsResponseTimeout Wird gesendet, wenn ein Sitzungszeitlimit auftritt, wenn der Benutzer nicht innerhalb der smsSessionTimeoutCount festgelegten Zeit antwortet.

Im Watson Assistant-Dialog definierte Variablen

Sie können die folgenden Statusvariablen im Watson Assistant-Dialog setzen, um das SMS Gateway-Verhalten zu ändern. Wenn eine Variable mit einer zugehörigen Umgebungsvariablen nicht gesetzt ist, wird der Wert aus der zugehörigen Umgebungsvariablen verwendet.

Tabelle 4. Im Watson Assistant-Dialog definierte Variablen
Statusvariablenname Erwarteter Wert Beschreibung Zugehörige Umgebungsvariable
smsConversationResponseTimeout Zeit in Millisekunden Die Zeit in Sekunden, die SMS Gateway auf den Empfang einer Antwort vom Watson Assistant-Service wartet. Wenn die Zeit überschritten wird, versucht SMS Gateway erneut, eine Verbindung zum Watson Assistant-Service herzustellen. Wenn der Service daraufhin immer noch nicht erreicht werden kann, schlägt die SMS-Antwort fehl. Version 1.0.0.5a und höher. WATSON_CONVERSATION_READ_TIMEOUT