Telephony, Messaging and Conferencing APIs

Placing a call

TringMe provides multiple ways to place calls - using REST API, using Flash, SIP, Instant messenger (e.g.Google-Talk), Mobile VoIP etc. This particular API will give you all the information needed to place a call using REST.

Fundamentally speaking, this will create a callback between two parties. The system will call ‘src’ first and then ‘dest’ and then bridge both the calls. By default, the ‘src’ will receive the call with the caller-id of the invoker (as set by the ‘setcallerid’ API). The ‘dest’ will receive the ‘src’ number as the caller-id. The caller-id behavior can be modified by setting the private caller-id flag. In private caller-id case, both ‘src’ and ‘dest’ with receive the caller id of the invoker thereby enabling the communication between two parties without revealing each other’s number. The API is extremely powerful and supports a lot of combinations (for e.g. broadcasting a message to multiple phone numbers, playing greeting messages, taking user input and so on).

Parameters
op
call
src
First party phone number. Call will be first placed to this number. If the call is not answered, the API will terminate.

You can also specify comma separated multiple phone numbers to make bulk calls. This feature is specifically useful when broadcasting a voice message or inviting multiple people to a conference (e.g. 18585551212,19125551212). If you specify multiple phone numbers, then ‘dest’ should not be specified (Readmore about ‘dest’ below).

cookie [optional]
Cookie which was obtained using ‘login’.
dest [optional]
Second party phone number. Destination is optional if ‘greeting’ parameter is specified. This will enable call(the ‘src’ ) and play a message functionality.
callerid [optional]
Caller-ID to be used (set using ‘setcallerid’ API).
tag [optional]
User supplied parameter to associate a call in the Call Data Records. This should be alphanumeric only (a-z, A-Z, 0-9). All other characters will be replaced by ‘X’. It can be a maximum of 31 characters.If you with to be notified via a notify URL (‘setnotifyurl’), please ensure that tag is specified. Otherwise the notify URL will not be invoked. This is to ensure that you can identify the call with the tag.
duration [optional]
Duration after which the call should automatically disconnect. The duration is the timeframe from the moment ‘src’ is answered till the time when the call disconnects.
greeting [optional]
Greeting that should be played immediately after the ‘src’ answers. It can be either:
● URL of the wave file. Check supported formats below.
● A text string that should be spoken. It needs to prefixed with "male:" or "female:" to specify the type of voice to be used. For e.g.("male:Welcome to XYZ Bank")
postcallgreeting [optional]
Greeting that should be played before disconnecting the call. It can be either:
● URL of the wave file. Check supported formats below.
● A text string that should be spoken. It needs to prefixed with "male:" or "female:" to specify the type of voice to be used. For e.g. ("male:Thank you for using XYZ Bank")
dtmfmaxdigits [optional]
Maximum number of DTMF digits expected to enter by user after playing a greeting. The default value for this option is 0.
dtmfretries [optional]
Number of times DTMF entry will be retried. The default value is 1. This is valid only if ‘dtmfmaxdigits’ > 0 and ‘greeting’ is specified.
dtmftimeout [optional]
DTMF timeout in seconds. The default value is 10 seconds. This is valid only if ‘dtmfmaxdigits’ > 0 and ‘greeting’ is specified.
dtmftimeoutgreeting [optional]
Greeting that should be played if DTMF timeout is reached. It can be either:
● URL of the wave file. Check supported formats below.
● A text string that should be spoken. It needs to prefixed with "male:" or "female:" to specify the type of voice to be used. For e.g. ("male:You have entered the PIN. Please try again")
flag [optional]
One or more combinations of the flags below:
0 - Disables all notifications.
1 - Send call completed and DTMF input notifications. This is the default value.
2 - Send call-in-progress notifications (e.g. SRCANSWERED)
16 - Private Callerid.
when [optional]
Time in seconds, after which call should be invoked. This is how calls can be scheduled in the future. Value should be more than 60 seconds.

Supported Formats in Greeting Audio File:

● WAV file - 8KHz sampled, 16 bit linear, mono, uncompressed.

Sample Request URL
http://api.tringme.com/api.php?op=call&src=18585551234&dest=15015551234&cookie=1234567890123456789012345678901&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OK <[operationid]>
Sample Responses
OK
OK 1feh68fdkry60bs43

Send SMS

This API is used to send an SMS to worldwide destinations.

Parameters
op
sms
dest
Destination phone numbers where the SMS should be sent. You can also specify comma separated multiple phone numbers to send bulk SMS.
msg
Message to be sent (HTTP URL Encoded)
cookie [optional]
Cookie which was obtained using ‘login’.
callerid [optional]
Caller-ID to be used (set using ‘setcallerid’ API).
when [optional]
Time in seconds, after which call should be invoked. This is how SMS can be scheduled to be sent at a later time.
Sample Request URL
http://api.tringme.com/api.php?op=sms&dest=15015551234&msg=hai+joe&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OK
Sample Responses
OK

