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 prompt to be played to callers only once when the calls join the ring group.

Valid value:

  • Empty string: Play the next stage's prompt; if no prompt exists, play the caller's own ringing tone (beep sound).
  • Other value: The filename of the custom prompt (e.g. demo.wav).
    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 prompt or music to be played to callers before members answer the calls.

Valid value:

  • Empty string: Continue to play the previous stage's prompt; if no prompt exists, play the caller's own ring tone (beep sound).
  • Other value: The filename of custom prompt (e.g. demo.wav) or the name of MoH (music on hold) playlist.
    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 music to be played to callers when the calls are put on hold.

Valid value:

  • follow_system: Follow system setting (Set on PBX Settings > Voice Prompt > Prompt Preferences > Music on Hold).
  • Empty string: No music played.

  • Other value: The name of the MoH (Music on Hold) playlist.

    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 ringtone for member's Linkus clients.

Valid value:

  • Empty string: The system will use the ringtone set on the Linkus clients.
  • Other value: The filename of the ringtone (e.g. Ring1.mp3).
    Note: You can query the ringtone name using Query Custom Ringtone List.
member_list Yes Array <Ring_Group_Member> The information of members in the ring group.
enb_extension_always_forward No Integer Whether to apply the Always call forwarding destinations of the extensions in the member list for the ring group calls.

After enabled, if a member's extension has an Always call forwarding destination configured to Extension, Mobile Number, or External Number, and is currently in the corresponding presence, the system will directly ring the configured forwarding destination instead of the member's extension upon receiving a ring group call, while other members still ring normally based on the ring strategy.

Valid value:
  • 0: Disable.
  • 1: Enable.
external_number_call_confirm No Integer Whether call confirmation is enabled for the external number members in the ring group.
Valid value:
  • 0: Disable.
  • 1: Enable. The external number member will be required to press a key to confirm acceptance before the call is connected, preventing the call from being answered by voicemail or automated systems.
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 defines different settings depending on the value of fail_dest.
  • 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 is required. It defines the play count of the prompt, and only integer in the range 1 - 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.
enable_time_condition No Integer Whether to enable time condition.

Valid value:

  • 0: Disable.
  • 1: Enable.
Note: When set to 1, timezone_id, outoffice_dest, holiday_dest, and their corresponding destination parameters are required.
timezone_id No Integer Time zone ID.
Note: You can query time zone ID using Query Time Zone List.
outoffice_dest No String

The destination type for ring group calls outside business hours.

Valid value:

  • receive_call: Receive calls.
  • 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.
outoffice_dest_prefix No String
The destination prefix for ring group calls outside business hours.
Note: Configure this parameter only when outoffice_dest is set to external_num or play_greeting.
  • If outoffice_dest is set to external_num, this parameter defines the dial-out prefix of the external number.
  • If outoffice_dest is set to play_greeting, this parameter defines the play count of the prompt, and only integers from 1 to 5 are supported.
outoffice_dest_value No String

The detailed destination for ring group calls outside business hours.

Note: This parameter is required when outoffice_dest is set to any value except end_call and receive_call.
  • If outoffice_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 outoffice_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 outoffice_dest is set to external_num, this parameter defines the external number.
holiday_dest No String

The destination type for ring group calls during holidays.

Valid value:

  • receive_call: Receive calls.
  • 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.
holiday_dest_prefix No String
The destination prefix for ring group calls during holidays.
Note: Configure this parameter only when holiday_dest is set to external_num or play_greeting.
  • If holiday_dest is set to external_num, this parameter defines the dial-out prefix of the external number.
  • If holiday_dest is set to play_greeting, this parameter defines the play count of the prompt, and only integers from 1 to 5 is supported.
holiday_dest_value No String

The detailed destination for ring group calls during holidays.

Note: This parameter is required when holiday_dest is set to any value except end_call and receive_call.
  • If holiday_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 holiday_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 holiday_dest is set to external_num, this parameter defines the external number.
ignore_holiday_dest No Integer Whether to route ring group calls received during holidays according to the business hours destination.

