Provider-specific settings

Enables only connections to the bot server that use a self-signed certificate; otherwise, connection attempts are rejected.

• true

• false (Default)

Enables connection to the speech-to-text provider even if it uses a self-signed certificate.

• true

• false (Default)

Note: Setting this parameter to true can expose VoiceAI Connect to MITM attacks. Therefore, it should be avoided if possible and only enabled in safe environments (e.g., when using ac-stt-api with self-signed certificate).

Enables connection to the text-to-speech provider even if it uses a self-signed certificate.

• true

• false (Default)

Note: Setting this parameter to true can expose VoiceAI Connect to MITM attacks. Therefore, it should be avoided if possible and only enabled in safe environments (e.g., when using ac-stt-api with self-signed certificate).

Defines the URL of the OAuth 2.0 authorization server that provides the access token for OAuth authorization. Configuring the parameter implies that OAuth 2.0 authentication is enabled.

This is

Note:

• The parameter is applicable when the AC Bot API is used (see ) or when Nuance Mix is used for speech services (see Text-to-speech service information).

• The value must be provided to AudioCodes by the Customer.

• If the parameter is configured, you also need to configure the oauthClientId and oauthClientSecret parameters.

Defines the OAuth scope (permissions) that is sent in the request to the OAuth 2.0 authorization server that provides the access token for OAuth authorization when the AC Bot API is used. For more information, see . The parameter can be configured with multiple scopes.

Note:

• The value is optional and is provided to AudioCodes by the Customer.

• If the parameter is configured, you also need to configure the oauthClientId and oauthClientSecret parameters.

Contains the credentials to access the bot framework, speech-to-text, or text-to-speech. The parameter has the following optional fields:

• accessKey (applicable only to AWS)

• secretKey (applicable only to AWS)

• key (applicable only to Azure, AudioCodes LVCSR, ElevenLabs, or Yandex speech services).

• privateKey (applicable only to Google Dialogflow)

• clientEmail (applicable only to Google Dialogflow)

• token (applicable only to Membit, AmiVoice, or AudioCodes Bot API)

• overrideAccessToken (used only for internal AudioCodes testing)

• oauthClientId: The Client ID provided by the API for OAuth 2.0 authorization. This is mandatory if the oauthTokenUrl parameter is configured. This parameter is applicable only to the AC Bot API or Nuance Mix speech services.

• oauthClientSecret: The Client secret provided by the API for OAuth 2.0 authorization. This is mandatory if the oauthTokenUrl parameter is configured. This parameter is applicable only to the AC Bot API or Nuance Mix speech services.

Note:

• The value must be provided to AudioCodes by the Customer from the service providers.

• Each of the above secret types can be securely stored in Azure's Key Vault (preventing attackers from obtaining these keys). If this is the case, instead of using the credentials parameter, use the credentialsAzureSecrets parameter, with the same attribute names as listed above.

By default, the bot secret is passed to Direct Line, which generates access token in the backend.

If azureUseDirectlineToken is true, a token is requested before starting the conversation, and used for authentication.

This is mostly needed for bots that use Direct Line App Service Extensions.

• true

• false (Default)

Note: This parameter is only applicable to Microsoft Azure.

Uses Streaming extension for Direct Line, which posts messages to the bot via WebSocket.

• true

• false (Default)

Note: This parameter is only applicable to Microsoft Azure.

Defines an optional base URL for retrieving the token.

If it is not set, the default URL is: https://directline.botframework.com/v3/directline.

The full URL used for getting the token is <baseUrl>/tokens/generate.

Token refresh does not use this configured URL. Refresh URL depends on botUrl or botHost (see here). The URL used for refresh is <botUrl>/tokens/refresh. For more information on Refreshing a Direct Line token, click here.

The parameter is used as an alternative to the credentials parameter (above). Each of the attributes listed under the credentials parameter can be used with credentialsAzureSecrets parameter. Instead of plain text values, the values are specified using Azure Key Vault URLs (where the credentials are securely stored).

The following is an example for the key attribute:

{
  "name": "my_azure",
  "type": "azure",
    "region": "westeurope",
    "credentialsAzureSecrets": {
        "key": "https://keyvault-name.vault.azure.net/secrets/MY-SECRET/VERSION"
      }
}

You need to add the plain-text credential to Azure's Key Vault. Once added, you need to generate a URL (HTTPS) for the credential, and then use this URL ('Secret Identifier' field) as the value for the credentialsAzureSecrets parameter. Therefore, the credential is not shown in the VoiceAI Connector configuration file; instead, only a URL to the Key Vault is shown. When the credential is required for access, the VoiceAI Connector uses this URL to access and authenticate with the Key Vault. For more information on Azure's Key Vault feature, go to https://docs.microsoft.com/en-us/azure/key-vault/general/secure-your-key-vault.

