Add an IVR

Add an IVR to a tenant.

Request URL

POST {base_url}/uc-cconfig/api/v1/ivrs

Request parameters

Headers


Parameter	Required	Type	Description
Authorization	Yes	String	The access token used for authentication. Format: Bearer `{access_token}`.
x-tenant-code	Yes	String	The tenant name. Note: You can obtain tenant name using the Query Tenants interface.

Body parameters


Parameter	Required	Type	Description
extension	Yes	String	The IVR extension number. Note: The extension number must contain 1 - 11 digits and cannot start with `0`.
name	Yes	String	The IVR name.
joinAnnouncement	No	String	The prompt played when a caller enters the IVR. Valid value: `default` Custom prompt ID. Note: You can obtain the ID using the GET /uc-cconfig/api/v1/sounds/options/custom-prompts interface.
repeatAnnouncements	No	Array<String>	The prompt played to remind callers of the available IVR options when they don't provide input within the configured response timeout. Valid value: `default` Custom prompt ID. Note: You can obtain the ID using the GET /uc-cconfig/api/v1/sounds/options/custom-prompts interface. Note: Up to 10 prompts are supported.
maxTimeout	No	Integer	The maximum number of times `repeatAnnouncements` can be played when the caller does not provide input within the configured `responseTimeout`. Valid value: 1 to 5
responseTimeout	No	Integer	The time (in seconds) the system waits for caller input after playing `joinAnnouncement` or `repeatAnnouncements`.
interDigitTimeout	No	Integer	The time (in seconds) the system waits for the caller to enter the next digit.
alertInfo	No	String	The alert-info text to be added to the Alert-Info header of INVITE requests, which is used to trigger IP phones to play a specific ringtone when receiving an IVR call.
dialUser	No	Object<User_List>	The configuration for allowing callers to reach internal users through the IVR.
dialCallFeature	No	Object<Call_Feature_List>	The configuration for allowing callers to reach ring groups or queues through the IVR.
dialOutboundRoutes	No	Object<Outbound_Route_List>	The configuration for allowing callers to reach external numbers through outbound routes via the IVR.
keyPressEvents	No	Object<Keypress_List>	The configuration for keypress events.
timeoutDestination	No	Object<Destination>	The destination to route the call when the caller does not provide any input after `maxTimeout` is reached.
invalidDestination	No	Object<Destination>	The destination to route the call when the caller enters a digit that is not defined in the IVR menu.
timeBasedRoutingEnabled	No	Boolean	Whether to enable time-based routing. Valid value: `true`: Enabled `false`: Disabled
timeBasedRoutingProfileId	No	String	The ID of the business hours profile used for time-based routing.
timeBasedRoutingConfig	No	Object<Time_Based_Routing>	The time-based routing configuration.
directDidIds	No	Object<Direct_DID_List>	The DID numbers associated with the IVR.

User_List


Parameter	Required	Type	Description
enabled	No	Boolean	Whether to enable direct dialing to internal users. Valid value: `true`: Enabled `false`: Disabled
mode	No	String	The direct dialing mode. `ALL`: Allow callers to reach all users. `ALLOWED`: Allow callers to reach only the specified users. `RESTRICTED`: Allow callers to reach all users except the specified users.
userIds	No	Object<User_ID>	The IDs of internal users. Note: This parameter is required only when `mode` is `ALLOWED` or `RESTRICTED`.

User_ID


Parameter	Required	Type	Description
values	No	Array<String>	The IDs of internal users. Note: You can obtain user ID using the Get Available Users for IVRs interface.

Call_Feature_List


Parameter	Required	Type	Description
enabled	No	Boolean	Whether to allow callers to reach ring groups or queues through the IVR. Valid value: `true`: Enabled `false`: Disabled
items	No	Object<Call_Feature_Items>	The ring groups or queues that callers can reach through the IVR.

Call_Feature_Items


Parameter	Required	Type	Description
values	No	Array<Call_Feature_Item>	The ring groups or queues that callers can reach through the IVR.

Call_Feature_Item


Parameter	Required	Type	Description
type	No	String	The type of call feature. Valid value: `FEATURE_RING_GROUP`: Ring Group `FEATURE_QUEUE`: Queue
value	No	String	The ID of the ring group or queue. Note: You can obtain the ID using the Get Available Ring Groups for IVRs and Get Available Queues for IVRs interfaces.

