Skip to main content

What is Web-To-Call?

Web-to-call takes a different approach to communicating with the customer. Since the introduction of WebRTC technologies, modern browsers (Chrome®, Firefox® and Chromium based browsers) are capable of handling multi-media streams and access microphones and speakers. This leads to a possibility of using the browser (mobile or desktop) as a communications tools - providing a means of communications directly from the browser.

Why Web-To-Call?​

Simple - Data and Context. Tools as Google Analytics, Google Tag Manager and others provide us with great insight into how customers use our websites. We are able to track and 'paint' customers and visitors, analyze their usage pattern, assign tracking codes to them and optimize their customer experience. By enabling similar functionality for voice calls, we enable new insights into usage - but most importantly, new insights into sales and acceleration of these.

Imagine that you're browsing your favorite online retailer and you have a call regarding a product. Imagine being able to click on the product and when the agent on the other side picks up, he already knows who you are and what product you would like to talk about. Implementing the above using Click-2-Call will require multiple phone numbers, one for each product (or even more, depending on the analytical level) - in other words, a costly experience. With Web-To-Call the process is seamless and economically sensible.

How does Web-To-Call Work?​

This scenario is applicable for both mobile and desktop browsers.

Web-To-Call relies on several pre-conditions, these are:

  • It is best to create a Cloudonix subscriber for each of the pages you want Web-To-Call to be enabled on. This will ensure that you will be able to identify each page.
  • You will need to create a public-outbound trunk to your existing call center platform.
  • You will need to create a remote micro-service, to handle call authorization.
  • You will need to create a remote CXML application, to track your calls and route them correctly.

Step 0: Install the cloudonix-cli tool​

Follow the instructions available at https://www.npmjs.com/package/@cloudonix.io/cloudonix-cli. Or, if you are truly impatient, do this:

$ npm install -g @cloudonix.io/cloudonix-cli

Now, setup your cloudonix-cli with your assigned Cloudonix tenant API-key:

$ cloudonix-cli config set --apikey=your_apikey_string --domain=my.default.domain.com

At this point, your cloudonix-cli should be ready for action. You can validate your installation by issuing the following:

$ cloudonix-cli config get

The result should print out the previous configuration you had set.

Step 1: Creating Cloudonix subscribers​

We shall now create a subscriber within the previously created domain:

$ cloudonix-cli subscribers create --domain=my.default.domain.com --msisdn=883999001 --self

This will create a new subscriber, whose msisdn designation is 883999001. You are probably wondering what made my choose 883999001 as the number, here is the explanation:

  • 883 - This is an ITU dialing code for 'nongeographic long distance calling'
  • 999 - An arbitrary identification number for my tracked website
  • 001 - An arbitrary identification number for the web page being tracked

The above should result in something similar to this:

id:           2994
domainId:     174
msisdn:       883999001
profile:
active:       true
sipPassword:
sip-password:

Step 2: Setup your public-outbound SIP trunk​

A SIP trunk is basically a VoIP (Voice over IP) connection between systems. A trunk will normally include the following information:

  • Remote IP - An IP Number or FQDN
  • Remote Port - A port number (normally, this will be 5060)
  • Remote Transport - A transport type (normally, this will be UDP)
  • Remote Prefix - A remote prefix (if required) to be added to destination numbers sent to the trunk for dialing

Let us assume that the following represents the SIP information of our call center:

Remote IP: 199.3.4.1
Remote Port: 5060
Remote Transport: UDP
Remote Prefix: 4545

We shall now use the cloudonix-cli trunks wizard to create the trunk. Issue the following command:

$ cloudonix-cli trunks wizard --domain=my.default.domain.com --self

Use the following as your input sample:

? Select a SIP configuration wizard Custom configuration
? Select trunk direction Termination (Outbound calls)
? Select trunk transport UDP
? Please enter your SIP trunk IP/FQDN 199.3.4.1
? Please enter your SIP trunk port number 5060
? Please enter a technical prefix 4545
? Please name your trunk trunk-199.3.4.1-outbound
? We will now create your trunk, using the below information:
ip:        199.3.4.1
name:      trunk-199.3.4.1-outbound
port:      5060
direction: public-outbound
transport: udp
prefix:    4545
domain:    my.default.domain.com

Once confirmed, the output should look like this:

id:        47
tenantId:  1
domainId:  174
name:      trunk-199.3.4.1-outbound
ip:        199.3.4.1
port:      5060
transport: udp
prefix:    4545
direction: public-outbound
profile:
active:    true
metric:    0

Step 3: Setup your Cloudonix WebRTC SDK Client Demo​

For a simple web based calling experience, clone our web widget repository - available via Github:

$ git clone git@github.com:cloudonix/cloudonix-webrtc-widget-demo.git

Make sure the cloned repository is available for browsing.

Important

For the widget to function properly, your web pages MUST be served over HTTPS. Unless served via HTTPS, the browsers will completely disable all WebRTC extensions - due to security restrictions.

Step 4: Setup your server side for RegFree dialing​

Web-To-Call is best operated using RegFree Dialing. RegFree Dialing enables a web customer to activate the an outbound call, using a single time, none re-playable token. This ensures that customers are authorized on a per call basis - not utilizing the normal Username/Password combination scenario - which is both insecure and prone to various privacy issues.

For the purpose of this how-to, imagine that your subscriber (883999001) would like to call the connected call center, using the phone number (DNID) - 12127773456.

