Outbound calling

In a typical bot deployment, VoiceAI Connect receives a phone call and connects it to your bot. The outbound calling feature allows a third-party dialer application to initiate a phone call towards a target number and connect this call to your bot. This setup is often used by companies for outbound dialing campaigns, whereby the dialer automatically initiates calls with potential customers. This feature is also termed "dialout".

The basic call flow for outbound calling is as follows:

1. The outbound dialer application sends an HTTP request to VoiceAI Connect, triggering it to make an outbound call to the specified target URI.

2. Optionally, VoiceAI Connect sends an event to the bot indicating the outbound call initiation, including the parameters of the call (e.g., the called number).

3. VoiceAI Connect initiates the outbound call over SIP to the end user.

4. When the end user answers the call, speech-to-text begins and the user’s first utterance (e.g., "Hi") is sent to the bot to trigger its logic (e.g., reply with "Hi there, we are calling from…"). In addition, VoiceAI Connect notifies the bot that the call has been answered, by sending it the call-initiation event.

5. Optionally, VoiceAI Connect sends the dialer application asynchronous status notifications of the call ("answered", "failed" or "completed") using HTTP.

Additionally, VoiceAI Connect can be configured to detect if a human or machine (fax or answering) has answered the call.

The following diagram shows a high-level call-flow for outbound calling:

How do I use it?

To use the outbound calling feature, you should follow the following steps which are described In the following sections:

1. Generate credentials (client id and client secret) that will be used for OAuth 2.0 authorization.

2. Configure your bot for allowing outbound calling, by defining the application with the following policy:

   • Role: VAIC/BOTS/DIALOUT

   • Scope: You can define the scope for all bots (using *), for a specific bot (by name), or for multiple bots that have a specific authorization tag (tag=) configured using the authorizationTag parameter (below).
     
     For more information on assigning policies (roles and scopes) to users and applications, see Managing users.

3. If using basic authentication, use the application's client ID and client secret as the username and password. If using OAuth 2.0, perform authentication for retrieving an OAuth 2.0 access token by issuing an HTTP POST to the /oauth/token URL.

4. Trigger the outbound call by performing HTTP POST to the /api/v1/actions/dialout URL.

Optionally, VoiceAI Connect can send call-status notifications to your dialer application. For enabling such notifications, your dialer application should expose an HTTP server which is accessible to VoiceAI Connect installation.

Generating credentials

The credentials consists of client id and client secret, which are required for authenticating your REST requests.

The following table explains how the credentials are generated:

Configuring your bot

When using VoiceAI Connect Enterprise, the following bot configuration parameters should be set to enable outbound calling:

Performing authentication

The dialer application must be authenticated in order to trigger an outbound call. The authentication can be done in one of the methods which can be enabled by the administrator: HTTP basic authentication or OAuth 2.0 authentication. See Client authentication for more details.

The following table explains how to use the authentication methods for outbound calling:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

-u "username:password"

Authorization: BEARER 223d0d870a364a4a

-H "Authorization: Bearer ACCESS_TOKEN"

Triggering the outbound call

The dialer application triggers VoiceAI Connect to make an outbound call, by sending an HTTP POST request to the /api/v1/actions/dialout endpoint.

An HTTP Authorization header must be included in the request, as explained in the previous section.

The HTTP POST body should contain a JSON object with the following properties:

For example:

POST /api/v1/actions/dialout HTTP/1.1
Host: server.example.com
Content-Type: application/json;charset=UTF-8
Authorization: BEARER 223d0d870a364a4a

{
  "bot": "Bot1",
  "target": "tel:+123456789",
  "caller": "1-800-111-111",
  "notifyUrl": "https://my-app.example.com/call/454/notify",
  "machineDetection": "detect”, 
  "voicemailEndTimeoutSec": 20, 
  "metadata": {
    "participantName": "Alice"
  }
}

In case the triggering of the outbound call was successful, VoiceAI Connect will respond 200 OK with a JSON body with the following properties:

For example:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8


{
  "conversationId": "daf0c30f-e7a7-4644-b20b-667676b70615"
}

Receiving 200 OK response only means that the outbound call was triggered. It does not mean that it was actually performed. See Receiving call-status notifications below for a way to get the outcome of the outbound call.

In case of error, one of the following response codes will be sent:

• 400: The request was invalid.

• 401: There was an authentication error.

• 500: An internal error occurred.

An example of error response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8


{
  "error": "request should have required property 'bot'"
}

Receiving dialoutInitiated event

If the value "dialoutInitiated" is included in the sendEventsToBot bot configuration parameter, VoiceAI Connect will send the dialoutInitiated event to the bot when an outbound call is initiated (before it was answered).

This event can be used for receiving the call details on the bot in a early stage, so it will have them even in case the call has failed. It includes all the parameters that are sent with the initial event that is sent to the bot.

See Receiving outbound call-initiated notification for more details.

Receiving the metadata on the call initiation

When the user answers the call, the call-initiation event is sent to the bot (see Call initiation).

This event contains the metadata that was sent by the dialer application.

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

{
  "type": "event",
  "name": "start",
  "parameters": {
    "callee": "+123456789",
    "caller": "1-800-111-111",
    "dialoutMetadata": {
      "participantName": "Alice"
    }
  }
}

