Disconnecting the call

At any stage of the conversation, the bot can disconnect the conversation. Typically, this causes VoiceAI Connect to send a SIP BYE message to the SIP peer.

Upon disconnecting the conversation, the bot can also specify a textual reason. This reason is passed to the peer on the SIP Reason header and appears in the CDR of the call. The bot can also add SIP headers and their values, which are included in the SIP BYE message.

Sometimes it is important for the bot to specify the result of the bot operation for this conversation, so this data could be used after the call was disconnected. For example, when the conversation is part of an outbound campaign, the dialer application can use this data for determining the status of the target of the conversation. See Specifying bot operation result below for more details.

How do I use it?

AudioCodes Bot API

For disconnecting the conversation, the bot should send a hangup event:

{
  "type": "event",
  "name": "hangup"
}
Microsoft Bot Framework

For disconnecting the conversation, the bot should send a hangup event:

{
  "type": "event",
  "name": "hangup"
}
Microsoft Copilot Studio

For disconnecting the conversation, the bot should send a hangup event with event activity (see Sending event to VoiceAI Connect).

Microsoft Copilot Studio legacy

For disconnecting the conversation, the bot should send a hangup event:

[Activity
  "type": "event",
  "name": "hangup"
]
Dialogflow CX

For Google Dialogflow CX agents, the conversation can be disconnected by adding a transition to "End Session" or "End Flow".

For more information, see here.

As an alternative, the conversation can be disconnected by adding a Custom Payload response with a hangup event:

{
  "activities": [{
    "type": "event",
    "name": "hangup"
  }]
}
Dialogflow ES

For Google Dialogflow ES agents, the conversation can also be disconnected by selecting "Set this intent as end of conversation" on the intent response.

As an alternative, the conversation can be disconnected by adding a Custom Payload response with a hangup event:

{
  "activities": [{
    "type": "event",
    "name": "hangup"
  }]
}

Event parameters

The following table lists the parameters associated with this event:

See Changing call settings for details on how these parameters can be applied.

Parameter

Type

Description

hangupReason String

Conveys a textual reason for hanging up.

This reason will be passed to the peer on the SIP Reason header and will appear on the CDR of the call.

hangupSipHeaders

Array of Objects

Array of objects listing SIP headers that should be sent when the bot ends the call. VoiceAI Connect includes these headers in the SIP BYE message sent to the SIP peer.

The total length should not exceed 12,000 characters.

Up to 100 SIP headers can be defined.

Each object comprises a name and a value attribute in the bot message.

For more information, see Adding below.

To configure the parameter on VoiceAI Connect, use the key (string) and value (string) attributes, as shown in the following example:

{
   "hangupSipHeaders":[
      {
         "name":"X-My-Header",
         "value":"my_value"
      },
      {
         "name":"Another-X-Header",
         "value":"my_other_value"
      }
   ]
}

VoiceAI Connect Enterprise supports this parameter from Version 3.2 and later.

The following example shows how to set the hangup reason and hangup SIP headers:

AudioCodes Bot API

Send a hangup event with the hangupReason parameter set.

{
  "type": "event",
  "name": "hangup",
  "activityParams": {
    "hangupReason": "completed successfully"
  }
}
Microsoft Bot Framework

Send a hangup event with the hangupReason parameter set.

{
  "type": "event",
  "name": "hangup",
  "channelData": {
    "activityParams": {
      "hangupReason": "completed successfully"
    }
  }
}
Microsoft Copilot Studio

Send a hangup event with the hangupReason parameter set in the value box (see Sending event to VoiceAI Connect). 

{
  "activityParams": {
  "hangupReason": "completed successfully"
  }
}
Microsoft Copilot Studio legacy

Send a hangup event with the hangupReason parameter set.

[Event
  "type": "event",
  "name": "hangup",
  "channelData": ${json(`
  {
  "activityParams": {
  "hangupReason": "completed successfully"
  }
 }
`)}
}
Dialogflow CX

Set the hangupReason parameter before the transition that ends the conversation, by adding a Custom Payload response with the following content:

