BROMBLER APIs quick reference

Important notice: API calls are limited to one call per second
Brombler APIs use the same error codes as HTTP.

Class implementations:
#PHP | #node.js | #python | C# (async) | C# (sync) | #cas

Quick samples:


<?php
require('brombler.php');

// create a brombler instance
$brombler = new Brombler("Bearer [your_auth_token]");

// creating a call
$brombler->call("[your_phone_number]", array(
	"_" => "Hello! Do you want to talk?",
	"yes | sure | want -not" => array(
		// here you can set a callback URL to mange the response (documentation below)
		"\$api https://website.com/callme.php?opaque=sessionId" => "Hooray! I'm glad!"
	),
	"no" => "Me neither!"
));

// to get a list of active calls
print_r($brombler->list());

// getting a token (client_id, client_secret, expiration_in_seconds)
$key = Brombler::apiKey("[your_client_id]", "[your_client_secret]", 3600 * 24);
?>

In order to use the Brombler APIs these steps must be followed:

Step 1 - Obtaining a key

To obtain your access token client_id and client_secret must be POST-ed to https://brombler.com/auth.cas.
Note: client_id and client_secret are available in the settings menu

curl -d client_id=[your_client_id] -d client_secret=[your_client_secret] -d exp=86400 https://brombler.com/auth.cas

The token should resemble this:

{
    "access_token": "[your_auth_token]",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Step 2 - Making a phone call

API URL: https://brombler.com/call.cas

Set the Authorization HTTP header to "Bearer [your_auth_token]"

GET or POST parameters (both methods supported, POST recommended):
who: the called phone number
tree: a URI-encoded string or a JSON string containing the text or call tree (see below)
timeout (optional): maximum call duration, in seconds

The next example calls [your_phone_number] saying "Hello".

curl -H "Authorization: Bearer [your_auth_token]" "https://brombler.com/call.cas?who=[your_phone_number]&tree=Hello"

You can also POST a JSON object: 

curl -H "Authorization: Bearer [your_auth_token]" -H "Content-Type: application/json" "https://brombler.com/call.cas" -d "{\"who\": \"[your_phone_number]\", \"tree\": \"Hello!\"}"

For complex interactions, a JSON tree like this may be used:

{
  "_"  : "Hello! Do you want to speak with me?",
  "yes": "$redirect [your_phone_number]",
  "no" : "Okay then! Bye!"
}

This must be URI-encoded (see encodeURIComponent). The same example becomes: 

curl -H "Authorization: Bearer [your_auth_token]" "https://brombler.com/call.cas?who=[your_phone_number]&tree=%7B%22_%22%3A%22Hello!+Do+you+want+to+speak+with+me%3F%22%2C%22yes%22%3A%22%24redirect+[your_phone_number]%22%2C%22no%22%3A%22Okay+then!+Bye!%22%7D

The API response should look like this:

{
   "response":200,
   "responseText":"OK",
}

An URL callback example: 

{
  "_"  : "Hello! Do you want to talk?",
  "yes": {
    "$redirect [your_phone_number]": "You will be redirected to an agent!",
  },
  "no" : {
    "$api https://adresa_url/serviciuCallback": "Ok! Bye!"
  }
}

The previous example will redirect the call to [your_phone_number] when "yes" is heard. If "no" is heard, a GET request to the URL indicated after $api will be made.

Callback URL parameters that will be received:
e: event type (open, close, tree)
path: tree path
from: caller identity
to: callee identity
id: call unique id
answered=true: only when the call was answered
duration: call duration in seconds

If the callback URL already contains GET parameters, for example $api https://adresa_url/serviciuCallback?session=d00de", will be transparently forwarded. This is useful in adding opaque values to identify a callback to its original API call.


Step 3 - Monitoring the calls

API URL: https://brombler.com/list.cas

Set the Authorization HTTP header to "Bearer [your_auth_token]"

This list all the active calls for the current account:

curl -H "Authorization: Bearer [your_auth_token]" "https://brombler.com/list.cas"
{
   "response":200,
   "responseText":"OK",
   "list":{
      "bf0e91a0-2e719948@192.168.2.120":{
         "account":"[identity]",
         "isInvite":0,
         "from":"[your_phone_number]",
         "to":"[identity]",
         "callDuration":1996,
         "path":""
      }
   }
}

To end a call via API, https://brombler.com/close.cas with who parameter set to the call id (for the example above bf0e91a0-2e719948@192.168.2.120).


Optional WebRTC service for Call Centers (requires CallCenter account - contact sales)

To get an WebRTC CallCenter access token, client_id and client_secret must be sent via HTTP POST to https://brombler.com/auth.cas.
Note: client_id and client_secret are available in the settings menu

curl -d client_id=[your_client_id] -d client_secret=[your_client_secret] -d webrtc=1 -d exp=86400 https://brombler.com/auth.cas

The response should look like this:

{
    "access_token": "token_de_acces_WebRTC",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Once you have an access token, you may use the WebRTC services as it follows: 
  <html>
    <head>
       ...
      <script src="https://brombler.com/js/BromblerPhone.js"></script>
      <script>
        var bp = new BromblerPhone("call_center_user", "token_de_acces_WebRTC");
        bp.onIncoming = function(session, caller)  {
	        console.log("Call from: " + caller);
        };

        bp.onEnded = function(session, caller) {
	        console.log("Call from " + caller + " ended");
        };

        bp.onAnswered = function(session, caller) {
	        console.log("Call from " + caller + " was answered");
        };

        bp.onFailed = function(session, caller) {

        };

        function call() {
	        bp.call(numar_de_telefon);
        }

        function answer() {
	        bp.answer();
        }

        function reject() {
	        bp.close();
        }
      </script>
    </head>
    <body>
      ...
    </body>
  </html>

To redirect a call to a call center agent, you must use the refer(call_id, call_center_user) method. The call list is posted in real time by using $forward https://server/endpoint in the conversational tree. The list will be sent in JSON format by Brombler every second.