Edit a Ring Group

Edit a ring group.

Request URL

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

Request parameters

Parameter Required Type Description
id Yes Integer The unique ID of the ring group.
Note: You can query the ring group's ID using Search Specific Ring Groups.
name No String The ring group name.
Note: The maximum character length is 127.
ring_strategy No String The ring strategy of the ring group.

Valid value:

  • ring_all: Ring all available extensions simultaneously.
  • sequentially: Ring all available extensions sequentially.
  • memory_hunt: Ring the first available extension in the member list. If no answer within the ring time, progressively ring the next available extension, until all the available extensions in the list rang.
  • custom: Ring extensions according to their individual ring delays and stop ringing after their individual ring timeouts.
ring_timeout No Integer

The waiting time (in seconds) before ringing the next member or routing the call to Failover Destination.

Note: This parameter is required only when ring_strategy is set to ring_all, sequentially or memory_hunt.
join_prompt No String The filename of the custom prompt (e.g. demo.wav) to be played to callers only once when the calls join the ring group.
Note:

You can query the filename of custom prompts using Get Menu Options ("menu":"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.
welcome_prompt 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.
moh No String The name of the MoH (music on hold) playlist to be played to callers when the calls are put on hold.
Note: You can query the name of MoH playlists using Query MoH Playlists.
alert_info No String

The keyword to be added to Alert-info header in INVITE request, determining which ringtone to be played to identify ring group calls.

Note:
  • The maximum character length is 31.
  • Only numbers, letters, space, and special characters -_ are allowed.
client_unique_ringtone No String The filename of the ringtone (e.g. Ring1.mp3) for member's Linkus clients.
Note: You can query the ringtone name using Query Custom Ringtone List.
member_list Yes Array <Ring_Group_Member> The information of each member in the ring group.
fail_dest No String

The destination type for ring group calls unanswered within ring timeout.

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

The destination prefix for ring group calls unanswered within ring timeout.

Note: This parameter is required when fail_dest is set to external_num or play_greeting.
  • If fail_dest is set to external_num, this parameter defines the dial-out prefix of the external number, and the maximum character length is 7.
  • If fail_dest is set to play_greeting, this parameter defines the play count of the prompt, and only integer in the range 0 - 5 is supported.
fail_dest_value No String

The detailed destination for ring group calls unanswered within ring timeout.

Note: This parameter is required when fail_dest is set to any value except end_call.
  • If fail_dest is set to play_greeting, this parameter defines the filename of custom prompt (e.g. demo.wav).

    You can query the filename of custom prompts using Get Menu Options ("menu":"custom_prompt").

  • If fail_dest is set to 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.

  • If fail_dest is set to external_num, this parameter defines the external number.
enb_miss_call No Integer Whether to record missed ring group calls in call logs of extensions included in failover destination.
Valid value:
  • 0: Disable.
  • 1: Enable.
Note: This parameter is available only when ring_strategy is set to ring_all, memory_hunt or custom, and fail_dest is set to extension, ring_group, or queue.
no_agent_online_dest No String

The destination type for ring group calls with no online extensions.

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.
no_agent_online_prefix No String

The destination prefix for ring group calls with no online extensions.

Note: This parameter is required when no_agent_online_dest is set to external_num or play_greeting.
  • If no_agent_online_dest is set to external_num, this parameter defines the dial-out prefix of the external number, and the maximum character length is 7.
  • If no_agent_online_dest is set to play_greeting, this parameter defines the play count of the prompt, and only integer in the range 0 - 5 is supported.
no_agent_online_value No String

The detailed destination for ring group calls with no online extensions.

Note: This parameter is required when no_agent_online_dest is set to any value except end_call.
  • If no_agent_online_dest is set to play_greeting, this parameter defines the filename of custom prompt (e.g. demo.wav).

    You can query the filename of custom prompts using Get Menu Options ("menu":"custom_prompt").

  • If no_agent_online_dest is set to 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.

  • If no_agent_online_dest is set to external_num, this parameter defines the external number.
Ring_Group_Member
Parameter Required Type Description
value No String The ID of the ring group member (extension or extension group).
Note:
type No String The type of the ring group member.

Valid value:

  • extension: Extension.
  • ext_group: Extension group.
Note:

This parameter is required when ring_strategy is set to ring_all, sequentially, or memory_hunt.
sub_option No Array <Custom_Strategy_Member> The extensions and extension groups included in the ring group member entry.
Note: This parameter is required when ring_strategy is set to custom.
delay_time No Integer The time delay (in seconds) before ringing all extensions included in the ring group member entry.

Valid value: 0 - 600

Note: This parameter is required when ring_strategy is set to custom.
timeout No Integer The waiting time (in seconds) before ringing the next member or routing the call to Failover Destination.

Valid value: 0 - 600

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

Custom_Strategy_Member

Parameter Required Type Description
value Yes String The ID of the ring group member (extension or extension group).
Note: You can query the extension ID using Search Specific Extensions, and query the extension group ID using Search Specific Extension Groups.
type Yes String The type of the ring group member.

Valid value:

  • extension: Extension.
  • ext_group: Extension group.

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 specified ring group (ID: 8023):
  • Replace the name of the ring group with "Technical Support Team 2".
  • Change the ring timeout to "30". 
POST /openapi/v1.0/ringgroup/update?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 
Host: 192.168.5.150:8088
Content-Type: application/json
{
    "id": 8023,
    "name": "Technical Support Team 2",
    "ring_timeout": 30
}
Response example
HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS"
}