{
  "sessionParams": {
    "hangupReason": "completed successfully"
  }
}
Dialogflow ES

Set the hangupReason parameter on the intent marked to end the conversation, by adding a Custom Payload response with the following content:

{
  "sessionParams": {
    "hangupReason": "completed successfully"
  }
}

Adding SIP headers

When the bot ends the call, it can add SIP headers which VoiceAI Connect can include in the SIP BYE message that it sends to the SIP peer.

VoiceAI Connect Enterprise supports this feature from Version 3.2 and later.

This is done by the hangupSipHeaders parameter. This parameter contains an array of JSON objects with the following attributes:

Attribute

Type

Description

name

String

Name of the SIP header.

value

String

Value of the SIP header.

For example, the following event can be used to add the header "X-My-Header" with the value "my_value":

AudioCodes Bot API

Send a hangup event with the hangupSipHeaders parameter set.

{
  "type": "event",
  "name": "hangup",
  "activityParams": {
    "hangupReason": "completed successfully",
...."hangupSipHeaders": [
        {
          "name": "X-My-Header",
          "value": "my_value"
        }
      ]
  }
}
Microsoft Bot Framework

Send a hangup event with the hangupSipHeaders parameter set.

{
  "type": "event",
  "name": "hangup",
  "channelData": {
    "activityParams": {
      "hangupReason": "completed successfully",
      "hangupSipHeaders": [
        {
          "name": "X-My-Header",
          "value": "my_value"
        }
      ]
    }
  }
}
Microsoft Copilot Studio

Send a hangup event with the hangupSipHeaders parameter set in the value.

{
  "activityParams": {
    "hangupReason": "completed successfully",
    "hangupSipHeaders": [
      {
        "name": "X-My-Header",
        "value": "my_value"
      }
    ]
  }
}
Microsoft Copilot Studio legacy

Send a hangup event with the hangupSipHeaders parameter set.

[Activity
  "type": "event",
  "name": "hangup",
  "channelData": ${json(`
  {
    "activityParams": {
      "hangupReason": "completed successfully",
      "hangupSipHeaders": [
        {
          "name": "X-My-Header",
          "value": "my_value"
        }
      ]
    }
  }
`)}
]
Dialogflow CX

Set the hangupSipHeaders parameter with the headers that you want included, by adding a Custom Payload response with the following content:

{
  "sessionParams": {
    "hangupReason": "completed successfully",
    "hangupSipHeaders": [
      {
        "name": "X-My-Header",
        "value": "my_value"
      }
    ]
  }
}
Dialogflow ES

Set the hangupSipHeaders parameter with the headers that you want included, by adding a Custom Payload response with the following content:

{
  "sessionParams": {
    "hangupReason": "completed successfully",
    "hangupSipHeaders": [
      {
        "name": "X-My-Header",
        "value": "my_value"
      }
    ]
  }
}

Specifying bot operation result

For specifying the result of the bot operation, the bot sets the below parameters. The values of those parameters are passed on the outbound call-status notifications (see Receiving call-status notifications) and included in the CDRs (see CDR fields).

Make sure that the value of the parameters is set, in case the user disconnects in the middle of the conversation. It is recommended that the bot sets the parameters using sessionParams throughout the conversation, whenever it has an update to the result, and not just on the hangup activity. Only the last value of the parameters will be used
VoiceAI Connect Enterprise supports this feature from Version 3.20 and later.

Parameters can be set on configuration or dynamically by the bot as explained in Changing call settings.

Parameters can be set on configuration or dynamically by the bot as explained in Changing call settings.

Parameter

Type

Description

botOperationResult

String

The bot operation result.

Can have one of the following values:

  • "success": The operation was successful.

  • "failure": The operation has failed.

By default, this parameter is not set.

botOperationData

Object

Additional information to include alongside the operation result.

Can be any valid JSON object. For example:

{
  "botOperationData": {
    "feedback": "user was not cooperative"
  }
}

By default, this parameter is not set.

See Receiving call-status notifications for how these values are sent on outbound call-status notifications.

See CDR fields for how these values are sent on the CDR.