Add an IVR

Add and configure an IVR.

Request URL

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

Request parameters

Parameter Required Type Description
number Yes String IVR number.
name Yes String IVR name.
prompt Yes String The name of the IVR prompt.
Valid value:
  • default: The default prompt.
  • Name of the existing custom prompt file on PBX (Path: PBX Settings > Voice Prompt > Custom Prompt).
Note:
  • Up to 5 prompts are supported.
  • Use a comma to separate multiple custom prompt file names. E.g. default,IVR.wav.
prompt_repeat Yes Integer The maximum number of times the IVR prompt will be repeated.

Valid value: 1 - 5.
resp_timeout Yes Integer The timeout duration for callers to input keys after playing the IVR prompt (Unit: Second).

Valid value: 1 - 10.

Note: If no input is received after the timeout, the system will repeat the IVR prompt until the maximum number of times is reached. If there is still no input after the timeout, the call will be routed to the Timeout Destination.
digit_timeout Yes Integer The timeout duration between the caller inputting a key and the next key (Unit: Second).

Valid value: 1 - 10.
alert_info No String The "Alert-info" Header in the INVITE request to trigger the IP phone to play distinctive ringtones when receiving an incoming call from this IVR.
client_unique_ringtone No String The distinctive ringtone that will be played on agents' Linkus clients when they receive calls from this IVR.
Valid value:
  • Empty string: The system will use the ringtone set on the Linkus clients.
  • Other value: The filename of the ringtone (e.g. Ring1.mp3).
    Note: You can query the ringtone name using Query Custom Ringtone List.
dial_ext_option Yes String Whether to allow callers to dial extensions via IVR.

Valid value:

  • disable: Prohibit callers from dialing any extensions.
  • all: Allow callers to dial all extensions.
  • allow: Allow callers to dial specified extensions.
  • restrict: Prohibit callers from dialing specified extensions.
dial_ext_list No Array <Allow_Ext_List> Extensions or extension groups that callers are allowed to call within the IVR.
Note: This parameter is required when dial_ext_option is set to allow.
restrict_dial_ext_list No Array <Restrict_Ext_List> Extensions or extension groups that callers are prohibited from calling within the IVR.
Note: This parameter is required when dial_ext_option is set to restrict.
enb_dial_call_number No Integer Whether to allow callers to directly dial ring group, queue, and conference room numbers via the IVR.

Valid value:

  • 0: Disallow.
  • 1: Allow.
dial_call_number_list No Array <Allow_Call_Number_List> Ring group, queue, and conference room numbers that callers are allowed to call via the IVR.
enb_dial_outb_routes No Integer Whether to allow callers to use outbound routes to make outbound calls from the IVR.

Valid value:

  • 0: Disallow.
  • 1: Allow.
dial_outb_route_list No Array <Allow_Route_List> The outbound route that callers are allowed to use within the IVR.
Note: This parameter is required when enb_dial_outb_routes is set to 1.
enb_dial_check_vm No Integer Whether to allow callers to check voicemail via IVR.

Valid value:

  • 0: Disallow.
  • 1: Allow.
prompt_manger_enb No Integer Whether to allow users to dial the feature code #9 to modify the IVR prompt.
Valid value:
  • 0: Disallow.
  • 1: Allow.
prompt_manger_password No String The password for modifying IVR prompts.
Note: This parameter is required when prompt_manger_enb is set to 1.
enb_dest_caller_id_name No String Whether to enable configuring additional caller ID name for key events.

Valid value:

  • 0: Disable.
  • 1: Enable.
pressX_dest No String The destination type of key X.
Note: X refers to a specific number between 0 and 9.
Valid value:
  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.
pressX_dest_prefix No String

This parameter defines different settings depending on the destination type of key X (pressX_dest).

Note: X refers to a specific number between 0 and 9.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.
pressX_dest_value No String The destination of key X. This parameter defines different settings depending on the destination type of key X (pressX_dest).
Note: X refers to a specific number between 0 and 9.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.
pressX_message_config No Object <Key_Destination_Message> The configuration for messages triggered by key X.
Note: This parameter is required when pressX_dest is set to send_sms or send_whatsapp.
pressX_dest_caller_id_name No String The additional caller ID name for key X.

When the key X event is triggered, the call is routed to corresponding destination, and this name is prepended to the original caller ID name and displayed on the callee's incoming call window.

Note:
  • X refers to a specific number between 0 and 9.
  • This parameter takes effect only when enb_dest_caller_id_name is set to 1 and pressX_dest is set to ring_group or queue.
  • The maximum character length is 127.
allow_out_recordX No Integer After a call has been routed to the destination of key X, stop recording the call.
Note: X refers to a specific number between 0 and 9.
Valid value:
  • 0: Disable.
  • 1: Enable.
press_hash_dest No String The destination type of key #.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.
press_hash_dest_prefix No String This parameter defines different settings depending on the destination type of key #.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.
press_hash_dest_value No String The destination of key #. This parameter defines different settings depending on the destination type of key #.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.
press_hash_message_config No Object <Key_Destination_Message> The configuration for messages triggered by key #.
Note: This parameter is required when press_hash_dest is set to send_sms or send_whatsapp.
press_hash_dest_caller_id_name No String The additional caller ID name for key #.

When the key # event is triggered, the call is routed to corresponding destination, and this name is prepended to the original caller ID name and displayed on the callee's incoming call window.

Note:
  • This parameter takes effect only when enb_dest_caller_id_name is set to 1 and press_hash_dest is set to ring_group or queue.
  • The maximum character length is 127.
allow_out_record_hash No Integer After a call has been routed to the destination of key #, stop recording the call.
Valid value:
  • 0: Disable.
  • 1: Enable.
press_star_dest No String The destination type of key *.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.
press_star_dest_prefix No String The parameter defines different settings depending on the destination type of key *.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.
press_star_dest_value No String The destination of key *. This parameter defines different settings depending on the destination type of key *.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.
press_star_message_config No Object <Key_Destination_Message> The configuration for messages triggered by key *.
Note: This parameter is required when press_star_dest is set to send_sms or send_whatsapp.
press_star_dest_caller_id_name No String The additional caller ID name for key *.

When the key * event is triggered, the call is routed to corresponding destination, and this name is prepended to the original caller ID name and displayed on the callee's incoming call window.

Note:
  • This parameter takes effect only when enb_dest_caller_id_name is set to 1 and press_star_dest is set to ring_group or queue.
  • The maximum character length is 127.
allow_out_record_star No Integer After a call has been routed to the destination of key *, stop recording the call.

Valid value:

  • 0: Disable.
  • 1: Enable.
timeout_dest No String The destination type of Response Timeout.
Note: Response Timeout occurs when the system has played the prompt repeatedly for the maximum number of times, but the caller has not taken any action within the specified time.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
timeout_dest_prefix No String This parameter defines different settings depending on the destination type of Response Timeout.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.
timeout_dest_value No String The destination of Response Timeout. This parameter defines different settings depending on the destination type of Response Timeout.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.
timeout_dest_caller_id_name No String The additional caller ID name for Response Timeout.

Upon response timeout, the call is routed to corresponding destination, and this name is prepended to the original caller ID name and displayed on the callee's incoming call window.

Note:
  • This parameter takes effect only when enb_dest_caller_id_name is set to 1 and timeout_dest is set to ring_group or queue.
  • The maximum character length is 127.
allow_out_record_timeout No Integer After a call has been routed to the destination of Response Timeout, stop recording the call.

Valid value:

  • 0: Disable.
  • 1: Enable.
invalid_dest No String The destination type of invalid input.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.
invalid_dest_prefix No String This parameter defines different settings depending on the destination type of invalid input.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.
invalid_dest_value No String The destination of invalid input. This parameter defines different settings depending on the destination type of invalid input.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.
invalid_message_config No Object <Key_Destination_Message> The configuration for messages triggered by invalid input.
Note: This parameter is required when invalid_dest is set to send_sms or send_whatsapp.
invalid_dest_caller_id_name No String The additional caller ID name for invalid input.

If the key input is invalid, the call is routed to corresponding destination, and this name is prepended to the original caller ID name and displayed on the callee's incoming call window.

Note:
  • This parameter takes effect only when enb_dest_caller_id_name is set to 1 and invalid_dest is set to ring_group or queue.
  • The maximum character length is 127.
allow_out_record_invalid No Integer After a call has been routed to the destination of invalid input, stop recording the call.

Valid value:

  • 0: Disable.
  • 1: Enable.

enable_time_condition

No

Integer

Whether to enable time condition.

Valid value:

  • 0: Disable.
  • 1: Enable.

time_condition_type

No

String

The time condition type.

Note: Required when enable_time_condition is 1.

Valid value:

  • unified: The same time condition applies to all key presses.
  • custom: A custom time condition applies to each key press.

time_base_mode

No

String

The time-based mode.

Valid value:

  • global_office_time: Based on business hours configured for the time zone.
  • custom_office_time: Based on custom business hours.
  • custom_time_periods: Based on custom time periods.

timezone_id

No

Integer
The ID of the time zone.
Note: You can obtain the ID using the Query Time Zone List interface.

time_conditions

No

 Array<Time_Condition>

Time condition configuration.

press_key_option_list

No

 Array<Keypress_Setting>

IVR key configuration.
Allow_Ext_List
Parameter Required Type Description
value Yes String The ID of the extension / extension group / organization that callers are allowed to call.
Note: You can use Get Menu Options to query ID of the desired extension, extension group, and organization.
type Yes String The type of the object that callers are allowed to call.

Valid value:

  • extension
  • ext_group
  • organization
Restrict_Ext_List
Parameter Required Type Description
value Yes String The ID of the extension / extension group / organization that callers are prohibited from calling.
Note: You can use Get Menu Options to query ID of the desired extension, extension group, and organization.
type Yes String The type of the object that callers are prohibited from calling.

Valid value:

  • extension
  • ext_group
  • organization
Allow_Call_Number_List
Parameter Required Type Description
value Yes String The ID of the ring group / queue / conference that callers are allowed to call via the IVR.
Note: You can use Get Menu Options to query ID of the desired ring group, queue, and conference.
type Yes String The type of the object that callers are allowed to call via the IVR.
  • ring_group
  • queue
  • conference
Allow_Route_List
Parameter Required Type Description
text No String The name of the outbound route that callers are allowed to use.
value Yes String The ID of the outbound route that callers are allowed to use.
Note: You can use Search Specific Outbound Routes to query the ID of the desired outbound route.
Key_Destination_Message
Parameter Required Type Description
sms_config No Object <SMS_Channel_Message> The configuration for SMS messages triggered by keypress events.
Note: This parameter is required when whatsapp_config is not set.
whatsapp_config No Object <WhatsApp_Channel_Message> The configuration for WhatsApp messages triggered by keypress events.
Note: This parameter is required when sms_config is not set.

SMS_Channel_Message

Parameter Required Type Description
content No String The text content to be sent.
Note:
  • The maximum character length is 1600.
  • This parameter is required when msg_type is set to 1.
did_id Yes Integer The DID number of SMS messaging channel.
Note: You can query the available DID number of SMS messaging channel using Get Menu Options ("menu":"message_channel").
msg_type No Integer The type of the SMS message.

Valid value:

  • 1: Text.
  • 2: File.
    Note: This value takes effect only for keypress events.
file_content No String The JSON content in the file.
Note:
  • This parameter is required when msg_type is set to 2.
  • You can upload files for messaging using Upload Files for Messaging, set this parameter to the JSON-serialized result of one single file from the response structure.

WhatsApp_Channel_Message

Parameter Required Type Description
did_id Yes Integer The DID number of WhatsApp messaging channel.
Note: You can query the available DID number of WhatsApp messaging channel using Get Menu Options ("menu":"message_channel").
template_params Yes String The JSON content of WhatsApp message templates.
Note: You can query the complete JSON content using Get WhatsApp Message Templates.
Keypress_Setting
Parameter Required Type Description

time_base_mode

No

String

Time-based mode.

  • all_time
  • global_office_time: Based on business hours configured for the time zone.
  • custom_office_time: Based on custom business hours.
  • custom_time_periods: Based on custom time periods.

time_conditions

No

 Array<Time_Condition>
Time condition configuration.
Note: This parameter takes effect when time_base_mode is custom_time_periods.

timezone_id

No

Integer

The ID of the time zone.

ivr_id

No

Integer

The ID of the IVR.

id

No

Integer

The ID of the record.

press_key

No

String

The key.

  • 0-9
  • *
  • #
  • i: Invalid input
  • t: Response timeout

allow_out_record

No

Integer

 Whether to stop recording the call after it is routed to the destination configured for the key.
Note: This parameter takes effect when time_base_mode is all_time.

Valid value:

  • 0: Disable.
  • 1: Enable.

dest

No

String

The destination type.

Note: This parameter takes effect when time_base_mode is all_time.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.
Note: Effect when time_base_mode is all_time.

dest_prefix

No

String

The destination prefix.

Note: This parameter takes effect when time_base_mode is all_time.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.

dest_value

No

String

 The destination value.
Note: This parameter takes effect when time_base_mode is all_time.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.

dest_caller_id_name

No

String

 The additional caller ID name for the key.

When a call is routed to a ring group or queue through a key, this name is prepended to the original caller ID name and displayed in the callee's incoming call window.

Note: This parameter takes effect when time_base_mode is all_time.

office_allow_out_record

No

Integer

 Whether to stop recording the call after it is routed to the business hours destination.
Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.

Valid value:

  • 0: Disable.
  • 1: Enable.

office_dest

No

String

Business hours destination.

Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.

office_dest_caller_id_name

No

String

 The additional caller ID name for business hours destination.
Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.

When a call is routed to a ring group or queue through a key, this name is prepended to the original caller ID name and displayed in the callee's incoming call window.

office_dest_prefix

No

String

The destination prefix.

Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.

office_dest_value

No

String

 The destination value for business hours destination.
Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.

non_office_allow_out_record

No

Integer

 Whether to stop recording the call after it is routed to outside business hours destination.
Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.

Valid value:

  • 0: Disable.
  • 1: Enable.

non_office_dest

No

String

Outside business hours destination.

Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.

non_office_dest_caller_id_name

No

String

 The additional caller ID name for the outside business hours destination.
Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.

When a call is routed to a ring group or queue through a key, this name is prepended to the original caller ID name and displayed in the callee's incoming call window.

non_office_dest_prefix

No

String

The destination prefix.

Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.

non_office_dest_value

No

String

 The value for the destination outside business hours.
Note: This parameter takes effect when time_base_mode is global_office_time or custom_office_time.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.

holiday_allow_out_record

No

Integer

 Whether to stop recording the call after it is routed to the holiday destination.

Valid value:

  • 0: Disable.
  • 1: Enable.

holiday_dest

No

String

Holiday destination.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.

holiday_dest_caller_id_name

No

String

 The additional caller ID name for the holiday destination.

When a call is routed to a ring group or queue through a key, this name is prepended to the original caller ID name and displayed in the callee's incoming call window.

holiday_dest_prefix

No

String

The prefix for the holiday destination.

  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.

holiday_dest_value

No

String

 The destination value for holiday destination.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.

default_allow_out_record

No

Integer

 Whether to stop recording the call it is routed to the default destination.
Note: This parameter takes effect when time_base_mode is custom_time_periods and no time period matches.

Valid value:

  • 0: Disable.
  • 1: Enable.

default_dest

No

String

Default destination.

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.

default_dest_caller_id_name

No

String

 The additional caller ID name for default destination.

When a call is routed to a ring group or queue through a key, this name is prepended to the original caller ID name and displayed in the callee's incoming call window.

Note: This parameter takes effect when time_base_mode is all_time.

default_dest_prefix

No

String

The destination prefix for default destination.

Note: This parameter takes effect when time_base_mode is all_time.
  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.

default_dest_value

No

String

 The destination value for default destination.
Note: This parameter takes effect when time_base_mode is all_time.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.

ignore_holiday_dest

No

Integer

Whether to ignore holiday destination.

Valid value:
  • 0: Disabled
  • 1: Enabled
Time_Condition
Parameter Required Type Description

allow_out_record

No

Integer

 Whether to stop recording the call after it is routed to the destination of key.

Valid value:

  • 0: Disable.
  • 1: Enable.
months No String The months during which the business hour applies.
Note:
  • This parameter takes effect only when the advanced time condition is enabled (time_condition_switch is 1).
  • Separate multiple months by spaces.

Valid value:

  • all: Every month.
  • jan: January.
  • feb: February.
  • mar: March.
  • apr: April.
  • may: May.
  • jun: June.
  • jul: July.
  • aug: August.
  • sep: September.
  • oct: October.
  • nov: November.
  • dec: December.
days No String The days of the month on which the business hour applies.
Note: This parameter takes effect only when the advanced time condition is enabled (time_condition_switch is 1).

Valid value:

  • all: Every day.
  • 1 - 31
days_of_week No String The days of the week on which the business hour applies.
Note:
  • Required when time_condition_switch is 0.
  • Separate multiple values by spaces.

Valid value:

  • all: Every day.
  • sun: Sunday.
  • mon: Monday.
  • tue: Tuesday.
  • wed: Wednesday.
  • thu: Thursday.
  • fri: Friday.
  • sat: Saturday.

office_times

No

 Array<Time_Period>

Office time period list.
time_condition_switch No Integer Whether to enable the advanced time condition.

Valid value:

  • 0: Disabled.
  • 1: Enabled.
    Note: If enabled, the months and days parameters take effect.

dest

No

String

 The destination type of key.

Valid value:

  • end_call: Hang Up.
  • extension: Extension.
  • ext_vm: Extension Voicemail.
  • ivr: IVR.
  • call_flow: Call Flow.
  • ai_receptionist: AI Receptionist.
  • ring_group: Ring Group.
  • queue: Queue.
  • group_vm: Group Voicemail.
  • conference: Conference.
  • dial_by_name: Dial by Name.
  • external_num: External Number.
  • play_greeting: Play Prompt and Exit.
  • play_prompt: Play Prompt and Return to IVR.
  • send_sms: Send SMS messages.
  • send_whatsapp: Send WhatsApp messages.

dest_prefix

No

String

The destination prefix.

  • When the destination type is external_num, this parameter defines the dial-out prefix of the external number.
  • When the destination type is play_greeting or play_prompt, this parameter defines the play count of the prompt. The valid value is 1 - 5.

dest_value

No

String

 The destination value.
  • When the destination type is play_greeting or play_prompt, this parameter defines the custom prompt file name. E.g. demo.wav.
  • When the destination type is extension, ext_vm, ivr,call_flow, ring_group, queue, group_vm, or conference, 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.

  • When the destination type is external_num, this parameter defines the external number.

dest_caller_id_name

No

String

 The additional caller ID name for the key.

When a call is routed to a ring group or queue through a key, this name is prepended to the original caller ID name and displayed in the callee's incoming call window.
Time_Period
Parameter Type Description
value String The time period in the format HH:MM-HH:MM.
Note: The end time must be later than the start time.

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 IVR.

Examples

Request example
POST /openapi/v1.0/ivr/create?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 

Host: yeastardocs.example.yeastarcloud.com
Content-Type:  application/json
{
    "number":  "6210",
    "name":  "VoiceMenu Navigator",
    "prompt":  "default",
    "prompt_repeat":  3,
    "resp_timeout":  3,
    "digit_timeout":  3,
    "alert_info":  "",
    "client_unique_ringtone": "example.wav",
    "dial_ext_option":  "allow",
    "dial_ext_list":  [
        {
            "value":  "85",
            "type":  "extension"
        },
        {
            "value":  "86",
            "type":  "ext_group"
        }
    ],
    "enb_dial_outb_routes":  1,
    "dial_outb_route_list":  [
        {
            "text":  "",
            "value":  "1"
        }
    ],
    "enb_dial_call_number": 1,
    "dial_call_number_list": [
         {
             "value": "1",
             "type": "conference"
            },
            {
             "value": "1",
             "type": "ring_group"
            },
            {
             "value": "1",
             "type": "queue"
            }
        ],
    "enb_dial_check_vm":  0,
    "prompt_manger_enb":  0,
    "prompt_manger_password":  "",
    "press2_dest":  "extension",
    "press2_dest_prefix":  "",
    "press2_dest_value":  "85",
    "allow_out_record2":  1,
    "press3_dest":  "play_greeting",
    "press3_dest_prefix":  "2",
    "press3_dest_value":  "IVR.wav",
    "allow_out_record3":  1,
    "press4_dest":  "external_num",
    "press4_dest_prefix":  "155",
    "press4_dest_value":  "18691000000",
    "allow_out_record4":  1,
    "timeout_dest":  "play_greeting",
    "timeout_dest_prefix":  "1",
    "timeout_dest_value":  "IVR.wav",
    "allow_out_record_timeout":  1,
    "invalid_dest":  "play_prompt",
    "invalid_dest_prefix":  "1",
    "invalid_dest_value":  "IVR.wav",
    "allow_out_record_invaild":  1  
}
Response example
HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 9
}