Skip to Content

Edit a Queue

Edit a queue.

Request URL

POST {base_url}/{api_path}/queue/update?access_token={access_token}

Request parameters

ParameterRequiredTypeDescription
idYesIntegerThe unique ID of the queue.
numberNoStringQueue number.
nameNoStringQueue name.
enb_queue_skill_based_routingNoIntegerWhether to route queue calls based on agents' skill levels.
Valid value:
  • 0: Disable.
  • 1: Enable.
ring_strategyNoStringThe ring strategy of the queue.

Valid value:

  • ring_all: Ring all available agents simultaneously until someone answers.
  • least_recent: Ring the available agent that was least recently called.
  • fewest_calls: Ring the available agent with the fewest completed calls.
  • random: Ring the agents randomly.
  • rrmemory: Round robin with memory.
  • linear: Ring the available agent in specific order based on the type of agents in the queue.
Note:If enb_queue_skill_based_routing is set to 1, queue calls will be routed in descending order of the agents' skill levels, and the ring strategy will only apply to agents with the same skill level.
mohNoStringThe music to be played when callers are waiting in the queue.
Valid value:
  • default: The default music on hold.
  • Name of the existing music on hold playlist on PBX (Path: PBX Settings > Voice Prompt > Music on Hold).
max_wait_timeNoIntegerThe maximum time that callers are allowed to wait for an available agent in the queue (Unit: Second).Valid value: 0 - 9999999.Note:0 indicates no restriction on the caller's waiting time in the queue.
fail_destNoStringThe destination type of unanswered queue calls.Note:This applies to the following scenarios:

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • group_vm: Group Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow
  • ring_group: Ring Group.
  • queue: Queue.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
fail_dest_prefixNoStringThis parameter defines different settings depending on the destination type of unanswered queue calls (fail_dest).
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting, this parameter defines the play count of the prompt. The valid value is 1 - 5.
fail_dest_valueNoStringThe destination of unanswered queue calls. This parameter defines different settings depending on the destination type of unanswered queue calls (fail_dest).
  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.

  • When the destination type is extension, ext_vm, group_vm, ivr, call_flow, ring_group, or queue, this parameter should be the unique ID of the destination.

    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.

  • When the destination type is external_num, this parameter defines the external number.
agent_timeoutNoIntegerRinging timeout for agents (Unit: Second).Valid value: 1 - 9999999.Note:If an agent did not answer the call after the ringing timeout, system will ring the next available agent according to the ring strategy.
retry_timeNoIntegerThe time interval before ringing the next available agent after the previous available agent's ringing timeout (Unit: Second).

Valid value: 1 - 9999999.

wrap_up_timeNoIntegerWrap-up time for agents, which can be used to handle post-call tasks after finishing a call (Unit: Second).

Valid value: 1 - 9999999.

Note:Agents will NOT receive queue calls until the wrap-up time is over.
agent_promptNoStringThe prompt to be played to agents when they answer a queue call.

Valid value: Name of the existing custom prompt file on PBX (Path: PBX Settings > Voice Prompt > Custom Prompt).

enb_ring_in_useNoIntegerAssign queue calls to agents that are during an active call.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_auto_pauseNoIntegerWhen the number of consecutive missed queue calls for an agent reach the threshold, the system automatically pauses the agent and sends a notification email.

Valid value:

  • 0: Disable.
  • 1: Enable.
max_pause_miss_callNoIntegerThe threshold for agent's consecutive missed calls.

Valid value: 1 - 5.

Note:This parameter is required when enb_auto_pause is set to 1.
dynamic_agent_listNoArray <Dynamic_Agent_List>Information of the dynamic agents.
static_agent_listNoArray <Static_Agent_List>Information of the static agents.
manager_listNoArray <Manager_List>Information of the queue managers.
enb_email_miss_callNoIntegerNotify queue managers by email when a queue call is missed.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_email_abandon_callNoIntegerNotify queue managers by email when a queue call is abandoned.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_email_sla_alarmNoIntegerNotify queue managers by email when the Service Level Agreement (SLA) is lower than its alarm threshold.
Valid value:
  • 0: Disable.
  • 1: Enable.
enb_ip_phone_missed_call_displayNoIntegerDecide whether to display the call records for missed queue calls on agents' IP phones.
Valid value:
  • 0: Disable.
  • 1: Enable.