Cancel a scheduled Call /SMS / Conference

This API is used to cancel a scheduled call, SMS or conference. This is a premium API and will be available on request only. Note that it's not always possible to cancel the scheduled call, SMS or conferences if there is not a sufficient time to cancel or calls/sms are already placed in queue.

Parameters
op
cancel
id
Call/SMS/Conference identifier.
Sample Request URL
http://api.tringme.com/api.php?op=cancel&id=1q6gts8ers4&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OK
Sample Responses
OK

Get Voicemails

This API is used to retrieve voicemails.

Parameters
op
getvoicemail
cookie
cookie which was obtained using 'login'.
Sample Request URL
http://api.tringme.com/api.php?op=getvoicemal&cookie=1234567890123456789012345678901&json=1&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OKJ along with voicemail information in JSON format
Sample Responses
OKJ [{"voicemail":"v1t412345678901234567891","srcphone":"","recvtime":"45"},{"voicemail":"v1t412345678802234567892","srcphone":"","recvtime":"138"}]

Delete Voicemails

This API is used to delete voicemails.

Parameters
op
deletevoicemail
cookie
cookie which was obtained using 'login'.
id
Voicemail identifier available in the result obtained using 'getvoicemail'. If 'id' is set to 0, then all voicemails will be deleted.
Sample Request URL
http://api.tringme.com/api.php?op=deletevoicemail&cookie=1234567890123456789012345678901&id=v1t412345678901234567891&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OK
Sample Responses
OK

Create a Conference

This API is used to schedule a conference call.

Parameters
op
createconference
pin
PIN number that every attendee will be required to specify for authentication purposes before joining the conference call.
apin
PIN number of the administrator. Administrator has special privileges to control the conferencing parameters.
maxusers [optional]
Max number of users that can attend this conference call. The default value is 10
flag [optional]
Flags
duration [optional]
Duration of this conference call in minutes. The default value is 60 minutes.
when [optional]
Time in seconds, after which conference should be activated.
Sample Request URL
http://api.tringme.com/api.php?op=createconference&pin=12345&apin=41234&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OK <id>
Sample Responses
OK 1234567890123456789012345678901

Set CallerID

This API is used to set caller-id.

Parameters
op
setcallerid
cookie
Cookie which was obtained using ‘login’.
message
Message that should be sent to the user. Note that you can include %TRINGMEAUTHCODE% as a placeholder in your message where TringMe will insert the verification code. This verification code will be required for ‘verifycallerid’ API to complete the process of setting a verified caller-id. You can insert %TRINGMEAUTHCODE% as many times as you want in the message. For e.g. A typical use case of this could be to repeat the code if a call is placed to the user.
callerid
Phone number to be set as the callerid. To verify the authenticity of callerid, a call or an SMS will be placed with a verification code which can be passed to ‘verifycallerid’ API subsequently to complete the process. . The choice of using call or SMS for verification can be controlled by the ‘flag’ parameter below. Please note that SMS or Call charges as applicable will be charged to the user.
flag
One or more combinations of the flags below:
Following bit values can be specified:
● Bit 0 - Use SMS (0) or Call (1) for verification. '0' is the default value
● Bit 1 - Set this phone number as the default caller-id. This is useful when you have multiple verified caller-ids (default is ON).
● Bit 2 - Forced verification. This is useful when you want to force a caller-id verification even if that 'callerid' was already verified earlier.
Sample Request URL
http://api.tringme.com/api.php?op=setcallerid&cookie=1234567890123456789012345678901&message=setcallerid+operation+is+successful with+authenticaion+code+%25TRINGMEAUTHCODE%25&callerid=1234567890&flag=0&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OK
Sample Responses
OK

Verify CallerID

This API is used to verify the caller-id that was being requested to set via ‘setcallerid’ API.

Parameters
op
verifycallerid
cookie
Cookie which was obtained using ‘login’.
code
The verification code that was sent in the SMS or call. The SMS or call was placed in response to ‘setcallerid’ API invocation.
Sample Request URL
http://api.tringme.com/api.php?op=verifycallerid&cookie=1234567890123456789012345678901&code=4kjq1ew5&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OK
Sample Responses
OK

Delete CallerID

This API is used to delete existing caller-id that was being set via ‘setcallerid’ API.

Parameters
op
deletecallerid
cookie
Cookie which was obtained using ‘login’.
callerid
The phone number that should be deleted as the caller-id.
Sample Request URL
http://api.tringme.com/api.php?op=deletecallerid&cookie=1234567890123456789012345678901&callerid=18585551234&apikey=b12345678901234567890123456789012345&sig=f1234567890123456789012345678901
Expected Response
OK
Sample Responses
OK