Add a Ring Group

Adds a ring group with members, ringing strategy, prompts, and a failover destination.

Request URL

POST {base_url}/uc-cconfig/api/v1/ring-groups

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 extension number of the ring group, which contains 1 to 31 characters.
name	Yes	String	The name of the ring group, which contains 1 to 127 characters.
ringTimeout	Yes	Integer	The ring timeout for each round, in seconds, ranging from 5 to 300.
memberIds	Yes	Array<String>	The list of user IDs of the ring group members. You can obtain the IDs using the Get Available Users for Ring Groups interface.
id	No	String	The pre-assigned ID of the ring group. If omitted, the system assigns an ID.
ringStrategy	No	String	The ringing strategy: - `RING_ALL`: Ring all the members at the same time (default). - `SEQUENTIALLY`: Ring the members one by one in order. - `MEMORY_HUNT`: Ring from the member who answered the last call first.
joinAnnouncement	No	String	The join announcement, which is the prompt file name played when a caller enters the ring group.
playJoinAnnouncementBeforeRinging	No	Boolean	Whether to play the join announcement before ringing.
musicOnWait	No	String	The music on wait.
musicOnHold	No	String	The music on hold.
alertInfo	No	String	The Alert-Info SIP header for outbound calls, which is used to distinguish the ringing mode. This parameter contains up to 31 characters.
failoverDestination	No	Object<Destination>	The failover destination when the call is not answered.
recordMissCalls	No	Boolean	Whether to record missed calls.
timeBasedRoutingEnabled	No	Boolean	Whether time-based routing is enabled.
timeBasedRoutingProfileId	No	String	The ID of the business hours configuration associated with time-based routing.
timeBasedRoutingConfig	No	Object<Time_Based_Routing_Config>	The time-based routing configuration.
directDidIds	No	Object<Direct_Did_Ids>	The DID binding configuration of the destinations.

Destination


Parameter	Required	Type	Description
type	No	String	The destination type: - `HANGUP`: Hang up (default). - `USER`: Extension. - `IVR`: IVR. - `RING_GROUP`: Ring group. - `EXTERNAL_NUMBER`: External number. - `QUEUE`: Queue. - `USER_VOICEMAIL`: User voicemail. `value` is the user ID. - `GROUP_VOICEMAIL`: Group voicemail. `value` is the ring group ID. - `PLAY_PROMPT`: Play the prompt and hang up. `value` is the prompt file name. - `RECEIVE_CALLS`: Receive calls, which are handled by the feature itself. This type applies to the outside and holiday destinations of time-based routing only, and does not require `value`.
value	No	String	The destination value, such as the resource ID, prompt file name, or external number.
prefix	No	String	The dial-out prefix. This parameter applies only when `type` is `EXTERNAL_NUMBER`.
repeatCount	No	Integer	The number of playback times, ranging from 1 to 5. This parameter applies only when `type` is `PLAY_PROMPT`. `0` means not set.

Time_Based_Routing_Config


Parameter	Required	Type	Description
holidayHandling	No	String	The holiday handling mode: - `route`: Route calls to the holiday destination. - `play_prompt`: Play the prompt. - `ignore`: Ignore holidays and follow the normal routing.
outsideDestination	No	Object<Destination>	The destination outside business hours.
holidayDestination	No	Object<Destination>	The destination on holidays.

Direct_Did_Ids


Parameter	Required	Type	Description
didIds	No	Array<String>	The list of DID IDs to bind, each greater than `0`.
force	No	Boolean	Whether to forcibly replace the occupied DID bindings. If a DID is occupied and `force` is `false`, the request fails with `DID_DIRECT_OCCUPIED`. If `force` is `true`, the old binding is deleted and the new one is created.
warningDidIds	No	Array<String>	The DIDs that are pre-authorized for replacement when `force` is `false`. 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<Ring_Group>	The created ring group.

Ring_Group


Parameter	Type	Description
id	String	The ID of the ring group.
extension	String	The extension number of the ring group.
name	String	The name of the ring group.
ringStrategy	String	The ringing strategy: - `RING_ALL`: Ring all the members at the same time. - `SEQUENTIALLY`: Ring the members one by one in order. - `MEMORY_HUNT`: Ring from the member who answered the last call first.
ringTimeout	Integer	The ring timeout for each round, in seconds.
members	Array<Member>	The list of ring group members.
joinAnnouncement	String	The join announcement of the ring group.
playJoinAnnouncementBeforeRinging	Boolean	Whether to play the join announcement before ringing.
musicOnWait	String	The music on wait.
musicOnHold	String	The music on hold.
alertInfo	String	The Alert-Info SIP header for outbound calls.
failoverDestination	Object<Destination>	The failover destination when the call is not answered.
recordMissCalls	Boolean	Whether to record missed calls.
version	Integer	The version number of the data, which increments on each change.
createdAt	String	The time when the ring group was created, in Unix timestamp format (milliseconds).
updatedAt	String	The time when the ring group was last updated, in Unix timestamp format (milliseconds).
timeBasedRoutingEnabled	Boolean	Whether time-based routing is enabled.
timeBasedRoutingProfileId	String	The ID of the business hours configuration associated with time-based routing.
timeBasedRoutingConfig	Object<Time_Based_Routing_Config>	The time-based routing configuration.
directDidNumbers	Array<Direct_Did_Number>	The list of DIDs bound to the ring group destinations.

