VoiceBot API

The TENIOS VoiceBot API enables the integration of any bot system to the telephony channel. The TENIOS API works as a link between the interface of the bot system and the telecommunication network. By combining state-of-the-art TTS (Text-to-Speech) and STT (Speech-to-Text) technology, the bot is given a voice that enables real-time voice dialogue.

VoiceBot API en

 

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 Control API

 

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":20xxxx,"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: 200xxx
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" ],                                   		 (optional) 
               "asrStart" : true,                                                                (optional)
               "asrStartOffsetMs" : -1500                                                        (optional)
                
}

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.

On request, the integration of TTS / ASR services can also be offered as an on-premise model. Please contact sales@tenios.de.

 

Architecture of VoiceBot API technology

VoiceBot API Requests en

 

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 
BRIDGE: Initiates Call Forward via a) external target number, b) SIP account or c) SIP trunk.
ANNOUNCEMENT:  Using this block, announcements that were loaded in the TENIOS customer portal can be played.
ROUTINGPLAN: This block can be used to integrate pre-defined routingplans in the call flow.
HANGUP:  It can be used to terminate a call.
CALL SETTINGS: This function replaces the original number of the caller with a CallerID / signaling number. This number must be in the TENIOS number pool. In addition, so-called X headers can be set in the SIP protocol, which are transmitted to the customer system via the SIP trunk.
COLLECT DIGITS:  This is used to request keyboard input (DTMF). In the routing block, the caller is requested to enter the numbers via DTMF. The input is defined as a variable for the internal processing of the requests.
SAY: In this case, the customer’s system transmits a text. TENIOS converts the text into audio and plays it back. The conversion is done by voice output via the text-to-speech cloud services of Google, Amazon or Microsoft.
REFER-CALL: By using the Refer Call API, it is possible to return live calls to the customer’s system via SIP trunk.

 

Please note:
In the routing plan, further steps can be set as blocks after the “Call Control API” routing block. If no response or an incorrect response is transmitted by the customer system, the routing plan continues with these blocks.
This ensures that
a) errors in the transmission or in the format of the response do not lead to a call abort and
b) dynamic call routing with call control can be combined with static elements in the routing plan.

 

For the structure and the definition of the parameters, please refer to the documentation on the following page: https://www.tenios.de/en/doc/api-spec

TENIOS prepared some sample applications and made them available on Github. See https://github.com/teniosgmbh/tenios-api-examples/tree/master/external-call-control-java

TOP