Dokumentation

Call Control Voice API

Das Konzept für Call Control sieht vor, dass die Anrufsteuerung von der kundenseitigen Anwendung übernommen wird. TENIOS übernimmt auf Basis der Steuerungsbefehl (Routing-Blöcke) die Anrufverarbeitung auf seiner Cloud Communications Plattform. Diese Funktion wird aktiviert, indem ein Call Control API Block in einem Routingplan eingefügt wird (Details finden Sie hier).

Um die Call Control API nutzen zu können, brauchen Sie einen HTTPS-fähigen Webserver (z. B. Apache httpd oder nginx), der bereits für die Verarbeitung von HTTPS-Verkehr (SSL / TLS) konfiguriert ist. Welche Anpassungen Sie vornehmen sollen, finden Sie hier. 

 

Anfrageparameter (von TENIOS zu Ihrem Server):

requestTypeDer Typ der API-Anfrage.
Hat immer den Wert EXTERNAL_CALL_CONTROL für alle External Call Control API Anfragen
customerNumber Ihre Kundennummer (Der selbe Wert, den Sie auch in Klammern in der rechten oberen Ecke des Kundenportals sehen).
Bitte überprüfen Sie diesen Wert bei jeder Anfrage.
accessKeyDer accessKey, den Sie in Ihrer Konfiguration des Call Control API block (Im TENIOS-Kundenportal) definiert haben.
Der access key muss von Ihnen definiert werden und dient zur Absicherung der API gegen unbefugten Zugriff. Bitte überprüfen Sie diesen Wert bei jeder Anfrage.
variablesEine key/value Map mit den Keys, die mit übermittelt werden.
Kann für beliebige Zwecke verwendet werden, z.B. Logging oder zum Bestimmen der nächsten Schritte.
loopCountBeginnend von 0, die Anzahl der Anfragen, die innerhalb dieser Instanz des Call Control API Blocks gemacht wurden.
In vielen einfachen Anwendungen, können alle Blöcke in der initialen Anfrage zurückgegeben werden, wenn der loopCount gleich 0 ist. Bei komplizierteren Anwendungen ist es eventuell erforderlich, verschiedene Blöcke bei mehreren Iterationen zurückzugeben.
requestStatusMögliche Typen sind:

  • REQUESTING_BLOCKS: bedeutet, dass Sie berechtigt sind einen oder mehrere Blöcke in der Antwort zurückzugeben.
  • VALIDATION_ERRORS: bedeutet, dass es bei der Ausführung der zuvor gesendeten Blöcke Validierungsfehler gegeben hat.
    • Sehen Sie sich hierzu die im Feld blocksProcessingResult aufgelisteten validationErrors an.
    • ZUDEM sind Sie nicht mehr berechtigt weitere Blöcke in Ihrer Antwort zurückzugeben (werden doch Blöcke zurückgegeben, werden diese ignoriert). Sehen Sie dazu das „Basisbeispiel“ und das „Basisbeispiel mit Error“.

 

blocksProcessingResult
(nur wenn loopCount > 0)		Enthält das Feld validationErrors , welches eine Liste von Fehlermeldungen enthält.                          In zukünftigen Versionen kann das blocksProcessingResult weitere Informationen beinhalten.

Antwortparameter (von Ihren Server an TENIOS ):

blocksEin Array von Blöcken. Wenn dieses Array leer ist, wird von TENIOS die Ausführung des Call Control API Blocks beendet.

 

Jeder Block muss das folgende Format haben:

blockType
Obligatorisch 		Art des Blockes. Mögliche Typen sind:

  • BRIDGE: Anrufweiterleitung (PARALLEL oder SEQUENTIAL)
  • ANNOUNCEMENT: Abspielen von Ansagen (Standard/Vordefinierte Ansagen oder Ansagen, die über TENIOS Kundenportal definiert wurden)
  • SAY: für gesprochene Texte (Text-to-Speech)
  • ROUTINGPLAN: kann verwendet werden, um einen Routingplan zurückzugeben. Routingpläne können im TENIOS Kundenportal angelegt werden
  • COLLECT_DIGITS: kann verwendet werden, um (mehrere) Ziffern über DTMF in einer benannten Variable zu sammeln. Hinweis: Sie können den Wert dieser Variablen in den nachfolgenden Anforderungen für die externe Anrufsteuerung für denselben Anruf sehen.
  • COLLECT_SPEECH: kann verwendet werden um Sprache zu erkennen bzw. in Text umzuwandeln. Der erkannte Text wird in der unter variableName angegebenen Variablen gespeichert.
  • HANGUP: kann verwendet werden um einen Anruf mit einem bestimmten Auflegegrund zu trennen.
  • CALL_SETTINGS: setzt eine CallerID, die beim Anruf angezeigt werden soll.
