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|
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.
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|
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.
Following sections describe the mandatory API parameters which should be a part of every API request that is sent by the client:
|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.
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:
‘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:
|FAIL||Operation Failed (however API key, signature etc were okay)|
|INVALIDKEY||Invalid API Key|
|BADDEST||Destination is invalid|
|USEREXIST||User already exists|
|AUTHFAIL||Authorization Fail or Session Expired/Invalid cookie (get new cookie)|
|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|
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:
Setting up a conference is quick and easy. Here are the steps to follow:
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.
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 firstname.lastname@example.org