Member


Parameter	Type	Description
userId	String	The ID of the user.
extension	String	The extension number of the user.
name	String	The name of the member.

Direct_Did_Number


Parameter	Type	Description
id	String	The DID ID.
number	String	The DID number.
name	String	The DID name.

Example

Request example

POST /uc-cconfig/api/v1/ring-groups HTTP/1.1
Host: api.cn.novoone.com
Authorization: Bearer eyJraWQiOiJjbi0wLWtleS0xIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkaXN0cmlidXRvcmV4YW1wbGVAb3V0bG9vay5jb20iLCJncmFudF90eXBlIjoib3BlbmFwaSIsImNsaWVudF9leHQiOnsiZGVzY3JpcHRpb24iOiLnrKzkuInmlrnlkIjkvZzkvJnkvLTlupTnlKgiLCJwYXJ0bmVyIjoi56S65L6L5ZCI5L2c5LyZ5Ly0In0sImNsaWVudF90eXBlIjoib3BlbmFwaSIsImV4cCI6MTc5MDc3NTMyMCwiaWF0IjoxNzkwNzUzNzIwLCJqdGkiOiI2ZDg1ZTg2NC1jOTk0LTRjZTItOGUzYi1mMTRiODE1Y2M4NDIiLCJjbGllbnRfaWQiOiJub3ZvLW9wZW4tcGxhdGZvcm0iLCJ1c2VyX2V4dCI6eyJyb2xlSWRzIjpbM10sInN0eXBlIjoiQURNSU4iLCJ0ZW5hbnRDb2RlIjpudWxsLCJ0eXBlIjoiUF9BQ0NPVU5UIiwidXNlcklkIjozMDc2OTEzNjQ0OTE1OTk4NzIwLCJlbWFpbCI6ImRpc3RyaWJ1dG9yZXhhbXBsZUBvdXRsb29rLmNvbSIsInVzZXJuYW1lIjoiZGlzdHJpYnV0b3JleGFtcGxlQG91dGxvb2suY29tIiwidWNJZCI6MzA3NjkxMzY0NDg5MDgzMjg5Nn19.o8tXb4Q9dImuGjtnui9LWTCukF9S5HKMkqYYWT7rjd1H7_2S40ZUjYuGonzGZR37q66kWBxrbHI0a9c7ICQO4MAq-0X0Ev6coK1Q8ud9yWFq1cf7H58pC0wYxE_bCjnDdKLxQk6lHCFbD_WiMTjuuK_Vtckuv6sI9-3ILspzK1WLJLktESKBV1qbsMJY-pO-pD8enoZq9I1Lo_kWIOHckg5Hq4kKjwq9iN1pecnSVQwKsL5Z8KDiJS8QXuoJrZtySacLbGB0-_GeljzDXk5JmsmOrpUr3UWDD7Lh4rcYq3Xwc6ya126GV5ETTZHAM4uX-OWev69cR29MHRxw5eNZIw
Content-Type: application/json
x-tenant-code: jint
{
  "extension": "6300",
  "name": "zz-test-rg",
  "ringTimeout": 30,
  "ringStrategy": "SEQUENTIALLY",
  "memberIds": [
    "355536619424391168"
  ],
  "failoverDestination": {
    "type": "USER_VOICEMAIL",
    "value": "355536619424391168"
  }
}

Response example

HTTP/1.1 200 OK
{
  "requestId": "80ca7318a1ecc823656d735f5702ca02",
  "code": "200",
  "message": "SUCCESS",
  "detailMessage": "",
  "result": {
    "id": "363588204383244288",
    "extension": "6300",
    "name": "zz-test-rg",
    "ringStrategy": "SEQUENTIALLY",
    "ringTimeout": 30,
    "members": [
      {
        "userId": "355536619424391168",
        "extension": "1000",
        "name": "3 1"
      }
    ],
    "failoverDestination": {
      "type": "USER_VOICEMAIL",
      "value": "355536619424391168",
      "prefix": "",
      "repeatCount": 0
    },
    "version": 1,
    "createdAt": "1790753383077",
    "updatedAt": "1790753383077"
  }
}