Outbound_Route_List


Parameter	Required	Type	Description
enabled	No	Boolean	Whether to allow callers to reach external numbers through outbound routes via the IVR. Valid value: `true`: Enabled `false`: Disabled
routeIds	No	Object<Outbound_Route_Item>	The outbound routes that callers can use to reach external numbers through the IVR.

Outbound_Route_Item


Parameter	Required	Type	Description
values	No	Array<String>	The list of outbound route IDs. Note: You can obtain the IDs using the Get Available Outbound Routes for IVRs interface.

Key_Press_List


Parameter	Required	Type	Description
`{keypress}`	No	String	The key pressed by the caller. Valid value: `0` - `9` `*` `#`
`{destination}`	No	Object<Destination>	The destination for calls when the caller presses the specified key.

Time_Based_Routing


Parameter	Required	Type	Description
holidayHandling	No	String	The holiday handling mode. Valid value: `route`: Route IVR calls during holidays to a specific destination. `ignore`: Ignore holidays and route calls according to the business hours settings.
outsideDestination	No	Object<Destination>	The destination for IVR calls received outside business hours.
holidayDestination	No	Object<Destination>	The destination for IVR calls received during holidays.

Destination


Parameter	Required	Type	Description
type	No	String	The destination type. Valid value: `USER` `USER_VOICEMAIL` `IVR` `RING_GROUP` `QUEUE` `EXTERNAL_NUMBER` `HANGUP` `PLAY_PROMPT`: Play the prompt and hang up. `PLAY_PROMPT_RETURN_IVR`: Play the prompt and return to the IVR. `PLAY_IVR_PROMPT`: Play the IVR prompt and return to the IVR.
value	No	String	The destination value. Note: This parameter is required in the following circumstances: When `type` is `USER` or `USER_VOICEMAIL`, you need to specify User ID, which can be obtained from the Get Available Users for IVRs interface. When `type` is `IVR`, `RING_GROUP`, or `QUEUE`, you need to specify call feature ID, which can be obtained from the Get Available IVRs for IVRs, Get Available Ring Groups for IVRs, and Get Available Queues for IVRs interfaces. When `type` is `PLAY_PROMPT` or `PLAY_PROMPT_RETURN_IVR`, you need to specify custom prompt ID, which can be obtained from the GET /sounds/options/custom-prompts interface.
prefix	No	String	The dial-out prefix. Note: This parameter applies only when `type` is `EXTERNAL_NUMBER`.
turnOffRecording	No	Boolean	Whether to turn off call recording. Valid value: `true`: Enabled `false`: Disabled Note: This parameter applies only when `type` is `USER`, `IVR`, `RING_GROUP`, or `QUEUE`.
repeatCount	No	Integer	The number of times to play the prompt when `type` is `PLAY_PROMPT` or `PLAY_PROMPT_RETURN_IVR`.

Direct_DID_List


Parameter	Required	Type	Description
didIds	No	Array<String>	The unique identifier of the DID number. Note: You can obtain the ID using the POST /uc-cconfig/api/v1/dids/search-page interface.
force	No	Boolean	Whether to forcibly replace the occupied DID bindings. Valid value: `true`: If the DID number is occupied, the old binding is deleted and the DID number is associated with the IVR. `false`: If the DID number is occupied, the request fails with `DID_DIRECT_OCCUPIED` response.
warningDidIds	No	Array<String>	The DIDs that are pre-authorized for replacement when `force` is `false`. Note: A DID in this list is replaced directly; a DID not in this list causes `DID_DIRECT_OCCUPIED`.

Response parameters


Parameter	Type	Description
requestId	String	The unique ID of the request, which can be used to quickly locate the request.
code	String	The HTTP status code of the request. `200`: Request succeeded. Non-200 value: Request failed.
message	String	The status message of the request.
detailMessage	String	The detailed error information. When the request is successful, this parameter returns empty.
result	Object<IVR>	The details of the IVR.

IVR


