添加响铃组

添加并配置响铃组。

请求 URL

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

请求参数

参数 是否必填 类型 说明
number 是 String 响铃组号码。
注： 最大字符长度为 7。
name 是 String 响铃组名称。
注： 最大字符长度为 127。
ring_strategy 是 String 响铃组的响铃策略。

取值范围：

  • ring_all：响铃组中所有可用的分机同时响铃。
  • sequentially：响铃组中可用的分机按顺序响铃。
  • memory_hunt：先响铃响铃组中的第一个可用分机。如果在响铃期间没有应答，则继续响铃下一个可用分机，直到列表中的所有可用分机都响铃完毕。
  • custom：根据分机各自的延迟响铃时间进行响铃，并在各自的响铃超时时间后结束响铃。
ring_timeout 否 Integer

在响铃下一个成员或将来电路由到无人接听目的地之前的等待时间 (秒)。

注： 该参数仅在 ring_strategy 取值为 ring_all、sequentially 或 memory_hunt 时必填。
join_prompt 否 String 当呼叫进入响铃组时，系统会向呼叫者播放一次的提示音。

取值范围：

  • 空字符串：继续播放上一阶段的提示音；若无可用提示音，则播放主叫自定义铃声 (Beep 提示音)。
  • 其他值：自定义提示音的文件名 (如 demo.wav)。
    注：

    可使用 获取菜单选项 接口查询自定义提示音的文件名 ("menu":"custom_prompt")。
play_full_join_prompt 否 Integer 系统是否播完欢迎提示音后再响铃成员。
取值范围：
  • 0：启用。
  • 1：禁用。
welcome_prompt 否 String 在成员接听来电之前，系统会向呼叫者播放的音频。

取值范围：

  • 空字符串：继续播放上一阶段的提示音；若无可用提示音，则播放主叫自定义铃声 (Beep 提示音)。
  • 其他值：自定义提示音的文件名 (如 demo.wav) 或等待音乐播放列表的名称。
    注： 可使用 获取菜单选项 接口查询自定义提示音的文件名 ("menu":"custom_prompt")，或使用 查询等待音乐列表 接口查询等待音乐播放列表的名称。
moh 否 String 当通话被保持时，系统向呼叫者播放的音频。

取值范围：

  • follow_system：跟随系统设置 (在 PBX设置 > 提示音 > 提示音选项 > 等待音乐 中设置)。
  • 空字符串：不播放等待音乐。

  • 其他值：等待音乐播放列表的名称。

    注： 可使用 查询等待音乐列表 接口查询等待音乐播放列表的名称。
alert_info 否 String

要添加到 INVITE 请求的 Alert-Info 头域中的关键字，用于决定播放哪个铃声以识别响铃组来电。

注：
  • 最大字符长度为 31。
  • 仅允许输入数字、字母、空格、以及特殊符号-_。
client_unique_ringtone 否 String 成员的 Linkus 客户端的铃声。

取值范围：

  • 空字符串：系统将播放在 Linkus 客户端上设置的自定义铃声。
  • 其他值：铃声的文件名 (如 Ring1.mp3)。
    注： 可使用 查询自定义铃声列表 接口查询铃声文件名。
member_list 是 Array <Ring_Group_Member> 每个响铃组成员的信息。
enb_extension_always_forward 否 Integer 是否为响铃组来电应用成员列表中的分机的 总是 呼叫前转目的地。

启用后，如果成员分机已设置 总是 呼叫前转目的地为 分机、手机号码 或 外部号码，且该分机当前处于对应状态，系统在收到响铃组来电时将直接响铃配置的前转目的地，而非该成员分机；响铃组中的其他成员仍按照响铃策略正常响铃。

取值范围：
  • 0：禁用。
  • 1：启用。
external_number_call_confirm 否 Integer 是否对响铃组中的外部号码成员启用呼叫确认。
取值范围：
  • 0：禁用。
  • 1：启用。外部号码成员需在通话接通前根据提示按键以确认接听，以防止来电被语音信箱或其他自动系统应答。
fail_dest 是 String

响铃组来电超时未接听时的目的地类型。

