编辑 IVR

编辑 IVR 的配置。

请求 URL

POST {base_url}/{api_path}/ivr/update?access_token={access_token}

请求参数

参数 是否必填 类型 说明
id 是 Integer IVR 的唯一 ID。
注： 可使用 搜索特定 IVR 接口查询 IVR 的 ID。
number 否 String IVR 号码。
name 否 String IVR 的名称。
prompt 否 String IVR 提示音的名称。
取值范围：
  • default：默认提示音。
  • PBX 系统中已有的自定义提示音名称 (查看路径：PBX 设置 > 提示音 > 自定义提示音)。
注：
  • 最多支持五个提示音。
  • 用半角逗号 , 分隔多个提示音名称。例如 default,IVR.wav。
prompt_repeat 否 Integer IVR 提示音重复播放的最大次数。

取值范围：1 - 5。
resp_timeout 否 Integer IVR 提示音播放完成后，系统等待呼叫者输入按键的响应超时时长 (单位：秒)。

取值范围：1 - 10。

注： 若超时未响应，系统将重复播放 IVR 提示音直至达到最大次数，若此时仍超时无响应，通话将被转移至 响应超时目的地。
digit_timeout 否 Integer 呼叫者输入的按键和下一个按键间隔的超时时长 (单位：秒)。

取值范围：1 - 10。
alert_info 否 String INVITE 请求中 Alert-info 头域携带的 “info” 标签值，用于触发话机进行区别振铃。
client_unique_ringtone 否 String 分机用户接收到来自该 IVR 来电时，其 Linkus 客户端将播放的特色铃声。
取值范围：
  • 空字符串：系统将播放在 Linkus 客户端上设置的自定义铃声。
  • 其他值：铃声的文件名 (如 Ring1.mp3)。
    注： 可使用 查询自定义铃声列表 接口查询铃声文件名。
dial_ext_option 否 String 是否允许呼叫者通过该 IVR 拨打分机。

取值范围：

  • disable：禁止拨打分机。
  • all：允许拨打所有分机。
  • allow：允许拨打指定的分机。
  • restrict：禁止拨打指定的分机。
dial_ext_list 否 Array <Allow_Ext_List> 允许呼叫者在 IVR 中呼叫的分机或分机组。
注： 当 dial_ext_option 取值为 allow 时，该参数 必填。
restrict_dial_ext_list 否 Array <Restrict_Ext_List> 禁止呼叫者在 IVR 中呼叫的分机或分机组。
注： 当 dial_ext_option 取值为 restrict 时，该参数 必填。
enb_dial_call_number 否 Integer 是否允许呼叫者通过 IVR 直接拨打响铃组、队列和会议室号码。

取值范围：

  • 0：禁止。
  • 1：允许。
dial_call_number_list 否 Array <Allow_Call_Number_List> 允许呼叫者通过 IVR 拨打响铃组、队列和会议室的号码。
enb_dial_outb_routes 否 Integer 是否允许呼叫者在 IVR 中使用呼出路由拨打外线电话。

取值范围：

  • 0：禁止。
  • 1：允许。
dial_outb_route_list 否 Array <Allow_Route_List> 允许呼叫者在 IVR 中使用的呼出路由。
注： 当 enb_dial_outb_routes 取值为 1 时，该参数 必填。
enb_dial_check_vm 否 Integer 是否允许呼叫者通过 IVR 查阅语音留言。

取值范围：

  • 0：禁止。
  • 1：允许。
prompt_manger_enb 否 Integer 是否允许呼叫者拨打特征码 #9 修改 IVR 提示音。

取值范围：

  • 0：禁止。
  • 1：允许。
prompt_manger_password 否 String 设置用于修改 IVR 提示音的密码。
注： 当 prompt_manger_enb 取值为 1 时，此参数为 必填。
enb_dest_caller_id_name 否 String 是否启用为按键事件配置附加来电显示名称的功能。

取值范围：

  • 0：禁用。
  • 1：启用。
pressX_dest 否 String 按键 X 的目的地类型。
注： X 指代 0-9 之间的具体数字。
取值范围：
  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • ivr：IVR。
  • call_flow：通话流程。
  • ai_receptionist：AI 接待员。
  • ring_group：响铃组。
  • queue：队列。
  • group_vm：群语音信箱。
  • conference：会议室。
  • dial_by_name：通过名称呼叫。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
  • play_prompt：播放提示音后返回当前 IVR。
  • send_sms：发送 SMS 消息。
  • send_whatsapp：发送 WhatsApp 消息。
pressX_dest_prefix 否 String

此参数的设置取决于按键 X 的目的地类型 (pressX_dest)。

