API : PBX : Playback Update

Introduction

A Playback is a dialplan object that plays back audio files or speaks a composed text that may consist of a mix of texts and variables to be spoken.

Request

This request will update a playback. As little as a single property may be provided.

URL	https://api.telecomx.dk/pbx/playback/PLAYBACK_ID
Method	POST
Access level	MANAGER or OWNER if user belongs to the customer. RESELLER if customer belongs to the reseller. ADMIN.
Params	PLAYBACK_ID	Id	Id of playback item to update.
Body	name	String	Name/description of the playback.
	number	String	`[optional]` The phone number to dial to reach this playback item locally. Null if not used.
	startAudio	Id	`[optional]` A sound item to playback when the playback is entered.
	redirect	String	`[optional]` Number to redirect to when execution starts. Used to quickly circumvent the playback. Null if not used.
	notes	String	Notes about the playback.
	speak	Object	Speak settings
	speak.message	String	The message to perform text-to-speech on, including variables.
	speak.engine	String	`[Optional]` Which TTS engine to use: ELEVEN_TURBO, ELEVEN_FLASH, ELEVEN_ML, ELEVEN_V3. Defaults to ELEVEN_FLASH.
	speak.language	String	`[Optional]` Optional language of the message. ISO 639-1 format. If not set, it is inferred from the voice.
	speak.voice	String	The voice to speak with.
	speak.speed	Number	`[Optional]` Speaking speed, optional, default to 100, range 70-120 (fastest).
	speak.stability	Number	`[Optional]` Stability, default 50, min 0, max 100.
	goto	ObjectID	The PbxDialplans item to goto when done.

Request body example

  number: '700',
  goto: '1234567890123457890AABB'
}

Speak message formatting

Speak will use the given voice and speed to speak the message, if a message is given. A number of variables can be injected into the message using the format: <TYPE ARGUMENT FORMATTING>.

Type, argument and formatting is case-insensitive. Format is optional, and argument is only used if the type supports it.

Examples:

det koster {VARIABLE beloeb MONEY} at benytte denne service.

Døren er {SWITCH door OPEN_CLOSED}.

Alarmen er {SWITCH alarmstate ENABLED_DISABLED}.

Klokken er nu {DATE_NOW TIME} og kontoret er lukket indtil imorgen.

Der er i øjeblikket {QUEUE_CALLERS_COUNT 1234567890123457890ABCD} i kø foran dig.

Optagelse af dette kald er {RECORD ENABLED_DISABLED}.

{PRESENCE_COMBO 1234567890123457890ABCD}.

Speak message variables - types & arguments

Type	Argument	Formatting	Description
Call variables
CALL_VARIABLE	Name of variable	STRING	Speak a call variable as a string (default). Example: Amagerbrogade 23.
CALL_VARIABLE	Name of variable	NUMBER	Speak a call variable as a number. Example: tre og halvfjerds.
CALL_VARIABLE	Name of variable	PHONENUMBER	Speak a call variable as a phone number. Example: 71 91 99 99.
CALL_VARIABLE	Name of variable	DATETIME	Speak a call variable as a date and time. Example: Mandag den 23. september 2018 klokken tolv tre og tyve.
CALL_VARIABLE	Name of variable	DATE	Speak a call variable as a date. Example: Mandag den 23. september 2018.
CALL_VARIABLE	Name of variable	TIME	Speak a call variable as a time. Example: Fjorten tre og tyve.
CALL_VARIABLE	Name of variable	MONEY	Speak a call variable as money. Example: To hundrede og tre og fyrre komma fem og tyve..
System variables
VARIABLE	Name of variable	STRING	Speak a system variable as a string (default). Example: Amagerbrogade 23.
VARIABLE	Name of variable	NUMBER	Speak a system variable as a number. Example: tre og halvfjerds.
VARIABLE	Name of variable	PHONENUMBER	Speak a system variable as a phone number. Example: 71 91 99 99.
VARIABLE	Name of variable	DATETIME	Speak a system variable as a date and time. Example: Mandag den 23. september 2018 klokken tolv tre og tyve.
VARIABLE	Name of variable	DATE	Speak a system variable as a date. Example: Mandag den 23. september 2018.
VARIABLE	Name of variable	TIME	Speak a system variable as a time. Example: Fjorten tre og tyve.
VARIABLE	Name of variable	MONEY	Speak a system variable as money. Example: To hundrede og tre og fyrre komma fem og tyve..
Switches
SWITCH	Name of switch	ON_OFF	Speak the state of a system switch (default). Example: Tændt or Slukket.
SWITCH	Name of switch	ACTIVE_DISABLED	Speak the state of a system switch. Example: Aktiveret or ikke aktiveret.
SWITCH	Name of switch	OPEN_CLOSED	Speak the state of a system switch. Example: Åben or Lukket.
SWITCH	Name of switch	YES_NO	Speak the state of a system switch. Example: Ja or Nej.
Caller and callee
A_NUMBER	n/a	n/a	Speaks the callers number.
A_NAME	n/a	n/a	speaks the callers name (if available).
B_NUMBER	n/a	n/a	Speaks the called number.
B_NAME	n/a	n/a	Speaks the called name (if available).
CDR_NOTE	n/a	n/a	Speaks the note stored with the CDR for the call.
DIVERSION_NUMBER	n/a	n/a	Speaks the number that diverted this call, if it was diverted.
Queue stats
QUEUE_MEMBERS_COUNT	Id of queue	n/a	The number of members who answers calls for the queue. Example: 10.
QUEUE_MEMBERS_AVAILABLE	Id of queue	n/a	The number of members who are not busy. Example: 2.
QUEUE_CALLERS_COUNT	Id of queue	n/a	The number of callers in the queue. Example: 6.
QUEUE_CALLERS_MAX_WAIT	Id of queue	n/a	The time the first in the queue has currently waited. Example: 4 minutter.
Presence
PRESENCE_NAME	Id of employee	n/a	Name of the employee.
PRESENCE_STATE	Id of employee	n/a	The current presence state of the employee.
PRESENCE_LOCATION	Id of employee	n/a	The current presence location of the employee.
PRESENCE_MESSAGE	Id of employee	n/a	The current presence message of the employee.
PRESENCE_EXPIRES	Id of employee	n/a	The current presence expires date for the employee.
PRESENCE_COMBO	Id of employee	n/a	A combined presence of the employee. Example: Donald Ducks location is “in car”, and is busy until 14:30.
Recording state
RECORD	n/a	IS_RECORDING	If call is recorded, speaks: “this call is being recorded”, otherwise nothing. (default).
		YES_NO	Speaks recording state: “Yes” or “No”
		ENABLED_DISABLED	Speaks recording state: “Enabled” or “Disabled”.
Date and time
DATE_NOW	n/a	DATETIME	The current date and time (default).
		DATE	The current date.
		TIME	The current time (hours and minutes).
		YEAR	The current year.
		MONTH	The current month.
		DAY	The current day.
		HOUR	The current hour.
		MINUTE	The current minute.
		SECOND	The current second.

Response

JSON object
_id	Id	Unique id of the playback item.
type	String	Always 'PLAYBACK'.
customer	Id	Id of the customer the playback belongs to.
name	String	Name/description of the playback item.
number	String	The phone number to dial to reach this playback item locally, null if it is not dial-able.
startAudio	Id	A sound item to playback when the playback item is entered, null if not used.
redirect	String	Number to redirect to when execution starts. Used to quickly circumvent the playback item.
notes	String	Notes about the playback item.
speak	Object	Speak settings
speak.message	String	The message to perform text-to-speech on, including variables.
speak.engine	String	`[Optional]` Which TTS engine to use: ELEVEN_TURBO, ELEVEN_FLASH, ELEVEN_ML, ELEVEN_V3. Defaults to ELEVEN_FLASH.
speak.language	String	`[Optional]` Optional language of the message. ISO 639-1 format. If not set, it is inferred from the voice.
speak.voice	String	The voice to speak with.
speak.speed	Number	`[Optional]` Speaking speed, optional, default to 100, range 70-120 (fastest).
speak.stability	Number	`[Optional]` Stability, default 50, min 0, max 100.
goto	Id	The PbxDialplans item to goto when done.

Example

{
  _id: '12345678901234567890ABCD',
  name: 'VIP Welcome',
  number: '700',
  startAudio: null,
  redirect: null,
  notes: 'Welcome message for VIP customers',
  speak: {
    message: 'Hello <A_NAME>, the time is now <DATE_NOW TIME> and the office is closed. As you are a VIP customer, you are now forward to VIP support. There are current <QUEUE_CALLERS_COUNT 12345678901234567890BBBB> callers in the queue, but we expect to be talking to you in about <QUEUE_CALLERS_MAX_WAIT 12345678901234567890BBBB>.',
    voice: '4df8tr156fg5g156fg15ggd',
    speed: 100,
    engine: 'ELEVEN_V3'
  },
  goto: '1234567890123457890AABB'
}

Errors

Error code	Message	Description
404	customer	Customer not found or not active
404	not_found	Playback 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	Start audio file not found
404	goto	Dialplan item not found
422	speak.voice	Missing or invalid
422	speak.speed	Missing or invalid
409	speak.message	Unmatched tags - cannot parse message
422	speak.message[x].format	Invalid formatting
422	speak.message[x].argument	Argument is missing
422	speak.message[x].argument	Argument is missing or invalid
422	speak.message[x].type	Invalid type
404	speak.message[x].argument	Queue not found
404	speak.message[x].argument	Employee not found
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents