API : PBX : URL Router Create

Introduction

A URL Router is a dialplan object that make a request to a URL with a number of arguments and based on the response routes the call.

Request

This request will create a URL router. All properties are optional except for customer and name.

URL	https://api.telecomx.dk/pbx/urlrouter
Method	POST
Access level	MANAGER or OWNER if user belongs to the customer. RESELLER if customer belongs to the reseller. ADMIN.
Body	customer	Id	Id of the customer the URL router belongs to.
	name	String	Name/description of the URL router.
	number	String	The phone number to dial to reach this URL router locally, null if it is not dial-able.
	startAudio	Id	A sound item to playback when the URL router is entered, null if not used.
	redirect	String	Number to redirect to when execution starts. Used to quickly circumvent the URL router item.
	notes	String	Notes about the URL router item.
	request	Object	Request settings
	request.url	String	URL to call.
	request.method	String	The method to use for the request: GET, POST or POST_JSON which is like post, but with a JSON body.
	request.data	String	This is the data to send. The body of the request if the method is not GET, otherwise query key/values added to the URL.
			GET example: caller=%A_NUMBER%&duration=%CALL_DURATION%.
			POST example: caller=%A_NUMBER%&duration=%CALL_DURATION%.
			POST_JSON example: { “caller”: “%A_NUMBER%”, “duration”: “%CALL_DURATION%” }.
	request.timeout	Number	Number of seconds to wait for a response before giving up. 0-10 seconds.
	response	Object	Response settings
	response.action	String	The action to perform with the response from the request:
			DIAL	the response is a phone number to dial.
			COMPARE	the response is compared against another value.
			CALL_VARIABLE	the response is stored in a variable that only exists with the call.
			CALL_VARIABLE_JSON	the response is stored in a variable that only exists with the call as an object.
			VARIABLE	the response is stored in a PBX wide persistent variable.
			JSON	the response is a JSON array or objects with type, target (if needed) and value that can set multiple variables and settings - see JSON response below.
	response.target	String	Depending on the response.action:
			COMPARE	either CALL_VARIABLE or VARIABLE to compare against the value stored in the variable, or VALUE to compare against the value in response.value.
			This is not used for DIAL, JSON, CALL_VARIABLE, CALL_VARIABLE_JSON and VARIABLE actions.
	response.value	String	When action is COMPARE:
			response.target = CALL_VARIABLE	this is the name of the call variable to compare against.
			response.target = VARIABLE	this is the name of the PBX wide variable to compare against.
			response.target = VALUE	this is the value to compare against.
			When action is CALL_VARIABLE, CALL_VARIABLE_JSON or VARIABLE this is the name of the variable to store the response into.
	response.comparison	String	When response.action is COMPARE this controls how the comparison is performed: EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, STARTS_WITH, ENDS_WITH, CONTAINS, LENGTH, RX.
	onMatchGoto	Id	Dialplan item to goto when response.action is COMPARE and the result is positive.
	whenDoneGoto	Id	Dialplan item to goto when the URL router has completed its work or if the response.action is COMPARE and the result was negative.
	onTimeoutGoto	Id	Dialplan item to goto if the URL request times out, if not set whenDoneGoto is used instead.

Request data variables

The request.data property supports the following variables, which must be enclosed like this: %A_NUMBER%.

Variable	Description
A_NUMBER	The phone number of the calling part in E.164 format, unless it's a local caller.
A_NAME	The name of the calling part, if available.
B_NUMBER	The phone number called in E.164 format, unless it's a local destination.
B_NAME	The name of the called part, if available.
CALL_DURATION	The current duration of the call in seconds.
CALL_VARIABLE:<name>	The value of a call variable called <name>.
VARIABLE:<name>	The value of a system variable called <name>.
SWITCH:<name>	The value of a system switch called <name>.
GUID	Auto generated guid.

Repsonse action JSON

If the response.action is JSON, the result from the request must be a JSON array of objects with type, target (if applicable) and value. This can be used to set multiple variables and configuration parameters as a result.

Field	Type	Description
type	String	Type of item to set value of:
		CALL_VARIABLE	a variable that only exists with the call
		VARIABLE	a PBX wide persistent variable
		SWITCH	an on/off switch
		A_NUMBER	the callers number
		A_NAME	the callers name
		B_NUMBER	the called number
		CDR_NOTE	a note stored with the CDR for the call
		LANGUAGE	the language to use
		MUSIC_ON_HOLD	the music on hold to use
		PRESENCE_STATE	employee presence status
		PRESENCE_LOCATION	employee presence location
		PRESENCE_MESSAGE	employee presence message
		PRESENCE_EXPIRES	employee presence expires
		REDIRECT	set redirect for a PbxDialplans item
		RECORD	set recording state on/off for this call
		EMAIL	send an e-mail
		SMS	send an sms
target	String	Some types requires a target:
		CALL_VARIABLE VARIABLE SWITCH	name of the item.
		PRESENCE_STATE PRESENCE_LOCATION PRESENCE_MESSAGE PRESENCE_EXPIRES	id of the employee to set presence on.
		EMAIL	Recipient e-mail address.
		SMS	Recipient mobile phone number.
		REDIRECT	id PbxDialplan item to set.
		For all other types this field is not used.
