API : PBX : Set Value Update

Introduction

A Set Value item is a dialplan object that can set and manipulate various properties on a call or on the system. Send e-mail and SMS notifications, and receive input from a caller.

Request

This request will update a set value item. As little as a single property may be provided. The actions array must be provided in whole.

URL	https://api.telecomx.dk/pbx/setvalue/SET_VALUE_ID
Method	POST
Access level	MANAGER or OWNER if user belongs to the customer. RESELLER if customer belongs to the reseller. ADMIN.
	Property	Type	Description
Params	SET_VALUE_ID	Id	Id of the set value item to update.
Body	name	String	Name/description of the set value item.
	number	String	`[optional]` The phone number to dial to reach this set value item locally. Null if not used.
	startAudio	Id	`[optional]` A sound item to playback when the set value item is entered.
	redirect	String	`[optional]` Number to redirect to when execution starts. Used to quickly circumvent the set value item. Null if not used.
	notes	String	Notes about the set value item.
	inputMode	Boolean	True if this requires the caller to enter digits. Input entered by the caller, is stored in a CALL_VARIABLE named input, and can also be stored elsewhere in actions.
	inputLength	Number	Number of digits to receive from the caller, 1-50 (input mode only).
	inputRepeat	Number	Number of times to repeat the input process before giving up. Default 0 (no repeat), can be 0-10.
	timeout	Number	Number of seconds to wait for input, 1-30 (input mode only).
	timeoutAudio	Id	Id of sound item to playback when input timeout occurs (input mode only).
	timeoutGoto	Id	Id of dialplan item to goto on timeout (input mode only).
	goto	Id	Id of dialplan item to go to when done.
	actions	Array	Array of actions to perform - see definition below.
	actions[].type	String	Type of item to perform action on.
	actions[].target	String	Target for types that requires it.
	actions[].targetType	String	Type of target: SYSTEM, SHARED, PERSONAL (only used by action types VARIABLE and SWITCH).
	actions[].targetId	String	Id of employee the target points to (only used by action types VARIABLE and SWITCH when targetType is PERSONAL.
	actions[].how	String	How to affect the target of the action.
	actions[].value	String	Value to use.

Action object
Type	Description	Target	How	Value
CALL_VARIABLE	A variable that only exists with the call	Name of the variable a-z A-Z 0-9 _ and -	EQUALS	Text or number to set variable to.
			EQUALS_INPUT	n/a - sets to caller entered digits.
			PREFIX	String to prefix variable with.
			POSTFIX	String to postfix variable with.
			ADD	Number to add to variable.
			SUBTRACT	Number to subtract from variable.
			DELETE	n/a - variable is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the variable.
			CUT_POST	Number of characters to remove from the end of the variable.
VARIABLE	A persistent system variable	Name of the variable a-z A-Z 0-9 _ and -	EQUALS	Text or number to set variable to.
			EQUALS_INPUT	n/a - sets to caller entered digits.
			PREFIX	String to prefix variable with.
			POSTFIX	String to postfix variable with.
			ADD	Number to add to variable.
			SUBTRACT	Number to subtract from variable.
			DELETE	n/a - variable is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the variable.
			CUT_POST	Number of characters to remove from the end of the variable.
SWITCH	A persistent switch that can be on or off	Name of the switch a-z A-Z 0-9 _ and -	EQUALS	true, false, 1, 0, yes, no.
SWITCH	A persistent switch that can be on or off	Name of the switch a-z A-Z 0-9 _ and -	EQUALS_INPUT	n/a - set to caller entered digits 1 or 0.
A_NUMBER	The callers phone number		EQUALS	Phone number to set.
			EQUALS_INPUT	n/a - sets to caller entered number.
			PREFIX	Number to prefix with.
			POSTFIX	Number to postfix with.
			DELETE	n/a - Number is deleted/made secret.
			CUT_PRE	Number of digits to remove from the beginning of the phone number.
			CUT_POST	Number of digits to remove from the end of the phone number.
A_NAME	The callers name		EQUALS	String to set name to.
			PREFIX	String to prefix the name with.
			POSTFIX	String to postfix the name with.
			DELETE	n/a - name is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the name.
			CUT_POST	Number of characters to remove from the end of the name.
B_NUMBER	The called phone number		EQUALS	Phone number to set.
			EQUALS_INPUT	n/a - sets to caller entered number.
			PREFIX	Number to prefix with.
			POSTFIX	Number to postfix with.
			DELETE	n/a - Number is deleted/made secret.
			CUT_PRE	Number of digits to remove from the beginning of the phone number.
			CUT_POST	Number of digits to remove from the end of the phone number.
CDR_NOTE	A note stored with the CDR for the call		EQUALS	Text or number to set the note to.
			EQUALS_INPUT	n/a - sets to caller entered digits.
			PREFIX	String to prefix the note with.
			POSTFIX	String to postfix the note with.
			ADD	Number to add to the note.
			SUBTRACT	Number to subtract from the note.
			DELETE	n/a - note is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the note.
			CUT_POST	Number of characters to remove from the end of the note.
LANGUAGE	The language to use on the call		EQUALS	Langauge to use: da or en.
MUSIC_ON_HOLD	Set the music on hold class to use		EQUALS	Id of the music on hold class to use.
PRESENCE_STATE	Set the presence state of an employee	Id of employee	EQUALS	The state to set: AVAILABLE, BUSY, OUT_OF_OFFICE, OFF_WORK, HOLIDAY.
PRESENCE_LOCATION	The presence location for an employee	Id of employee	EQUALS	Text to set.
			PREFIX	String to prefix location with.
			POSTFIX	String to postfix location with.
			DELETE	n/a - location is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the location.
			CUT_POST	Number of characters to remove from the end of the location.
PRESENCE_MESSAGE	The presence message for an employee	Id of employee	EQUALS	Text to set.
			PREFIX	String to prefix message with.
			POSTFIX	String to postfix message with.
			DELETE	n/a - message is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the message.
			CUT_POST	Number of characters to remove from the end of the message.
PRESENCE_EXPIRES	Set or remove expiration on an employee's presence	Id of employee	EQUALS	When the presence shall expire: IN_5 - in 5 minutes IN_10 - in 10 minutes IN_15 - in 15 minutes IN_30 - in 30 minutes IN_60 - in 1 hour IN_90 - in 1.5 hour IN_120 - in 2 hours IN_180 - in 3 hours IN_240 - in 4 hours ON_THE_HOUR - at the next whole hour END_OF_DAY - at midnight TOMORROW_AT_8 - tomorrow at 08:00 END_OF_WEEK - at the end of the week END_OF_MONTH - at the end of the month.
PRESENCE_EXPIRES	Set or remove expiration on an employee's presence	Id of employee	DELETE	n/a - removes the expiration.
REDIRECT	Control redirection of dialplan items	Id of dialplan item	EQUALS	Number to redirect to.
REDIRECT	Control redirection of dialplan items	Id of dialplan item	DELETE	n/a - removes the redirect.
RECORD	Control if call is recorded		EQUALS	true or false.
EMAIL	Send an e-mail	Recipient e-mail address	EQUALS	Body of e-mail, max. 256 chars.
SMS	Send an SMS	Recipient phone number	EQUALS	SMS message, max. 256 chars.
RINGTONE	Set alternative ringtone to use on supported SIP phones		EQUALS	Ringtone 0-9.
RINGTONE	Set alternative ringtone to use on supported SIP phones		DELETE	n/a - removes alternative ringtone.

Request body example

  startAudio: '12345678901234567890CCCC',
  inputRepeat: 1
  timeout: 15
}

Response

JSON object
Property	Type	Description
_id	Id	Unique id of the set value item.
type	String	Always 'SET_VALUE'.
customer	Id	Id of the customer the set value item belongs to.
name	String	Name/description of the set value item.
number	String	The phone number to dial to reach this set value item locally, null if it is not dial-able.
startAudio	Id	A sound item to playback when the set value item is entered, null if not used.
redirect	String	Number to redirect to when execution starts. Used to quickly circumvent the set value item.
notes	String	Notes about the set value item.
inputMode	Boolean	True if this requires the caller to enter digits. Input entered by the caller, is stored in a CALL_VARIABLE named input, and can also be stored elsewhere in actions.
inputLength	Number	Number of digits to receive from the caller, 1-50 (input mode only).
inputRepeat	Number	Number of times to repeat the input process before giving up. Default 0 (no repeat), can be 0-10.
timeout	Number	Number of seconds to wait for input, 1-30 (input mode only).
timeoutAudio	Id	Id of sound item to playback when input timeout occurs (input mode only).
timeoutGoto	Id	Id of dialplan item to goto on timeout (input mode only).
goto	Id	Id of dialplan item to go to when done.
actions	Array	Array of actions to perform - see definition below.
actions[].type	String	Type of item to perform action on.
actions[].target	String	Target for types that requires it.
actions[].how	String	How to affect the target of the action.
actions[].value	String	Value to use.

Action object
Type	Description	Target	How	Value
CALL_VARIABLE	A variable that only exists with the call	Name of the variable a-z A-Z 0-9 _ and -	EQUALS	Text or number to set variable to.
			EQUALS_INPUT	n/a - sets to caller entered digits.
			PREFIX	String to prefix variable with.
			POSTFIX	String to postfix variable with.
			ADD	Number to add to variable.
			SUBTRACT	Number to subtract from variable.
			DELETE	n/a - variable is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the variable.
			CUT_POST	Number of characters to remove from the end of the variable.
VARIABLE	A persistent system variable	Name of the variable a-z A-Z 0-9 _ and -	EQUALS	Text or number to set variable to.
			EQUALS_INPUT	n/a - sets to caller entered digits.
			PREFIX	String to prefix variable with.
			POSTFIX	String to postfix variable with.
			ADD	Number to add to variable.
			SUBTRACT	Number to subtract from variable.
			DELETE	n/a - variable is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the variable.
			CUT_POST	Number of characters to remove from the end of the variable.
SWITCH	A persistent switch that can be on or off	Name of the switch a-z A-Z 0-9 _ and -	EQUALS	true, false, 1, 0, yes, no.
SWITCH	A persistent switch that can be on or off	Name of the switch a-z A-Z 0-9 _ and -	EQUALS_INPUT	n/a - set to caller entered digits 1 or 0.
A_NUMBER	The callers phone number		EQUALS	Phone number to set.
			EQUALS_INPUT	n/a - sets to caller entered number.
			PREFIX	Number to prefix with.
			POSTFIX	Number to postfix with.
			DELETE	n/a - Number is deleted/made secret.
			CUT_PRE	Number of digits to remove from the beginning of the phone number.
			CUT_POST	Number of digits to remove from the end of the phone number.
A_NAME	The callers name		EQUALS	String to set name to.
			PREFIX	String to prefix the name with.
			POSTFIX	String to postfix the name with.
			DELETE	n/a - name is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the name.
			CUT_POST	Number of characters to remove from the end of the name.
B_NUMBER	The called phone number		EQUALS	Phone number to set.
			EQUALS_INPUT	n/a - sets to caller entered number.
			PREFIX	Number to prefix with.
			POSTFIX	Number to postfix with.
			DELETE	n/a - Number is deleted/made secret.
			CUT_PRE	Number of digits to remove from the beginning of the phone number.
			CUT_POST	Number of digits to remove from the end of the phone number.
CDR_NOTE	A note stored with the CDR for the call		EQUALS	Text or number to set the note to.
			EQUALS_INPUT	n/a - sets to caller entered digits.
			PREFIX	String to prefix the note with.
			POSTFIX	String to postfix the note with.
			ADD	Number to add to the note.
			SUBTRACT	Number to subtract from the note.
			DELETE	n/a - note is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the note.
			CUT_POST	Number of characters to remove from the end of the note.
