REST API Overview

TringMe REST API calls are made over the internet by sending HTTP GET or POST requests to our server. For example, to get the TringMe user id, following URL should be constructed:

Sample Request URL
http://api.tringme.com/api.php?apikey=12sdas8dadadsadajs3&
sig=4b61af9cd869706edc6a4569fc4e7b33 &op=getuid&
email=api@anexample.com

You will require API keys in order to use TringMe REST API. To obtain API keys, login and go to Settings page. In the Developer Settings section you can request for you API keys. API keys are available in a pair, public and private keys.

To access the TringMe API, you should pass your public API key, operation code and signature of the request to the TringMe’s API server. Depending on requested operation, you will also need to pass one or more required parameters. All API request must include checksum signature using private key to avoid any tampering of the request. Note that, you MUST NOT include your private key for any transaction.


Basic Concepts

Telephony and Messaging is not new to us; we use it every day in our life. Infact it has become an integral part of our day-to-day communication Whether it is just a phone call, a conference we attend, interact with an automated bank assistant via IVR, voice chat with our buddy half-way around the world via instant messenger or just send an SMS, it is clear that communication has only increased and the types of devices we use to interact have grown as well.

Hence, with evolving trends, we are not restricted to phone to converse anymore. One could be using phone to call another user on phone or SIP or say Gtalk and vice versa. Apart from the peer to peer calls, we often dial to automated voice response system (say phone banking) or multi-party destination (say conference). This gives a plenty of combinations how one calls and how one receives the call.

TringMe’s APIs allows you to communicate with all of the above mentioned source an destination types. Before we get deeper into this, let’s define some terminology which will be used throughout this document. Source: Who is initiating call and how. Source could be placing the call from phone, Flash widget or Flash phone, SIP, Instant Messenger, or a mobile device using VoIP. Destination: This identifies to whom the call is initiated to. It can be an individual, a multi-party conferencing or an IVR (VoicePHP) application. The individuals can receive the call on wide range of devices that TringMe’s unified communication platform offers and supports - Phone, Instant Messenger (Gtalk, Skype), SIP, etc. Take a look at the “Supported Destination” section below to understand the specifics of how various types of destination can be specified.

As you go through the document, it will become clear as to how various combinations of source and destination can be used by your application. However to give you a quick glimpse of how simple to use source & destination, invoking following URL will place call between two phone numbers 18585551234 & 15015551234:

Sample Request URL
http://api.tringme.com/api.php?apikey=12sdas8dadadsadajs3&
sig=4b61af9cd869706edc6a4569fc4e7b33 &op=call&src=18585551234 &dest=15015551234

Simple isn’t? In later sections, we will show more powerful examples like how to play greetings, defining destinations for recurring use (channels), scheduling calls and conferences etc.


Invoking REST API

Following sections describe the mandatory API parameters which should be a part of every API request that is sent by the client:

Parameter Description
apikey Public API Key, this is used to identify the invoker for an API operation. To obtain API keys, login and go to Settings page. In the Developer Settings section you can request for you API keys
op Operation to be performed. The addition parameters needed for the successful execution of a specific operation is as specified in the documentation.
sig Signature is used to ensure that the API request coming to TringMe is actually coming from you. It is generated by concatenating all the parameters needed for an operation with keys in sorted order as = , private key and taking md5 of it.
debug[optional] Signature is used to ensure that the API request coming to TringMe is actually coming from you. It is generated by concatenating all the parameters needed for an operation with keys in sorted order as = , private key and taking md5 of it.

In any API operation, if cookie is omitted, the operation will be performed from API user’s account.

Some APIs take duration as a parameter. Although we strive hard to ensure that duration as specified is honored, it may vary by a few seconds as call-setup and disconnection involves signaling.


API Return Value

Unless otherwise specified, all the APIs return following:

If successful, it will return ‘OK’ or ‘OK ’.

On failure, it will return ‘FAIL ’. For explanation of reason code, please refer to the API Results section below.

TringMe API only allows clients to make a limited number of calls in a given hour. For most usages, our limits are sufficient. It is best practice for applications to use local database and invoke TringMe API only when needed. TringMe dynamically throttles API requests if necessary, especially when invoked without real usage or calls.

API response is indicated by OK or FAIL condition. Success will be indicated by following output:

OK []

‘value’ will be operation specific and optional. Please refer to the specific API for how to interpret the value.

Failure will be indicated by one of the values tabulated below:

Parameter Description
FAIL Operation Failed (however API key, signature etc were okay)
NOKEY Missing Key
NOSIG Missing Signature
NOOP Missing Operation
BADSIG Bad Signature
INVALIDKEY Invalid API Key
INSUFFICIENTCREDITS Insufficient Credits
BADDEST Destination is invalid
MISSINGPARA Missing parameters
USEREXIST User already exists
AUTHFAIL Authorization Fail or Session Expired/Invalid cookie (get new cookie)
NOTLOGGEDIN Login Required
BADDURATION Duration value is out of limit. Ensure that you are using the right unit (minute vs. second)
BADCHANNEL Channel does not exist OR not owned by API holder
TOOMANYCHANNELS Channel quota exceeded
TOOMANYCONFS Number of conference you can schedule is exceeded

API Usage

In this section, you will find common techniques to use APIs for specific purpose. Given the capability of the API, there are several different ways to use them to your benefit or application requirement. Our intent here is to give you basic building blocks which can then enable you to use them for more complex requirements as needed.

Placing a call

Setting up a call is quick and easy. Here are the steps to follow:

  • 1. Use ‘call’ API to place a call. You need to specify ‘src’ and either ‘dest’ or a ‘greeting’. You can specify optional parameters like duration and when to control scheduling aspects of the call. If successful, your call will be placed.
  • 2. if the ‘when’ parameter is specified, it will return a if successful.
Create a Conference

Setting up a conference is quick and easy. Here are the steps to follow:

  • 1. Use ‘createconference’ API to create a conference. You can specify optional parameters like duration and when to control scheduling aspects of the conference. If successful, it will return a .
  • 2. Once the is available, conference can be invoked in multiple ways:
  • Using conf: : as a ‘dest’ parameter in ‘call’ API. The ‘src’ parameter can contain the phone numbers of the users as a comma separated list.
  • Creating a channel and specify conf: : in the ‘dest’.
  • Use that channel created in step above (b) to invoke calls from Flash, ‘call’ API
  • Use SIP client and invoke sip: @sip.tringme.com to join the conference.

If you are not using PHP and like to use TringMe API, you need to generate signature and API URL and use appropriate library (e.g. libcurl) to invoke the API using URL. In above code, all mentioned functionalities are handled by function TringMeAPI.

Below is description of how you can generate signature and API URL manually.


Support

If you have any questions or have encountered a bug, please visit our support pages

If you have specific requirements which cannot be met using these APIs, contact us with your requirement details and we will get back to you.

Use of TringMe API is subject to TringMe TOS.

If you are an enterprise and would like to know better how TringMe can help you reduce cost and at the same time benefit you,
please send a mail to bizdev@tringme.com