Starting An Outbound Service

You start your outbound application by invoking your Outbound Service on Aculab Cloud that refers to your application by name. You can do this manually from the Outbound Services page or you can call a web service on Aculab Cloud to start it.

Aculab Cloud makes an outbound call and when it is answered it requests your application's First Page.

If far-end classification is enabled, when the call is answered Aculab Cloud will attempt to classify the far-end. If answering machine be detected it wait for the machine's prompt message to be played before requesting your application's First Page.

Note: An Outbound Service is configured either to call a Telephone Number/SIP address or a conference. If configured incorrectly, the outbound call will fail.

Starting an Outbound Service from the Outbound Services page

Press the gearwheel icon next to your outbound service on the Outbound Services page. You should see a form like this one;
Configuration options for starting an outbound rest service
Under the Test Settings fill in the destination for the outbound call and the other parameters if necessary then press the Start Test button.

Starting an Outbound Service using the service_start Web Service

The outbound parameters argument for service_start, when used to start a REST API service, requires a JSON format string that specifies the destination of the call. This can either be a single JSON object containing the following parameters or an array of JSON objects each containing the following parameters. If an array is provided, then a new instance of the service is started for each object provided:

Property Required/Optional Description
to required A string containing the destination for the outbound call. This can be a phone number, SIP address or conference room name.
from required only if to is a telephone number A string containing the origin telephone number (or SIP address) from which the call is being made. If to is a telephone number, then this needs to be a validated caller id (see Caller IDs).
token optional A string containing a user-defined token that will be passed transparently to the Web App in the token property of the instance_info argument to the page request.
outbound parameters optional A string containing user-defined data that will be passed transparently to the Web App in the this_call.outbound_parameters property of the instance_info argument to the page request.

Http authentication username and password:

The authentication username and password contain details of the service to call and the account on which it is configured.   The username contains three elements delimited by '/':

cloudId / 
account username /
name of the outbound service
		

The password should be the outbound service password specified for the selected outbound service.

e.g.
Username: 1-2-0/user@example.com/MyOutboundService
Password: MyOutboundServicePassword

High-level Language Wrappers