value	String	Value to assign:
		SWITCH RECORD	a boolean value (true/false).
		A_NUMBER B_NUMBER REDIRECT	+ a phone number (+ and digits).
		LANGUAGE	da or en.
		MUSIC_ON_HOLD	Id of music on hold category.
		PRESENCE_STATE	one of AVAILABLE, BUSY, OUT_OF_OFFICE, OFF_WORK, HOLIDAY.
		PRESENCE_EXPIRES	a Date.
		For all other it is a text string.

Request body example

{
  customer: '123457890123457890ADEF',
  name: 'Lookup on-duty supporter',
  number: '823',
  startAudio: null,
  redirect: null,
  notes: 'Get the phone number of the on duty supporter for 24H service',
  request: {
    url: 'https://som.server.com/api/support.aspx',
    method: 'GET',
    data: 'number=%A_NUMBER%'
  },
  response: {
    action: 'CALL_VARIABLE',
    target: null,
    value: 'ON_DUTY_NUMBER',
    comparison: null
  },
  onMatchGoto: '12345678901234567890AAAA',
  whenDoneGoto: '1234567890123457890BBBB',
  onTimeoutGoto: '1234567890123457890CCCC'
}

Response

request	Object	Request settings
JSON object
_id	Id	Unique id of the URL router.
type	String	Always 'URL_ROUTER'.
customer	Id	Id of the customer the URL router belongs to.
name	String	Name/description of the URL router.
number	String	The phone number to dial to reach this URL router locally, null if it is not dial-able.
startAudio	Id	A sound item to playback when the URL router is entered, null if not used.
redirect	String	Number to redirect to when execution starts. Used to quickly circumvent the URL router item.
notes	String	Notes about the URL router item.
request.url	String	URL to call.
request.method	String	The method to use for the request: GET, POST or POST_JSON which is like post, but with a JSON body.
request.data	String	This is the data to send. The body of the request if the method is not GET, otherwise query key/values added to the URL.
		GET example: caller=%A_NUMBER%&duration=%CALL_DURATION%.
		POST example: caller=%A_NUMBER%&duration=%CALL_DURATION%.
		POST_JSON example: { “caller”: “%A_NUMBER%”, “duration”: “%CALL_DURATION%” }.
request.timeout	Number	Number of seconds to wait for a response before giving up. 0-10 seconds.
response	Object	Response settings
response.action	String	The action to perform with the response from the request:
		DIAL	the response is a phone number to dial.
		COMPARE	the response is compared against another value.
		CALL_VARIABLE	the response is stored in a variable that only exists with the call.
		CALL_VARIABLE_JSON	the response is stored in a variable that only exists with the call as an object.
		VARIABLE	the response is stored in a PBX wide persistent variable.
		JSON	the response is a JSON array or objects with type, target (if needed) and value that can set multiple variables and settings - see JSON response below.
response.target	String	Depending on the response.action:
		COMPARE	either CALL_VARIABLE or VARIABLE to compare against the value stored in the variable, or VALUE to compare against the value in response.value.
		This is not used for DIAL, JSON, CALL_VARIABLE, CALL_VARIABLE_JSON and VARIABLE actions.
response.value	String	When action is COMPARE:
		response.target = CALL_VARIABLE	this is the name of the call variable to compare against.
		response.target = VARIABLE	this is the name of the PBX wide variable to compare against.
		response.target = VALUE	this is the value to compare against.
		When action is CALL_VARIABLE, CALL_VARIABLE_JSON or VARIABLE this is the name of the variable to store the response into.
response.comparison	String	When response.action is COMPARE this controls how the comparison is performed: EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, STARTS_WITH, ENDS_WITH, CONTAINS, LENGTH, RX.
onMatchGoto	Id	Dialplan item to goto when response.action is COMPARE and the result is positive.
whenDoneGoto	Id	Dialplan item to goto when the URL router has completed its work or if the response.action is COMPARE and the result was negative.
onTimeoutGoto	Id	Dialplan item to goto if the URL request times out, if not set whenDoneGoto is used instead.

Example

{
  _id: '12345678901234567890ABCD',
  type: 'URL_ROUTER',
  customer: '1234567890123457890BCED',
  name: 'Lookup on-duty supporter',
  number: '823',
  startAudio: null,
  redirect: null,
  notes: 'Get the phone number of the on duty supporter for 24H service',
  request: {
    url: 'https://som.server.com/api/support.aspx',
    method: 'GET',
    data: 'number=%A_NUMBER%'
  },
  response: {
    action: 'CALL_VARIABLE',
    target: null,
    value: 'ON_DUTY_NUMBER',
    comparison: null
  },
  onMatchGoto: '12345678901234567890AAAA',
  whenDoneGoto: '1234567890123457890BBBB',
  onTimeoutGoto: '1234567890123457890CCCC'
}

Errors

Error code	Message	Description
404	customer	Customer not found or not active
422	name	Name must be at least 3 characters
409	number	Number is in use by another dialplan item
422	number	Number is invalid, only 0-9 is allowed and no public service numbers
422	redirect	Redirect number is invalid, only + 0-9, # and * is allowed
404	redirect	Redirect number is local but does not point to an existing dialplan item
404	startAudio	Start audio file not found
404	onMatchGoto	Dialplan item not found
404	whenDoneGoto	Dialplan item not found
404	onTimeoutGoto	Dialplan item not found
422	request.url	Not a valid URL
409	request.method	Value is not one of the permitted values.
422	request.data	Invalid JSON
422	request.data	Uneven number of % chars
422	request.data	Variable named X is not a valid variable
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents