Channels APIs

So far we have used cookie and destination combination to make the calls. Channel offers finer control over call destinations. In a way, you can perceive a channel as restricted version of cookie having defined rules on what is allowed over channel. For example, a channel could allow to call worldwide, or it could be restricted to call a particular destination or a set of destinations only. In other words, voice channel defines the complete configuration for the destination leg.

Channels are ideally suited for applications with recurrently tasks (say bulk calls or conferencing) or where you cannot expose the cookie (say, Flash Push & Talk applications). In such cases, you can define channel with fixed destination and use where you have used cookie earlier (e.g. call or Flash API).

Channel allows developer to control some aspects of the destination that will be connected – type of device, duration of the call and so on. Most importantly, developer may want to set these channels and re-use them from thereon without. Channels make it easy for one to create destination specific configuration and there onwards refer to them using just a single identifier. There are two key parts to using Voice Channels.

  • 1. Channel Creation – This will show you how to create a channel, what are the available options and the capabilities that a channel offers.
  • 2. Using Channels – This will show you how a channel can be used instead of cookie.

Before we plunge into the details of creating channels, let’s understand some key concepts of channels:

  • Channels are associated with a user. It can be associated with API owner or the user whose cookie is passed during the channel creation.
  • Channels can specify duration, validity or usage to control the ‘expiry’ of the channel. Please refer to the ‘setchannel’ API for precise list of parameters.
  • Channels can be created, modified or deleted.

Since channels control how the call is ‘routed’ to the destination, refer to the destination section. Once the channel is created, it is available till it expires or is deleted. Expiration can happen when duration, validity or uses expires. It is recommended that developers delete a channel explicitly if they don’t need it anymore. TringMe will send notification when any channel is deleted due to usage.

Note: Channel can be used exactly same as cookie in REST telephony API, or in Flash API. Here are the basic channel related APIs in REST


Create or Modify a Channel

This API creates a channel. Several parameters can be specified to define the behavior of the channel.

Parameters
op setchannel
cookie [optional] Cookie which was obtained using ‘login’.
channel [optional] Channel. If a channel is specified, then that channel is modified. If none is specified, then a new channel is created.
dest [optional] Destination for this channel. For Phone and SIP types of destination, wildcards can be specified.
  • When wildcards are specified in Phone, only phone numbers which match the criteria would be allowed to go through this channel. *, ? should be used for wildcards.
  • In SIP, wildcard can be specified as well.
  • sip:@mysipserver.com - to call all supported users/numbers at mysipserver.com SIP.
  • sip: <sip-id> - to call any number using the sip-id.
duration [optional] Call duration after which the call should automatically disconnect. The duration is the time from the moment call is answered till the time when the call disconnects
validity [optional] Validity of this channel in seconds.
maxusage [optional] Maximum number of call attempts.
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 16 characters
dtmf [optional] DTMF that should be sent on this channel.
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)
Sample Request URL
http://api.tringme.com/api.php ?op=setchannel &cookie=1234567890123456789 012345678901 &dest=gtalk%3Ajoe.dirt%40gmail.com &apikey=b12345678901234567 890123456789012345 &sig=f1234567890123456789 012345678901
Expected Response
'OK <channel> <channelcount>'. The <channel> is the identifier that can be used in APIs which require channel as an input. The <channelcount> is the current count of the valid channels of this api key
Sample Responses
OK
OK 2b4567a90123f567890c2345d789011 2

Get Channel Information

This API retrieves channel information being requested. Returns the validity of the channel in seconds.

Parameters
op getchannel
channel Channel whose information is being requested.
Sample Request URL
http://api.tringme.com/api.php?op=getchannel &channel=2b4567a90123f56 7890c2345d789011 &apikey=b1234567890123456 7890123456789012345 &sig=f12345678901234567890 12345678901
Expected Response
'OK <validity>'.
Sample Responses
OK 86400

Delete Channel

This API Delete the specified channel .

Parameters
op deletechannel
channel Channel to be deleted.
Sample Request URL
http://api.tringme.com/api.php ?op=deletechannel &channel=2b4567a90123f567890 c2345d789011 &apikey=b1234567890123456789 0123456789012345 &sig=f123456789012345 6789012345678901
Expected Response
OK
Sample Responses
OK

Accessing Channels using SIP

Channel can also be accessed by outside world using SIP. Each channel has it’s own unique SIP address – [channel]@sip.tringme.com which is accessible from any SIP capable device or phone in the world. This allows you to create your own phone service, IVR or conference service and accessible using SIP.

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