callback_enb_request_emailNoIntegerNotify queue managers by email when callers successfully request a queue callback.
Valid value:
  • 0: Disable.
  • 1: Enable.
callback_enb_failed_emailNoIntegerNotify queue managers by emails when callers fail to request a queue callback.
Valid value:
  • 0: Disable.
  • 1: Enable.
max_callsNoIntegerThe maximum number of callers allowed to wait in the queue.

Valid value: 1 - 9999.

alert_infoNoStringThe "Alert-info" Header in the INVITE request to trigger the IP phone to play distinctive ringtones when receiving an incoming call from this IVR.
client_unique_ringtoneNoStringThe distinctive ringtone that will be played on agents' Simu Connect clients when they receive calls from this queue.
Valid value:
  • Built-in ringtones: Ring{x}.mp3 (where x = 0 - 10).
  • Custom ringtone: The file name of an existing custom ringtone on the PBX (Path: PBX Settings > Voice Prompt > Custom Ringtone). E.g. example.wav.
enb_leave_emptyNoIntegerForce waiting callers to leave the queue when there are no available agents in the queue.

Valid value:

  • 0: Disable.
  • 1: Enable.
empty_defined_for_leave_emptyNoArray<String>Define the scenario(s) in which the queue is considered to have no available agents. In such scenarios, waiting callers are forced to leave the queue, and the call is routed to the failover destination (fail_dest).Note:
  • If you don't configure this parameter, it will be filled with the default value ["1","2"].
  • This parameter applies only to version 83.23.0.24 or earlier. For 83.23.0.83 or later version, see the leave_empty_no_agent_list parameter.
Valid value:
  • 1: Agents are unavailable (Off Line)
  • 2: Agents are paused
  • 3: Agents are busy
leave_empty_no_agent_listNoArray<Leave_Empty_Rules>Define the scenario(s) in which the queue is considered to have no available agents. In such scenarios, waiting callers are forced to leave the queue, and the call is routed to the specified destination.
Note:This parameter applies only to version 83.23.0.83 or later.
enb_disallow_to_join_when_emptyNoIntegerDisallow callers to join a queue where no agents are available.Valid value:
  • 0: Disable.
  • 1: Enable.
empty_defined_for_disallow_to_join_when_emptyNoArray<String>Define the scenario(s) in which the queue is considered to have no agents available, and callers are NOT allowed to join.
Note:
  • If you don't configure this parameter, it will be filled with the default value ["1","2"].
  • This parameter applies only to version 83.23.0.24 or earlier. For 83.23.0.83 or later version, see the join_empty_no_agent_list parameter.
Valid value:
  • 1: Agents are unavailable (Off Line)
  • 2: Agents are paused
  • 3: Agents are busy
join_empty_no_agent_listNoArray<Join_Empty_Rules>The scenario(s) in which the queue is considered to have no available agents. In such scenarios, callers are NOT allowed to join the queue, and the call is routed to the specified destination.
Note:This parameter applies only to version 83.23.0.83 or later.
sla_timeNoIntegerThe Service Level Agreement (SLA) time (Unit: Second).

Valid value: 1 - 9999.

sla_intervalNoIntegerThe evaluation interval (Unit: Minute).

The time interval to compare the queue's SLA performance against the SLA alarm threshold, so the system can send a notification email accordingly.

Valid value: 1 - 9999.

sla_alarm_thresholdNoIntegerThe Service Level Agreement (SLA) alarm threshold for the queue.

Valid value: 1 - 999.

join_promptNoStringThe prompt played to callers when they join the queue.

Valid value: Name of the existing custom prompt file on PBX (Path: PBX Settings > Voice Prompt > Custom Prompt).

play_full_join_promptNoIntegerWhether to play full join prompt to callers before ringing members.
Valid value:
  • 0: Disable.
  • 1: Enable.
ringback_toneNoStringThe filename of custom prompt (e.g. demo.wav) or the name of MoH (music on hold) playlist. The specified audio will be played to callers before members answer the calls.
Note:You can query the filename of custom prompts using Get Menu Options ("menu":"custom_prompt"), and query the name of MoH playlists using Query MoH Playlists.
enb_announce_agent_idNoIntegerAnnounce the agent ID to callers.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_announce_default_promptNoIntegerPeriodically play the prompt "Thank You for Your Patience" to callers while they are waiting in the queue.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_announce_posNoIntegerWhen callers are waiting in the queue, periodically announce the number of people waiting ahead of them.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_announce_hold_timeNoIntegerPeriodically announce the estimated waiting time to callers while they are waiting in the queue.