blockTimeout

 

Timeout in Sekunden für den gesamten Block.

Einige Blöcke benötigen dieses Attribut, bei anderen ist es NICHT erlaubt

  • BRIDGE blocks im PARALLEL Modus benötigt dieses Attribut
  • BRIDGE blocks in SEQUENTIAL Modus ist dieses Attribut NICHT erlaubt
  • ANNOUNCEMENT ist dieses Attribute NICHT erlaubt
  • HANGUP ist dieses Attribute NICHT erlaubt
Weitere Informationen zu den blockspezifischen Attributen sowie Beispiele finden Sie hier.

Prozessablauf:

 

 

  Der content-type für alle HTTPS-Anfragen und Antworten in diesem API ist application/json. 

Bei der Ausführung eines Call Control API Blocks im Routingplan, wird eine POST-Anfrage von TENIOS an Ihren Server geschickt. 

TENIOS POST-Request 0:

{ 
    "requestType" : "EXTERNAL_CALL_CONTROL", 
    "customerNumber" : 200000, 
    "accessKey" : "XXXXX-XXXX-XXXXXX", 
    "variables" : { 
                    "call_uuid" : "1ecd8430-a926-11e3-a701-f9e70cd7ff59", 
                    "destination_number" : "+49800123456789", 
                    "caller_id_number" : "+4989444444444" 
                  }, 
    "loopCount" : 0, 
    "requestStatus" : "REQUESTING_BLOCKS",  
    "blocksProcessingResult" : null 
}
  • loopCount: 0 bedeutet, dass dieses die erste Anfrage von diesem Call Control API Block ist (es gibt noch weitere Anfragen, siehe weiter unten)
  • requestStatus: „REQUESTING_BLOCKS“  bedeutet, dass Sie berechtigt sind Routing-Blöcke in Ihrer Antwort zu senden
  • Ein blocksProcessingResult mit dem Wert null, kann bei dieser ersten Anfrage ignoriert werden 

Beispiel-Antwort von Ihren Server an TENIOS

Sie können auf diese HTTPS-Anfrage wie folgt antworten:

Kundenserver-Response 0:

mit einem Block
{
  "blocks" : [ {
    "blockType" : "ANNOUNCEMENT",
    "announcementName" : "Voicemail_Ansage",
    "standardAnnouncement" : true
  } ]
}

  • Sie können auch mehrere mit Komma getrennte Ansagen innerhalb des Blocks senden
  • Der Ansage- Block (blockType: „ANNOUNCEMENT“) verwendet eine  vordefinierte (Standard-) Ansage. D.h.  KEINE  Ansage, die Sie selber hochgeladen haben.
  • Die Ansage ist definiert über den Namen „Voicemail_Ansage“  (Weitere Informationen erhalten Sie hier.)

Kundenserver-Response 0:

mit mehreren Blocks
{ 
   "blocks" :
   [ 
       { "blockType" : "ANNOUNCEMENT", 
         "announcementName" : "Voicemail_Ansage", 
         "standardAnnouncement" : true
       }, 
       { "blockType" : "SAY", 
          "text" : "Hello, how are you doing?", 
          "voiceName" : "de.female.3", 
          "useSsml" : false
       }, 
       {  
         "blockType" : "BRIDGE",
         "destinations" : [ { "destination" : "1001",
                              "destinationType" : "SIP_USER",
                              "timeout" : 25 }, 
                            { "destination" : "+4978787878",
                              "destinationType" : "EXTERNALNUMBER",
                              "timeout" : 30 }
                           ],
        "bridgeMode" : "SEQUENTIAL"
       }
   ] 
}

 

Sobald die Antwort von TENIOS empfangen wurde, werden die darin enthaltenen Blöcke ausgeführt. Vorausgesetzt die Antwort ist syntaktisch korrekt und die Ansage existiert und kann abgespielt werden, erhalten Sie danach weitere Anfragen wie folgt:

TENIOS POST-Request 1:

{
  "requestType" : "EXTERNAL_CALL_CONTROL",
  "customerNumber" : 200000,
  "accessKey" : "XXXXX-XXXX-XXXXXX",
  "variables" : {
    "call_uuid" : "1ecd8430-a926-11e3-a701-f9e70cd7ff59",
    "destination_number" : "+49800123456789",
    "caller_id_number" : "+4989444444444"
  },
  "loopCount" : 1,
  "requestStatus" : "REQUESTING_BLOCKS",
  "blocksProcessingResult" : {
    "validationErrors" : [ ]
  }
}
  • loopCount: 1 bedeutet, dass es sich um die zweite Anfrage Call Control API Blocks handelt.Die Zählung hat bei 0 begonnen, somit hat die zweite Anfrage den Wert 1
  • Der requestStatus hat weiterhin den Wert „REQUESTING_BLOCKS“, was bedeutet, dass Sie weiterhin berechtigt sind, Routing-Blöcke in Ihren Antworten zurückzugeben (falls gewünscht).
  • Der blocksProcessingResult beinhaltet ein leeres Array von validationErrors – was in diesem Fall positiv ist. Es bedeutet, dass in Ihrer zuvor gelieferten Antwort keine Validierungsfehler aufgetreten sind. 

