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


Parameter	Required	Type	Description
number	Yes	String	The ring group number. Note: The maximum character length is 7.
name	Yes	String	The ring group name. Note: The maximum character length is 127.
ring_strategy	Yes	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	Yes	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: This parameter is required when `ring_strategy` is set to `ring_all`, `sequentially`, or `memory_hunt`. You can query the extension ID using Search Specific Extensions, and query the extension group ID using Search Specific Extension Groups.
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.
id	Integer	The 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
}