添加响铃组

添加并配置响铃组。

请求 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 自定义提示音的文件名 (如 demo.wav)。当呼叫进入响铃组时，系统会向呼叫者播放该提示音且仅播放一次。
注：

可使用 获取菜单选项 接口查询自定义提示音的文件名 ("menu":"custom_prompt")。
play_full_join_prompt 否 Integer 系统是否播完欢迎提示音后再响铃成员。
取值范围：
  • 0：启用。
  • 1：禁用。
welcome_prompt 否 String 自定义提示音的文件名 (如 demo.wav) 或等待音乐播放列表的名称。在成员接听来电之前，系统会向呼叫者播放指定的音频。
注： 可使用 获取菜单选项 接口查询自定义提示音的文件名 ("menu":"custom_prompt")，或使用 查询等待音乐列表 接口查询等待音乐播放列表的名称。
moh 否 String 等待音乐播放列表的名称。当通话被保持时，系统会向呼叫者播放该列表中的音频。
注： 可使用 查询等待音乐列表 接口查询等待音乐播放列表的名称.
alert_info 否 String

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

注：
  • 最大字符长度为 31。
  • 仅允许输入数字、字母、空格、以及特殊符号-_。
client_unique_ringtone 否 String 成员的 Linkus 客户端的铃声文件名 (如 Ring1.mp3)。
注： 可使用 查询自定义铃声列表 接口查询铃声文件名。
member_list 是 Array <Ring_Group_Member> 每个响铃组成员的信息。
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 取值为 external_num 或 play_greeting 时必填。
  • 如果 fail_dest 取值为 external_num，此参数定义外部号码的呼出前缀，最大字符长度为 7。
  • 如果 fail_dest 取值为 play_greeting，此参数定义提示音的播放次数，支持 0 - 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 时生效。
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 取值为 external_num 或 play_greeting 时必填。
  • 如果 no_agent_online_dest 取值为 external_num，此参数定义外部号码的呼出前缀，最大字符长度为 7。
  • 如果 no_agent_online_dest 取值为 play_greeting，此参数定义提示音的播放次数，支持 0 - 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 响铃组成员 (分机或分机组) 的 ID。
注：

  • 此参数仅在 ring_strategy 取值为 ring_all、sequentially 或 memory_hunt 时必填。

  • 可使用 搜索特定分机 接口查询分机 ID，或使用 搜索特定分机组 接口查询分机组的 ID。
type 否 String 响铃组成员的类型。

取值范围：

  • extension：分机。
  • ext_group：分机组。
注：

此参数仅在 ring_strategy 取值为 ring_all、sequentially 或 memory_hunt 时必填。
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：分机组。

响应参数

参数 类型 说明
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"
        }
    ],
    "fail_dest": "end_call"
}
  • 添加响铃策略为 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"
                }
            ],
            "delay_time": 20,
            "timeout":20
        }
    ],
    "fail_dest": "end_call"
}
响应示例
HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 8023
}