By using the Aculab site, you agree with our use of cookies.
right  Talk To Us!

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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyRequired/OptionalDefaultDescription
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:

PropertyRequired/OptionalDefaultDescription
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 successful connect action will be returned via the subsequent http request to the next page in action result as follows:

PropertyDescription
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 a secondary 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.

 See also: Simple Connect
  • 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"
          }
      }