取值范围：

  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • group_vm：群语音信箱。
  • ivr：IVR。
  • call_flow：通话流程
  • ring_group：响铃组。
  • queue：队列。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
fail_dest_prefix 否 String

响铃组来电超时未接听时的目的地前缀。

注： 此参数的定义取决于 fail_dest 的取值。
  • 如果 fail_dest 取值为 external_num，此参数定义外部号码的呼出前缀，最大字符长度为 7。
  • 如果 fail_dest 取值为 play_greeting，此参数必填，用于定义提示音的播放次数，支持 1 - 5 范围内的整数。
fail_dest_value 否 String

响铃组来电超时未接听时的详细目的地。

注： 此参数仅在 fail_dest 取值非 end_call 时必填。
  • 如果 fail_dest 取值为 play_greeting，此参数定义自定义提示音的文件名 (如 demo.wav)。

    可使用 获取菜单选项 接口查询自定义提示音的文件名 ("menu":"custom_prompt")。

  • 如果 fail_dest 取值为 extension、ext_vm、group_vm、ivr、call_flow、ring_group 或 queue，此参数定义目的地的 ID。

    例如，目的地是分机 2002，则此参数应设置为分机的 ID 2。

  • 如果 fail_dest 取值为 external_num，此参数定义外部号码。
enb_miss_call 否 Integer 是否将响铃组未接来电记录到来电超时未接听的目的地包括的分机的通话记录中。
取值范围：
  • 0：禁用。
  • 1：启用。
注： 此参数仅在 ring_strategy 取值为 ring_all、memory_hunt 或 custom，且 fail_dest 取值为 extension、ring_group 或 queue 时生效。
enable_time_condition 否 Integer 是否启用时间条件。
取值范围：
  • 0：禁用。
  • 1：启用。
注： 当设置为 1 时，timezone_id、 outoffice_dest、holiday_dest 以及对应的目的地参数必填。
timezone_id 否 Integer 时区 ID。
注： 可通过 查询时区列表 接口查询时区 ID。
outoffice_dest 否 String

非办公时间呼入响铃组的来电的目的地类型。

取值范围：

  • receive_call：接收来电。
  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • group_vm：群语音信箱。
  • ivr：IVR。
  • call_flow：通话流程。
  • ring_group：响铃组。
  • queue：队列。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
outoffice_dest_prefix 否 String
非办公时间呼入响铃组的来电的目的地前缀。
注： 仅当 outoffice_dest 取值为 external_num 或 play_greeting 时配置该参数。
  • 如果 outoffice_dest 取值为 external_num，此参数定义外部号码的呼出前缀。
  • 如果 outoffice_dest 取值为 play_greeting，此参数定义提示音的播放次数，支持 1 - 5 范围内的整数。
outoffice_dest_value 否 String

非办公时间呼入响铃组的来电的详细目的地。

注： 此参数仅在 outoffice_dest 取值非 end_call 和 receive_call 时必填。
  • 如果 outoffice_dest 取值为 play_greeting，此参数定义自定义提示音的文件名 (如 demo.wav)。

    可使用 获取菜单选项 接口查询自定义提示音的文件名 ("menu":"custom_prompt")。

  • 如果 outoffice_dest 取值为 extension、ext_vm、group_vm、ivr、call_flow、ring_group 或 queue，此参数定义目的地的 ID。

    例如，目的地是分机 2002，则此参数应设置为分机的 ID 2。

  • 如果 outoffice_dest 取值为 external_num，此参数定义外部号码。
holiday_dest 否 String

假期期间呼入响铃组的来电的目的地类型。

取值范围：

  • receive_call：接收来电。
  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • group_vm：群语音信箱。
  • ivr：IVR。
  • call_flow：通话流程。
  • ring_group：响铃组。
  • queue：队列。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
holiday_dest_prefix 否 String
假期期间呼入响铃组的来电的目的地前缀。
注： 仅在 holiday_dest 取值为 external_num 或 play_greeting 时配置该参数。
  • 如果 holiday_dest 取值为 external_num，此参数定义外部号码的呼出前缀。
  • 如果 holiday_dest 取值为 play_greeting，此参数定义提示音的播放次数，支持 1 - 5 范围内的整数。
holiday_dest_value 否 String