The service_start web service can be called using one of our high-level language wrappers:

  • Examples:

    • Using the service_start web service to call a telephone number:

      https://ws.aculabcloud.net/service_start?outbound_parameters=
        {
          "to" : "441908283800",
          "from" : "441908283801",
          "token" : "my token info",
          "outbound_parameters" : "some user data"
        }
      							

      with:

        Username: cloudId/accountName/outboundServiceName (e.g. 1-2-0/user@example.com/MyOutboundService)
        Password: outboundServicePassword
      							
    • Using the service_start web service to call a conference:

      https://ws.aculabcloud.net/service_start?outbound_parameters=
        {
          "to" : "myConference",
          "token" : "my token info",
          "outbound_parameters" : "some user data"
        }
      							

      with:

        Username: cloudId/accountName/outboundServiceName (e.g. 1-2-0/user@example.com/MyOutboundService)
        Password: outboundServicePassword
      							
    • Using the service_start web service to start multiple instances of a service each of which will call one of the specified destinations:

      https://ws.aculabcloud.net/service_start?outbound_parameters=
        [
          {
              "to" : "441908283800",
              "from" : "441908283801",
              "token" : "token1",
              "outbound_parameters" : "some user data"
          },
          {
              "to" : "sip:bob@acompany.com",
              "token" : "token2"
          },
          {
              "to" : "sip:bill@anotherCompany.com",
              "from" : "sip:bob@acompany.com",
              "token" : "token3"
          }
        ]
      							

      with:

        Username: cloudId/accountName/outboundServiceName (e.g. 1-2-0/user@example.com/MyOutboundService)
        Password: outboundServicePassword
      							
  • class OutboundRESTAPIService

    Constructors:

      OutboundRESTAPIService(WebServiceWrappers.PlatformAccount account, String serviceName, String servicePassword);
      OutboundRESTAPIService(String connection, String username, String serviceName, String servicePassword);
    					

    Members:

      List<ServiceInvocation> Start(OutboundCall call);
      List<ServiceInvocation> Start(List<OutboundCall> calls);
      List<ServiceInvocation> UpdateStatus(out bool finished);
      bool Finished;
    					

    class OutboundCall

    Constructors:

      OutboundCall(String to);
      OutboundCall(String to, String from);
    					

    Members:

      String Token;
      String OutboundParameters;
    					

    class ServiceInvocation

    Members:

      String ApplicationInstanceId;
      bool Finished;
      ServiceStatus Status;
      String ReturnText;
      int ReturnCode;
      DateTime ApplicationStatusEta;
    					

    Examples:

    • Use the OutboundRESTAPIService class to call a telephone number:

        // Create the service object
        OutboundRESTAPIService myService = new OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myOutboundService", "myOutboundServicePassword");
        // Create the target
        OutboundCall call = new OutboundCall("441908273800", "441908273801");
        call.Token = "my token info";
        call.OutboundParameters = "some user data";
      
        // Start the service
        List<ServiceInvocation> invocations = myService.Start(call);
      							
    • Use the OutboundRESTAPIService class to call a conference:

        // Create the service object
        OutboundRESTAPIService myService = new OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myCallAConferenceService", "myCallAConferenceServicePassword");
        // Create the target
        OutboundCall call = new OutboundCall("myConference");
        call.Token = "my token info";
        call.OutboundParameters = "some user data";
      
        // Start the service
        List<ServiceInvocation> invocations = myService.Start(call);
      							
    • Use the OutboundRESTAPIService class to start multiple instances of a service each of which will call a different destination. Wait for all the service instances to complete.:

        // Create the service object
        OutboundRESTAPIService myService = new OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myOutboundService", "myOutboundServicePassword");
      
        // Create multiple targets
        List<OutboundCall> calls = new List<OutboundCall>(3);
        calls.Add(new OutboundCall("441908273800", "441908273801"));
        calls[0].Token = "my token info 1";
        calls[0].OutboundParameters = "some user data";
        calls.Add(new OutboundCall("sip:bob@acompany.com"));
        calls[1].Token = "my token info 2";
        calls.Add(new OutboundCall("sip:bill@anothercompany.com", "sip:bob@acompany.com"));
        calls[2].Token = "my token info 3";
      
        // Start the services
        List<ServiceInvocation> invocations = myService.Start(call2);
      
        // Wait until all instances of this service run have completed.
        bool finished;
        do
        {
          invocations = myService.UpdateStatus(out finished);
          Thread.Sleep(2000);
        } while (!finished);
      							
  • Class OutboundRESTAPIService

    Constructors:

      New(account As WebServiceWrappers.PlatformAccount, serviceName As String, servicePassword As String)
      New(connection As String, username As String, serviceName As String, servicePassword As String)
    					

    Members:

      Start(call As OutboundCall) As List(Of ServiceInvocation)
      Start(calls As List(Of OutboundCall)) As List(Of ServiceInvocation)
      UpdateStatus(ByRef finished As Boolean) As List(Of ServiceInvocation)
      Finished As Boolean
    					

    Class OutboundCall

    Constructors:

      New(to As String)
      New(to As String, from As String)
    					

    Members:

      Token As String
      OutboundParameters As String
    					

    Class ServiceInvocation

    Members:

      Finished As Boolean
      Status As WebServiceWrappers.ServiceStatus
      ApplicationInstanceId As String
      ReturnText As String
      ReturnCode As Integer
      ApplicationStatusEta As DateTime
    					

    Examples:

    • Use the service_start web service to call a telephone number:

        ' Create the service object
        Dim myService As OutboundRESTAPIService = New OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myOutboundService", "myOutboundServicePassword")
        ' Create the target
        Dim call As OutboundCall = New OutboundCall("441908273800", "441908273801")
        call.Token = "my token info"
        call.OutboundParameters = "some user data"
      
        ' Start the service
        Dim invocations As List(Of ServiceInvocation) = myService.Start(call)
      							
    • Use the service_start web service to call a conference:

        ' Create the service object
        Dim myService As OutboundRESTAPIService = New OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myCallAConferenceService", "myCallAConferenceServicePassword")
        ' Create the target
        Dim call As OutboundCall = New OutboundCall("myConference")
        call.Token = "my token info"
        call.OutboundParameters = "some user data"
      
        ' Start the service
        Dim invocations As List(Of ServiceInvocation) = myService.Start(call)
      							
    • Use the service_start web service to start multiple instances of a service each of which will call a different destination. Wait for all the service instances to complete:

        ' Create the service object
        Dim myService As OutboundRESTAPIService = New OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myOutboundService", "myOutboundServicePassword")
      
        ' Create multiple targets
        Dim calls List(Of OutboundCall) = New List(Of OutboundCall)(3)
        calls.Add(New OutboundCall("441908273800", "441908273801"))
        calls(0).Token = "my token info 1"
        calls(0).OutboundParameters = "some user data"
        calls.Add(New OutboundCall("sip:bob@acompany.com"))
        calls(1).Token = "my token info 2"
        calls.Add(New OutboundCall("sip:bill@anothercompany.com", "sip:bob@acompany.com"))
        calls(2).Token = "my token info 3"
      
        ' Start the services
        Dim invocations As List(Of ServiceInvocation) = myService.Start(calls)
      
        ' Wait until all instances of this service run have completed.
        Dim finished As Boolean
        Do
          invocations = myService.UpdateStatus(finished)
          Thread.Sleep(2000)
        Loop while Not finished
      							
  • class OutboundRESTAPIService

    Constructors:

      OutboundRESTAPIService(String connection, String cloudUsername, String serviceName, String servicePassword)
    					

    Members:

      List<ServiceInvocation> start(OutboundCall call);
      List<ServiceInvocation> start(List<OutboundCall> calls);
      List<ServiceInvocation> updateStatus();
    					

    class OutboundCall

    Constructors:

      OutboundCall(String to);
      OutboundCall(String to, String from);
    					

    Members:

      void setToken(String token);
      void setOutboundParameters(String outboundParameters);
    					

    class ServiceInvocation

    Members:

      boolean isFinished();
      ServiceStatus getStatus();
      String getApplicationInstanceId();
      String getReturnText();
    					

    Examples:

    • Use the service_start web service to call a telephone number:

        // Create the service object
        OutboundRESTAPIService myService = new OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myOutboundService", "myOutboundServicePassword");
      
        // Create the target
        OutboundCall call = new OutboundCall("441908273800", "441908273801");
        call.setToken("my token info");
        call.setOutboundParameters("some user data");
      
        // Start the service
        List<ServiceInvocation> invocations = myService.start(call);
      							
    • Use the service_start web service to call a conference:

        // Create the service object
        OutboundRESTAPIService myService = new OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myCallAConferenceService", "myOutboundServicePassword");
        // Create the target
        OutboundCall call = new OutboundCall("myConference");
        call.setToken("my token info");
        call.setOutboundParameters("some user data");
      
        // Start the service
        List<ServiceInvocation> invocations = myService.start(call);
      							
    • Use the service_start web service to start multiple instances of a service each of which will call a differnet destination. Wait for all the service instances to complete:

        // Create the service object
        OutboundRESTAPIService myService = new OutboundRESTAPIService("1-2-0", "bob@acompany.com", "myCallAConferenceService", "myOutboundServicePassword");
      
        // Create multiple targets
        List<OutboundCall> calls = new ArrayList<OutboundCall>(3);
        calls.add(new OutboundCall("441908273800", "441908273801"));
        calls[0].setToken("my token info 1");
        calls[0].setOutboundParameters("some user data");
        calls.add(new OutboundCall("sip:bob@acompany.com"));
        calls[1].setToken("my token info 2");
        calls.add(new OutboundCall("sip:bill@anothercompany.com", "sip:bob@acompany.com"));
        calls[2].setToken("my token info 3");
      
        // Start the services
        List<ServiceInvocation> invocations = myService.start(call2);
      
        // Wait until all instances of this service run have completed.
        do
        {
          invocations = myService.updateStatus();
          Thread.sleep(2000);
        } while (!myService.isFinished());
      							
  • Starting an outbound service.

    The python web_services module exposes a function called invoke_outbound_service and a class called OutboundCalls.
    invoke_outbound_service(target, 
                            username, 
                            service_name, 
                            service_password, 
                            outbound_calls):
    					

    Arguments:

    Parameter Name Description
    target The id of the cloud you want to connect to, e.g, 1-2-0.
    username Your username on the target, e.g, my@email.address.
    service_name The name of the outbound service you want to invoke.
    service_password Your outbound service password as set in the outbound services page.
    outbound_calls This is an instance of a class of type OutboundCalls

    class OutboundCalls

    Constructors:

    OutboundCalls(call_to,
                  call_from=None,
                  token=None,
                  outbound_parameters=None)
    					

    Members:

    def add_call(self, call_to,
                       call_from=None,
                       token=None,
                       outbound_parameters=None):
    					
    Parameter Name Description
    call_to The call destination, a telephone number or SIP address.
    call_from The call origin. If calling a telephone number this might have to be a validated number.
    token A string that will be passed to your application as part of the instance info object.
    outbound_parameters Additional arguments that you want passed to the outbound application that will be triggered by the outbound service.
    def get_calls(self):
    					

    Examples:

    • Using the service_start web service to call a telephone number:

      from web_services import invoke_outbound_service, OutboundCalls
      
      outbound_calls = OutboundCalls(call_to="441908273800",
                                     call_from="441908273801",
                                     token="my token info",
                                     outbound_parameters="some additional data")
      
      invoke_outbound_service(target='1-2-0',
                              username="bob@acompany.com",
                              service_name="myOutboundService",
                              service_password="myOutboundServicePassword",
                              outbound_calls=outbound_calls)
      							
    • Using the service_start web service to call a conference:

      from web_services import invoke_outbound_service, OutboundCalls
      
      outbound_calls = OutboundCalls(call_to="myConference",
                                     token="my token info",
                                     outbound_parameters="some additional data")
      
      # Please note that the outbound service must be configured as a conference destination
      invoke_outbound_service(target='1-2-0',
                              username="bob@acompany.com",
                              service_name="myOutboundConferenceService",
                              service_password="myOutboundServicePassword",
                              outbound_calls=outbound_calls)
      							
    • Using the service_start web service to start multiple instances of a service each of which will call one of the specified destinations:

      from web_services import invoke_outbound_service, OutboundCalls
      
      outbound_calls = OutboundCalls(call_to="441908273800",
                                     call_from="441908273801",
                                     token="my token info 1",
                                     outbound_parameters="some additional data")
      outbound_calls.add_call(call_to="sip:bob@acompany.com",
                              token="my token info 2",
                              outbound_parameters="some additional data")
      outbound_calls.add_call(call_to="sip:bill@anothercompany.com",
                              call_from="sip:bob@acompany.com",
                              token="my token info 3",
                              outbound_parameters="some additional data")
      
      invoke_outbound_service(target='1-2-0',
                              username="bob@acompany.com",
                              service_name="myOutboundService",
                              service_password="myOutboundServicePassword",
                              outbound_calls=outbound_calls)
      							
  • The OutboundService class

    Class synopsis

    class OutboundService extends WebServiceBase{
        /* methods */
        public __construct(string $target, string $user_name, string $service_name, string $service_password)
        public mixed startInstance(mixed $instanceConfigurations)
        public mixed getInstanceStatus(mixed $instanceIds)
    
        /* inherited methods */
        public void setProxy(string $proxy_uri, boolean $request_fulluri)
        public void setErrorCallback(callable $callback)
    }
    					

    Description

    Represents a configured outbound service.
    The $target of the constructor is a cloud identifier (such as '1-2-0')

    startInstance() takes either a single OutboundInstanceConfiguration or an array of them. Upon success it returns an array of strings, each string being an instance identifier that can be passed to getInstanceStatus(). Upon failure, the return value is either an integer that is the HTTP response code or the value false

    getInstanceStatus() takes either a single string or an array of strings. Each string being an instance identifier that came from a call to startInstance(). Upon success it returns an array of OutboundInstanceStatus objects keyed by the instance identifier strings. Upon failure, the return value is either an integer that is the HTTP response code or the value false

    setErrorCallback() can be used to set a callback that is called when a HTTP error occurs. The callback is called with two parameters, the HTTP response code as an integer and the HTTP response body as a string. This is intended to aid debugging.

    The OutboundInstanceConfiguration class

    Class synopsis

    class OutboundInstanceConfiguration {
        /* methods */
        public __construct(string $to, string $from = '')
        public void setToken(string $token)
        public void setOutboundParameters(string $outbound_parameters)
    }
    					

    Description

    Represents the configuration used to start an outbound instance.

    The OutboundInstanceStatus class

    Class synopsis

    class OutboundInstanceStatus {
        /* methods */
        public boolean isFinished()
        public string getStatus()
        public string getStatusDetail()
        public DateTime getApplicationStatusETA()
        public string getApplicationInstanceId()
    }
    					

    Description

    Represents the status of an outbound instance.

    Examples:

    • Using the service_start web service to call a telephone number:

          $service = new Aculab\TelephonyRestAPI\OutboundService('1-2-0', 'user@example.com', 'appname', 'pass');
          $instconf = new Aculab\TelephonyRestAPI\OutboundInstanceConfiguration('441908283800', '441908283801');
          $instconf->setToken('my token info');
          $instconf->setOutboundParameters('some user data');
          $ids = $service->startInstance($instconf);
      							
    • Using the service_start web service to call a conference:

          $service = new Aculab\TelephonyRestAPI\OutboundService('1-2-0', 'user@example.com', 'appname', 'pass');
          $instconf = new Aculab\TelephonyRestAPI\OutboundInstanceConfiguration('myConference');
          $instconf->setToken('my token info');
          $instconf->setOutboundParameters('some user data');
          $ids = $service->startInstance($instconf);
      							
    • Using the service_start web service to start multiple instances of a service each of which will call one of the specified destinations:

          $service = new Aculab\TelephonyRestAPI\OutboundService('1-2-0', 'user@example.com', 'appname', 'pass');
      
          $inst1 = new Aculab\TelephonyRestAPI\OutboundInstanceConfiguration('441908283800', '441908283801');
          $inst1->setToken('token1');
          $inst1->setOutboundParameters('some user data');
      
          $inst2 = new Aculab\TelephonyRestAPI\OutboundInstanceConfiguration('sip:bob@acompany.com');
          $inst2->setToken('token2');
      
          $inst3 = new Aculab\TelephonyRestAPI\OutboundInstanceConfiguration('sip:bill@anotherCompany.com', 'sip:bob@acompany.com');
          $inst3->setToken('token3');
      
          $instconfs = array($inst1, $inst2, $inst3);
          $ids = $service->startInstance($instconfs);