Skip to Content

Add an IVR

Add and configure an IVR.

Request URL

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

Request parameters

ParameterRequiredTypeDescription
numberYesStringIVR number.
nameYesStringIVR name.
promptYesStringThe 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_repeatYesIntegerThe maximum number of times the IVR prompt will be repeated.

Valid value: 1 - 5.

resp_timeoutYesIntegerThe 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_timeoutYesIntegerThe timeout duration between the caller inputting a key and the next key (Unit: Second).

Valid value: 1 - 10.

alert_infoNoStringThe "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_ringtoneNoStringThe distinctive ringtone that will be played on agents' Simu Connect clients when they receive calls from this IVR.
Valid value:
  • Built-in ringtones: Ring{x}.mp3 (where x = 0 - 10).
  • Custom ringtone: The file name of an existing custom ringtone on the PBX (Path: PBX Settings > Voice Prompt > Custom Ringtone). E.g. example.wav.
dial_ext_optionYesStringWhether 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_listNoArray <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_listNoArray <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_numberNoIntegerWhether 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_listNoArray <Allow_Call_Number_List>Ring group, queue, and conference room numbers that callers are allowed to call via the IVR.
enb_dial_outb_routesNoIntegerWhether to allow callers to use outbound routes to make outbound calls from the IVR.

Valid value:

  • 0: Disallow.
  • 1: Allow.
dial_outb_route_listNoArray <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_vmNoIntegerWhether to allow callers to check voicemail via IVR.

Valid value:

  • 0: Disallow.
  • 1: Allow.
prompt_manger_enbNoIntegerWhether to allow users to dial the feature code #9 to modify the IVR prompt.Valid value:
  • 0: Disallow.
  • 1: Allow.
prompt_manger_passwordNoStringThe password for modifying IVR prompts.
Note: This parameter is required when prompt_manger_enb is set to 1.
pressX_destNoStringThe 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.
pressX_dest_prefixNoString

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_valueNoStringThe 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.
allow_out_recordXNoIntegerAfter 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: Disabled.
  • 1: Enabled.
press_hash_destNoStringThe 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.
press_hash_dest_prefixNoStringThis 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_valueNoStringThe 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.
allow_out_record_hashNoIntegerAfter a call has been routed to the destination of key #, stop recording the call.
Valid value:
  • 0: Disabled.
  • 1: Enabled.
press_star_destNoStringThe 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.
press_star_dest_prefixNoStringThe 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_valueNoStringThe 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.
allow_out_record_starNoIntegerAfter a call has been routed to the destination of key *, stop recording the call.

Valid value:

  • 0: Disabled.
  • 1: Enabled.
timeout_destNoStringThe 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_prefixNoStringThis 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_valueNoStringThe 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.
allow_out_record_timeoutNoIntegerAfter a call has been routed to the destination of Response Timeout, stop recording the call.

Valid value:

  • 0: Disabled.
  • 1: Enabled.
invalid_destNoStringThe 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.
invalid_dest_prefixNoStringThis 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_valueNoStringThe 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.
allow_out_record_invalidNoIntegerAfter a call has been routed to the destination of invalid input, stop recording the call.

Valid value:

  • 0: Disabled.
  • 1: Enabled.

Allow_Ext_List

ParameterRequiredTypeDescription
valueYesStringThe 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.
typeYesStringThe type of the object that callers are allowed to call.

Valid value:

  • extension
  • ext_group
  • organization

Restrict_Ext_List

ParameterRequiredTypeDescription
valueYesStringThe 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.
typeYesStringThe type of the object that callers are prohibited from calling.

Valid value:

  • extension
  • ext_group
  • organization

Allow_Call_Number_List

ParameterRequiredTypeDescription
valueYesStringThe 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.
typeYesStringThe type of the object that callers are allowed to call via the IVR.
  • ring_group
  • queue
  • conference

Allow_Route_List

ParameterRequiredTypeDescription
textNoStringThe name of the outbound route that callers are allowed to use.
valueYesStringThe 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.

Response parameters

ParameterTypeDescription
errcodeIntegerReturned error code.
  • 0: Succeed.
  • Non-zero value: Failed.
Note:You can check the error code and error message in Error Code and Error Message.
errmsgStringReturned message.
  • SUCCESS: Succeed.
  • FAILURE: Failed.
idIntegerThe unique ID of the IVR.

Examples

Request example

POST /openapi/v1.0/ivr/create?access_token=sRuPSzYcPflKgdwSVpA1lhxlVLw0q0z1 HTTP/1.1 
Host: 192.168.5.150:8088
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
}