In zukünftigen Versionen werden wahrscheinlich weitere Informationen für das blocksProcessingResult zur Verfügung stehen. Falls Ihnen an dieser Stelle Informationen fehlen, wenden Sie sich an unseren Kundensupport!

Wird der Anruf angenommen, erhalten sie keine weitere TENIOS Anfragen. Weitere Anrufinformationen in Echtzeit können Sie in den „Erweiterte Einstellungen“ für Rufnummern-Routing konfigurieren. Details finden Sie auch hier.

 

Angenommen Sie möchten jetzt keine weiteren Blöcke mehr zurückgeben. In diesem Fall senden Sie einfach die folgende Antwort zurück:

Kundenserver-Response 1:

keine weitere Blocks

{
   "blocks": []
}
Nachdem TENIOS diese Anfrage empfangen hat, wird mit der normalen Verarbeitung des Anrufs fortgefahren. Falls im Routingplan nach dem Call Control API Block weitere Blöcke konfiguriert sind, werden diese nun ausgeführt.

Beispiele für fehlerhafte Anfragen:

Für dem Fall, dass die von Ihnen gelieferte Antwort 0 Fehler enthält:

Kundenserver-Response 0:

(mit Fehler)

{ 
   "blocks" : [ 
               { "blockType" : "ANNOUNCEMENT", 
                 "standardAnnouncement" : true 
                } 
              ]
 }
In diesem Fall fehlt das Attribut für die Ansage.
Sobald einer der Blöcke, die Sie zurückgeben Validierungsfehler enthält, wird der Call Control API Block beendet.
Es wird aber eine weitere Anfrage geschickt mit Informationen zu dem Fehler der aufgetreten ist:

TENIOS POST-Request 1:

Informationen zu dem Fehler

{  
     "requestType" : "EXTERNAL_CALL_CONTROL", 
     "customerNumber" : 200000, 
     "accessKey" : "XXXXX-XXXX-XXXXXX",
     "variables" : { "call_uuid" : "1ecd8430-a926-11e3-a701-f9e70cd7ff59", 
                     "destination_number" : "+49800123456789", 
                     "caller_id_number" : "+4989444444444" }, 
     "loopCount" : 1,
     "requestStatus" : "VALIDATION_ERRORS", 
     "blocksProcessingResult" : { 
                                  "validationErrors" : [ "Validation error: blocks[0].announcementName may not be null" ]
                                 }
 }
  • Der requestStatus hat den Wert VALIDATION_ERRORS – was bedeutet, dass Sie keine weiteren Blöcke mehr in der Antwort zurücksenden können (Diese würden ignoriert) und Sie sich blocksProcessingResult genauer anschauen müssen
  • blocksProcessingResult enthält eine Liste von Fehlermeldungen, welche Ihnen bei der Fehleranalyse weiterhelfen können. Bitte beachten Sie, dass bei LOW-Level Fehlern auf JSON-Ebene nur die Zeilen und Spaltennummer geliefert bekommen.

 

Weitere Informationen zu den blockspezifischen Attributen sowie Beispiele finden Sie hier.
Call Control Funktionen können optional auch via Makecall Funktion integriert werden. Details finden Sie hier.

 

Allgemeine Hinweise

Wenn Sie eine Anfrage empfangen, haben Sie (derzeit) einen Zeitrahmen von 30 Sekunden, um eine Antwort zu schicken.

Bitte beachten Sie, dass in der Zeit zwischen dem TENIOS die Anfrage sendet und die Antwort empfängt, mit dem Anruf nichts gemacht wird. Sie sollten zusehen, dass Ihre Anwendung so schnell wie möglich auf Anfragen antwortet, damit keine unnötigen Verzögerungen entstehen.

Aus dem gleichen Grund, falls Sie mehrere Blöcke ausführen möchten, ist es am besten wenn Sie diese direkt nach der ersten Anfrage zurückgeben (falls Ihre Applikationslogik dieses erlaubt) und nicht jeden Block einzeln nach mehreren Anfragen zurückgeben. 

Wenn Sie eine HTTPS-Antwort mit einem Code ungleich 200 zurückgeben, wird der Call Control API Block beendet.

Um den Block korrekt zu beenden sollten Sie immer eine Antwort mit dem HTTP Code 200, und dem Inhalt  {„blocks“:[]} zurückliefern!

Dieser Artikel könnte Sie auch interessieren …