Note:

Azure's Key Vault can be used to store secrets for any bot provider (e.g., Google or Yandex).

You can mix credentials and credentialsAzureSecrets, as long as you don't have the same key in both parameters. For example:

{  
"name": "my_google",
  "type": "google",
  "projectId": "my-project",
  "credentialsAzureSecrets": {
    "privateKey": "https://keyvault-    name.vault.azure.net/secrets/MY-SECRET/VERSION"
  },
  "credentials": {
    "clientEmail": "service@my-    project.iam.gserviceaccount.com"
    }
}

Defines a unique name identifier of the specific provider. This name is used by the provider, ttsProvider or sttProvider bot parameters for associating the bot with this provider.

Note: This parameter is mandatory.

Defines the name of the bot framework provider.

• ac-api - for AudioCodes API

• almagu - for Almagu speech provider

• amivoice - for AmiVoice speech provider

• audiocodes-lvcsr

• ws

• azure

• azure-mock - for AudioCodes internal testing only

• deepgram - for Deepgram speech provider

• elevenlabs - for ElevenLabs speech provider

• google - for Google speech provider

• google-cx - - for Google CX

• google-agent-assist - for Google Agent Assist

• membit

• nuance - for Nuance

• nuance-grpc - for Nuance GRPC

• yandex - for Yandex

• uniphore - for Uniphore

Note:

• This parameter is mandatory.

• ac-bot-api has been deprecated and replaced by ac-api.

Defines the region where the bot framework is geographical located (e.g., "us-west-2").

The default value is global.

Note:

• The parameter is applicable only to AWS, Azure, and Google Dialogflow (CX and ES). For more information on Dialogflow CX, click here. For more information on Google Dialogflow ES, click here.

• This string is obtained from the bot framework provider by the Customer and supplied to AudioCodes.

Defines the Google region (Region ID) in which this agent is deployed.

The default value is global.

Note: This string is obtained from the bot framework provider by the Customer and supplied to AudioCodes.

Defines the specific Direct Line endpoint where traffic is routed.

The default value is undefined.

This parameter is only applicable for Azure bots and can be configured with one of the following Direct Line endpoints listed here.

Defines the Google Dialogflow agent version and environment of the bot.

For more information, refer to the Google documentation for Dialogflow ES and Dialogflow CX bots.

The default is draft ("Draft" environment).

Note:

The parameter is applicable only to Google Dialogflow (CX and ES).

This string is obtained from the bot framework provider by the Customer and must be provided to AudioCodes.

Defines the Project ID of the bot. This is needed for connecting to Google Dialogflow.

Note:

• The parameter is applicable only to Google Dialogflow.

• This string is obtained from the bot framework provider by the Customer and supplied to AudioCodes.

Defines the Google Dialogflow CX agent to integrate with. Each Dialogflow CX project can have multiple agents.

Note:

• The parameter is applicable only to Google Dialogflow CX.

• This string is obtained from the bot framework provider by the Customer and supplied to AudioCodes.

Defines the Folder ID for Yandex and AmiVoice bots.

Note:

• The parameter is applicable only to Yandex and AmiVoice.

• This string is obtained from the bot framework provider by the Customer and supplied to AudioCodes.

Defines the IP address and port of the speech-to-text service provider. This overrides the speech-to-text hostname when, for example, an HTTP proxy is used between the VoiceAI Connector and speech-to-text provider.

Defines the IP address and port of the text-to-speech service provider. This overrides the text-to-speech hostname when, for example, an HTTP proxy is used between the VoiceAI Connector and text-to-speech provider.

Defines the URL of the text-to-speech service provider. This overrides the text-to-speech URL when, for example, an HTTP proxy is used between the VoiceAI Connector and text-to-speech provider.

The following example uses AudioCodes API (ac-api) for integration with a third-party text-to-speech vendor:

{ 
"name": "my_ac_api",
 "type": "ac-api",
 "ttsUrl": "https://localhost:8043/cognitiveservices/v1",
 "credentials": {
 "key": "AQVNy2mt2NAD8WZm91IEwtGa1g8o3fepJIAZQuDz"
 }
}

Note: This parameter has precedence over the ttsHost parameter.

Defines the URL of the speech-to-text service provider. This parameter can be used to override the default URL used by the speech-to-text service.

The following example uses AudioCodes API (ac-api) for integration with a third-party, speech-to-text provider:

{
 "name": "my_ac_api",
 "type": "ac-api",
 "sttUrl": "wss://localhost:8043/mySttServiceUrl",
 "credentials": {
   "key": "AQVNy2mt2NAD8WZm91IEwtGa1g8o3fepJIAZQuDz"
 }
}

Note:

• This parameter has precedence over the sttHost parameter.

