Edit a Queue

Edit a queue.

Request URL

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

Request parameters

Parameter Required Type Description
id Yes Integer The unique ID of the queue.
number No String Queue number.
name No String Queue name.
enb_queue_skill_based_routing No Integer Whether to route queue calls based on agents' skill levels.
Valid value:
  • 0: Disable.
  • 1: Enable.
ring_strategy No String The 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.
moh No String The 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_time No Integer The 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_dest No String The 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_prefix No String This 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_value No String The 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_timeout No Integer Ringing 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_time No Integer The time interval before ringing the next available agent after the previous available agent's ringing timeout (Unit: Second).

Valid value: 1 - 9999999.
wrap_up_time No Integer Wrap-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_prompt No String The 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_use No Integer Assign queue calls to agents that are during an active call.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_auto_pause No Integer When 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_call No Integer The 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_list No Array <Dynamic_Agent_List> Information of the dynamic agents.
static_agent_list No Array <Static_Agent_List> Information of the static agents.
manager_list No Array <Manager_List> Information of the queue managers.
enb_email_miss_call No Integer Notify queue managers by email when a queue call is missed.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_email_abandon_call No Integer Notify queue managers by email when a queue call is abandoned.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_email_sla_alarm No Integer Notify 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_display No Integer Decide whether to display the call records for missed queue calls on agents' IP phones.
Valid value:
  • 0: Disable.
  • 1: Enable.
callback_enb_request_email No Integer Notify queue managers by email when callers successfully request a queue callback.
Valid value:
  • 0: Disable.
  • 1: Enable.
callback_enb_failed_email No Integer Notify queue managers by emails when callers fail to request a queue callback.
Valid value:
  • 0: Disable.
  • 1: Enable.
max_calls No Integer The maximum number of callers allowed to wait in the queue.

Valid value: 1 - 9999.
alert_info No String The "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_ringtone No String The distinctive ringtone that will be played on agents' Linkus 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_empty No Integer Force 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_empty No Array<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 84.23.0.24 or earlier. For 84.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_list No Array<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 84.23.0.83 or later.
enb_disallow_to_join_when_empty No Integer Disallow callers to join a queue where no agents are available.
Valid value:
  • 0: Disable.
  • 1: Enable.
empty_defined_for_disallow_to_join_when_empty No Array<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 84.23.0.24 or earlier. For 84.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_list No Array<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 84.23.0.83 or later.
sla_time No Integer The Service Level Agreement (SLA) time (Unit: Second).

Valid value: 1 - 9999.
sla_interval No Integer The 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_threshold No Integer The Service Level Agreement (SLA) alarm threshold for the queue.

Valid value: 1 - 999.
join_prompt No String The 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_prompt No Integer Whether to play full join prompt to callers before ringing members.
Valid value:
  • 0: Disable.
  • 1: Enable.
ringback_tone No String The 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_id No Integer Announce the agent ID to callers.

Valid value:

  • 0: Disable.
  • 1: Enable.
enb_announce_default_prompt No Integer Periodically 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_pos No Integer When 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_time No Integer Periodically announce the estimated waiting time to callers while they are waiting in the queue.

Valid value:

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

Valid value: 1 - 999.
sys_announce_prompt No String The 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_freq No Integer The time interval to play the queue announcements (Unit: Second).

Valid value: 1 - 9999.
satisfa_survey_prompt No String The 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_prompt No String The 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_list No Array <Satisfaction_Survey_Point_List> Satisfaction survey points. Different keys correspond to different points.
press_key No String The 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_dest No String The 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_prefix No String This 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_value No String The 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_callback No Integer Whether to enable queue callback.

Valid value:

  • 0: Disable.
  • 1: Enable.
callback_method No String Method 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_key No String The 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_timeout No Integer The 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_prefix No String The prefix of the outbound route which is used for queue callback.
callback_timeout No String Type 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_num No Integer Callback 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_queue No Integer Whether to enable priority queue.
Valid value:
  • 0: Disabled.
  • 1: Enabled.
weight No Integer The initial weight of the queue.

Valid value: 1 - 999
enb_acceleration_weight No Integer Whether to enable acceleration weight.
Valid value:
  • 0: Disabled.
  • 1: Enabled.
acceleration No Integer The 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_language No Integer

Whether to enable custom prompt language for the queue.

Valid value:
  • 0: Disabled.
  • 1: Enabled.
prompt_language No String The 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
Parameter Required Type Description
value Yes String The extension ID of the dynamic agent.
Note: You can query agent's extension ID using Search Specific Extensions.
type No String The type of the dynamic agent.

Valid value:

  • extension
number_value No Integer The skill level of the dynamic 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.
Static_Agent_List
Parameter Required Type Description
value Yes String The extension ID of the static agent.
Note: You can query agent's extension ID using Search Specific Extensions.
type No String The type of the static agent.

Valid value:

  • extension
number_value No Integer The 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
Parameter Required Type Description
value Yes String The extension ID of the queue manager.
Note: You can query the manager's extension ID using Search Specific Extensions.
type No String The type of the queue manager.

Valid value:

  • extension
Leave_Empty_Rules/Join_Empty_Rules
Parameter Required Type Description
no_agent_include_list Yes Array<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_to Yes String The 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_prefix No String This 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_value No String The 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
Parameter Required Type Description
K Yes String Satisfaction survey rating keys.

Valid value:

  • Number 0 - 9
  • *
P Yes Integer Satisfaction survey points.

Valid value: -99 - 99

Response parameters

Parameter Type Description
errcode Integer Returned error code.
  • 0: Succeed.
  • Non-zero value: Failed.
Note: You can check the error code and error message in Error Code and Error Message.
errmsg String Returned 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: yeastardocs.example.yeastarcloud.com
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"
}