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"
          }
      }
      
    • Connect one of two calls, classifying the callee. If it is an answering machine wait for the message to finish but hang up if it's a fax machine:

      "connect" :
      {
          "destinations" : [ "441908273800", "441908273802" ],
          "call_from" : "441908273801",
          "hold_media" : { "play" : { "play_list" : [ { "file_to_play" : "welcome.wav" } ] } },
          "seconds_answer_timeout" : 30,
          "secondary_call" : 
          {
              "call_recording" : true,
              "minutes_max_call_duration" : 240
          },
          "classify_callee" :
          {
              "milliseconds_timeout" : 5000,
              "hang_up_on_answering_machine" : false,
              "hang_up_on_fax_machine" : true,
              "answering_machine_ready_to_record" :
              {
                  "milliseconds_min_beep_duration" : 180,
                  "milliseconds_post_beep_silence" : 1000,
                  "milliseconds_no_beep_silence" : 4000,
                  "seconds_max_message_duration" : 10
              }
          },
          "next_page" : 
          {
              "url" : "connectNextPage"
          }
      }
      
    • Make two calls, requesting connectFirstPage when the first of the two calls is answered. Connect this call once all connectFirstPage's actions have run:

      "connect" :
      {
          "destinations" : [ "441908273800", "441908273802" ],
          "call_from" : "441908273801",
          "hold_media" : { "play" : { "play_list" : [ { "file_to_play" : "welcome.wav" } ] } },
          "seconds_answer_timeout" : 30,
          "secondary_call" : 
          {
              "call_recording" : true,
              "minutes_max_call_duration" : 240,
              "first_page" : "connectFirstPage",
              "final_page" : "connectFinalPage",
              "error_page" : "connectErrorPage"
          },
          "next_page" : 
          {
              "url" : "connectNextPage"
          }
      }
      
  • API Reference:

    class Connect : TelephonyAction

    Represents a connect action.

    Constructors:

    Connect(String destination);
    

    Members:

    AddDestination(String destination);
    String CallFrom;
    Play HoldMedia;
    int SecondsAnswerTimeout;
    EnableCalleeClassification();
    EnableCalleeClassification(ClassifyCallee classifyCallee);
    SecondaryCall SecondaryCall;
    WebPageRequest NextPage;
    
    class ClassifyCallee

    Represents parameters that control aspects of callee classification.

    Constructors:

    ClassifyCallee();
    ClassifyCallee(int millisecondsTimeout, bool hangUpOnAnsweringMachine);
    ClassifyCallee(int millisecondsTimeout, bool hangUpOnAnsweringMachine, bool hangUpOnFaxMachine);
    

    Members:

    int MillisecondsTimeout;
    bool HangUpOnAnsweringMachine;
    bool HangUpOnFaxMachine;
    ConfigureAnsweringMachineReadyToRecord(AnsweringMachineReadyToRecord answeringMachineReadyToRecord);
    
    class SecondaryCall

    Represents the pages and properties relating to the outbound (secondary) call.

    Constructors:

    SecondaryCall();
    SecondaryCall(WebPageRequest firstPage);
    SecondaryCall(WebPageRequest firstPage, int minutesMaxDuration, bool callRecording);
    

    Members:

    bool CallRecording;
    bool CallRecordingEncryption;
    int MinutesMaxCallDuration;
    WebPageRequest FirstPage;
    WebPageRequest FinalPage;
    WebPageRequest ErrorPage;
    
    class AnsweringMachineReadyToRecord

    Represents an object that controls how to wait for an answering machine message to finish in order to be ready to record a message.

    Constructors:

    AnsweringMachineReadyToRecord();
    AnsweringMachineReadyToRecord(int millisecondsMinBeepDuration, 
                                  int millisecondsPostBeepSilence,
                                  int millisecondsNoBeepSilence, 
                                  int secondsMaxMessageDuration);
    

    Members:

    int MillisecondsMinBeepDuration;
    int MillisecondsPostBeepSilence;
    int MillisecondsNoBeepSilence;
    int SecondsMaxMessageDuration;
    
    class WebPageRequest

    Represents a request to a web page.

    Constructors:

    WebPageRequest(String url);
    WebPageRequest(String url, String method);
    

    Members:

    String Method;
    
    class ConnectResult : ActionResult

    Represents the result of a connect action.

    Members:

    double SecondsConnectedDuration;
    

    Examples:

    • Make a call to a single destination, without classifying the callee, and connect it to the existing call:

      Connect connectAction = new Connect("441908273800");
      connectAction.CallFrom = "441908273801";
      connectAction.NextPage = new WebPageRequest("ConnectNextPage.aspx");
      actions.Add(connectAction);
      

      The connect result is obtained from the request for the next page:

      ConnectResult connectResult = (ConnectResult)ourRequest.InstanceInfo.ActionResult;
      double connectedDuration = connectResult.SecondsConnectedDuration;
      ...
      
    • Connect one of two calls, classifying the callee. If it is an answering machine wait for the message to finish:

      Connect connectAction = new Connect("441908273800");
      connectAction.AddDestination("441908273802");
      connectAction.CallFrom = "441908273801";
      connectAction.HoldMedia = Play.PlayFile("welcome.wav");
      connectAction.SecondsAnswerTimeout = 30;
      connectAction.SecondaryCall = new SecondaryCall(null, 240, true);
      
      ClassifyCallee classifyCallee = new ClassifyCallee(5000, false);
      classifyCallee.ConfigureAnsweringMachineReadyToRecord(new AnsweringMachineReadyToRecord(180, 1000, 4000, 10));
      connectAction.EnableCalleeClassification(classifyCallee);
      
      connectAction.NextPage = new WebPageRequest("ConnectNextPage.aspx");
      
      actions.Add(connectAction);
      
    • Make two calls, requesting connectFirstPage when the first of the two calls is answered. Connect this call once all connectFirstPage's actions have run:

      Connect connectAction = new Connect("441908273800");
      connectAction.AddDestination("441908273802");
      connectAction.CallFrom = "441908273801";
      connectAction.HoldMedia = Play.PlayFile("welcome.wav");
      connectAction.SecondsAnswerTimeout = 30;
      connectAction.SecondaryCall = new SecondaryCall(new WebPageRequest("ConnectFirstPage.aspx"), 240, true);
      connectAction.SecondaryCall.FinalPage = new WebPageRequest("ConnectFinalPage.aspx");
      connectAction.SecondaryCall.ErrorPage = new WebPageRequest("ConnectErrorPage.aspx");
      
      connectAction.NextPage = new WebPageRequest("ConnectNextPage.aspx");
      
      actions.Add(connectAction);
      
  • API Reference:

    Class Connect Inherits TelephonyAction

    Represents a connect action.

    Constructors:

    New(destination As String)
    

    Members:

    AddDestination(destination As String)
    CallFrom As String
    HoldMedia As RestAPIWrapper.Play
    SecondsAnswerTimeout As Integer
    EnableCalleeClassification()
    EnableCalleeClassification(classifyCallee As RestAPIWrapper.ClassifyCallee)
    SecondaryCall As RestAPIWrapper.SecondaryCall
    NextPage As RestAPIWrapper.WebPageRequest
    
    Class ClassifyCallee

    Represents parameters that control aspects of callee classification.

    Constructors:

    New()
    New(millisecondsTimeout As Integer, hangUpOnAnsweringMachine As Boolean)
    New(millisecondsTimeout As Integer, hangUpOnAnsweringMachine As Boolean, hangUpOnFaxMachine As Boolean)
    

    Members:

    MillisecondsTimeout As Integer
    HangUpOnAnsweringMachine As Boolean
    HangUpOnFaxMachine As Boolean
    ConfigureAnsweringMachineReadyToRecord(answeringMachineReadyToRecord As RestAPIWrapper.AnsweringMachineReadyToRecord)
    
    Class SecondaryCall

    Represents the pages and properties relating to the outbound (secondary) call.

    Constructors:

    New()
    New(firstPage As RestAPIWrapper.WebPageRequest)
    New(firstPage As RestAPIWrapper.WebPageRequest, minutesMaxDuration As Integer, callRecording As Booleab)
    

    Members:

    CallRecording As Boolean
    CallRecordingEncryption As Boolean
    MinutesMaxCallDuration As Integer
    FirstPage As RestAPIWrapper.WebPageRequest
    FinalPage As RestAPIWrapper.WebPageRequest
    ErrorPage As RestAPIWrapper.WebPageRequest
    
    Class AnsweringMachineReadyToRecord

    Represents an object that controls how to wait for an answering machine message to finish in order to be ready to record a message.

    Constructors:

    New()
    New(millisecondsMinBeepDuration As Integer,  
        millisecondsPostBeepSilence As Integer,
        millisecondsNoBeepSilence As Integer, 
        secondsMaxMessageDuration As Integer)
    

    Members:

    MillisecondsMinBeepDuration As Integer
    MillisecondsPostBeepSilence As Integer
    MillisecondsNoBeepSilence As Integer
    SecondsMaxMessageDuration As Integer
    
    Class WebPageRequest

    Represents a request to a web page.

    Constructors:

    New(url As String)
    New(url As String, method As String)
    

    Members:

    Method As String
    
    Class ConnectResult Inherits RestAPIWrapper.ActionResult

    Represents the result of a connect action.

    Members:

    SecondsConnectedDuration As Double
    

    Examples:

    • Make a call to a single destination, without classifying the callee, and connect it to the existing call:

      Dim connectAction As Connect = New Connect("441908273800")
      connectAction.CallFrom = "441908273801"
      connectAction.NextPage = New WebPageRequest("ConnectNextPage.aspx")
      actions.Add(connectAction)
      

      The connect result is obtained from the request for the next page:

      Dim connectResult As ConnectResult = ourRequest.InstanceInfo.ActionResult
      Dim connectedDuration As Double = connectResult.SecondsConnectedDuration
      ...
      
    • Connect one of two calls, classifying the callee. If it is an answering machine wait for the message to finish:

      Dim connectAction As Connect = new Connect("441908273800")
      connectAction.AddDestination("441908273802")
      connectAction.CallFrom = "441908273801"
      connectAction.HoldMedia = Play.PlayFile("welcome.wav")
      connectAction.SecondsAnswerTimeout = 30
      connectAction.SecondaryCall = New SecondaryCall(Nothing, 240, True)
      
      Dim classifyCallee As ClassifyCallee = New ClassifyCallee(5000, False)
      classifyCallee.ConfigureAnsweringMachineReadyToRecord(New AnsweringMachineReadyToRecord(180, 1000, 4000, 10))
      connectAction.EnableCalleeClassification(classifyCallee)
      
      connectAction.NextPage = New WebPageRequest("ConnectNextPage.aspx")
      
      actions.Add(connectAction)
      
    • Make two calls, requesting connectFirstPage when the first of the two calls is answered. Connect this call once all connectFirstPage's actions have run:

      Dim connectAction As Connect = new Connect("441908273800")
      connectAction.AddDestination("441908273802")
      connectAction.CallFrom = "441908273801"
      connectAction.HoldMedia = Play.PlayFile("welcome.wav")
      connectAction.SecondsAnswerTimeout = 30
      connectAction.SecondaryCall = New SecondaryCall(new WebPageRequest("ConnectFirstPage.aspx"), 240, True)
      connectAction.SecondaryCall.FinalPage = New WebPageRequest("ConnectFinalPage.aspx")
      connectAction.SecondaryCall.ErrorPage = New WebPageRequest("ConnectErrorPage.aspx")
      
      connectAction.NextPage = New WebPageRequest("ConnectNextPage.aspx")
      
      actions.Add(connectAction)
      
  • API Reference:

    class Connect extends TelephonyAction

    Represents a connect action.

    Constructors:

    Connect(String destination);
    

    Members:

    addDestination(String destination);
    setCallFrom(String callFrom);
    setHoldMedia(Play media);
    setSecondsAnswerTimeout(int secondsTimeout);
    enableCalleeClassification();
    enableCalleeClassification(ClassifyCallee classifyCallee);
    setSecondaryCall(SecondaryCall secondaryCall);
    setNextPage(WebPageRequest nextPage);
    
    class ClassifyCallee

    Represents parameters that control aspects of callee classification.

    Constructors:

    ClassifyCallee();
    ClassifyCallee(int millisecondsTimeout, boolean hangUpOnAnsweringMachine);
    

    Members:

    setMillisecondsTimeout(int millisecondsTimeout);
    setHangUpOnAnsweringMachine(boolean hangUp);
    configureAnsweringMachineReadyToRecord(AnsweringMachineReadyToRecord answeringMachineReadyToRecord);
    
    class SecondaryCall

    Represents the pages and properties relating to the outbound (secondary) call.

    Constructors:

    SecondaryCall();
    SecondaryCall(WebPageRequest firstPage);
    SecondaryCall(WebPageRequest firstPage, int minutesMaxDuration, boolean callRecording);
    

    Members:

    setCallRecording(boolean enable);
    setCallRecordingEncryption(boolean enable);
    setMinutesMaxCallDuration(int minutesMaxCallDuration);
    setFirstPage(WebPageRequest firstPage);
    setFinalPage(WebPageRequest finalPage);
    setErrorPage(WebPageRequest errorPage);
    
    class AnsweringMachineReadyToRecord

    Represents an object that controls how to wait for an answering machine message to finish in order to be ready to record a message.

    Constructors:

    AnsweringMachineReadyToRecord();
    AnsweringMachineReadyToRecord(int millisecondsMinBeepDuration, 
                                  int millisecondsPostBeepSilence,
                                  int millisecondsNoBeepSilence, 
                                  int secondsMaxMessageDuration);
    

    Members:

    setMillisecondsMinBeepDuration(int millisecondsMinBeepDuration);
    setMillisecondsPostBeepSilence(int millisecondsPostBeepSilence);
    setMillisecondsNoBeepSilence(int millisecondsNoBeepSilence);
    setSecondsMaxMessageDuration(int secondsMaxMessageDuration);
    
    class WebPageRequest

    Represents a request to a web page.

    Constructors:

    WebPageRequest(String url);
    WebPageRequest(String url, String method);
    

    Members:

    setMethod(String method);
    
    class ConnectResult extends ActionResult

    Represents the result of a connect action.

    Members:

    double getSecondsConnectedDuration();
    

    Examples:

    • Make a call to a single destination, without classifying the callee, and connect it to the existing call:

      Connect connectAction = new Connect("441908273800");
      connectAction.setCallFrom("441908273801");
      connectAction.setNextPage(new WebPageRequest("connectNextPage"));
      actions.add(connectAction);
      

      The connect result is obtained from the request for the next page:

      ConnectResult connectResult = (ConnectResult)ourRequest.getInstanceInfo().getActionResult();
      double connectedDuration = connectResult.getSecondsConnectedDuration();
      ...
      
    • Connect one of two calls, classifying the callee. If it is an answering machine wait for the message to finish:

      Connect connectAction = new Connect("441908273800");
      connectAction.addDestination("441908273802");
      connectAction.setCallFrom("441908273801");
      connectAction.setHoldMedia(Play.PlayFile("welcome.wav"));
      connectAction.setSecondsAnswerTimeout(30);
      connectAction.setSecondaryCall(new SecondaryCall(null, 240, true));
      
      ClassifyCallee classifyCallee = new ClassifyCallee(5000, false);
      classifyCallee.configureAnsweringMachineReadyToRecord(new AnsweringMachineReadyToRecord(180, 1000, 4000, 10));
      connectAction.enableCalleeClassification(classifyCallee);
      
      connectAction.setNextPage(new WebPageRequest("connectNextPage"));
      
      actions.add(connectAction);
      
    • Make two calls, requesting connectFirstPage when the first of the two calls is answered. Connect this call once all connectFirstPage's actions have run:

      Connect connectAction = new Connect("441908273800");
      connectAction.addDestination("441908273802");
      connectAction.setCallFrom("441908273801");
      connectAction.setHoldMedia(Play.PlayFile("welcome.wav"));
      connectAction.setSecondsAnswerTimeout(30);
      SecondaryCall secondaryCall  = new SecondaryCall(new WebPageRequest("connectFirstPage"), 240, true);
      secondaryCall.setFinalPage(new WebPageRequest("connectFinalPage"));
      secondaryCall.setErrorPage(new WebPageRequest("connectErrorPage"));
      connectAction.setSecondaryCall(secondaryCall);
      
      connectAction.setNextPage(new WebPageRequest("connectNextPage"));
      
      actions.add(connectAction);
      
  • API Reference:

    class Connect

    Represents a connect action.

    Constructors:

    Connect()
    

    Members:

    def set_next_page(next_page) # A WebPage object, see Redirect() for details
    def set_call_origin(origin)
    def set_hold_media(play_action) # A Play object, see Play() for details
    def set_seconds_answer_timeout(seconds_answer_timeout)
    def append_call_destination(destination)
    def set_classify_callee(classify_callee) # A ClassifyCallee object
    def set_secondary_call(secondary_call) # A SecondaryCall object
    
    AnsweringMachineReadyToRecord

    Answering machine ready configuration options. Used by ClassifyCallee.

    Constructors:

    AnsweringMachineReadyToRecord(milliseconds_min_beep_duration=None, 
                                  milliseconds_post_beep_silence=None, 
                                  milliseconds_no_beep_silence=None, 
                                  seconds_max_message_duration=None)
    
    ClassifyCallee

    Callee classification options. Used by Connect.

    Constructors:

    ClassifyCallee(enable=True, 
                   milliseconds_timeout=None, 
                   hang_up_on_answering_machine=None,
                   hang_up_on_fax_machine=None,
                   answering_machine_ready_to_record=None)
    
    SecondaryCall

    Secondary call options. Used by Connect.

    Constructors:

    SecondaryCall(first_page=None, 
                  final_page=None, 
                  error_page=None, 
                  minutes_max_call_duration=None, 
                  call_recording=None,
                  call_recording_encryption=None)
    

    Examples:

    • Make a call to a single destination, without classifying the callee, and connect it to the existing call:

      from aculab.telephony_rest_api import *
      
      my_actions = Actions(token='Usage example 1: Connect.')
      my_connection = Connect()
      
      my_connection.append_call_destination('441908273800')
      my_connection.set_call_origin('441908273801')
      my_connection.set_next_page(WebPage(url='connect_next_page'))
      
      my_actions.add(my_connection)
      response_body = my_actions.get_json()
      
    • Connect one of two calls, classifying the callee. If it is an answering machine wait for the message to finish but hang up on a fax machine:

      from aculab.telephony_rest_api import *
      my_actions = Actions(token='Usage example 2: Connect.')
      my_connection = Connect()
      
      my_connection.append_call_destination('441908273800')
      my_connection.append_call_destination('441908273802')
      my_connection.set_call_origin('441908273801')
      my_connection.set_hold_media(Play(file_to_play='welcome.wav'))
      my_connection.set_seconds_answer_timeout(seconds_answer_timeout=30)
      my_connection.set_secondary_call(SecondaryCall(minutes_max_call_duration=240, 
                                                     call_recording=True))
      
      answering_machine_options = AnsweringMachineReadyToRecord(milliseconds_min_beep_duration=180, 
                                                                milliseconds_post_beep_silence=1000, 
                                                                milliseconds_no_beep_silence=4000, 
                                                                seconds_max_message_duration=10)
      classify_callee = ClassifyCallee(enable=True, 
                                       hang_up_on_answering_machine=False,
                                       hang_up_on_fax_machine=True,
                                       answering_machine_ready_to_record=answering_machine_options)
      my_connection.set_classify_callee(classify_callee)
      
      my_connection.set_next_page(WebPage(url='connect_next_page'))
      
      my_actions.add(my_connection)
      response_body = my_actions.get_json()
      
    • Make two calls, requesting connect_first_page when the first of the two calls is answered. Connect this call once all connect_first_page's actions have run:

      from aculab.telephony_rest_api import *
      my_actions = Actions(token='Usage example 3: Connect.')
      my_connection = Connect()
      
      my_connection.append_call_destination('441908273800')
      my_connection.append_call_destination('441908273802')
      my_connection.set_call_origin('441908273801')
      my_connection.set_hold_media(Play(file_to_play='welcome.wav'))
      my_connection.set_seconds_answer_timeout(seconds_answer_timeout=30)
      my_connection.set_secondary_call(SecondaryCall(first_page=WebPage(url='connect_first_page'),
                                                     final_page=WebPage(url='connect_final_page'),
                                                     error_page=WebPage(url='connect_error_page'),
                                                     minutes_max_call_duration=240, 
                                                     call_recording=True))
      
      my_connection.set_next_page(WebPage(url='connect_next_page'))
      
      my_actions.add(my_connection)
      response_body = my_actions.get_json()
      
  • API Reference:

    The Connect class

    Introduction

    Represents a connect action.

    Class synopsis

    class Connect extends ActionBase {
    
        /* methods */
        public __construct()
        public void addDestination(string $dest)
        public void setCallFrom(string $from)
        public void setHoldMedia(Play $play)
        public void setSecondsAnswerTimeout(int $seconds)
        public void setClassifyCallee(ClassifyCalleeConfiguration $classify)
        public void setSecondaryCallConfiguration(SecondaryCallConfiguration $call_config)
        public void setNextPage(string $next_page, string $method = null)
    }
    
    The SecondaryCallConfiguration class

    Introduction

    Represents the secondary call configuration for a connect action.

    Class synopsis

    class SecondaryCallConfiguration {
    
        /* methods */
        public __construct()
        public void setCallRecording(boolean $record)
        public void setCallRecordingEncryption(boolean $encrypt)
        public void setMinutesMaxCallDuration(int $minutes)
        public void setFirstPage(string $first_page, string $method = null)
        public void setFinalPage(string $final_page, string $method = null)
        public void setErrorPage(string $error_page, string $method = null)
    }
    
    The ClassifyCalleeConfiguration class

    Introduction

    Represents the callee classification configuration for a connect action.

    Class synopsis

    class ClassifyCalleeConfiguration {
    
        /* methods */
        public __construct()
        public void setMillisecondsTimeout(int $milliseconds)
        public void setHangupOnFaxMachine(boolean $hangup)
        public void setHangupOnAnsweringMachine(boolean $hangup)
        public void setReadyToRecordConfiguration(
            int $milliseconds_min_beep_duration,
            int $milliseconds_post_beep_silence,
            int $milliseconds_no_beep_silence,
            int $seconds_max_message_duration
        )
    }
    
    The ConnectResult class

    Introduction

    Represents the result of a connect action.

    Class synopsis

    class ConnectResult extends ActionResult {
    
        /* methods */
        public float getSecondsConnectedDuration()
        
        /* inherited methods */
        public string getAction()
        public boolean getInterrupted()
    }
    

    Examples:

    • Make a call to a single destination, without classifying the callee, and connect it to the existing call:

      $connect = new Aculab\TelephonyRestAPI\Connect();
      $connect->addDestination('441908273800');
      $connect->setCallFrom('441908273801');
      $connect->setNextPage('connectNextPage');
      
      $actions->add($connect);
      

      Obtain the duration for which the two calls were connected from the action's next page request:

      $info = InstanceInfo::getInstanceInfo();
      $connectResult = $info->getActionResult();
      $durationConnected = $connectResult->getSecondsConnectedDuration();
      
    • Connect one of two calls, classifying the callee. If it is an answering machine wait for the message to finish:

      $connect = new Aculab\TelephonyRestAPI\Connect();
      $connect->addDestination('441908273800');
      $connect->addDestination('441908273802');
      $connect->setCallFrom('441908273801');
      $connect->setHoldMedia(Aculab\TelephonyRestAPI\Play::playFile('welcome.wav'));
      $connect->setSecondsAnswerTimeout(30);
      $connect->setNextPage('connectNextPage');
      
      $call_config = new Aculab\TelephonyRestAPI\SecondaryCallConfiguration();
      $call_config->setMinutesMaxCallDuration(240);
      $call_config->setRecord(true);
      $connect->setSecondaryCallConfiguration($call_config);
      
      $classify_configuration = new Aculab\TelephonyRestAPI\ClassifyCalleeConfiguration();
      $classify_configuration->setMillisecondsTimeout(5000);
      $classify_configuration->setHangupOnAnsweringMachine(false);
      $classify_configuration->setAnsweringMachineReadyToRecordConfiguration(180, 1000, 4000, 10);
      $connect->setClassifyCallee($classify_configuration);
      
      $actions->add($connect);
      
    • Make two calls, requesting connectFirstPage when the first of the two calls is answered. Connect this call once all connectFirstPage's actions have run:

      $connect = new Aculab\TelephonyRestAPI\Connect();
      $connect->addDestination('441908273800');
      $connect->addDestination('441908273802');
      $connect->setCallFrom('441908273801');
      $connect->setHoldMedia(Aculab\TelephonyRestAPI\Play::playFile('welcome.wav'));
      $connect->setSecondsAnswerTimeout(30);
      $connect->setNextPage('connectNextPage');
      
      $call_config = new Aculab\TelephonyRestAPI\SecondaryCallConfiguration();
      $call_config->setMinutesMaxCallDuration(240);
      $call_config->setRecord(true);
      $call_config->setFirstPage('connectFirstPage');
      $call_config->setErrorPage('connectErrorPage');
      $call_config->setFinalPage('connectFinalPage');
      $connect->setSecondaryCallConfiguration($call_config);
      
      $actions->add($connect);