Valid value:

  • 0: Disable.
  • 1: Enable.
caller_announce_freqNoIntegerThe time interval to announce the number of people waiting ahead to the callers (Unit: Second).

Valid value: 1 - 999.

sys_announce_promptNoStringThe queue announcement which is periodically played to callers after they reach the queue.

Valid value: Name of the existing custom prompt file on PBX (Path: PBX Settings > Voice Prompt > Custom Prompt).

sys_announce_freqNoIntegerThe time interval to play the queue announcements (Unit: Second).

Valid value: 1 - 9999.

satisfa_survey_promptNoStringThe satisfaction survey prompt played to the caller after the agent hangs up the call.

Valid value:

  • default: The default prompt.
  • Name of the existing custom prompt file on PBX (Path: PBX Settings > Voice Prompt > Custom Prompt).
satisfa_survey_end_promptNoStringThe prompt played to callers after they press the key to rate agent's service.

Valid value:

  • default: The default prompt.
  • Name of the existing custom prompt file on PBX (Path: PBX Settings > Voice Prompt > Custom Prompt).
Note:This parameter ONLY takes effect when satisfa_survey_prompt is configured.
satisfaction_survey_point_listNoArray <Satisfaction_Survey_Point_List>Satisfaction survey points. Different keys correspond to different points.
press_keyNoStringThe key to trigger the key press event.

After callers input the key according to the prompt, the call will be routed to the specified destination.

Valid value:
  • Number 0 - 9
  • *
  • #
key_destNoStringThe destination type of the key.Valid value:
  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • group_vm: Group Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow
  • ring_group: Ring Group.
  • queue: Queue.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
key_dest_prefixNoStringThis parameter defines different settings depending on the destination type of the key (key_dest).
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting, this parameter defines the play count of the prompt. The valid value is 1 - 5.
key_dest_valueNoStringThe destination of the key. This parameter defines different settings depending on the destination type of the key (key_dest).
  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.

  • When the destination type is extension, ext_vm, group_vm, ivr, call_flow, ring_group, or queue, this parameter should be the unique ID of the destination.

    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.

  • When the destination type is external_num, this parameter defines the external number.
enb_callbackNoIntegerWhether to enable queue callback.

Valid value:

  • 0: Disable.
  • 1: Enable.
callback_methodNoStringMethod for callers to trigger callback requests when the queue is busy.

Valid value:

  • digit: Triggered by caller input.
  • timeout: Auto triggered after the timeout.
callback_press_keyNoStringThe key to trigger a callback request.
Note:This parameter is required when callback_method is set to digit.

Valid value:

  • Number 0 - 9
  • *
  • #
callback_trigger_timeoutNoIntegerThe timeout duration to trigger the callback request (Unit: Second).
Note:This parameter is required when callback_method is set to timeout.

Valid value: 0 - 1800

callback_outbound_prefixNoStringThe prefix of the outbound route which is used for queue callback.
callback_timeoutNoStringType of the callback timeout.
Note: Callback timeout refers to the duration that a callback request can be reserved in the queue.

Valid value:

  • queue_max_wait_time: The maximum waiting time of the queue.
  • custom: Custom timeout duration.
callback_timeout_numNoIntegerCallback timeout duration (Unit: Second).

If there are no available agents in the queue within the timeout duration, the callback request will be cancelled.

Note:This parameter is required when callback_timeout is set to custom.

Valid value: 0 - 1800

enb_priority_queueNoIntegerWhether to enable priority queue.Valid value:
  • 0: Disabled.
  • 1: Enabled.
weightNoIntegerThe initial weight of the queue.

Valid value: 1 - 999

enb_acceleration_weightNoIntegerWhether to enable acceleration weight.
Valid value:
  • 0: Disabled.
  • 1: Enabled.
accelerationNoIntegerThe amount of time (in secondes) a call has been waiting in the queue before the weight is increased by 1.

Valid value: 10 - 1800

enb_custom_languageNoInteger

Whether to enable custom prompt language for the queue.

Valid value:
  • 0: Disabled.
  • 1: Enabled.
prompt_languageNoStringThe custom language for system prompts in the queue.

Valid value: The prompt language existed in PBX System Prompt.

Note:You can query the available system prompt languages using Get Menu Options ("menu":"system_prompt").

Dynamic_Agent_List

ParameterRequiredTypeDescription
valueYesStringThe extension ID of the dynamic agent.
Note:You can query agent's extension ID using Search Specific Extensions.
typeNoStringThe type of the dynamic agent.

Valid value:

  • extension
number_valueNoIntegerThe skill level of the dynamic agent.Valid value: 1 - 99Note:
  • The smaller the number, the higher the skill level, and consequently the higher the priority for ringing.
  • If you do not configure this parameter, it will be filled with the default value 1 (the highest skill level).
  • This parameter takes effect ONLY when enb_queue_skill_based_routing is set to 1.

Static_Agent_List

ParameterRequiredTypeDescription
valueYesStringThe extension ID of the static agent.
Note:You can query agent's extension ID using Search Specific Extensions.
typeNoStringThe type of the static agent.

Valid value:

  • extension
number_valueNoIntegerThe skill level of the static agent.Valid value: 1 - 99
Note:
  • The smaller the number, the higher the skill level, and consequently the higher the priority for ringing.
  • If you do not configure this parameter, it will be filled with the default value 1 (the highest skill level).
  • This parameter takes effect ONLY when enb_queue_skill_based_routing is set to 1.

Manager_List

ParameterRequiredTypeDescription
valueYesStringThe extension ID of the queue manager.Note:You can query the manager's extension ID using Search Specific Extensions.
typeNoStringThe type of the queue manager.

Valid value:

  • extension

Leave_Empty_Rules/Join_Empty_Rules

ParameterRequiredTypeDescription
no_agent_include_listYesArray<String>The scenarios considered as having no available agents.Valid value:
  • 1：All agents are currently offline.
  • 2：All agents are currently on hold.
  • 3：All agents are currently busy.
dest_toYesStringThe destination type for routing calls in scenarios where there are no available agents.Valid value:
  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • group_vm: Group Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow
  • ring_group: Ring Group.
  • queue: Queue.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
dest_prefixNoStringThis parameter returns different values depending on the destination type (dest_to).
Note:This parameter is required when dest_to is set to play_greeting.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting, this parameter defines the play count of the prompt. The valid value is 1 - 5.
dest_valueNoStringThe destination for routing calls in scenarios where there are no available agents. This parameter returns different values depending on the destination type (dest_to).Note:This parameter is required when dest_to is set to any type other than end_call.
  • When the destination type is play_greeting, this parameter defines the custom prompt file name. E.g. demo.wav.

  • When the destination type is extension, ext_vm, group_vm, ivr, call_flow, ring_group, or queue, this parameter should be the unique ID of the destination.

    For example, the destination is the extension 2002, then this parameter should be set to the extension's ID 2.

  • When the destination type is external_num, this parameter defines the external number.

Satisfaction_Survey_Point_List

ParameterRequiredTypeDescription
KYesStringSatisfaction survey rating keys.

Valid value:

  • Number 0 - 9
  • *
PYesIntegerSatisfaction survey points.

Valid value: -99 - 99

Response parameters

ParameterTypeDescription
errcodeIntegerReturned error code.
  • 0: Succeed.
  • Non-zero value: Failed.
Note:You can check the error code and error message in Error Code and Error Message.
errmsgStringReturned message.
  • SUCCESS: Succeed.
  • FAILURE: Failed.

Examples

Request example

Update the following configurations for the queue with ID "6":

  • Replace the queue name with "PreSale".
  • Change the ring strategy to "Ring All".
  • Replace the static agents with users (Extension ID: 76 & 85).
POST /openapi/v1.0/queue/update?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 
Host: 192.168.5.150:8088
Content-Type: application/json
{
    "id":6,
    "name": "PreSale",
    "ring_strategy":"ring_all",
    "static_agent_list": [
        {
           "value":"76",
           "type":"extension"
       },
        {
           "value":"85",
           "type":"extension"
       }
    ]
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS"
}