A Queue item is a dialplan call distribution entity with advanced features for members and callers.
This request will create a queue. All properties are optional except for customer and name.
| URL | https://api.telecomx.dk/pbx/queue | ||
|---|---|---|---|
| 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 queue belongs to. |
| name | String | Name/description of the queue. | |
| number | String | [optional] The phone number to dial to reach this queue locally. Null if not used. |
|
| startAudio | Id | [optional] A sound item to playback when the queue is entered. |
|
| redirect | String | [optional] Number to redirect to when execution starts. Used to quickly circumvent the queue. Null if not used. |
|
| notes | String | Notes about the queue. | |
| strategy | String | How calls are distributed to the queue members: CONCURRENT - call all available members simultaneously. ROUND_ROBIN - call next available member. SEQUENTIAL - call first available member(s) according to member priority. LONGEST_IDLE - call the available member that has been idle for the longest time. LEAST_CALLS - call the available member that has answered the fewest calls today. RANDOM - call a random available member. |
|
| musicOnHold | Id | Id of music on hold class to use for music when waiting in the queue. Null to inherit previously set class or fallback to default class. | |
| whenAllMembersBusyGoto | Id | Id of dialplan item to send caller to if all members are busy, null if not used. | |
| whenNoMembersGoto | Id | Id of dialplan item to send caller to if queue has no members, null if not used. | |
| whenTimeoutGoto | Id | Id of dialplan item to send caller to on timeout. | |
| maxWaitTime | Number | Number of seconds a caller may stay in the queue before timeout - 1-86400 seconds, 0 to disable. | |
| announcePosition | Boolean | If the current queue position should be announced when the caller advances in the queue. | |
| announceWaitTime | Boolean | If the expected remaining wait time should be announced when the caller advances in the queue. | |
| outboundCallerId | String | Number to present when calling external members and mobile phones: DEFAULT - callers number NUMBER - phone number specified in outboundCallerIdNumber SECRET - call is marked as secret caller, no number is presented. MARK - callers number is postfixed with *outboundCallerIdNumber. |
|
| outboundCallerIdNumber | String | If outboundCallerId is NUMBER, this is the number to present on outbound calls. If outboundCallerId is MARK, this is the number to postfix the callers number with. |
|
| priority | Number | Priority in relation to other queues, 1-10. Lowest gets access to members first. | |
| ringLoopLength | Number | Number of seconds members are rung in each ring loop before timing out. Default 30 seconds. | |
| prefixNameWithLabel | String | Optional text label to prefix callers name with, on SIP phones. | |
| prefixNameWithWaitTime | Boolean | True to prefix callers name with the time the caller waited in the queue. | |
| serviceLevel | Number | Max. seconds a call may wait to be answered to uphold the service level, default 60. | |
| serviceLevelCritical | Number | Max. seconds a call may wait to be answered before it is considered critical, default 300. | |
| callback | Object | Callback settings | |
| callback.enabled | boolean | Permit callback, where the caller confirms her number, is hung up, and when first in the queue is called back, when a member answers. | |
| callback.delay | number | This is the number of seconds the caller must have waited in the queue for callback to be available. 0-3600 seconds. | |
| callback.domesticOnly | boolean | If callback is only available for domestic callers. | |
| callback.message | Id | Id of audio to playback to the caller after caller presses 1 to enable callback. Null if not used. | |
| breakout | Object | Breakout settings | |
| breakout.enabled | boolean | True if feature is enabled. | |
| breakout.delay | number | This is the number of seconds the caller must have waited in the queue for breakout to be available. 0-3600 seconds. | |
| breakout.key | string | Key to press to break out of the queue. | |
| :::: | breakout.goto | Id | Id of dialplan item to goto when breakout key is pressed. |
| announcements | Array | List of announcements to playback to the caller | |
| announcements[].delay | Number | Number of seconds caller waits in the queue before this announcement is played. 0-3600 seconds. | |
| announcements[].message | Id | Id of audio to playback. | |
| announcementsLoop | Boolean | True to start over on the announcement list after playing the last announcement. | |
| member | Object | Member settings | |
| member.wrapup | Number | Period of time after a member has finished a call, before the next call may be offered to the member. 0-3600 seconds. | |
| member.announce | Id | Id of audio to playback to the member before handing over the caller. Null if not used. | |
| member.accept | Boolean | If true and the called member is an external number or a mobile phone - then the member will be presented with “this is a call from queue X from caller NUMBER and NAME (if available) - press 1 to accept call or hangup”. Then enabled the member to accept the call or let it pass on to to the next in line. | |
| member.dynamic | Boolean | True if members can join and leave the queue. False if only MANAGER and up may add/remove members. | |
| member.group | Id | Id of a group whose members are the only ones who may join the queue. Requires dynamic to be true. Null if not used. | |
| member.sipOnly | Boolean | True if only SIP phones should be called. If extensions has both SIP and mobile phones, only the SIP phones will get calls from the queue. | |
| member.overrideOffWork | Boolean | True if members with status OFF_WORK and OUT_OF_OFFICE shall also be called. | |
| member.persistPriority | Boolean | True if members priority is persisted, so that when the member joins again without providing priority the last known priority is used. | |
| member.lockLastMember | Boolean | True if last member of queue is locked and can't leave | |
{ customer: '12345678901234567890ABCD', name: 'Support queue', number: '510', startAudio: null, redirect: null, notes: 'Technical support queue - manager is Donald Duck', strategy: 'CONCURRENT', musicOnHold: '12345678901234567890AAAA', whenAllMembersBusyGoto: '123456789012334567890BBBB', whenNoMembersGoto: '12345678901234567890CCCC', whenTimeoutGoto: '12345678901234567890DDDD', maxWaitTime: 600, announcePosition: false, announceWaitTime: false, outboundCallerId: 'NUMBER', outboundCallerIdNumber: '+4570305052', priority: 1, ringLoopLength: 30, prefixNameWithLabel: 'SUPQ:', prefixNameWithWaitTime: true, serviceLevel: 60, serviceLevelCritical: 300, callback: { enabled: true, delay: 180, domesticOnly: true, message: '12345678901234567890EEEE' }, breakout: { enabled: true, delay: 180, key: '1', goto: '12345678901234567890ABCD' }, announcements: [ { delay: 60, message: '12345678901234567890FFFF' }, { delay: 180, message: '12345678901234567890FEFE' } ], announcementsLoop: true, member: { wrapup: 30, announce: null, accept: true, dynamic: true, group: '1234567890123457890DEDE', sipOnly: false, overrideOffWork: false, persistPriority: false, lockLastMember: true } }
| JSON object | ||
|---|---|---|
| _id | Id | Unique id of the queue item. |
| type | String | Always 'DIAL'. |
| name | String | Name/description of the dial item. |
| number | String | The phone number to dial to reach this dial item locally, null if it is not dial-able. |
| startAudio | Id | A sound item to playback when the dial item is entered, null if not used. |
| redirect | String | Number to redirect to when execution starts. Used to quickly circumvent the dial item. |
| notes | String | Notes about the dial item. |
| strategy | String | How calls are distributed to the queue members: CONCURRENT - call all available members simultaneously. ROUND_ROBIN - call next available member. SEQUENTIAL - call first available member(s) according to member priority. LONGEST_IDLE - call the available member that has been idle for the longest time. LEAST_CALLS - call the available member that has answered the fewest calls today. RANDOM - call a random available member. |
| musicOnHold | Id | Id of music on hold class to use for music when waiting in the queue. Null to inherit previously set class or fallback to default class. |
| whenAllMembersBusyGoto | Id | Id of dialplan item to send caller to if all members are busy, null if not used. |
| whenNoMembersGoto | Id | Id of dialplan item to send caller to if queue has no members, null if not used. |
| whenTimeoutGoto | Id | Id of dialplan item to send caller to on timeout. |
| maxWaitTime | Number | Number of seconds a caller may stay in the queue before timeout - 1-86400 seconds, 0 to disable. |
| announcePosition | Boolean | If the current queue position should be announced when the caller advances in the queue. |
| announceWaitTime | Boolean | If the expected remaining wait time should be announced when the caller advances in the queue. |
| outboundCallerId | String | Number to present when calling external members and mobile phones: DEFAULT - callers number NUMBER - phone number specified in outboundCallerIdNumber SECRET - call is marked as secret caller, no number is presented. MARK - callers number is postfixed with *outboundCallerIdNumber. |
| outboundCallerIdNumber | String | If outboundCallerId is NUMBER, this is the number to present on outbound calls. If outboundCallerId is MARK, this is the number to postfix the callers number with. |
| priority | Number | Priority in relation to other queues, 1-10. Lowest gets access to members first. |
| ringLoopLength | Number | Number of seconds members are rung in each ring loop before timing out. Default 30 seconds. |
| prefixNameWithLabel | String | Optional text label to prefix callers name with, on SIP phones. |
| prefixNameWithWaitTime | Boolean | True to prefix callers name with the time the caller waited in the queue. |
| serviceLevel | Number | Max. seconds a call may wait to be answered to uphold the service level, default 60. |
| serviceLevelCritical | Number | Max. seconds a call may wait to be answered before it is considered critical, default 300. |
| callback | Object | Callback settings |
| callback.enabled | boolean | Permit callback, where the caller confirms her number, is hung up, and when first in the queue is called back, when a member answers. |
| callback.delay | number | This is the number of seconds the caller must have waited in the queue for callback to be available. 0-3600 seconds. |
| callback.domesticOnly | boolean | If callback is only available for domestic callers. |
| callback.message | Id | Id of audio to playback to the caller after caller presses 1 to enable callback. Null if not used. |
| breakout | Object | Breakout settings |
| breakout.enabled | boolean | True if feature is enabled. |
| breakout.delay | number | This is the number of seconds the caller must have waited in the queue for breakout to be available. 0-3600 seconds. |
| breakout.key | string | Key to press to break out of the queue. |
| breakout.goto | Id | Id of dialplan item to goto when breakout key is pressed. |
| announcements | Array | List of announcements to playback to the caller |
| announcements[].delay | Number | Number of seconds caller waits in the queue before this announcement is played. 0-3600 seconds. |
| announcements[].message | Id | Id of audio to playback. |
| announcementsLoop | Boolean | True to start over on the announcement list after playing the last announcement. |
| member | Object | Member settings |
| member.wrapup | Number | Period of time after a member has finished a call, before the next call may be offered to the member. 0-3600 seconds. |
| member.announce | Id | Id of audio to playback to the member before handing over the caller. Null if not used. |
| member.accept | Boolean | If true and the called member is an external number or a mobile phone - then the member will be presented with “this is a call from queue X from caller NUMBER and NAME (if available) - press 1 to accept call or hangup”. Then enabled the member to accept the call or let it pass on to to the next in line. |
| member.dynamic | Boolean | True if members can join and leave the queue. False if only MANAGER and up may add/remove members. |
| member.group | Id | Id of a group whose members are the only ones who may join the queue. Requires dynamic to be true. Null if not used. |
| member.sipOnly | Boolean | True if only SIP phones should be called. If extensions has both SIP and mobile phones, only the SIP phones will get calls from the queue. |
| member.overrideOffWork | Boolean | True if members with status OFF_WORK and OUT_OF_OFFICE shall also be called. |
| member.persistPriority | Boolean | True if members priority is persisted, so that when the member joins again without providing priority the last known priority is used. |
{ _id: '12345678901234567890ABCD', name: 'Support queue', number: '510', startAudio: null, redirect: null, notes: 'Technical support queue - manager is Donald Duck', strategy: 'CONCURRENT', musicOnHold: '12345678901234567890AAAA', whenAllMembersBusyGoto: '123456789012334567890BBBB', whenNoMembersGoto: '12345678901234567890CCCC', whenTimeoutGoto: '12345678901234567890DDDD', maxWaitTime: 600, announcePosition: false, announceWaitTime: false, outboundCallerId: 'NUMBER', outboundCallerIdNumber: '+4570305052', priority: 1, ringLoopLength: 30, prefixNameWithLabel: 'SUPQ:', prefixNameWithWaitTime: true, serviceLevel: 60, serviceLevelCritical: 300, callback: { enabled: true, delay: 180, domesticOnly: true, message: '12345678901234567890EEEE' }, breakout: { enabled: true, delay: 180, key: '1', goto: '12345678901234567890ABCD' }, announcements: [ { delay: 60, message: '12345678901234567890FFFF' }, { delay: 180, message: '12345678901234567890FEFE' } ], announcementsLoop: true, member: { wrapup: 30, announce: null, accept: true, dynamic: true, group: '1234567890123457890DEDE', sipOnly: false, overrideOffWork: false, persistPriority: false } }
| 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 | musicOnHold | The music on hold class does not exist |
| 404 | whenAllMembersBusyGoto | Dialplan item not found |
| 404 | whenNoMembersGoto | Dialplan item not found |
| 404 | whenTimeoutGoto | Dialplan item not found |
| 422 | announcements[x].delay | Delay is invalid, must be 1-3600 seconds |
| 404 | announcements | One or more audios was not found |
| 404 | member.announce | Audio not found |
| 404 | callback.message | Audio not found |
| 404 | breakout.goto | Dialplan item not found |
| 422 | breakout.key | Invalid key |
| 404 | member.group | Group not found |
| 409 | strategy | Value is not one of the permitted values |
| 422 | maxWaitTime | Invalid wait time, must be 0-86400 seconds |
| 409 | outboundCallerId | Value is not one of the permitted values |
| 422 | outboundCallerIdNumber | Number is missing or invalid |
| 422 | callback.delay | Invalid delay, must be 0-3600 seconds |
| 422 | member.wrapup | Invalid wrapup, must be 0-3600 seconds |
| 422 | ringLoopLength | Invalid ring loop length, must be 5-3600 seconds. |
| 403 | access_denied | Insufficient access level |
| 500 | internal_error | <Unspecified> |