AudioCodes Voice.AI Gateway Integration Guide

Integration Guide

AudioCodes Intuitive Human Communications for Chatbot Services

Voice.AI Gateway

Version 1.8

Notice

Voice.AI Gateway | Integration Guide

Notice

Information contained in this document is believed to be accurate and reliable at the time of printing. However, due to ongoing product improvements and revisions, AudioCodes cannot guarantee accuracy of printed material after the Date Published nor can it accept responsibility for errors or omissions. Updates to this document can be downloaded from

https://www.audiocodes.com/library/technical-documents.

This document is subject to change without notice.

Date Published: August-20-2020

WEEE EU Directive

Pursuant to the WEEE EU Directive, electronic and electrical waste must not be disposed of with unsorted waste. Please contact your local recycling authority for disposal of this product.

Customer Support

Customer technical support and services are provided by AudioCodes or by an authorized AudioCodes Service Partner. For more information on how to buy technical support for AudioCodes products and for contact information, please visit our website at

https://www.audiocodes.com/services-support/maintenance-and-support.

Documentation Feedback

AudioCodes continually strives to produce high quality documentation. If you have any comments (suggestions or errors) regarding this document, please fill out the Documentation Feedback form on our website at https://online.audiocodes.com/documentation-feedback.

Stay in the Loop with AudioCodes

- ii -

Notice

Voice.AI Gateway | Integration Guide

Notes and Warnings

OPEN SOURCE SOFTWARE. Portions of the software may be open source software and may be governed by and distributed under open source licenses, such as the terms of the GNU General Public License (GPL), the terms of the Lesser General Public License (LGPL), BSD and LDAP, which terms are located at

https://www.audiocodes.com/services-support/open-source/ and all are incorporated

herein by reference. If any open source software is provided in object code, and its accompanying license requires that it be provided in source code as well, Buyer may receive such source code by contacting AudioCodes, by following the instructions available on AudioCodes website.

Document Revision Record

LTRT Description

30920 Initial document release.

30921 Parameters added- sttContextId, , sttContextPhrases, sttContextBoost.

30922 "Amazon Lex" and "Google Dialogflow" terms added; AudioCodes API syntax

example for initial sent message; hangupReason updated (CDR); handover changed to transfer; event type (e.g., string) added; sttEndpointID (description updated)' miscellaneous.

30923 Updated to Ver. 1.4. VOICE_AI_WELCOME event replaced by WELCOME.

30924 Dialogflow text length limitation; typo (Product Notice replaced by Product

Description).

30926 Updated to Ver. 1.6; Nuance add for STT/TTS; transferSipHeaders (typo);

transferReferredByURL (added); sttContextId (updated)

30927 Bot-controlled parameters added.

- iii -

Notice

Voice.AI Gateway | Integration Guide

LTRT Description

30928 Updated to Ver. 1.8. startRecognition and stopRecognition (added to activities);

participant (added to initial message); participant, from, and participantUriUser (added to text message); sendMetaData (added to activities)

30929 No User Input Event section added; DTMF Event corrected re "value"

- iv -

Content

Voice.AI Gateway | Integration Guide

1 Introduction 1

Purpose 1 Targeted Audience 1

2 Required Information 2

Required Information of Bot Framework Provider 2 Required Information of STT Provider 3 Required Information of TTS Provider 4

3 Messages Sent by Voice.AI Gateway 7

Initial Message 7 End of Conversation Message 10 Text Message 10 DTMF Event 12 No User Input Event 13

4 Messages Sent by Bot 15

Basic Activity Syntax 15 message Activity 15 event Activities 16

hangup 17

transfer 17

Adding SIP Headers on Call Transfer 18

playUrl 19

config 20

startRecognition and stopRecognition 20

sendMetaData 21

Bot Framework Specific Details 21

AudioCodes Bot API 21

Microsoft Azure 21

Google Dialogflow 22

Parameters Controlled Also by Bot 24

- v -

CHAPTER1 Introduction

1 Introduction

AudioCodes Voice.AI Gateway enhances chatbot functionality by allowing human communication with chatbots through voice (voicebot), offering an audio- centric user experience. Integrating the Voice.AI Gateway into your chatbot environment provides you with a single-vendor solution, assisting you in migrating your text-based chatbot experience into a voice-based chatbot.

● Prior to reading this document, it is recommended that you read the Voice.AI

Gateway Product Description to familiarize yourself with AudioCodes Voice.AI

Gateway architecture and solution.

● Most of the information provided in this document is relevant to all bot frameworks.

Where a specific bot framework uses different syntax, a note will indicate this.

Purpose

Voice.AI Gateway | Integration Guide

This guide provides the following:

■ Information that you need to supply AudioCodes for connecting the Voice.AI Gateway to

the third-party cognitive services used in your chatbot environment - bot framework(s), speech-to-text (STT) engine(s), and text-to-speech (TTS) engine(s).

■ Description of the messages sent by the Voice.AI Gateway to the bot, and messages sent

by the bot to the Voice.AI Gateway to achieve the desired functionality. These descriptions allow the bot developer to adapt the bot's behavior to the voice and telephony engagement channels.