Parameter	Type	Description
id	String	The unique identifier of the IVR.
extension	String	The extension number of the IVR.
name	String	The name of the IVR.
joinAnnouncement	String	The prompt played when a caller enters the IVR.
repeatAnnouncements	Array<String>	The prompt played to remind callers of the available IVR options when no input is received within the response timeout.
maxTimeout	Integer	The maximum number of times the `repeatAnnouncements` can be played when no input is received within the configured `responseTimeout`.
responseTimeout	Integer	The number of seconds the system waits for caller input after playing the `joinAnnouncement` or `repeatAnnouncements`.
interDigitTimeout	Integer	The number of seconds the system waits for the caller to enter the next digit.
alertInfo	String	The alert-info text added to the Alert-Info header of INVITE requests to trigger IP phones to play a specific ringtone when receiving an IVR call.
dialUser	Object<User_List>	The configuration for allowing callers to reach internal users through the IVR.
dialCallFeature	Object<Call_Feature_List>	The configuration for allowing callers to reach ring groups or queues through the IVR.
dialOutboundRoutes	Object<Outbound_Route_List>	The configuration for allowing callers to reach external numbers through outbound routes via the IVR.
keyPressEvents	Object<Keypress_List>	The configuration for keypress events.
timeoutDestination	Object<Destination>	The destination to route the call when the caller does not provide any input after `maxTimeout` is reached.
invalidDestination	Object<Destination>	The destination to route the call when the caller enters a digit that is not defined in the IVR menu.
timeBasedRoutingEnabled	Boolean	Whether time-based routing is enabled. `true`: Enabled `false`: Disabled
timeBasedRoutingProfileId	String	The ID of the business hours profile associated with time-based routing.
timeBasedRoutingConfig	Object<Time_Based_Routing>	The time-based routing configuration.
directDidNumbers	Array<Direct_DID_List>	The DID numbers associated with the IVR.

User_List


Parameter	Type	Description
enabled	Boolean	Whether direct dialing to internal users is enabled.
mode	String	The direct dialing mode. `ALL`: Allow callers to reach all users. `ALLOWED`: Allow callers to reach only the specified users. `RESTRICTED`: Allow callers to reach all users except the specified users. `DISABLED`: Direct dialing is disabled.
userIds	Object<User_ID>	The IDs of internal users. Note: This parameter is returned only when `mode` is `ALLOWED` or `RESTRICTED`.

User_ID


Parameter	Type	Description
values	Array<String>	The list of internal user IDs.

Call_Feature_List


Parameter	Type	Description
enabled	Boolean	Whether callers can reach ring groups or queues through the IVR. `true`: Enabled `false`: Disabled
items	Object<Call_Feature_Items>	The ring groups or queues that callers can reach through the IVR.

Call_Feature_Items


Parameter	Type	Description
values	Array<Call_Feature_Item>	The ring groups or queues that callers can reach through the IVR.

Call_Feature_Item


Parameter	Type	Description
type	String	The type of call feature. `FEATURE_RING_GROUP`: Ring Group `FEATURE_QUEUE`: Queue
value	String	The ID of the ring group or queue.

Outbound_Route_List


Parameter	Type	Description
enabled	Boolean	Whether callers can reach external numbers through outbound routes via the IVR.
routeIds	Object<Outbound_Route_Item>	The outbound routes that callers can use to reach external numbers through the IVR.

Outbound_Route_Item


Parameter	Type	Description
values	Array<String>	The list of outbound route IDs.

Keypress_List


Parameter	Type	Description
`{keypress}`	String	The key pressed by the caller.
`{destination}`	Object<Destination>	The destination for calls when the caller presses the specified key.

Time_Based_Routing_Config


Parameter	Type	Description
holidayHandling	String	The holiday handling mode. `route`: Route IVR calls during holidays to a specific destination. `ignore`: Ignore holidays and route calls according to the business hours settings.
outsideDestination	Object<Destination>	The destination for IVR calls received outside business hours.
holidayDestination	Object<Destination>	The destination for IVR calls received during holidays.

Destination


Parameter	Type	Description
type	String	The destination type. `USER` `USER_VOICEMAIL` `IVR` `RING_GROUP` `QUEUE` `EXTERNAL_NUMBER` `HANGUP` `PLAY_PROMPT`: Play the prompt and hang up. `PLAY_PROMPT_RETURN_IVR`: Play the prompt and return to the IVR. `PLAY_IVR_PROMPT`: Play the IVR prompt and return to the IVR.
value	String	The destination value.
prefix	String	The dial-out prefix.
turnOffRecording	Boolean	Whether call recording is disabled.
repeatCount	Integer	The number of times to play the prompt when `type` is `PLAY_PROMPT` or `PLAY_PROMPT_RETURN_IVR`.