Valid value:

  • 0: Disable.
  • 1: Enable.
Note: ignore_holiday_dest and enb_play_holiday_prompt_global can not both be enabled.
enb_play_holiday_prompt_global No Integer Whether to play holiday prompt before routing ring group calls received during holidays to the holiday destination.

Valid value:

  • 0: Disable.
  • 1: Enable.
Note: ignore_holiday_dest and enb_play_holiday_prompt_global can not both be enabled.
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 defines different settings depending on the value of no_agent_online_dest.
  • 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 is required. It defines the play count of the prompt, and only integer in the range 1 - 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 definition of this parameter depends on the value of type.
Note: This parameter is required when ring_strategy is set to ring_all, sequentially, or memory_hunt.
  • If type is set to extension, this parameter defines an extension ID.

    You can query the extension ID using Search Specific Extensions.

  • If type is set to ext_group, this parameter defines an extension group ID.

    You can query the extension ID using Search Specific Extension Groups.

  • If type is set to external, this parameter should be a string concatenated per the rules below.
    external_<ringgroup_number>_<prefix><external_number>
    Note: Replace <ringgroup_number> with the ring group number, <prefix> with a valid dial-out prefix and <external_number> with a valid external number.

    You can query the ring group number using Query Information of a Ring Group.

    Example:
    external_8018_8819167453692
type No String The type of the ring group member.

Valid value:

  • extension: Extension.
  • ext_group: Extension group.
  • external: External number.
Note: This parameter is required when ring_strategy is set to ring_all, sequentially, or memory_hunt.
text No String The definition of this parameter depends on the value of type.
  • If type is set to extension, this parameter defines the full name of the extension.
  • If type is set to ext_group, this parameter defines the extension group name.
  • If type is set to external, this parameter defines the first name for the external number and is required when ring_strategy is set to ring_all, sequentially, or memory_hunt and text3 is not set.
text2 No String The definition of this parameter depends on the value of type.
  • If type is set to extension, this parameter defines the extension number.
  • If type is set to ext_group, this parameter defines the extension group name.
  • If type is set to external, this parameter defines the external number and is required when ring_strategy is set to ring_all, sequentially, or memory_hunt.
text3 No String The last name of the external number.
Note: This parameter is required when other parameters meet the following requirements:
  • ring_strategy is set to ring_all, sequentially, or memory_hunt.
  • type is set to external.
  • text is not set.
text4 No String The dial-out prefix for the external number.
sub_option No Array <Custom_Strategy_Member> The extensions, extension groups and external numbers 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 members 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 definition of this parameter depends on the value of type.
  • If type is set to extension, this parameter defines an extension ID.

    You can query the extension ID using Search Specific Extensions.

  • If type is set to ext_group, this parameter defines an extension group ID.

    You can query the extension ID using Search Specific Extension Groups.

  • If type is set to external, this parameter should be a string concatenated per the rules below.
    external_<ringgroup_number>_<prefix><external_number>
    Note: Replace <ringgroup_number> with the ring group number, <prefix> with a valid dial-out prefix and <external_number> with a valid external number.
    Example:
    external_8018_8819167453692
type Yes String The type of the ring group member.

Valid value:

  • extension: Extension.
  • ext_group: Extension group.
  • external: External number.
text No String The definition of this parameter depends on the value of type.
  • If type is set to extension, this parameter defines the full name of the extension.
  • If type is set to ext_group, this parameter defines the extension group name.
  • If type is set to external, this parameter defines the first name for the external number and is required if text3 is not set.
text2 No String The definition of this parameter depends on the value of type.
  • If type is set to extension, this parameter defines the extension number.
  • If type is set to ext_group, this parameter defines the extension group name.
  • If type is set to external, this parameter defines the external number and is required.
text3 No String The last name for the external number.
Note: This parameter is required when type is set to external and text is not set.
text4 No String The dial-out prefix for the external number.

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: yeastardocs.example.yeastarcloud.com
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"
}