LANGUAGE	The language to use on the call		EQUALS	Langauge to use: da or en.
MUSIC_ON_HOLD	Set the music on hold class to use		EQUALS	Id of the music on hold class to use.
PRESENCE_STATE	Set the presence state of an employee	Id of employee	EQUALS	The state to set: AVAILABLE, BUSY, OUT_OF_OFFICE, OFF_WORK, HOLIDAY.
PRESENCE_LOCATION	The presence location for an employee	Id of employee	EQUALS	Text to set.
			PREFIX	String to prefix location with.
			POSTFIX	String to postfix location with.
			DELETE	n/a - location is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the location.
			CUT_POST	Number of characters to remove from the end of the location.
PRESENCE_MESSAGE	The presence message for an employee	Id of employee	EQUALS	Text to set.
			PREFIX	String to prefix message with.
			POSTFIX	String to postfix message with.
			DELETE	n/a - message is deleted.
			CUT_PRE	Number of characters to remove from the beginning of the message.
			CUT_POST	Number of characters to remove from the end of the message.
PRESENCE_EXPIRES	Set or remove expiration on an employee's presence	Id of employee	EQUALS	When the presence shall expire: IN_5 - in 5 minutes IN_10 - in 10 minutes IN_15 - in 15 minutes IN_30 - in 30 minutes IN_60 - in 1 hour IN_90 - in 1.5 hour IN_120 - in 2 hours IN_180 - in 3 hours IN_240 - in 4 hours ON_THE_HOUR - at the next whole hour END_OF_DAY - at midnight TOMORROW_AT_8 - tomorrow at 08:00 END_OF_WEEK - at the end of the week END_OF_MONTH - at the end of the month.
PRESENCE_EXPIRES	Set or remove expiration on an employee's presence	Id of employee	DELETE	n/a - removes the expiration.
REDIRECT	Control redirection of dialplan items	Id of dialplan item	EQUALS	Number to redirect to.
REDIRECT	Control redirection of dialplan items	Id of dialplan item	DELETE	n/a - removes the redirect.
RECORD	Control if call is recorded		EQUALS	true or false.
EMAIL	Send an e-mail	Recipient e-mail address	EQUALS	Body of e-mail, max. 256 chars.
SMS	Send an SMS	Recipient phone number	EQUALS	SMS message, max. 256 chars.
RINGTONE	Set alternative ringtone to use on supported SIP phones		EQUALS	Ringtone 0-9.
RINGTONE	Set alternative ringtone to use on supported SIP phones		DELETE	n/a - removes alternative ringtone.

If expandAction is true, the follow is added:

actions[].targetName	String	Name of the target (only for action type PRESENSE_STATE, PRESENCE_LOCATION, PRESENCE_MESSAGE, PRESENCE_EXPIRES and REDIRECT).
actions[].valueName	String	Name of the music on hold class (only for action MUSIC_ON_HOLD and how EQUALS).

Example

{
  _id: '12345678901234567890ABCD',
  type: 'SET_VALUE',
  customer: '12345678901234567890BCED',
  name: 'Get customer number',
  number: '830',
  startAudio: '12345678901234567890CCCC',
  redirect: null,
  notes: 'Get the customer number from the caller',
  inputMode: true,
  inputLength: 10,
  inputRepeat: 1,
  timeout: 15,
  timeoutAudio: '12345678901234567890BBBB',
  actions: [
    {
      type: 'CALL_VARIABLE',
      target: 'customer-number',
      how: 'EQUALS_INPUT'
    },
    {
      type: 'CDR_NOTE',
      how: 'EQUALS_INPUT'
    },
    {
      type: 'CDR_NOTE',
      how: 'PREFIX',
      value: 'customer='
  ]
}

Errors

Error code	Message	Description
404	customer	Customer not found or not active
404	not_found	Set value not found
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	Audio file not found
404	goto	Dialplan item not found
404	timeoutGoto	Dialplan item not found
404	timeoutAudio	Audio file not found
422	actions[x].type	Missing or invalid
422	actions[x].target	Missing or invalid
422	actions[x].how	Missing or invalid
422	actions[x].value	Missing or too long
422	actions[x].value	Missing or not a number
404	actions[x].value	Music on hold class not found
404	actions[x].target	Employee not found
404	actions[x].target	Dialplan item not found
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents