connect Action
Connects an existing inbound or outbound call (primary call) to a new call destination (secondary call). More than one possible destination can be specified, but only one secondary call ends up being connected. This is typically the first call to be answered.
Note that web apps that use the
connect
action require sufficient Extra Channels
to be set in the service configuration for the number of destinations specified.The connect properties are:
Property | Required/Optional | Default | Description |
---|---|---|---|
destinations | required | - | An array of strings each specifying a destination telephone number or a sip address. The first to answer is connected. The rest are hung up. |
call from | optional | a number or address that identifies the primary call | A telephone number or sip address that identifies who is calling. If destinations contains one or more telephone numbers then you may need to supply a validated caller id here. See Outbound Calls. |
hold media | optional | null | A play action. Media to play repeatedly to the primary call until the secondary call is connected. null signifies playing ringing to the call. |
seconds answer timeout | optional | 30 | An integer. The time to wait for the secondary call to be answered. |
classify callee | optional | null | A classify callee object that determines whether and how to classify the far end of the secondary call. null signifies that classification is disabled. |
secondary call | optional | null | A secondary call object that specifies pages and properties that are related to the lifetime of the secondary call. |
next page | optional | null | A web page request object that defines the web page to be requested once the connect has finished. If null or no page is specified then the subsequent action in the action array will be executed. |
classify callee controls some parameters used in the classification of the type of callee:
Property | Required/Optional | Default | Description |
---|---|---|---|
enable | optional | true | true or false. Whether to enable classification of the far end of the secondary call. |
milliseconds timeout | optional | 5000 | An integer. The timeout for classification in milliseconds. |
hang up on answering machine | optional | true | Hang up the secondary call if it is to an answering machine. |
hang up on fax machine | optional | true | Hang up the secondary call if it is to a fax machine. |
answering machine ready to record | optional | null | An answering machine ready to record object. null signifies using the default values. |
secondary call determines the pages and properties relating to the outbound (secondary) call:
Property | Required/Optional | Default | Description |
---|---|---|---|
call recording | optional | false | true or false. Whether to record the whole of the secondary call. |
call recording encryption | optional | false | true or false. Whether to encrypt the whole call recording. |
minutes max call duration | optional | 240 | An integer. The maximum duration of the secondary call in minutes. The secondary call is hung up if this is exceeded. |
first page | optional | null | The page to request when the secondary call has been answered (and classification completed, if it has been enabled). This gives the application an opportunity to interact with the secondary call before it is connected to the primary call. |
final page | optional | null | The page that is requested when either the primary or secondary call is hung up (i.e. the connection has been broken). |
error page | optional | null | The page to request when there is an error during the connect action. |
answering machine ready to record provides access to some advanced settings that control how an answering machine message is detected in preparation for it recording your message:
Property | Required/Optional | Default | Description |
---|---|---|---|
milliseconds min beep duration | optional | 180 | An integer. The minimum duration of a beep. |
milliseconds post beep silence | optional | 1000 | An integer. Wait for this period of silence after the beep. |
milliseconds no beep silence | optional | 4000 | An integer. Wait for this period of silence when no beep is detected. |
seconds max message duration | optional | 10 | An integer. The maximum duration of an answering machine prompt message. Give up waiting for the answering machine prompt to complete after this period. |
web page request defines how a specific web page is requested:
Property | Required/Optional | Default | Description |
---|---|---|---|
url | required | - | The address of the web page to request. |
method | optional | POST | One of "GET" or "POST". The HTTP request method to use when requesting the url . |
Returns
The result of a successfulconnect
action will be returned via the subsequent http request to the next page
in action result
as follows:Property | Description |
---|---|
seconds connected duration | A floating point value to one decimal place. The duration for which the two calls were connected. |
Remarks
The connect action makes outbound (secondary) calls to all specified destinations. As soon as one is answered either it is immediately connected to the primary call or, if asecondary call first page
is specified, the answered call's details are sent to it. Meanwile the other call attempts are dropped.If classification with
hang up on answering machine
is enabled, destinations that are classified as "answering_machine" will also be dropped and listed in the dropped calls
array sent to the secondary call's final page
. Similarly, if classification with hang up on fax machine
is enabled, destinations that are classified as "fax_machine" will also be dropped.Setting the
first page
property allows the application to interact with the secondary call before it is connected as illustrated in the following diagram:
In this example a first page
is specified that responds with a run menu
action. The selected option's page then returns a further play action. Once this has completed the primary and secondary calls are connected.
When the secondary call goes idle its final page
is requested. The this call
property in the request contains details of the secondary call. Note: if the primary call hangs up, the secondary call is automatically hung up.
Subsequently the connect's next page
is requested. The action result
contains details of the connect. Note: If no next page
is defined then the application continues with the next action in the action array.
If interaction with any of the secondary call's pages fails then a request is made to the secondary call's error page
with a description of the issues.
-
Examples:
-
Make a call to a single destination, without classifying the callee, and connect it to the existing call:
"connect" : { "destinations" : [ "441908273800" ], "call_from" : "441908273801", "next_page" : { "url" : "connectNextPage" } }
Once the connect action has finished the duration for which the two calls were connected is specified in the request for the next page:
"action_result" : { "action" : "connect", "result" : { "seconds_connected_duration" : "47.3" } }
-