In order to initiate a RegFree session, you are required to issue an HTTP POST as the following:

POST /calls/my.default.domain.com/outgoing/883999001
Host: api.voice.cloudonix.io
Authorization: bearer your_apikey_string
Content-Type: application/json

{
  "destination": "12127773456",
  "callback": "https://my.remote.status.report/script.php"
}

HTTP/1.1 200 OK

{
  "domainId": 174,
  "subscriberId": 2994,
  "destination": "12127773456",
  "direction": "outgoing",
  "token": "16a7294c989b11e7b3d32b9edb8660c7",
  "timeLimit": 7205
}

Pay close attention to the token provided. This token will be provided later on to the WebSDK, in order to authorise the outbound call from the WebSDK to the Cloudonix platform.

IMPORTANT

The above HTTP request MUST NOT be issued from the web browser. If you issue this from the web browser, you will be exposing your Cloudonix API key to the public eye - which is a security issue. It is crucial that you create your own server side for this.

Simple Example​

For a simple example, consider the following flow:

          +---------+                 +-------------+                  +---------------+
 Request: |         | -- HTTP GET --> |             | -- HTTP POST --> |               |
          | Browser |                 | Server Side |                  | Cloudonix API |
Response: |         | <-- Filtered -- |             | <-- RESPONSE --- |               |
          +---------+                 +-------------+                  +---------------+

Imagine that the HTTP GET will look something like this:

curl -X POST "https://my.default.domain.com/get_call_token?skey=my.public.skey&subscriber=883999001&destination=12127773456"

The above will proxy the following HTTP POST request to Cloudonix:

POST /calls/my.default.domain.com/outgoing/883999001
Host: api.voice.cloudonix.io
Authorization: bearer your_apikey_string
Content-Type: application/json

{
  "destination": "12127773456",
  "callback": "https://my.remote.status.report/script.php"
}

HTTP/1.1 200 OK

{
  "domainId": 174,
  "subscriberId": 2994,
  "destination": "12127773456",
  "direction": "outgoing",
  "token": "16a7294c989b11e7b3d32b9edb8660c7",
  "timeLimit": 7205
}

Which will eventually yield the following response:

HTTP/1.1 200 OK

{
  "token": "16a7294c989b11e7b3d32b9edb8660c7"
}

For more information about Cloudonix Call Control REST API, click here.

Step 5: Setup your server side Callback URL for status reports​

As defined in step 4, we've setup the callback URL as https://my.remote.status.report/script.php. This remote script will provide you with the insights of the call progress and its tracking. Your script will be invoked using an HTTP POST request - with the call's object as the JSON input.

For more information about Cloudonix Call Control REST API, click here.

Step 6: Setup a DNID catch-all to your application​

We shall now define a DNID to be routed into the call-routing application. Call routing is the most basic feature of the platform - and is invoked by default, if no subscriber is available for the provided DNID for dialing.

To do so, we shall use the cloudonix-cli tool again:

$ cloudonix-cli dnids create --dnid=12127773456 --global --self --domain=my.default.domain.com

The output of the above should look like this:

id:                     60
domainId:               174
applicationId:          244
messagingApplicationId: null
active:                 true
dnid:                   ^12127773456$
source:                 null
global:                 true
expression:             false
prefix:                 false
asteriskCompatible:     false
application:
  id:       244
  domainId: 174
  name:     call-routing
  profile:  null
  type:     Cloudonix:built-in
  url:      cx:///call-routing
  method:   GET
  active:   true

Let us assume that you would like to define routing to multiple DNID numbers, using a well defined pattern. In example, let's assume we would like to route all numbers starting with 1212777 followed by 4 digits. Thus, your CLI command will look like this:

$ cloudonix-cli dnids create --dnid=_1212777XXX --legacy --global --self --domain=my.default.domain.com

The output of the above should look like this:

id:                     61
domainId:               174
applicationId:          244
messagingApplicationId: null
active:                 true
dnid:                   ^(_1212777XXX)$
source:                 _1212777XXX
global:                 true
expression:             false
prefix:                 false
asteriskCompatible:     true
application:
  id:       244
  domainId: 174
  name:     call-routing
  profile:  null
  type:     Cloudonix:built-in
  url:      cx:///call-routing
  method:   GET
  active:   true

Step 7: Modify the WebRTC SDK Client Demo to RegFree Dialing​

Now that our routing patterns (DNID) and our various server-side components are ready, we can setup our WebSDK properly.

In the previously cloned directory, edit the cloudonixWidget.html file:

Step 7.1: Lines 10-15​

Change your cloned file to match your information. For RegFree dialing, this should look as following:

<script>
    var myDestination = '12127773456';
    var myCloudonixDomain = 'my.default.domain.com';
    var myCloudonixSubscriber = '883999001';
</script>
Step 7.2: Lines 143-145​

Your cloned file should look like this:

    Cloudonix.load();
    Cloudonix.init();
    Cloudonix.setCredentials(myCloudonixDomain, myCloudonixSubscriber, myCloudonixPassword);

Modify your code to look like this:

    Cloudonix.load();
    Cloudonix.init('Your.provided.remote.RegFree.Token');

It is up to you to obtain the remote token - so we'll leave that one up to you.

Step 8: Make your first call​

Load your modified web client and try making a call - the call should be automatically routed to your trunk.