Call initiation

When a call is initiated, VoiceAI Connect sends an event to the bot. The bot typically uses this event to trigger a welcome prompt that will be played to the user. This event includes call details such as the caller and called numbers, and caller display name. For agent-assist scenarios, the event also includes details of the participants of the call (e.g., the end-user and the human agent).

In addition, VoiceAI Connect can be configured for the following behaviors:

Play a ringing (ringback) tone to the user until the bot is connected to the call.
Manipulate the content of the event or disable the event entirely.
Forward to the bot certain information from the SIP INVITE message such as a contact-center call identifier.
Send a textual message (e.g., "Hello") to the bot to trigger it to send a welcome prompt. This is typically required in scenarios where the bot cannot handle the event.
Send a textual (welcome) message to the user. This is typically required in scenarios where the bot cannot sent a welcome message.
Wait for the media to connect before playing the welcome prompt to the user.

How do I use it?

By default, VoiceAI Connect sends an initial event to the bot.

The following data fields are sent with the initial event. However, you can customize this initial event by adding custom fields linked to specified headers (see Sending SIP headers).

Field	Type	Description
`vaigConversationId`	String	A unique identifier (UUID) of the conversation.
`callee`	String	Dialed phone number. This is typically obtained from the SIP To header.
`calleeHost`	String	Host part of the destination of the call. This is typically obtained from the SIP To header.
`caller`	String	Caller's phone number. This is typically obtained from the SIP From header.
`callerHost`	String	Host part of the source of the call. This is typically obtained from the SIP From header.
`callerDisplayName`	String	Caller's display name. This is typically obtained from the SIP From header.
`participants`	Array of Objects	For Agent assist: Participants of the conversation.
`outboundTarget`	String	For Outbound calling: The "target" of the outbound call.
`dialoutMetadata`	String	For Outbound calling: Metadata from the dialer application that is sent through VoiceAI Connect to the bot.
`agentConnected`	Boolean	For Agent assist using Agent assist API: Whether the agent assist client application is already connected or not.
<Additional attributes>	-	Optional additional attributes such as values from various SIP headers. These can be added by customization. VoiceAI Connect 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.

The syntax of the initial event depends on the bot framework:

AudioCodes Bot API

The event is sent as a start event, with the data fields inside the parameters property.

Example:

{
  "type": "event",
  "name": "start",
  "parameters": {
    "vaigConversationId": "37011f13-2df7-4a23-890e-649daf922ddc",
    "callee": "12345678",
    "calleeHost": "10.20.30.40",
    "caller": "12345678",
    "callerHost": "10.20.30.40"
  }
}

Microsoft Bot Framework

The message is sent as a channel event, with the data fields inside the channelData property.

Example:

{
  "type": "event",
  "name": "channel",
  "value": "telephony",
  "channelData": {
    "vaigConversationId": "37011f13-2df7-4a23-890e-649daf922ddc",
    "callee": "12345678",
    "calleeHost": "10.20.30.40",
    "caller": "12345678",
    "callerHost": "10.20.30.40"
  },
  "from": {
    "id": "12345678"
  },
  "locale": "en-US"
}

Microsoft Copilot Studio

By default, two events are sent to the Copilot Studio bot:

channel event to pass data.
startConversation event to trigger the Greeting topic in the Copilot Studio bot. to disable the startConversation event, see copilotSendStartConversation in Customizing behavior.

To see how to save and use data from the channel event, see Saving channel data

Example:

{
  "type": "event",
  "name": "channel",
  "value": "telephony",
  "channelData": {
    "vaigConversationId": "37011f13-2df7-4a23-890e-649daf922ddc",
    "callee": "12345678",
    "calleeHost": "10.20.30.40",
    "caller": "12345678",
    "callerHost": "10.20.30.40"
  },
  "from": {
    "id": "12345678"
  },
  "locale": "en-US"
}

Microsoft Copilot Studio legacy

By default, two events are sent to the PVA bot:

channel event to pass data.
startConversation event to trigger the Greeting topic in the PVA bot. to disable the startConversation event, see pvaSendStartConversation in Customizing behavior.

To see how to save and use data from the channel event, see Saving Channel Data

Example:

{
  "type": "event",
  "name": "channel",
  "value": "telephony",
  "channelData": {
    "vaigConversationId": "37011f13-2df7-4a23-890e-649daf922ddc",
    "callee": "12345678",
    "calleeHost": "10.20.30.40",
    "caller": "12345678",
    "callerHost": "10.20.30.40"
  },
  "from": {
    "id": "12345678"
  },
  "locale": "en-US"
}

Dialogflow CX

The message is sent as a WELCOME event, with the data fields as event parameters.

Example:

{
  "queryInput": {
    "event": {
      "languageCode": "en-US",
      "name": "WELCOME",
      "parameters": {
        "vaigConversationId": "37011f13-2df7-4a23-890e-649daf922ddc",
        "callee": "12345678",
        "calleeHost": "10.20.30.40",
        "caller": "12345678",
        "callerHost": "10.20.30.40"
      }
    }
  }
}

