Connecting to bot frameworks

To connect VoiceAI Connect to a third-party bot framework, you need to provide AudioCodes with the details of the specific bot framework, as mentioned below for each bot framework provider.

Bot frameworks with direct speech services

Some bot frameworks that also support voice channels, whereby VoiceAI Connect can pass the user's audio stream directly to the bot, also provide speech-to-text and text-to-speech services. These can be used instead of employing dedicated speech service providers.

This feature can only be configured by the VoiceAI Connect Administrator, using the following bot parameters:

Parameter	Type	Description
directSTT	Boolean	Enables the use of the bot framework’s speech-to-text service instead of a standalone one. true false (Default) Note: The parameter is applicable only to Google (CX and ES) and Azure bot frameworks. For the Azure bot framework, both the `directTTS` and directSTT parameter must be configured to true. If you are using the `additionalSttProviders` parameter, `directSTT` parameter must be configured to `false`.
directTTS	Boolean	Enables the use of the bot framework’s text-to-speech service instead of a standalone one. true false (Default) Note: The parameter is applicable only to Google (CX and ES) and Azure bot frameworks. For the Azure bot framework, both the `directTTS` and directSTT parameter must be configured to true. If you are using the `additionalTtsProviders` parameter, `directTTS` parameter must be configured to `false`.

Parameter

Type

Description

directSTT

Boolean

Enables the use of the bot framework’s speech-to-text service instead of a standalone one.

true
false (Default)

Note:

The parameter is applicable only to Google (CX and ES) and Azure bot frameworks.
For the Azure bot framework, both the directTTS and directSTT parameter must be configured to true.
If you are using the additionalSttProviders parameter, directSTT parameter must be configured to false.

directTTS

Boolean

Enables the use of the bot framework’s text-to-speech service instead of a standalone one.

true
false (Default)

Note:

The parameter is applicable only to Google (CX and ES) and Azure bot frameworks.
For the Azure bot framework, both the directTTS and directSTT parameter must be configured to true.
If you are using the additionalTtsProviders parameter, directTTS parameter must be configured to false.

Microsoft Azure bot framework

To connect to the Microsoft Azure bot framework, you need to provide AudioCodes with the bot's secret key. To obtain this key, refer to Azure's documentation.

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

Configuration

The key is configured on VoiceAI Connect using the botSecret parameter in the bots section.