注： X 指代 0-9 之间的具体数字。
  • 当目的地类型为 external_num 时，此参数用于指定外部号码的拨号前缀。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数指定提示音的播放次数，其取值范围为 1 - 5。
pressX_dest_value 否 String 设置按键 X 的目的地。此参数的设置取决于按键 X 的目的地类型 (pressX_dest)。
注： X 指代 0-9 之间的具体数字。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数用于指定自定义提示音的文件名。例如：demo.wav。
  • 当目的地类型为 extension、ext_vm、ivr、call_flow、ring_group、queue、group_vm、或 conference 时，此参数用于指定目的地的 ID。

    例如：目的地为分机 2002，则将该参数设置为分机 2002 的 ID 2。

  • 当目的地的类型为 external_num 时，此参数用于指定外部号码。
pressX_message_config 否 Object <Key_Destination_Message> 按键 X 触发的消息的配置。
注： 此参数在 pressX_dest 设置为 send_sms 或 send_whatsapp 时必填。
pressX_dest_caller_id_name 否 String 按键 X 的附加来电显示名称。

当按键 X 事件被触发时，来电被路由至相关目的地，该名称被拼接到原来电显示名称之前并显示在被叫的来电窗口中。

注：
  • X 指代为 0-9 之间的具体数字。
  • 此参数仅在 enb_dest_caller_id_name 设置为 1 且 pressX_dest 设置为 ring_group 或 queue 时生效。
  • 最大字符长度为 127。
allow_out_recordX 否 Integer 通话路由至按键 X 的目的地后，停止对该通话进行录音。
注： X 指代 0-9 之间的具体数字。

取值范围：

  • 0：禁用。
  • 1：启用。
press_hash_dest 否 String 按键 # 的目的地类型。

取值范围：

  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • ivr：IVR。
  • call_flow：通话流程。
  • ai_receptionist：AI 接待员。
  • ring_group：响铃组。
  • queue：队列。
  • group_vm：群语音信箱。
  • conference：会议室。
  • dial_by_name：通过名称呼叫。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
  • play_prompt：播放提示音后返回当前 IVR。
  • send_sms：发送 SMS 消息。
  • send_whatsapp：发送 WhatsApp 消息。
press_hash_dest_prefix 否 String 此参数的设置取决于按键 # 的目的地类型。
  • 当目的地类型为 external_num 时，此参数用于指定外部号码的拨号前缀。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数指定提示音的播放次数，其取值范围为 1 - 5。
press_hash_dest_value 否 String 按键 # 的目的地。此参数的设置取决于按键 # 的目的地类型。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数用于指定自定义提示音的文件名。例如：demo.wav。
  • 当目的地类型为 extension、ext_vm、ivr、call_flow、ring_group、queue、group_vm、或 conference 时，此参数用于指定目的地的 ID。

    例如：目的地为分机 2002，则将该参数设置为分机 2002 的 ID 2。

  • 当目的地的类型为 external_num 时，此参数用于指定外部号码。
press_hash_message_config 否 Object <Key_Destination_Message> 按键 # 触发的消息的配置。
注： 此参数在 press_hash_dest 设置为 send_sms 或 send_whatsapp 时必填。
press_hash_dest_caller_id_name 否 String 按键 # 的附加来电显示名称。

当按键 # 事件被触发时，来电被路由至相关目的地，该名称被拼接到原来电显示名称之前并显示在被叫的来电窗口中。

注：
  • 此参数仅在 enb_dest_caller_id_name 设置为 1 且 press_hash_dest 设置为 ring_group 或 queue 时生效。
  • 最大字符长度为 127。
allow_out_record_hash 否 Integer 通话路由至按键 # 的目的地后，停止对该通话进行录音。

取值范围：

  • 0：禁用。
  • 1：启用。
press_star_dest 否 String 按键 * 的目的地类型。

取值范围：

  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • ivr：IVR。
  • call_flow：通话流程。
  • ai_receptionist：AI 接待员。
  • ring_group：响铃组。
  • queue：队列。
  • group_vm：群语音信箱。
  • conference：会议室。
  • dial_by_name：通过名称呼叫。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
  • play_prompt：播放提示音后返回当前 IVR。
  • send_sms：发送 SMS 消息。
  • send_whatsapp：发送 WhatsApp 消息。
press_star_dest_prefix 否 String 此参数的设置取决于按键 * 的目的地类型。
  • 当目的地类型为 external_num 时，此参数用于指定外部号码的拨号前缀。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数指定提示音的播放次数，其取值范围为 1 - 5。
press_star_dest_value 否 String 按键 * 的目的地。此参数的设置取决于按键 * 的目的地类型。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数用于指定自定义提示音的文件名。例如：demo.wav。
  • 当目的地类型为 extension、ext_vm、ivr、call_flow、ring_group、queue、group_vm、或 conference 时，此参数用于指定目的地的 ID。

    例如：目的地为分机 2002，则将该参数设置为分机 2002 的 ID 2。

  • 当目的地的类型为 external_num 时，此参数用于指定外部号码。
press_star_message_config 否 Object <Key_Destination_Message> 按键 * 触发的消息的配置。
注： 此参数在 press_star_dest 设置为 send_sms 或 send_whatsapp 时必填。
press_star_dest_caller_id_name 否 String 按键 * 的附加来电显示名称。

当按键 * 事件被触发时，来电被路由至相关目的地，该名称被拼接到原来电显示名称之前并显示在被叫的来电窗口中。

注：
  • 此参数仅在 enb_dest_caller_id_name 设置为 1 且 press_star_dest 设置为 ring_group 或 queue 时生效。
  • 最大字符长度为 127。
allow_out_record_star 否 Integer 通话路由至按键 * 的目的地后，停止对该通话进行录音。

取值范围：

  • 0：禁用。
  • 1：启用。
timeout_dest 否 String 响应超时的目的地类型。
注： 响应超时是指当系统重复播放提示音达到最大次数后，呼叫者在限定时间内仍未执行任何操作。

取值范围：

  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • ivr：IVR。
  • call_flow：通话流程。
  • ai_receptionist：AI 接待员。
  • ring_group：响铃组。
  • queue：队列。
  • group_vm：群语音信箱。
  • conference：会议室。
  • dial_by_name：通过名称呼叫。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
  • play_prompt：播放提示音后返回当前 IVR。
timeout_dest_prefix 否 String 此参数的设置取决于响应超时的目的地类型。
  • 当目的地类型为 external_num 时，此参数用于指定外部号码的拨号前缀。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数指定提示音的播放次数，其取值范围为 1 - 5。
timeout_dest_value 否 String 响应超时的目的地。此参数的设置取决于响应超时的目的地类型。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数用于指定自定义提示音的文件名。例如：demo.wav。
  • 当目的地类型为 extension、ext_vm、ivr、call_flow、ring_group、queue、group_vm、或 conference 时，此参数用于指定目的地的 ID。

    例如：目的地为分机 2002，则将该参数设置为分机 2002 的 ID 2。

  • 当目的地的类型为 external_num 时，此参数用于指定外部号码。
timeout_dest_caller_id_name 否 String 响应超时的附加来电显示名称。

一旦来电响应超时，来电被路由至相关目的地，该名称被拼接到原来电显示名称之前并显示在被叫的来电窗口中。

注：
  • 此参数仅在 enb_dest_caller_id_name 设置为 1 且 timeout_dest 设置为 ring_group 或 queue 时生效。
  • 最大字符长度为 127。
allow_out_record_timeout 否 Integer 通话路由至响应超时的目的地后，停止对该通话进行录音。

取值范围：

  • 0：禁用。
  • 1：启用。
invalid_dest 否 String 无效按键的目的地类型。

取值范围：

  • end_call：挂断。
  • extension：分机。
  • ext_vm：分机语音信箱。
  • ivr：IVR。
  • call_flow：通话流程。
  • ai_receptionist：AI 接待员。
  • ring_group：响铃组。
  • queue：队列。
  • group_vm：群语音信箱。
  • conference：会议室。
  • dial_by_name：通过名称呼叫。
  • external_num：外部号码。
  • play_greeting：播放提示音后退出。
  • play_prompt：播放提示音后返回当前 IVR。
  • send_sms：发送 SMS 消息。
  • send_whatsapp：发送 WhatsApp 消息。
invalid_dest_prefix 否 String 此参数的设置取决于无效按键的目的地类型。
  • 当目的地类型为 external_num 时，此参数用于指定外部号码的拨号前缀。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数指定提示音的播放次数，其取值范围为 1 - 5。
invalid_dest_value 否 String 无效按键的目的地。此参数的设置取决于无效按键的目的地类型。
  • 当目的地类型为 play_greeting 或 play_prompt 时，此参数用于指定自定义提示音的文件名。例如：demo.wav。
  • 当目的地类型为 extension、ext_vm、ivr、call_flow、ring_group、queue、group_vm、或 conference 时，此参数用于指定目的地的 ID。

    例如：目的地为分机 2002，则将该参数设置为分机 2002 的 ID 2。

  • 当目的地的类型为 external_num 时，此参数用于指定外部号码。