Direct_DID_List


Parameter	Type	Description
id	String	The unique identifier of the DID number.
number	String	The DID number.
name	String	The DID name.

Example

Request example

POST /uc-cconfig/api/v1/ivrs HTTP/1.1
Host: api.cn.novoone.com
Authorization: Bearer eyJraWQiOiJjbi0wLWtleS0xIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkaXN0cmlidXRvcmV4YW1wbGVAb3V0bG9vay5jb20iLCJncmFudF90eXBlIjoib3BlbmFwaSIsImNsaWVudF9leHQiOnsiZGVzY3JpcHRpb24iOiLnrKzkuInmlrnlkIjkvZzkvJnkvLTlupTnlKgiLCJwYXJ0bmVyIjoi56S65L6L5ZCI5L2c5LyZ5Ly0In0sImNsaWVudF90eXBlIjoib3BlbmFwaSIsImV4cCI6MTc5MDc3Mzc4NSwiaWF0IjoxNzkwNzUyMTg1LCJqdGkiOiI0ZDkyZTY1Mi00ZGY3LTQ1YzEtYTEyMy1lM2M4NTQ1NzU3MGQiLCJjbGllbnRfaWQiOiJub3ZvLW9wZW4tcGxhdGZvcm0iLCJ1c2VyX2V4dCI6eyJyb2xlSWRzIjpbM10sInN0eXBlIjoiQURNSU4iLCJ0ZW5hbnRDb2RlIjpudWxsLCJ0eXBlIjoiUF9BQ0NPVU5UIiwidXNlcklkIjozMDc2OTEzNjQ0OTE1OTk4NzIwLCJlbWFpbCI6ImRpc3RyaWJ1dG9yZXhhbXBsZUBvdXRsb29rLmNvbSIsInVzZXJuYW1lIjoiZGlzdHJpYnV0b3JleGFtcGxlQG91dGxvb2suY29tIiwidWNJZCI6MzA3NjkxMzY0NDg5MDgzMjg5Nn19.QuOwtCNqOWcSHwH2n1MaDIrkJWnidV11bgrBfvTueqDahurTqkEKPRZRDEIkx41NbK65gDZOtGZRPkD1k9riERFobWiYcUBfHiAsc_inLBf41PXXltIV0awmHvG7wYdjpqWttPNrwB81mZJB40DzIPBIif7HvZcv_gqrxd4A_oVxGOGM2xqFwJQe8fkhNWTfcUH143hqpT7NNU7dDTFAGxLckQohu5POfzSMXZeJD0BQ7T4M9KihkmKUQegW5PwiroxzHa1-0bplkJOYN37uRXOAMal6f9viVJc_zdY9nkXqeq7wNvawlFookB4S-jpBTEPmw3v6wfdoXqLYRNlD2A
Content-Type: application/json
x-tenant-code: jint
{
  "extension": "6201",
  "name": "zz-test-ivr",
  "maxTimeout": 3,
  "responseTimeout": 5,
  "interDigitTimeout": 3
}

Response example

HTTP/1.1 200 OK
{
  "requestId": "8749a03e8364cc4bade4225e3a59a702",
  "code": "200",
  "message": "SUCCESS",
  "detailMessage": "",
  "result": {
    "id": "363581284498870272",
    "extension": "6201",
    "name": "zz-test-ivr",
    "joinAnnouncement": "default",
    "repeatAnnouncements": ["default"],
    "maxTimeout": 3,
    "responseTimeout": 5,
    "interDigitTimeout": 3,
    "alertInfo": "",
    "dialUser": {
      "enabled": false,
      "mode": "ALL"
    },
    "dialCallFeature": {
      "enabled": false
    },
    "dialOutboundRoutes": {
      "enabled": false
    },
    
    "keyPressEvents": {},
    "timeoutDestination": {
      "type": "HANGUP",
      "value": "",
      "prefix": "",
      "turnOffRecording": false,
      "repeatCount": 0
    },
    "invalidDestination": {
      "type": "PLAY_IVR_PROMPT",
      "value": "",
      "prefix": "",
      "turnOffRecording": false,
      "repeatCount": 0
    },
    "timeBasedRoutingEnabled": false,
    "timeBasedRoutingProfileId": "",
    "timeBasedRoutingConfig": null,
    "directDidNumbers": []
  }
}