Voice Services - API Documentation

Overview

Vorboss provides a basic, yet extremely functional VoIP integration API.

The main functions of the API are:

  1. Automating the placement of calls (e.g. “click to dial” from your CRM system)
  2. Checking in-progress call-state
  3. Management of call recordings

About Call UUIDs

The Vorboss VoIP API references calls by a globally-unique identifier, known as a UUID. This is compliant with the industry-standard format as described here: http://en.wikipedia.org/wiki/Universally_unique_identifier

Crucially, when a call is placed using the API, the UUID of the call is returned immediately, before the call has been established. This is extremely important, since the returned UUID becomes the reference “handle” for the call in subsequent requests. Typically this UUID will be stored in the application on the request-side of the integration, for example in order that the call can be linked to a CRM record.

Server Connection Details

The API is available via HTTPS only on api.vorboss.net

The API is actually powered by a pair of redundant API servers, these are api-01.vorboss.net and api-02.vorboss.net.

We normally publish IP addresses for both servers via api.vorboss.net. Depending on your software-stack, this “round-robin DNS” may provide the resilience that you need. If you need to hard-code your own failover algorithm, you can use the api-01 and api-02 hostnames directly, as these will always be supported in the future.

Requests and Responses

Requests are simple HTTP GET to the respective API URL (see below), where requests parameters are provided simply in the URL string. This facilitates testing from a web browser, cUrl client and so on.

Some (but not all) requests require authentication using an API key. API keys can be generated on our Control Panel at https://secure.vorboss.net. The API key can be supplied with the key URL parameter.

Responses are provided in XML format by default, however most API functions will also return a JSON response if the request URI is appended with .json.

Consider the following example:

Request XML (default)
Response:

<?xml version="1.0" encoding="UTF-8"?>
<vorboss-rpc-response>
    <header>
        <status>
            <code>200</code>
            <enum>OK</enum>
        </status>
        <message>API server is ready.</message>
        <exec-ms>0.077</exec-ms>
    </header>
</vorboss-rpc-response>

Request JSON
Response:

{
   "vorboss-rpc-response":{
      "header":{
         "message":"API server is ready.",
         "exec-ms":"0.068",
         "status":{
            "enum":"OK",
            "code":200
         }
      }
   }
}

You will note that these responses are essentially identical, however formatted in order to be simple to parse.

Responses always contain a header object, and this will always include the status object. The status object always contains both code and enum.

The response codes are mapped to standard HTTP status codes (see http://en.wikipedia.org/wiki/List_of_HTTP_status_codes). Successful operations always result in a 200 in the code field and an OK in the enum2/7/2015 8:05:57 PM field, per the above example.

The full list of supported API response codes are as follows:

Code Enum
Success Codes Success Codes
200 OK
Client Error Codes Client Error Codes
400 BAD_REQUEST
401 UNAUTHORISED
402 FORBIDDEN
403 NOT_FOUND
404 NOT_ALLOWED
Server Error Codes Server Error Codes
500 INTERNAL_SERVER_ERROR
501 NOT_IMPLEMENTED
502 SERVICE_UNAVAILABLE

Response Data

When an API call results in some response data, the response XML also includes a data element.

This can be seen in the following example response:

<?xml version="1.0" encoding="UTF-8"?>
<vorboss-rpc-response>
    <header>
        <status>
            <code>200</code>
            <enum>OK</enum>
        </status>
        <message>Call queued successfully.</message>
        <exec-ms>171.472</exec-ms>
    </header>
    <data>
        <call>
            <uuid>032c8a7e-b264-102e-98c4-000c292ce213</uuid>
        </call>
    </data>
</vorboss-rpc-response>

Handling Errors

When an error code is returned, you will always get a bit more detail in the header element. For example:

<?xml version="1.0" encoding="UTF-8"?>
<vorboss-rpc-response>
    <header>
        <status>
            <code>500</code>
            <enum>INTERNAL_SERVER_ERROR</enum>
        </status>
        <message>No API key specified on the request. Please use the 'key' parameter.</message>
    </header>
</vorboss-rpc-response>

To further simplify things, our API server sets the HTTP response header to match the code in the XML or JSON response. For example, if the XML response contains a 404 code, the HTTP header will also be a 404. This means that you don’t necessarily have to parse the header element, as in many programming languages the response will be treated as a failure automatically based on the HTTP header.

Always Test a Failed Response

Higher-level library-intensive languages such as Java and .NET will throw an exception if the HTTP header code is not 200. In these languages, make sure that you include sufficient error-checking code to handle API failure responses, since by default they will not return the response body to your application unless you explicitly code it to do so.

The fastest way to test this is to make an API call with an invalid API key or invalid request URI.

Available Functions

connectivity/verify

Test connectivity to the API server and verify that the server is available.

Params: None

connectivity/ip

Returns your current IP – useful for “what is my ip” type functions.

Params: None

voip/base/dial

Place a call between any two endpoints.

Params:

Parameter Type Description Required? Example
key API Key Your API Key Yes 073d65e9-172b-498b-a49a-6ed17121f84d
src Phone Number Source extension (3 digits for internal) or telephone number Yes 103
dst Phone Number Destination telephone number Yes 01392690001
account Integer(0-9999) 4-digit Accounting code No 5643
record Boolean Record the call? No TRUE

voip/recordings/fetch

Get the recording meta-data by call UUID.

Params:

Parameter Type Description Required? Example
key API Key Your API Key Yes 073d65e9-172b-498b-a49a-6ed17121f84d
uuid Call UUID Call UUID (as returned by dial function) Yes 032c8a7e-b264-102e-98c4-000c292ce213

voip/recordings/download

Downloads the mp3 call recording.

Params:

Parameter Type Description Required? Example
key API Key Your API Key Yes 073d65e9-172b-498b-a49a-6ed17121f84d
uuid Call UUID Call UUID (as returned by dial function) Yes 032c8a7e-b264-102e-98c4-000c292ce213

voip/recordings/delete

Delete the specified call recording from our servers.

Params:

Parameter Type Description Required? Example
key API Key Your API Key Yes 073d65e9-172b-498b-a49a-6ed17121f84d
uuid Call UUID Call UUID (as returned by dial function) Yes 032c8a7e-b264-102e-98c4-000c292ce213