Skip to Content

Add a Ring Group

Add and configure a ring group.

Request URL

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

Request parameters

ParameterRequiredTypeDescription
numberYesStringThe ring group number.
Note: The maximum character length is 7.
nameYesStringThe ring group name.
Note: The maximum character length is 127.
ring_strategyYesStringThe 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_timeoutNoInteger

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_promptNoStringThe 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_promptNoIntegerWhether to play full join prompt to callers before ringing members.Valid value:
  • 0: Disable.
  • 1: Enable.
welcome_promptNoStringThe 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.
mohNoStringThe 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_infoNoString

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_ringtoneNoStringThe filename of the ringtone (e.g. Ring1.mp3) for member's Simu Connect clients.
Note: You can query the ringtone name using Query Custom Ringtone List.
member_listYesArray <Ring_Group_Member>The information of each member in the ring group.
fail_destYesString

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_prefixNoString

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_valueNoString

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_callNoIntegerWhether 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_destNoString

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_prefixNoString

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_valueNoString

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

ParameterRequiredTypeDescription
valueNoStringThe ID of the ring group member (extension or extension group).Note:
typeNoStringThe 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_optionNoArray <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_timeNoIntegerThe 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.
timeoutNoIntegerThe 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

ParameterRequiredTypeDescription
valueYesStringThe 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.
typeYesStringThe type of the ring group member.

Valid value:

  • extension: Extension.
  • ext_group: Extension group.

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.
idIntegerThe unique ID of the ring group.

Examples

Request example

  • Add a ring group based on ring_all ring strategy.

    POST /openapi/v1.0/ringgroup/create?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 
Host: 192.168.5.150:8088
Content-Type: application/json
{
    "number": "6300",
    "name": "Technical Support",
    "ring_strategy": "ring_all",
    "ring_timeout": 60,
    "join_prompt": "demo.wav",
    "play_full_join_prompt": 1,
    "welcome_prompt": "SoftBreeze",
    "moh": "SoftBreeze",
    "alert_info": "ring-group-support",
    "client_unique_ringtone": "",
    "member_list": [
        {
            "value": "3071",
            "type": "extension"
        },
        {
            "value": "3074",
            "type": "extension"
        },
        {
            "value": "3075",
            "type": "extension"
        }
    ],
    "fail_dest": "end_call"
}

  • Add a ring group based on custom ring strategy.

    POST /openapi/v1.0/ringgroup/create?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 
Host: 192.168.5.150:8088
Content-Type: application/json
{
    "number": "6301",
    "name": "Markting",
    "ring_strategy": "custom",
    "ring_timeout": "20",
    "join_prompt": "demo.wav",
    "play_full_join_prompt": 1,
    "welcome_prompt": "SoftBreeze",
    "moh": "SoftBreeze",
    "alert_info": "ring-group-markting",
    "client_unique_ringtone": "",
    "member_list": [
        {
            "sub_option": [
                {
                    "value": "3071",
                    "type": "extension"
                },
                {
                    "value": "3074",
                    "type": "extension"
                },
                {
                    "value": "3075",
                    "type": "extension"
                }
            ],
            "delay_time": 20,
            "timeout":20
        }
    ],
    "fail_dest": "end_call"
}

Request example

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