The data fields are also sent inside the event-WELCOME session parameter, and can be used when generating the response text, by using a syntax such as this:

$session.params.event-WELCOME.callee

Dialogflow ES

The message is sent as a WELCOME event, with the data fields as event parameters.

Example:

{
  "queryInput": {
    "event": {
      "languageCode": "en-US",
      "name": "WELCOME",
      "parameters": {
        "vaigConversationId": "37011f13-2df7-4a23-890e-649daf922ddc",
        "callee": "12345678",
        "calleeHost": "10.20.30.40",
        "caller": "12345678",
        "callerHost": "10.20.30.40"
      }
    }
  }
}

The data fields can be used when generating the response text, by using a syntax such as this:

#WELCOME.caller

Amazon Lex V2

The call details are added to the sessionAttributes before the start message.

The default start message is: <start>. You can change this in the bot's configuration by setting initialMessageToBot. If you set it to an empty string, no start message will be sent.

Customizing behavior

For VoiceAI Connect, the following bot configuration parameters can be used to control the handling of call initiation:

Field	Type	Description
`initialMessageToBot`	String	Defines a textual message that is sent to the bot when conversation starts.
`initialActivityToBot`	Object	Defines a JSON object that is sent to the bot when conversation starts. This parameter overrides the default initial activity (if defined for the specific bot framework). To prevent the sending of an initial activity, configure the parameter to an empty object: {}.
`dialogflowWelcomeEvent`	String	Defines the name of the event to send to Dialogflow when the conversation starts. The default is "WELCOME". Notes: The parameter is applicable only to the Google bot framework. The parameter is only applicable if initialActivityToBot is not configured.
`connectOnPrompt`	Boolean	Enables VoiceAI Connect to wait for the first message from the bot before sending the Connect (200 OK) message to the user. true (Default) false
`sendStartAfterPrompt`	Boolean	Enables VoiceAI Connect to wait for the initial (welcome) prompt from the bot before sending the `start` event to the bot. By default, VoiceAI Connect sends the event immediately after connecting to the bot (doesn’t wait for initial prompt). true false (Default) Note: The parameter is applicable only to Azure bots. This parameter is applicable to VoiceAI Connect Enterprise Version 3.10 and later.
`welcome`	String	Defines text to be played to the user when conversation starts.
`maxCallDurationMinutes`	Number	Defines the maximum duration of a call (in minutes). If the call has not ended by the time this duration elapses, VoiceAI Connect ends the call. The valid value is 0 to 43200. The default is 0 (i.e., no limit to call). This parameter is applicable to VoiceAI Connect Enterprise Version 3.12 and later.
mediaConnectTimeoutMS	Number	Defines a timeout (milliseconds) to wait for the media (RTP) path to connect, before VoiceAI Connect plays the bot's intial welcome prompt message to the user. The timeout is triggered upon call connection. When the timeout expires, the media path is considered connected and VoiceAI Connect plays the bot's prompt. If the media is connected before the timeout expires, VoiceAI Connect plays the prompt immediately, without waiting for the timeout to expire. This feature is especially useful in scenarios where the first part of the bot's prompt message is not played. For example, the word "Welcome" from the "Welcome to the London tube bot" prompt may be missing and not heard by the user. This phenomenon is often due to the media (RTP) connection path not yet being established when the prompt starts to play. The valid value is 0 to 10000. The default is 2000. A value of 0 means play the prompt immediately upon call connect.
mediaConnectGiveUpTimeoutMS	Number	Defines a timeout (milliseconds) to disconnect if no media (RTP) is detected. The timeout is triggered upon call connection. When the timeout expires, the call is disconnected with reason of “no media” or “media broken connection”. The valid value is 0 to 30000. The default is 10000. A value of 0 means no timeout for disconnection.
copilotSendStartConversation	Boolean	Sends `startConversation` event to the Microsoft Copilot Studio bot. true (Default) false This parameter is applicable to VoiceAI Connect Enterprise Version 3.20 and later.
pvaSendStartConversation	Boolean	Sends `startConversation` event to the Microsoft Copilot Studio legacy bot. true (Default) false This parameter is deprecated from VoiceAI Connect Enterprise Version 3.20 and later.

In addition to the above parameters, you can use all the SBC features for customizing the behavior. For example, the SBC can be configured to play a ringback tone to the user until the bot is connected to the call.

Passing SIP headers to the bot

In some setups, it is important to forward SIP header values, extracted from the SIP INVITE message received by VoiceAI Connect, to the bot. For example, in contact centers, an ID is associated with the call which is usually sent in a SIP header, and may be required by the bot application.

VoiceAI Connect can be configured to extract values from the SIP INVITE message and then send them in the initial message to the bot. The values are sent as additional parameters of the initial event.

For more information, please contact AudioCodes support.