To overwrite the default URL (https://directline.botframework.com/v3/directline/) used to create a conversation with the Direct Line API, use the botURL parameter (string) in the providers section.

To specify a Direct Line endpoint, use the botHost parameter in the providers section.

The botHost parameter is applicable only to VoiceAI Connect Enterprise Version 2.6 and later.

The Azure bot framework supports the use of a voice channel. Therefore, instead of using a dedicated speech-to-text or text-to-speech service provider, you can use the bot for these services. To enable this, the VoiceAI Connect Administrator must configure both the directSTT and directTTS parameters to true.

Microsoft Copilot Studio

Open bot configuration

To connect to the Microsoft Copilot Studio bot framework, you need to provide AudioCodes with the bot's Direct Line Speech token endpoint.

To obtain this URL, go to Settings > Channels, click on the Direct Line Speech tile, and copy the Token Endpoint in your bot web page.

Configuration

The token endpoint is configured in VoiceAI Connect using the copilotTokenURL parameter in credentials parameter of the provider to the bot.

VoiceAI Connect Enterprise supports this parameter from Version 3.20 and later. For pre-3.20 releases, the pvaTokenURL parameter should be used instead.

Secured access configuration

If web channel security is enabled you need to provide the secret and EnvironmentId.

To obtain the bot secret, go to Settings > Security > Web channel security in the bot side panel.
To obtain the Environment-Id, go to Settings > Copilot details, click on the Advanced section and copy the bot Environment ID.

Configuration

The Environment Id needs to be in the bot provider under environment. The secret key is configured on VoiceAI Connect using the botSecret parameter in the credentials section of the bot configuration.

Microsoft Copilot Studio legacy bots

From VoiceAI Connect Enterprise Version 3.20, you can't create bots based on Microsoft's Copilot Studio legacy bots framework (formerly known as Microsoft Power Virtual Agents or PVA). To create bots, use Microsoft Copilot Studio.

To connect to the Microsoft Copilot Studio legacy bot framework, you need to provide AudioCodes with the bot's Direct Line secret key. To obtain this key, go to Security > Web channel security.

Configuration

The secret key is configured on VoiceAI Connect using the botSecret parameter in the bots > credentials section.

In addition to the secret, you need to configure the initialActivityToBot parameter as follows:

 "initialActivityToBot": {
        "name": "startConversation",
        "type": "event"
      },

For a quick walkthrough on how to configure your bot using Microsoft Copilot Studio legacy, click here.

Google Dialogflow ES bot framework

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. 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 bot
Region ID (location) of bot, if integrating VoiceAI Connect with Dialogflow ES agents that are deployed in regions other than the "global" (US) region
(Optional) Agent version and environment, if integrating VoiceAI Connect with multiple versions of your Dialogflow ES agent and publishing them to separate environments (integrating with a specific bot)

For VoiceAI Connect Enterprise, regions other than "global"and multiple versions of agents are supported only from Version 2.4.006 and later.

Configuration

The keys are configured on VoiceAI Connect using the privateKey and clientEmail parameters in the providers > credentials section. To create the account key, refer to Google's documentation. From the JSON object representing the key, extract the private key (including the "-----BEGIN PRIVATE KEY-----" prefix) and the service account email. These two values must be configured on VoiceAI Connect using the privateKey and clientEmail parameters.

In addition, to specify a specific bot, use the projectId parameter (Project ID) in the providers section.

To integrate with Dialogflow ES agents that are deployed in regions other than the "global" (US) region, you also need to configure the region parameter (with the region ID; default is global) in the providers section.

To integrate with multiple versions of your Dialogflow ES agent and environment, you also need to configure the environment parameter (with the environment-id of the required version; default is draft) in the providers section.

Once you are in the Dialogflow ES console, the value for the region parameter can be obtained from the URL of the specific agent:
https://dialogflow.cloud.google.com/?region=<region>#/agent/<projectId> /intents

The Dialogflow ES bot framework supports the use of a voice channel. Therefore, instead of using a dedicated speech-to-text or text-to-speech service provider, you can use the bot for these services. To enable this, the VoiceAI Connect Administrator should configure the directSTT or directTTS parameters to true, respectively.

Google Dialogflow CX bot framework

Live Hub: Dialogflow CX Voice API is supported by the Live Hub edition. For more information, visit https://livehub.audiocodes.io/.

VoiceAI Connect Enterprise: To connect to Dialogflow CX Text API, 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. 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 bot
- Agent ID of bot
- Region ID (location) of bot
- (Optional) Agent version and environment, if integrating VoiceAI Connect with multiple versions of your Dialogflow ES agent and publishing them to separate environments (integrating with a specific bot)

For VoiceAI Connect Enterprise, region and multiple versions of agents are supported only from Version 2.4.006 and later.

Configuration (VoiceAI Connect Enterprise)

The keys are configured on VoiceAI Connect using the privateKey and clientEmail parameters in the providers > credentials section. To create the account key, refer to Google's documentation. From the JSON object representing the key, extract the private key (including the "----BEGIN PRIVATE KEY----" prefix) and the service account email. These two values must be configured on VoiceAI Connect using the privateKey and clientEmail parameters.

In addition, to specify a specific bot, use the projectId, region and agentId parameters in the providers section.

Once you are in the Dialogflow CX console, the required parameters can be obtained from the URL of the specific agent: https://dialogflow.cloud.google.com/cx/projects/<projectId>/location/<region>/agents/<agentId>.

Amazon Lex V2 bot framework

Prior to connecting to Amazon Lex V2, you need to do the following:

Create an identity (user) that VoiceAI Connect Enterprise will use when accessing the Amazon Lex APIs.
Create security credentials for the identity.
Attach AmazonLexFullAccess policy to the identity.

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

AWS account keys:
- Access key
- Secret access key

To obtain the keys, refer to AWS documentation.

The same keys are used for all Amazon services (speech-to-text, text-to-speech, and bot framework).

Bot name ID (Bot details > ID, as shown below):

Bot alias ID (Deployment > Aliases > ID, as shown below):

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

Configuration

The keys are configured on VoiceAI Connect using the accessKey and secretKey parameters under the credentials parameter in the providers section. Each AWS provider should also have the region parameter configured.

To specify the bot name (ID), use the providerBotName parameter in the bots section.

To configure the bot alias ID, use the botAlias parameter in the bots section.

AudioCodes Bot API bot framework

To create the channel between the VoiceAI Connect's cognitive service component and the bot provider, see AudioCodes API.