假期期间呼入响铃组的来电的详细目的地。

注： 此参数仅在 holiday_dest 取值非 end_call 和 receive_call 时必填。
  • 如果 holiday_dest 取值为 play_greeting，此参数定义自定义提示音的文件名 (如 demo.wav)。

    可使用 获取菜单选项 接口查询自定义提示音的文件名 ("menu":"custom_prompt")。

  • 如果 holiday_dest 取值为 extension、ext_vm、group_vm、ivr、call_flow、ring_group 或 queue，此参数定义目的地的 ID。

    例如，目的地是分机 2002，则此参数应设置为分机的 ID 2。

  • 如果 holiday_dest 取值为 external_num，此参数定义外部号码。
ignore_holiday_dest 否 Integer

是否将假期期间呼入响铃组的来电按照办公时间目的地进行路由。

取值范围：
  • 0：禁用。
  • 1：启用。
注： ignore_holiday_dest 和 enb_play_holiday_prompt_global 不能同时启用。
enb_play_holiday_prompt_global 否 Integer

是否在将假期期间呼入响铃组的来电路由至假期目的地之前播放假期提示音。

取值范围：
  • 0：禁用。
  • 1：启用。
注： ignore_holiday_dest 和 enb_play_holiday_prompt_global 不能同时启用。
no_agent_online_dest 否 String

响铃组来电时无在线分机的目的地类型。

取值范围：

  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • group_vm：群语音信箱。
  • ivr：IVR。
  • call_flow：通话流程
  • ring_group：响铃组。
  • queue：队列。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
no_agent_online_prefix 否 String

响铃组来电时无在线分机的目的地前缀。

注： 此参数的定义取决于 no_agent_online_dest 的取值。
  • 如果 no_agent_online_dest 取值为 external_num，此参数定义外部号码的呼出前缀，最大字符长度为 7。
  • 如果 no_agent_online_dest 取值为 play_greeting，此参数必填，用于定义提示音的播放次数，支持 1 - 5 范围内的整数。
no_agent_online_value 否 String

响铃组来电时无在线分机的详细目的地。

注： 此参数仅在 no_agent_online_dest 取值非 end_call 时必填。
  • 如果 no_agent_online_dest 取值为 play_greeting，此参数表示自定义提示音的文件名 (如 demo.wav)。

    可使用 获取菜单选项 接口查询自定义提示音的文件名 ("menu":"custom_prompt")。

  • 如果 no_agent_online_dest 取值为 extension、ext_vm、group_vm、ivr、call_flow、ring_group 或 queue，此参数定义目的地的 ID。

    例如，目的地是分机 2002，则此参数应设置为分机的 ID 2。

  • 如果 no_agent_online_dest 取值为 external_num，此参数定义外部号码。
Ring_Group_Member
参数 是否必填 类型 说明
value 否 String 此参数的定义取决于 type 的取值。
注： 此参数仅在 ring_strategy 取值为 ring_all、sequentially 或 memory_hunt 时必填。
  • 如果 type 取值为 extension，此参数定义分机 ID。

    可使用 搜索特定分机 接口查询分机 ID。

  • 如果 type 取值为 ext_group，此参数定义分机组的 ID。

    可使用 搜索特定分机组 接口查询分机组的 ID。

  • 如果 type 取值为 external，此参数应为按照以下规则连接的字符串。
    external_<ringgroup_number>_<prefix><external_number>
    注： 将 <ringgroup_number> 替换为响铃组号码，将 <prefix> 替换为有效的呼出前缀，将 <external_number> 替换为有效的外部号码。
    示例：
    external_8018_8819167453692
type 否 String 响铃组成员的类型。

取值范围：

  • extension：分机。
  • ext_group：分机组。
  • external：外部号码。
注： 此参数仅在 ring_strategy 取值为 ring_all、sequentially 或 memory_hunt 时必填。
text No String 此参数的定义取决于 type 的取值。
  • 如果 type 取值为 extension，此参数定义分机的完整名称。
  • 如果 type 取值为 ext_group，此参数定义分机组的名称。
  • 如果 type 取值为 external，此参数定义外部号码的名字；当 ring_strategy 取值为 ring_all、sequentially 或 memory_hunt，且 text3 未取值时，此参数必填。