• For Azure speech-to-text services, this parameter can be used to define a private (custom) speech-to-text endpoint. For more information on how to use private endpoints with Azure Speech Services, refer to Azure's documentation.

Defines the maximum time (in milliseconds) that the VoiceAI Connector waits for a response from the text-to-speech provider.

The valid value is 10 to 600,000. The default is 5,000.

If no response is received when this timeout expires, the VoiceAI Connector tries one more time to communicate with the text-to-speech. If still no response, the VoiceAI Connector disconnects the call with the SBC.

If the call is disconnected, the SIP BYE message sent by the SBC to the user indicates this failure, by prefixing the value in the Reason header with "TTS Err:".

Note: In this scenario (disconnect), you can also configure the VoiceAI Connector to perform specific activities, for example, playing a prompt to the user or transferring the call (see the generalFailoverActivities parameter).

Defines the maximum time (in milliseconds) that the VoiceAI Connector waits for a response from the speech-to-text provider.

The valid value is 10 to 600,000. The default is 10,000.

If no response is received when this timeout expires, VoiceAI Connect disconnects the call with the SBC.

If the call is disconnected, the SIP BYE message sent by the SBC to the user indicates this failure by prefixing the value in the Reason header with "STT Err:".

Note:

• In this scenario (disconnect), you can also configure the VoiceAI Connector to perform specific activities, for example, playing a prompt to the user or transferring the call (see the generalFailoverActivities parameter).

• This parameter is not applicable to DNN and AWS speech-to-text providers.

Overrides parameters that are used when activating the speech-to-text request.

The value is a JSON object comprising key-value pairs denoting the parameters and their desired value.

Google example:

{"sampleRateHertz": 16384 }

Azure example:

The following example uses AudioCodes API (sttOverrideConfig) for integration with Azure speech-to-text provider:

"sttOverrideConfig": {
   "setServiceProperty": {
      "postprocessing": { 
         "value": "<STT Model ID>",
         "channel": "UriQueryParameter" 
      } 
   }
}

Notes:

• The parameters and values must suit the API used for performing the speech-to-text (according to the speech-to-text provider).

• This is an Admin parameter and can't be set by the bot.

• The parameter is applicable only to Azure, Google, and AC API speech-to-text providers.

Overrides parameters that are used when activating the text-to-speech request.

The value is a JSON object comprising key-value pairs denoting the parameters and their desired value.

Notes:

• The parameters and values must suit the API used for performing the text-to-speech (according to the text-to-speech provider).

• This is an Admin parameter and can't be set by the bot.

• The parameter is applicable only to Google, Amazon, and AC API speech-to-text providers.

Overrides streaming-configuration parameters that are used when activating the speech-to-text request.

The value is a JSON object comprising key-value pairs denoting the parameters and their desired value.

For example:

{"singleUtterance": false }

Note:

• The parameters and values must suit the API used for performing the speech-to-text (according to the speech-to-text provider).

• The parameter is currently applicable only to Google speech-to-text.

Defines the number of times the VoiceAI Connector attempts to send a message to an Azure bot before failing due to a timeout.

The valid range is 0 to 5. The default is 0.

Note: The parameter is applicable only to Azure.

Defines the maximum size of the Azure bot's ordered work queue.

The valid value is 0 to 10. The default is 2.

Note: The parameter is applicable only to Azure.

Defines the timeout for Azure bot actions.

The valid value is 10 to 10,000 milliseconds. The default is 300.

Note: The parameter is applicable only to Azure.

Defines the timeout (in milliseconds) that is triggered when sending DTMF digits, entered by the user, to the bot. The VoiceAI Connector sends each collected digit consecutively (in sequence) to the bot using the DTMF event message. The VoiceAI Connector sends the first digit immediately and then sends the next digit only when it receives a response from the bot (ACK / message posted) or this timeout expires (whichever occurs first).

For example, assume that the user enters digits "158#" and the timeout is configured to 600. The VoiceAI Connector first sends a DTMF event message with value "1". When it receives a response from the bot or 600 msec elapses (whichever occurs first), it sends another DTMF event message with value "5". When it receives a response from the bot or 600 msec elapses (whichever occurs first), it sends another DTMF event message with value "8", and so on until all the collected digits have been sent to the bot.

The valid value range is 0 (i.e., disabled) to 10,000. The default is 800 (i.e., feature is enabled by default).

Note:

• The parameter is applicable only to Azure bots.

• The parameter is applicable only if the DtmfCollect parameter is configured to false (i.e., sending of DTMF digits to the bot is one by one).

(Optional) Defines the text that appears in the deviceDescription field for this provider's alarms (alarms for which the alarm source was this provider).

If this parameter is not configured, deviceDescription is taken from the alarms generalConfig parameters deviceDescription or secondaryDeviceDescription.