VoiceBot API

Die Funktion der VoiceBot API ist ein Element der TENIOS . The function of the VoiceBot API is an element of the TENIOS Voice API. The concept of the API is that call control is handled by the bot system. TENIOS handles the call processing on its cloud communications platform based on the control requests (routing blocks).

Benefits of the VoiceBot API

1. Bot extension for telephony channel as a standard service Through an API integration, you can easily extend existing bots (chatbots – messenger bots, in-app bots) for telephony in just a few steps. As a cloud communications provider, we only charge the actual usage costs without high integration and provisioning costs. You only pay for what you actually use. _
2. Open-API API integration is done via standardized interfaces. They use web services via https requests, which are already available for other channels. _
3. Full dialogue control Dynamic control of calls is done through our Voice API. You can control any service and route the call to different paths. The processing is done in real time. _
4. Telecommunication expertise managed by TENIOS As a long-standing cloud communications provider, we specialize in voice dialogue systems. We handle TTS and STT services in addition to telephony interfaces. Likewise, if you need to integrate interfaces to telephony systems, PBX or call center applications (ACD), you are in good hands with TENIOS.

Technical details

Function structure

The VoiceBot API function is initiated by an incoming call on the TENIOS platform. The calls are made via: a) a phone number in the TENIOS NGN network or via b) a SIP trunk (inbound call). In variant a) the subscribers either call the TENIOS number directly or are routed to this number by the customer’s telephony system. The so-called inbound call is made via the public telephone network. For variant b), a SIP trunk is set up in the TENIOS web portal. This trunk establishes a SIP connection between the customer’s IP-based telephony system and the TENIOS platform. The incoming calls are routed to TENIOS via this SIP trunk.

Setup routing

In the Routing menu of the phone number or SIP trunk, the “Call Control API” block is selected within the call flow (routing plan). For this purpose, the customer enters the URL of the web service as well as the access key (from the customer) for authentication. In the routing, this block can be combined with various options.

Call processing

As soon as the “Call Control API” routing block is selected in the flow menu, the API function is executed for incoming calls. With initiation, an https request is sent to the specified URL of the customer. In the request all call parameters like caller number (ANI) dialed number (DNIS), timestamp are transmitted. The transmission is done via https requests (POST) in JSON format.  

Request example:

POST /shop/products/ HTTP/1.1
Host: api.customerserver1.de
Content-Type: application/json

{
   "requestType": "EXTERNAL_CALL_CONTROL",
   "customerNumber": 200000,
   "accessKey": "XXXXXXXXXXXXXXX",
   "variables": {
      "destination_number": "+49XXXXXXX",
      "correlation_id": "yyyyyyyyyyyyyyyyyy",
      "call_uuid": "aaaabbbbcccccdddddeeee",
      "caller_id_number": "+49XXXXXXXX"
   },
   "callControlUuid": "sssstttttuuuuwwww",
   "loopCount": 0,
   "requestStatus": "REQUESTING_BLOCKS",
   "blocksProcessingResult": null
}

Request Body

{
   "requestType": "EXTERNAL_CALL_CONTROL",
   "customerNumber": 200000,
   "accessKey": "XXXXXXXXXXXXXX",
   "variables": {
      "destination_number": "+49XXXXXXXXX",
      "collected_myvar": "My name is Alex Gardner, I have a question.",
      "correlation_id": "XXXXXXXXXXXXXXXXXX",
      "call_uuid": "XXXXXXXXXXXXX",
      "caller_id_number": "+49XXXXXXX",
      "callControlUuid": "XXXXXXXXXXXXXXXX"
   },
   "loopCount": 1,
   "requestStatus": "REQUESTING_BLOCKS"
}

Call Control

When the “Call Control API” routing block is started, the bot system takes over call control. The TENIOS platform merely executes the call processing via the transmitted blocks. For this purpose, the customer-side system transmits the “Collect-Speech” routing block in the response of the https request (POST). This is also done in JSON format. After each response, TENIOS transmits all call parameters via API as an https request back to the customer URL.   COLLECT SPEECH The voice control is set via Collect Speech. In the routing block, the caller is asked to play back his request / information as speech. The conversion is performed by voice input via the Speech-to-Text (ASR – Automatic-Speech-Recognition) cloud services from Google, Amazon or Microsoft. The text is defined as a variable for internal processing of the requests.

Example JSON Response

{
   "blocks": [
      {
         "blockType": "COLLECT_SPEECH",
         "text": "Hello, how are you doing?",
         "missingInputText": "Sorry, can you please repeat?",
         "voiceName": "en.female.3",
         "useSsml": false,
         "asrProvider": "GOOGLE or MICROSOFT",
         "language": "en-GB",
         "variableName": "myvar",
         "maxTries": 3,
         "keywordHints": [
            "word1",
            "word2"
         ],
         "asrStart": true,
         "asrStartOffsetMs": -1500
      }
   ]
}

The response to the TENIOS https request from the bot system is in JSON format. In addition to the test for the announcement, the language and the ASR service are defined. For multi-language bots, two additional languages can be specified. The transcription of the ASR service is set in the “variableName” field. Hint-Words To improve the ASR, so-called hintwords can be specified for the bot. These are transmitted to the ASR service so that the recognition rate for the request is optimized.   Start ASR Funktion / Barge-in The VoiceBot API enables the activation of the ASR function while the announcement is played. This is done by analyzing the voice channel from the caller and the audio stream from the VoiceBot separately. The caller’s voice input is transcribed by the ASR function while the announcement is playing. Via the parameter “asrStartOffsetMs” you can define when the ASR should start before the end of the announcement.   Transfer recording of the voice input As an additional option, TENIOS can record the caller’s voice input and transmit it as a file with the content type audio/wav in Wav format. Within the call control block, TENIOS numbers the requests. The numbering is transmitted as “loopCount” in the request to the customer URL. The call_uuid is transmitted in each request. This is used for the unique assignment of the call.

Speech input (ASR/STT) / Speech output (TTS)

The input and output of speech is done via the services of Google, Microsoft and Amazon. For speech recognition, the voice recording is streamed to the STT service. This transmits the transcribed text back to TENIOS, which is then transmitted to the bot system via API. The cloud services are also used as the TTS service. In addition to the “normal” voices, HQ voices are also available.

Architecture of VoiceBot API technology

After the call is received via SIP trunk or via a TENIOS phone number, call processing starts on the TENIOS cloud communications platform. Via the “Call Control API” function defined in the routing plan, the connection to the VoiceBot API is established. This is linked to the desired TTS/STT provider, which converts the voice input received from the caller into text. The text-based output is transmitted to the connected chatbot engine, where it is decoded and processed using NLU and ML. The bot’s response is returned in text form to the VoiceBot API, where the conversion from text to speech (TTS) is performed and returned to the caller as a voice response. Optionally, bot agent handover can be integrated on the Cloud Communications platform, which transfers the caller to a live human agent if desired and required.

Additional functions