text2 No String 此参数的定义取决于 type 的取值。
  • 如果 type 取值为 extension，此参数定义分机号。
  • 如果 type 取值为 ext_group，此参数定义分机组的名称。
  • 如果 type 取值为 external，此参数定义外部号码；当 ring_strategy 取值为 ring_all、sequentially 或 memory_hunt 时，此参数必填。
text3 No String 外部号码的姓氏。
注： 此参数在其他参数满足下列要求时必填：
  • ring_strategy 取值为 ring_all、sequentially 或 memory_hunt。
  • type 取值为 external。
  • text 未取值。
text4 No String 外部号码的呼出前缀。
sub_option 否 Array <Custom_Strategy_Member> 响铃组成员条目中包含的分机、分机组和外部号码。
注： 此参数仅在 ring_strategy 取值为 custom 时必填。
delay_time 否 Integer 在响铃响铃组成员条目中包含的所有成员前的延迟时间 (秒)。

取值范围：0 - 600

注： 此参数仅在 ring_strategy 取值为 custom 时必填。
timeout 否 Integer 在响铃下一个成员或将来电路由到无人接听目的地之前的等待时间 (秒)。

取值范围：0 - 600

注： 此参数仅在 ring_strategy 取值为 custom 时必填。

Custom_Strategy_Member

参数 是否必填 类型 说明
value 是 String 响铃组成员 (分机或分机组) 的 ID。
注： 可使用 搜索特定分机 接口查询分机 ID，或使用 搜索特定分机组 接口查询分机组的 ID。
type 是 String 响铃组成员的类型。

取值范围：

  • extension：分机。
  • ext_group：分机组。
text 否 String 此参数的定义取决于 type 的取值。
  • 如果 type 取值为 extension，此参数定义分机的完整名称。
  • 如果 type 取值为 ext_group，此参数定义分机组的名称。
  • 如果 type 取值为 external，此参数定义外部号码的名字；当 text3 未取值时，此参数必填。
text2 否 String 此参数的定义取决于 type 的取值。
  • 如果 type 取值为 extension，此参数定义分机号。
  • 如果 type 取值为 ext_group，此参数定义分机组的名称。
  • 如果 type 取值为 external，此参数定义外部号码且必填。
text3 否 String 外部号码的姓氏。
注： 如果 type 取值为 external 且 text 未取值，此参数必填。
text4 否 String 外部号码的呼出前缀。

响应参数

参数 类型 说明
errcode Integer 返回错误码。
  • 0：请求成功。
  • 非零值：请求失败。
注： 更多错误码和错误信息说明，请参见 错误码 & 错误信息。
errmsg String 返回信息。
  • SUCCESS：请求成功。
  • FAILURE：请求失败。
id Integer 响铃组的唯一 ID。

示例

请求示例

  • 添加响铃策略为 ring_all 的响铃组。
    POST /openapi/v1.0/ringgroup/create?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 

Host: yeastardocs.example.yeastarcloud.com
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"
        },
        {
            "value": "external_6300_8819167453692",
            "type": "external",
            "text": "Leo",
            "text2": "19167453692",
            "text3": "Bell",
            "text4": "88"
        }
    ],
    "external_number_call_confirm":1,
    "fail_dest": "end_call",
    "enable_time_condition":1,
    "timezone_id": 1,   
    "outoffice_dest": "receive_call",
    "holiday_dest": "play_greeting",
    "holiday_dest_prefix": "1",
    "holiday_dest_value": "userinput_TTS.wav",
    "enb_play_holiday_prompt_global":1
}
  • 添加响铃策略为 custom 的响铃组。
    POST /openapi/v1.0/ringgroup/create?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 

Host: yeastardocs.example.yeastarcloud.com
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"
                },
                {
                    "value": "external_6301_8819167453332",
                    "type": "external",
                    "text": "Emma",
                    "text2": "19167453332",
                    "text3": "Wilson",
                    "text4": "88"
                 }
            ],
            "delay_time": 20,
            "timeout":20
        }
    ],
    "external_number_call_confirm":1,
    "fail_dest": "end_call"
}
响应示例
HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 8023
}