Targeted Audience

This guide is intended for IT Administrators and Bot Developers who want to integrate AudioCodes Voice.AI Gateway into their bot solution.

- 1 -

CHAPTER2 Required Information

2 Required Information

This section lists the information that you need to supply AudioCodes for integrating and connecting the Voice.AI Gateway to the cognitive services of your chatbot environment. This includes information of the bot framework, Speech-to-Text (STT) provider, and Text-to-Speech (TTS) provider used in your environment.

Required Information of Bot Framework Provider

To connect the Voice.AI Gateway to bot frameworks, you need to provide AudioCodes with the bot framework provider's details, as listed in the following table.

Table 2-1: Required Information per Bot Framework

Voice.AI Gateway | Integration Guide

Bot

Framework

Microsoft Azure

AWS

Required Information

To connect to Microsoft Azure Bot Framework, you need to provide AudioCodes with the bot's secret key. To obtain this key, refer to Azure's documentation at https://docs.microsoft.com/en-us/azure/bot-

service/bot-service-channel-connect-directline.

Note: Microsoft Azure Bot Framework Direct Line Version 3.0 must be used.

To connect to Amazon Lex, you need to provide AudioCodes with the following:

■ AWS account keys:

✔ Access key

✔ Secret access key

To obtain these keys, refer to the AWS documentation at

https://docs.aws.amazon.com/general/latest/gr/managing-awsaccess-keys.html.

Note: The same keys are used for all Amazon services (STT, TTS and

bot framework).

Google

■ Name of the specific bot

■ AWS Region (e.g., "us-west-2")

To connect to Google Dialogflow, you need to provide AudioCodes with the following:

■ Private key of the Google service account. For information on how to

create the account key, refer to Google's documentation at

https://cloud.google.com/iam/docs/creating-managing-service-

- 2 -

CHAPTER2 Required Information

Voice.AI Gateway | Integration Guide

Bot

Framework

Required Information

account-keys. From the JSON object representing the key, you need to

extract the private key (including the "-----BEGIN PRIVATE KEY-----" prefix) and the service account email.

■ Client email

■ Project ID (of the bot)

AudioCodes Bot API

To create the channel between the Voice.AI Gateway's Cognitive Service component and the bot provider, refer to the document Voice.AI Gateway

API Reference Guide.

Required Information of STT Provider

To connect the Voice.AI Gateway to third-party, speech-to-text (STT) engines, you need to provide AudioCodes with the STT provider's details, as listed in the following table.

Table 2-2: Required Information per Supported STT Provider

STT

Provider

Microsoft Azure Speech Services

Required Information from STT Provider

Connectivity Language Definition

To connect to Azure's Speech Service, you need to provide AudioCodes with your subscription key for the service.

To obtain the key, see Azure's documentation at

https://docs.microsoft.com/enus/azure/cognitiveservices/speech-service/getstarted.

Note: The key is only valid for a

specific region.

To connect to Azure Speech Services, you need to provide AudioCodes with the following:

■ Relevant value in the 'Locale' column

in Azure's Text-to-Speech table (see below).

For example, for Italian (Italy), the 'Locale' column value is "it-IT".

For languages supported by Azure's Speech Services, see the Speech-to-text table in Azure's documentation at

https://docs.microsoft.com/enus/azure/cognitive-services/speechservice/language-support.

- 3 -

The Voice.AI Gateway can also use Azure's Custom Speech service. For more information, see Azure's documentation at

https://docs.microsoft.com/en-

CHAPTER2 Required Information

Voice.AI Gateway | Integration Guide

STT

Provider

Google Cloud Speechto-Text

Required Information from STT Provider

To connect to Google Cloud Speech-to-Text service, see

Required Information of Bot Framework Provider on page2

for required information.

us/azure/cognitive-services/speechservice/how-to-custom-speech-deploymodel . If you do use this service, you

need to provide AudioCodes with the custom endpoint details.

To connect to Google Cloud Speech-toText, you need to provide AudioCodes with the following:

■ Relevant value in the 'languageCode'

column in Google's Cloud Speech-toText table (see below).

For example, for English (South Africa), the 'Language code' column value is "enZA".

For languages supported by Google Cloud Speech-to-Text, see Google's documentation at

https://cloud.google.com/speech-totext/docs/languages.

Yandex

Nuance

Contact AudioCodes for more information.

Required Information of TTS Provider

To connect the Voice.AI Gateway to third-party, text-to-speech (TTS) engines, you need to provide AudioCodes with the TTS provider's details, as listed in the following table.

Table 2-3: Required Information per Supported TTS Provider

TTS

Provide

Micros oft

Connectivity Language Definition

To connect to Azure's Speech Service, you need

Required Information from TTS Provider

To connect to Azure Speech Services, you need to provide AudioCodes with the following:

- 4 -

CHAPTER2 Required Information

TTS

Provide

Voice.AI Gateway | Integration Guide

Required Information from TTS Provider

Azure Speech Service s

Google Cloud TexttoSpeech

to provide AudioCodes with your subscription key for the service.

To obtain the key, see Azure's documentation at

https://docs.microsoft.c om/enus/azure/cognitiveservices/speechservice/get-started.

