Changing call settings

At any stage of the call, the bot can dynamically change parameters of the call. For example, the bot can change the language.

Some of the parameters are specific to a feature, like the target number for call transfer, and some are generic, like the language.

A change can be done for the entire call duration, or for the current activity (the current text/audio that is played by the bot).

Any parameter that can be dynamically set by the bot, can also be statically configured by the administrator. For example, the administrator can set a target number for call transfer, which will be used if the bot has not set any value for this parameter.


How do I use it?

A bot can change a setting for a specific activity or change a setting for the entire call.

For setting parameters that affect the entire call duration, you should use the sessionParams. You can send sessionParams with any activity sent from the bot, or with the config event.

See Sending activities page on how to send activities using your bot framework.

For setting parameters that affect a specific activity (anything that happens between messages sent from the bot), you should use the activityParams in the related activity. Any parameter that was set for the current activity, restores to its previous value when the subsequent textual-message or audio-play activity is handled.

For example, if the language is changed from English to German using the activityParams property in a text message, VoiceAI Connect plays the message in German and activates speech-to-text in German, but the following message to the user is returned to English.

Supported parameters

The description of the parameters that can be changed using the activityParams and sessionParams properties can be found on the documentation of the various features of VoiceAI Connect.

In addition, Speech customization page describes speech-related parameters.

A complete list of the supported parameters can be found in the General bots parameters section of the parameters reference.

Example

Example of changing the language for a specific textual-message that will be played to the user (the voiceName value depends of the text-to-speech provider):

AudioCodes Bot API
{
  "type": "message",
  "text": "Dies ist eine Nachricht auf Deutsch.",
  "activityParams": {
    "language": "de-DE",
    "voiceName": "de-DE-KatjaNeural"
  }
}
Microsoft Bot Framework
{
  "type": "message",
  "text": "Dies ist eine Nachricht auf Deutsch.",
  "channelData": {
    "activityParams": {
      "language": "de-DE",
      "voiceName": "de-DE-KatjaNeural"
    }
  }
}
Microsoft PVA

Add the JSON to the message to channel data box in the message (see Sending messages)

{
  "activityParams": {
    "language": "de-DE",
    "voiceName": "de-DE-KatjaNeural"
  }
}
Microsoft PVA (classic bots)
[Activity
  "type": "message",
  "text": "Dies ist eine Nachricht auf Deutsch.",
  "channelData": ${json ('
  {
    "activityParams": {
      "language": "de-DE",
      "voiceName": "de-DE-KatjaNeural"
     }
  }
')}
]
Dialogflow CX

Add a Custom Payload response with the following content:

{
  "activities": [{
    "type": "message",
    "text": "Dies ist eine Nachricht auf Deutsch.",
    "activityParams": {
      "language": "de-DE",
      "voiceName": "de-DE-KatjaNeural"
    }
  }]
}
Dialogflow ES

Add a Custom Payload response with the following content:

{
  "activities": [{
    "type": "message",
    "text": "Dies ist eine Nachricht auf Deutsch.",
    "activityParams": {
      "language": "de-DE",
      "voiceName": "de-DE-KatjaNeural"
    }
  }]
}

Specific event for changing settings

In most cases, you would send the activityParams and sessionParams properties as part of an existing activity from the bot. For example, as part of a textual-message that should be played to the user.

However, there might be cases that the sole purpose of sending the activity is changing the settings. For this case, you can send the config event that will include the sessionParams property.

The following is an example of the config event, enabling the barge-in feature for the remainder of the call:

AudioCodes Bot API
{
  "type": "event",
  "name": "config",
  "sessionParams": {
    "bargeIn": true
  }
}
Microsoft Bot Framework
{
  "type": "event",
  "name": "config",
  "channelData": { 
    "sessionParams": {
      "bargeIn": true
    }
  }
}
Microsoft PVA

Send config event with event activity, add the JSON in the ‘value’ box (see Sending event to VoiceAI Connect).

{ 
    "sessionParams": {
    "bargeIn": true
    }
  }
Microsoft PVA (classic bots)
[Activity
  "type": "event",
  "name": "config",
  "channelData": ${json('
  { 
    "sessionParams": {
    "bargeIn": true
    }
  }
`)}
]
Dialogflow CX

On Dialogflow there is no need for the config event. The sessionParams property can be set directly using a Custom Payload response with the following content:

{
  "sessionParams": {
    "bargeIn": true
  }
}
Dialogflow ES

On Dialogflow there is no need for the config event. The sessionParams property can be set directly using a Custom Payload response with the following content:

{
  "sessionParams": {
    "bargeIn": true
  }
}
The config event supports only sessionParams.

Receiving notifications of parameters change

In some cases, it is desirable for the bot to get an event when a parameter is changed. For example, after changing the language, the bot should be "triggered" by an event to use the new language.

See Notifying bot of parameter changes for how this can be done with VoiceAI Connect.