invalid_message_config 否 Object <Key_Destination_Message> 无效按键触发的消息的配置。
注： 此参数在 invalid_dest 设置为 send_sms 或 send_whatsapp 时必填。
invalid_dest_caller_id_name 否 String 无效按键的附加来电显示名称。

如果输入无效按键，来电被路由至相关目的地，该名称被拼接到原来电显示名称之前并显示在被叫的来电窗口中。

注：
  • 此参数仅在 enb_dest_caller_id_name 设置为 1 且 invalid_dest 设置为 ring_group 或 queue 时生效。
  • 最大字符长度为 127。
allow_out_record_invalid 否 Integer 通话路由至无效按键的目的地后，停止对该通话进行录音。

取值范围：

  • 0：禁用。
  • 1：启用。
Allow_Ext_List
参数 是否必填 类型 说明
value 是 String 允许呼叫的分机 / 分机组 / 部门的 ID。
注： 可使用 获取菜单选项 接口查询分机、分机组及部门的 ID。
type 是 String 允许呼叫对象的类型。

取值范围：

  • extension：分机。
  • ext_group：分机组。
  • organization：部门。
Restrict_Ext_List
参数 是否必填 类型 说明
value 是 String 禁止呼叫的分机 / 分机组 / 部门的 ID。
注： 可使用 获取菜单选项 接口查询分机、分机组及部门的 ID。
type 是 String 禁止呼叫对象的类型。

取值范围：

  • extension：分机。
  • ext_group：分机组。
  • organization：部门。
Allow_Call_Number_List
参数 是否必填 类型 说明
value 是 String 允许呼叫者通过 IVR 拨打的响铃组 / 队列 / 会议室的 ID。
注： 你可以通过 获取菜单选项 查询所需的响铃组、队列和会议室的 ID。
type 是 String 允许呼叫者通过 IVR 呼叫的类型。
  • ring_group
  • queue
  • conference
Allow_Route_List
参数 是否必填 类型 说明
text 否 String 允许呼叫者使用的呼出路由的名称。
value 是 String 允许呼叫者使用的呼出路由的 ID。
注： 可使用 搜索特定呼出路由 接口查询呼出路由的 ID。
Key_Destination_Message
参数 是否必填 类型 说明
sms_config 否 Object <SMS_Channel_Message> 按键事件触发的自动回复 SMS 消息配置。
注： 此参数在 whatsapp_config 未设置时必填。
whatsapp_config 否 Object <WhatsApp_Channel_Message> 按键事件触发的自动回复 WhatsApp 消息配置。
注： 此参数在 sms_config 未设置时必填。

SMS_Channel_Message

参数 是否必填 类型 说明
content 否 String 要发送的内容。
注：
  • 最大字符长度为 1600。
  • 此参数在 msg_type 设置为 1 时必填。
did_id 是 Integer SMS 消息渠道的 DID 号码。
注： 可使用 获取菜单选项 接口查询 SMS 消息渠道可用的 DID 号码 ("menu":"message_channel")。
msg_type 否 Integer SMS 消息的类型。

取值范围：

  • 1：文本。
  • 2：文件。
    注： 该值仅对按键事件生效。
file_content 否 String 文件中的 JSON 内容。
注：
  • 此参数在 msg_type 设置为 2 时必填。
  • 可使用 上传消息文件 接口上传消息文件，然后使用接口响应结果中单个文件的 JSON 序列化结果设置此参数。

WhatsApp_Channel_Message

参数 是否必填 类型 说明
did_id 是 Integer WhatsApp 消息渠道的 DID 号码。
注： 可使用 获取菜单选项 接口查询 WhatsApp 消息渠道可用的 DID 号码 ("menu":"message_channel")。
template_params 是 String WhatsApp 消息模板的 JSON 内容。
注： 可使用 获取 WhatsApp 消息模板 接口查询完整的 JSON 内容。

响应参数

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

示例

请求示例

更新 ID 为 1 的 IVR 配置：
  • 替换名称为 “自助语音导航”。
  • 允许呼叫者通过 IVR 拨打 ID 为 85 的分机。
  • 修改按键 # 的事件为播放两次提示音后退出。
POST /openapi/v1.0/ivr/update?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 

Host: yeastardocs.example.yeastarcloud.com
Content-Type: application/json
{
    "id":1,
    "name": "自助语音导航",
    "dial_ext_option": "allow",
    "dial_ext_list": [
       {
            "value": "85",
            "type": "extension"
        }
    ],
    "press_hash_dest": "play_greeting",
    "press_hash_dest_prefix": "2",
    "press_hash_dest_value": "IVR.wav"
}
响应示例
HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS"
}