Note: The key is valid

only for a specific region.

To connect to Google Cloud Text-to- Speech service, see Required

Information of Bot Framework Provider on

page2 for required

information.

■ Relevant value in the 'Locale' column in

Azure's Text-to-Speech table (see below link).

■ Relevant value in the 'Short voice name'

column in Azure's Text-to-Speech table (see below link).

For example, for Italian (Italy), the 'Locale' column value is "it-IT" and the 'Short voice name' column value is "it-IT-ElsaNeural".

For languages supported by Azure's Speech Services, see the Text-to-Speech table in Azure's documentation at

https://docs.microsoft.com/enus/azure/cognitive-services/speechservice/language-support.

To connect to Google Cloud Text-to-Speech, you need to provide AudioCodes with the following:

■ Relevant value in the 'Language code' column

in Google's table (see below link).

■ Relevant value in the 'Voice name' column in

Google's table (see below link).

AWS Amazo n Polly

To connect to Amazon Polly Text-to-Speech service, see Required

Information of Bot Framework Provider on

page2 for required

information.

For example, for English (US), the 'Language code' column value is "en-US" and the 'Voice name' column value is "en-US-Wavenet-A".

For languages supported by Google Cloud Textto-Speech, see Google's documentation at

https://cloud.google.com/text-tospeech/docs/voices.

To connect to Amazon Polly TTS service, you need to provide AudioCodes with the following:

■ Relevant value in the 'Language' column in

Amazon Polly TTS table (see below link).

■ Relevant value in the 'Name/ID' column in

Amazon Polly TTS table (see below link).

For example, for English (US), the 'Language' column value is "English, US (en-US)" and the

- 5 -

CHAPTER2 Required Information

TTS

Provide

Voice.AI Gateway | Integration Guide

Required Information from TTS Provider

'Name/ID' column is "Matthew".

For languages supported by Amazon Polly TTS service, see the table in

https://docs.aws.amazon.com/polly/latest/dg/v oicelist.html.

Yandex

Almag u

Nuanc e

Contact AudioCodes for more information.

- 6 -

CHAPTER3 Messages Sent by Voice.AI Gateway

3 Messages Sent by Voice.AI Gateway

This section describes the messages that are sent by the Voice.AI Gateway.

Initial Message

When the conversation starts, a message is sent with the details of the call. These details include (when available) the following:

Table 3-1: Description of Initial Message Sent by Voice.AI Gateway

Property Type Description

Voice.AI Gateway | Integration Guide

callee

calleeHost

caller

callerHost

callerDisplayNa

<Additional

attributes>

String Dialed phone number. This is typically obtained

from the SIP To header.

String Host part of the destination of the call. This is

typically obtained from the SIP To header.

String Caller's phone number. This is typically obtained

from the SIP From header.

String Host part of the source of the call. This is typically

obtained from the SIP From header.

String Caller's display name. This is typically obtained from

the SIP From header.

- Defines additional attributes such as values from various SIP headers. These can be added by customization. The Voice.AI Gateway can be configured to extract values from the SIP INVITE message and then send them as additional attributes in the initial message to the bot.

participants

Array of Object s

Participants of the conversation when the Voice.AI Gateway is used with the SBC's SIPRec feature (e.g., for the Agent Assist solution). This parameter includes the following sub-parameters:

■ participant: (String) Role of the participant,

which can be one of the following values:

✔ caller

✔ callee

✔ user defined

- 7 -

CHAPTER3 Messages Sent by Voice.AI Gateway

Property Type Description

Voice.AI Gateway | Integration Guide

The value is obtained from the 'ac:role' element in the SIPRec XML body. The values should be set in the SIPRec XML using the SBC's Message Manipulation functionality, under the <participant> element, as shown in the following example:

<participant id="+123456789" session="0000-0000-0000-0000b44497aaf9597f7f"> <nameID aor="+123456789@example.com"></ nameID> <ac:role>caller</ac:role> </participant>

The values must be unique.

■ uriUser: (String) User-part of the URI of the

participant. The value is obtained from the userpart of the 'aor' property of the 'nameID' element in the SIPRec XML body.

■ uriHost: (String) Host-part of the URI of the

participant. The value is obtained from the hostpart of the 'aor' property of the 'nameID' element in the SIPRec XML body.

■ displayName: (String) Display name of the

participant. The value is obtained from the 'name' sub-element of the 'nameID' element in the SIPRec XML body.

The syntax of the initial message depends on the specific bot framework:

Table 3-2: Syntax of Initial Message Sent by Voice.AI Gateway

Bot

Framework

Message Syntax

AudioCodes Bot API

The message is sent as a start event, with the details inside the

parameters property.

Example:

{

"type": "event",

"name": "start",

- 8 -

+ 29 hidden pages

AudioCodes Voice.AI Gateway Integration Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Notes and Warnings

Related Documentation

Document Revision Record

Table of Contents

1 Introduction

Purpose

Targeted Audience

2 Required Information

Required Information of Bot Framework Provider

Required Information of STT Provider

Required Information of TTS Provider

3 Messages Sent by Voice.AI Gateway

Initial Message