Telephony, Messaging and Conferencing APIsPlacing 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] 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.
duration [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:Thank you for using XYZ Bank")
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=123456789012345678901 2345678901 &apikey=b12345678901234567890123 456789012345 &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).
private [optional] Create a private user. If this parameter is specified, user will be created in API user's private space. No emails will be sent by TringMe for any private users.
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=b1234567890123456789 0123456789012345 &sig=f1234567890123456789 012345678901
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=b123456789012345678 90123456789012345 &sig=f1234567890123456 789012345678901
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=reactivateuser &email=joe.dirt%40somedomain.com &apikey=b1234567890123456789012345 6789012345 &sig=f123456789012345678901 2345678901
Expected Response
OK along with voicemail information in JSON format
Sample Responses
OKJ
[ {"voicemail":"v1t41234567890 1234567891", "srcphone":"", "recvtime":"45"},
{ "voicemail":"v1t41234567880 2234567892", "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=123456789012345678901 2345678901 &id=v1t412345678901234567891 &apikey=b1234567890123456789012345 6789012345 &sig=f123456789012345678901 2345678901
Expected Response
OK
Sample Responses
OK

Create a Conference

This API is used to schedule a conference call.

Parameters
op createconference
src 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=b12345678901234567890123 456789012345 &sig=f1234567890123456789012 345678901
Expected Response
OK
Sample Responses
OK

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 [optional]

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=1234567890123456789 012345678901 &message=setcallerid+operation+is +successful with+authenticaion+ code+%25TRINGMEAUTHCODE%25 &callerid=1234567890 &flag=0 &apikey=b12345678901234567890123 456789012345 &sig=f1234567890123456789 012345678901
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=12345678901234567 89012345678901 &code=4kjq1ew5
&apikey=b123456789012345 67890123456789012345
&sig=f12345678901234567890 12345678901
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 callerid
Sample Request URL
http://api.tringme.com/api.php? op=deletecallerid
&cookie=123456789012345678901234 5678901
&callerid=18585551234 &apikey=b1234567890123456789012345 6789012345
&sig=f1234567890123456789012 345678901
Expected Response
OK
Sample Responses
OK

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