function
telecoms.num.route
Routes a phone number to a defined destination (eg to another phone number, a route plan, etc).
Arguments:
| arg | required? | syntax | info |
|---|
custID | N | posint | custID of account that owns the number to be re-routed (default is your own account) |
number | Y | posint | number to be re-routed |
routeto_type | Y | enum:nowhere|externally-routed|fax2email|number|routeplan|dayparting|sip|voicemail|ivr | specifies the destination type |
destnumber | conditional | posint | for routeto_type=number, the phone number to route to (no spaces) |
routeplanID | conditional | posint | for routeto_type=routeplan, the routeplanID to route to |
daypartID | conditional | posint | for routeto_type=dayparting, the dayparting ID where to route to |
mailboxID | conditional | posint | for routeto_type=voicemail, the voicemail mailbox ID where to route to |
ivrID | conditional | posint | for routeto_type=ivr, the ID of the IVR menu to route to |
destargs | conditional | array | for routeto_type=sip or routeto_type=fax2email, a sub-array of additional routing parameters |
Further argument information
routeto_type
routeto_type can be one of:
- 'nowhere' - route the number to nowhere; this effectively pauses the number - callers will hear an engaged or number unobtainable tone
- 'number' - to route to another phone number; requires the destnumber argument
- 'routeplan' - to route to a route plan; requires the routeplanID argument
- 'dayparting' - to route to a day parting; requires the daypartID argument
- 'voicemail' - to route directly to voicemail; requires the mailboxID argument. If you do this people will never be able to call you directly,
they'll only be able to leave messages. You would probably prefer to set up a route plan with a destination number as the first item and a
mailbox as the second item (see telecoms.routeplan.create)
- 'fax2email' - if you to send faxes to this number and have the fax emailed to you (default is a PDF file); requires the destargs argument.
- 'sip' - to redirect the number to a SIP destination; requires the destargs argument.
- 'ivr' - to redirect the number to an IVR menu; requires the ivrID argument.
- 'ida' - for making calls back out via our system (useful in conjunction with Call Recording); parameters are set via the
telecoms.facility.attr.set function
by defining attributes in the "ROU.IDA" class on the number. Use the telecoms.facility.attr.type.list function to get a list
of settable attributes.
- 'announcement' - for playing a sound file to a caller and then hanging up. Specify the sound file by using the soundclipID argument (you will need to have
uploaded a sound file using the
telecoms.soundclip.create function and assigned the 'announcement' role to that sound file).
- 'hangup' - causes the call to be immediately ended; optionally takes a Q.931 clear cause in the clear_cause argument use the
telecoms.clear.cause.list function
to get a list of permitted clear causes).
- 'silence' - a routing type of limited use; the call is connected but the caller hears silence. Used in conjuction with call recording and a caller whisper/announcement, this
feature could be used in lieu of voicemail, except that the recording will be downloadable via the API (whereas for voicemail, if the recording is to be emailed then this will
always be sent to the email address configued against the voicemail mailbox). A maximum call duration (in seconds) can optionally be specified in the max_duration argument;
the default is 86400 (24 hours).
- 'externally-routed' - you probably don't want to do this; numbers are only set to this under special arrangement.
destargs
For routeto_type=sip, a sub array consisting of:
- [host] (string, required) - hostname for SIP host
- [port] (integer, optional) - TCP port number (only specify this if you are using a non-standard port number on your SIP host)
- [ext] (string, optional) - SIP extension; if unspecified, the system defaults to the number the caller has dialled
- [ext.pre] (string, optional) - alternative to specifying [ext], specify a prefix string to prepend to the default extension
- [ext.suf] (string, optional) - alternative to specifying [ext], specify a suffix string to append to the default extension
- [auth_user] (string, optional) - if your SIP endpoint requires authentication, put the username here. Requires [auth_pass].
- [auth_pass] (string, required if [auth_user] is set) - your SIP endpoint's authentication password.
- [auth_realm] (string, optional) - specify this if you need to set a specific authentication realm (not usually required).
- [cli_format] (string, optional) - the format of the CLI being presented to the remote SIP endpoint; this can be one of four values:
- uk (default) - number in uk dial format, eg 01511231234 for a UK number, or double leading zero for a non-UK number
- ukhybrid - formats like uk for UK numbers, and like e164 for non-UK numbers
- e164 - e164 format including the leading "+", eg +441511231234
- e164bare - e164 format without the leading "+" eg 441511231234
For routeto_type=fax2email, a sub array consisting of:
- [to_addr] (email, required) - email address where the document should b sent
- [from_addr] (email, optional) - the sending email address; default is fax.noreply@barritel.com (at time of writing)
- [format] (either 'pdf' or 'tiff', optional) - file format, default=pdf
- [paper_size] ('a4','legal' or 'letter', optional) - paper size defined in PDF (if format=pdf); default=a4
Example 1
Route 08001231234 to 01123456789
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.num.route",
"args" : {
"number" : "08001231234",
"destnumber" : "01123456789",
"routeto_type" : "number"
}
}
JSON example response:
{
"results" : {
"eventID" : "548836"
},
"success" : "1"
}
Example 2
Route 08001231234 to a route plan with routeplanID 2433.
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.num.route",
"args" : {
"routeplanID" : 2433,
"number" : "08001231234",
"routeto_type" : "routeplan"
}
}
JSON example response:
{
"success" : "1",
"results" : {
"eventID" : "548838"
}
}
Example 3
Use 08001231234 as a fax number; specify the faxes to emailed as TIFF files to fred@example.com.
Perl example request:
JSON example request:
POST https://live.apicontrol.co.uk/1/json
{
"auth" : {
"username" : "YOURUSERNAME",
"password" : "YOURPASSWORD",
},
"func" : "telecoms.num.route",
"args" : {
"number" : "08001231234",
"destargs" : {
"to_addr" : "fred@example.com",
"format" : "tiff"
},
"routeto_type" : "fax2email"
}
}
JSON example response:
{
"results" : {
"eventID" : "548837"
},
"success" : "1"
}