Outbound call initialization and APIs

In order to make an outbound call, follow the below.

Perform authentication

The dialer application must be authenticated in order to trigger an outbound call.

To use the HTTP basic authentication method for outbound calling you should use the client secret as the password for the authentication.

The dialout request should include a header like the following (the value is built according to the username and the password):

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

For testing with the curl utility, the following command-line option can be used for sending the header:

-u "username:password"

Triggering the outbound call

The dialer application triggers Live Hub 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: livehub.audiocodes.io
Content-Type: application/json;charset=UTF-8
Authorization: BEARER 223d0d870a364a4a

{
  "bot": "UUID",
  "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, Live Hub 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, Live Hub 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.

Receiving the metadata on the call initiation

When the user answers the call, the call-initiation event is sent to the bot.

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, Live Hub 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 Live Hub 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 on the bot’s advanced parameters, using the following bot parameter:

Machine detection

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

When enabled, Live Hub 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 Live Hub 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, Live Hub 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 Live Hub 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"
}