{
  "type": "event",
  "name": "channel",
  "value": "telephony",
  "channelData": {
    "callee": "+123456789",
    "caller": "1-800-111-111",
    "dialoutMetadata": {
      "participantName": "Alice"
    }
  },
  "from": {
    "id": "12345678"
  },
  "locale": "en-US"
}

{
  "queryInput": {
    "event": {
      "languageCode": "en-US",
      "name": "WELCOME",
      "parameters": {
        "callee": "+123456789",
        "caller": "1-800-111-111",
        "dialoutMetadata": {
          "participantName": "Alice"
        }
      }
    }
  }
}

$session.params.event-WELCOME.dialoutMetadata.participantName

{
  "queryInput": {
    "event": {
      "languageCode": "en-US",
      "name": "WELCOME",
      "parameters": {
        "callee": "+123456789",
        "caller": "1-800-111-111",
        "dialoutMetadata": {
          "participantName": "Alice"
        }
      }
    }
  }
}

Receiving call-status notifications

For receiving call-status notifications, you should set the notifyUrl property on the dialout request.

When this property is set, VoiceAI Connect sends an HTTP POST requests towards the specified URL. This request contains a JSON body with the following properties:

For example:

POST /call/454/notify HTTP/1.1
Host: my-app.example.com
Content-Type: application/json;charset=UTF-8

{
  "conversationId": "daf0c30f-e7a7-4644-b20b-667676b70615",
  "status": "failed",
  "reasonCode": "busy",
  "reason": "SIP ;cause=486 ;text=\"Busy Here\""
}

The POST request is sent with no authorization header. It is recommended that the notifyUrl will include some unique identifier that will be used by the web server to authenticate the requests.

Disabling and enabling speech recognition upon call connect

By default, when an outbound (dialout) call is answered by the user, the user's initial words (e.g., "Hello" or an other welcome prompt) is not required and therefore, it is not sent to a speech-to-text provider. The start message sent by VoiceAI Connect to the bot does not include any speech recognition. This feature may save the provider unnecessary costs charged by the speech-to-text provider.

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

Machine detection

You can configure VoiceAI Connect to detect if a human or machine (fax or answering) has answered the call. VoiceAI Connect can differentiate between fax and answering machine.

When enabled, VoiceAI Connect monitors the audio stream of the outbound call immediately after it has been answered, and can then do one of the following (depending on configuration) upon detection:

• (Fax and answering machines) Disconnect the call

• (Answering machines only) Allow the bot to play a message to the answering machine

Playing bot message upon answering machine detection

If you want VoiceAI Connect to allow the bot to play a voice message when an answering machine is detected, set the machineDetection property to "detect" on the dialout request.

When configured and an answering machine is detected, instead of disconnecting the call, VoiceAI Connect does the following (in chronological order):

1. Sends a machineDetection event to the bot to notify the bot that it has detected an answering machine:

   AudioCodes Bot API

   {
     "type": "event",
     "name": "machineDetection",
     "value": "voicemail-prompt-start"
   }

   Microsoft Bot Framework

   {
     "type": "event",
     "name": "machineDetection",
     "value": "voicemail-prompt-start"
   }

   Dialogflow CX

   {
     "queryInput": {
       "event": {
         "languageCode": "en-US",
         "name": "machineDetection",
         "parameters": {
           "value": "voicemail-prompt-start"
         }
       }
     }
   }
   

   Dialogflow ES

   {
     "queryInput": {
       "event": {
         "languageCode": "en-US",
         "name": "machineDetection",
         "parameters": {
           "value": "voicemail-prompt-start"
         }
       }
     }
   }

2. Upon detection of the beep of the answering machine (or after a beep timeout set by the voicemailEndTimeoutSec property), it sends another event to the bot to notify the bot that it can start playing its message to the answering machine:

   AudioCodes Bot API

   {
     "type": "event",
     "name": "machineDetection",
     "value": "voicemail-prompt-end-beep"
   }

   Microsoft Bot Framework

   {
     "type": "event",
     "name": "machineDetection",
     "value": "voicemail-prompt-end-beep"
   }

   Dialogflow CX

   {
     "queryInput": {
       "event": {
         "languageCode": "en-US",
         "name": "machineDetection",
         "parameters": {
           "value": "voicemail-prompt-end-beep"
         }
       }
     }
   }

   Dialogflow ES

   {
     "queryInput": {
       "event": {
         "languageCode": "en-US",
         "name": "machineDetection",
         "parameters": {
           "value": "voicemail-prompt-end-beep"
         }
       }
     }
   }

Disconnecting call upon machine detection

If you want VoiceAI Connect to disconnect the call upon machine (fax or answering) detection, set the machineDetection property to "disconnect" on the dialout request.

When a call is disconnected due to machine detection, the reasonCode of the disconnect is set to "machine-detected" and the reason is set to "voicemail detected" or "fax detected". The following is an example of a notification sent to the dialer application when fax is detected:

{ 
  "conversationId": "daf0c30f-e7a7-4644-b20b-667676b70615", 
  "status": "completed",
  "reasonCode": "machine-detected",
  "reason": "fax detected"
}