Add a Queue

Adds a queue with agents, ringing strategy, prompts, and a failover destination.

Request URL

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

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
id No String The pre-assigned ID of the queue. If omitted, the system assigns an ID.
extension Yes String The extension number of the queue, which contains 1 to 31 characters.
name Yes String The name of the queue, which contains 1 to 127 characters.
ringStrategy No String

The ringing strategy for distributing calls to agents.

Valid value:

  • RING_ALL: Ring all the agents at the same time (default).
  • LONGEST_IDLE_AGENT: Ring the agent who has been idle for the longest time first.
  • FEWEST_CALLS: Ring the agent who has answered the fewest calls first.
  • RANDOM: Ring the agents in random order.
  • ROUND_ROBIN: Ring the agents one by one in rotation.
  • LINEAR: Ring the agents in the fixed order of the agent list.
maxWaitTime No Integer The maximum time that a caller waits in the queue, in seconds.
failoverDestination No Object<Destination> The failover destination when the call is not answered within the maximum wait time.
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.
ringTimeout No Integer The ring timeout for each agent, in seconds.
retryInterval No Integer The retry interval after an agent does not answer, in seconds. If omitted, the default value 30 is used. 0 means no interval.
wrapUpTime No Integer The wrap-up time after a call ends, in seconds. If omitted, the default value 30 is used. 0 means the agent resumes immediately.
ringInUse No Boolean Whether to ring the agents who are on a call at the same time.
agentAutoPause No Boolean Whether to automatically pause an agent after consecutive missed calls.
maxMissedCalls No Integer The maximum number of consecutive missed calls that triggers the automatic pause.
joinAnnouncement No String The join announcement, which is the prompt played when a caller enters the queue.
playJoinBeforeRing No Boolean Whether to play the join announcement before ringing the agents.
musicOnWait No String The music on wait.
positionAnnouncement No Boolean Whether to announce the queue position to waiting callers.
periodicAnnouncement No String The prompt played periodically to waiting callers.
waitingAnnouncementInterval No Integer The interval between periodic announcements, in seconds.
connectionAnnouncement No String The prompt played to the caller before the agent answers.
agentIdAnnouncement No Boolean Whether to announce the agent ID.
musicOnHold No String The music on hold.
customPromptLanguage No Boolean Whether to use a custom prompt language.
promptLanguage No String The prompt language.
staticAgentIds No Object<Int64_Array> The static agents of the queue. You can obtain the user IDs using the Get Available Users for Queues interface.
dynamicAgentIds No Object<Int64_Array> The dynamic agents of the queue. You can obtain the user IDs using the Get Available Users for Queues interface.
managerIds No Object<Int64_Array> The queue managers of the queue. You can obtain the user IDs using the Get Available Users for Queues interface.
notifyNoAnswer No Boolean Whether to send an email notification when an agent does not answer.
notifyAbandoned No Boolean Whether to send an email notification when a caller abandons the call.
maxCallers No Integer The maximum number of callers waiting in the queue.
endWaitingWhenNoAgents No Boolean Whether to end the waiting when no agent is available. If enabled, the call is routed to the failover destination directly.
endWaitingNoAgentConditions No Array<String>

The conditions based on which the waiting is ended when no agent is available.

Valid value:

  • OFFLINE
  • PAUSE
  • RING_BUSY
  • DND
blockCallsWhenNoAgents No Boolean Whether to reject new calls when no agent is available.
blockCallsNoAgentConditions No Array<String>

The conditions based on which new calls are rejected when no agent is available.

Valid value:

  • OFFLINE
  • PAUSE
  • RING_BUSY
  • DND
keyPressEventKey No String The DTMF key of the key press event, ranging from 0 to 9, , and #.
keyPressEventDestination No Object<Destination> The destination of the key press event.
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 queue.
Destination
Parameter Required Type Description
type No String

The destination type.

Valid value:

  • HANGUP: Hang up (default).
  • USER: Extension.
  • USER_VOICEMAIL: User voicemail. value is the user ID.
  • IVR: IVR.
  • RING_GROUP: Ring group.
  • QUEUE: Queue.
  • EXTERNAL_NUMBER: External number.
  • 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.

Valid value:

  • 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.
Int64_Array
Parameter Required Type Description
values No Array<String> The list of user IDs.
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<Queue_Data> The created queue.
Queue_Data
Parameter Type Description
id String The ID of the queue.
extension String The extension number of the queue.
name String The name of the queue.
ringStrategy String

The ringing strategy for distributing calls to agents:

  • RING_ALL: Ring all the agents at the same time.
  • LONGEST_IDLE_AGENT: Ring the agent who has been idle for the longest time first.
  • FEWEST_CALLS: Ring the agent who has answered the fewest calls first.
  • RANDOM: Ring the agents in random order.
  • ROUND_ROBIN: Ring the agents one by one in rotation.
  • LINEAR: Ring the agents in the fixed order of the agent list.
maxWaitTime Integer The maximum time that a caller waits in the queue, in seconds.
failoverDestination Object<Destination> The failover destination when the call is not answered within the maximum wait time.
alertInfo String The Alert-Info SIP header for outbound calls, which is used to distinguish the ringing mode.
ringTimeout Integer The ring timeout for each agent, in seconds.
retryInterval Integer The retry interval after an agent does not answer, in seconds.
wrapUpTime Integer The wrap-up time after a call ends, in seconds.
ringInUse Boolean Whether to ring the agents who are on a call at the same time.
agentAutoPause Boolean Whether to automatically pause an agent after consecutive missed calls.
maxMissedCalls Integer The maximum number of consecutive missed calls that triggers the automatic pause.
joinAnnouncement String The join announcement, which is the prompt played when a caller enters the queue.
playJoinBeforeRing Boolean Whether to play the join announcement before ringing the agents.
musicOnWait String The music on wait.
positionAnnouncement Boolean Whether to announce the queue position to waiting callers.
periodicAnnouncement String The prompt played periodically to waiting callers.
waitingAnnouncementInterval Integer The interval between periodic announcements, in seconds.
connectionAnnouncement String The prompt played to the caller before the agent answers.
agentIdAnnouncement Boolean Whether to announce the agent ID.
musicOnHold String The music on hold.
customPromptLanguage Boolean Whether to use a custom prompt language.
promptLanguage String The prompt language.
staticAgents Array<Member_Info> The list of static agents.
dynamicAgents Array<Member_Info> The list of dynamic agents.
managers Array<Member_Info> The list of queue managers.
notifyNoAnswer Boolean Whether to send an email notification when an agent does not answer.
notifyAbandoned Boolean Whether to send an email notification when a caller abandons the call.
maxCallers Integer The maximum number of callers waiting in the queue.
endWaitingWhenNoAgents Boolean Whether to end the waiting when no agent is available. If enabled, the call is routed to the failover destination directly.
endWaitingNoAgentConditions Array<String>

The conditions based on which the waiting is ended when no agent is available:

  • OFFLINE
  • PAUSE
  • RING_BUSY
  • DND
blockCallsWhenNoAgents Boolean Whether to reject new calls when no agent is available.
blockCallsNoAgentConditions Array<String>

The conditions based on which new calls are rejected when no agent is available:

  • OFFLINE
  • PAUSE
  • RING_BUSY
  • DND
keyPressEventKey String The DTMF key of the key press event, ranging from 0 to 9, , and #.
keyPressEventDestination Object<Destination> The destination of the key press event.
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.
version Integer The version number of the data, which increments on each change.
createdAt String The time when the queue was created, in Unix timestamp format (milliseconds).
updatedAt String The time when the queue was last updated, in Unix timestamp format (milliseconds).
directDidNumbers Array<Direct_Did_Number> The list of DIDs bound to the queue.
Destination
Parameter Type Description
type String

The destination type:

  • HANGUP: Hang up.
  • USER: Extension.
  • USER_VOICEMAIL: User voicemail. value is the user ID.
  • IVR: IVR.
  • RING_GROUP: Ring group.
  • QUEUE: Queue.
  • EXTERNAL_NUMBER: External number.
  • 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 String The destination value, such as the resource ID, prompt file name, or external number.
prefix String The dial-out prefix. This parameter applies only when type is EXTERNAL_NUMBER.
repeatCount 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 Type Description
holidayHandling 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 Object<Destination> The destination outside business hours.
holidayDestination Object<Destination> The destination on holidays.
Member_Info
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/queues HTTP/1.1
Host: api.cn.novoone.com
Authorization: Bearer eyJraWQiOiJjbi0wLWtleS0xIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkaXN0cmlidXRvcmV4YW1wbGVAb3V0bG9vay5jb20iLCJhcHBfa2V5Ijoic2xOdnQzaHc1NXB2Vm5HRlNhR2ZOVTNmMWxYQ3lpa08iLCJncmFudF90eXBlIjoib3BlbmFwaSIsImNsaWVudF9leHQiOnsiZGVzY3JpcHRpb24iOiLnrKzkuInmlrnlkIjkvZzkvJnkvLTlupTnlKgiLCJwYXJ0bmVyIjoi56S65L6L5ZCI5L2c5LyZ5Ly0In0sImNsaWVudF90eXBlIjoib3BlbmFwaSIsImV4cCI6MTc5MTkxMzkwNiwiaWF0IjoxNzkxODkyMzA2LCJqdGkiOiIyNjQzMzg4MC04OGI2LTQ1YjItYmMzZC1lMWFlM2MyZWM2NGIiLCJjbGllbnRfaWQiOiJub3ZvLW9wZW4tcGxhdGZvcm0iLCJ1c2VyX2V4dCI6eyJyb2xlSWRzIjpbM10sInN0eXBlIjoiQURNSU4iLCJ0ZW5hbnRDb2RlIjpudWxsLCJ0eXBlIjoiUF9BQ0NPVU5UIiwidXNlcklkIjozMDc2OTEzNjQ0OTE1OTk4NzIwLCJlbWFpbCI6ImRpc3RyaWJ1dG9yZXhhbXBsZUBvdXRsb29rLmNvbSIsInVzZXJuYW1lIjoiZGlzdHJpYnV0b3JleGFtcGxlQG91dGxvb2suY29tIiwidWNJZCI6MzA3NjkxMzY0NDg5MDgzMjg5Nn19.AMBnRYQuBmBxX5qZGethRuAqTm9JzAHAQJgq0rBW9kZo_B7ZJHYZOOt7hMyQRMG_fYfnJoU-LmZCM99e20jwQZ2vSipaTtIa7BGhpr7KK-EBunjLU2lAuv2FDEE6B9yGu-ZVg56tNXQRgv1xfTN-bQgN-qx9dcJc2j4wQX9Rqxd6NhjWO1eGUQlWOcVd-gpveaRCU-q6BwNlZL8JAS7rkFrf1uHYnKxUbDh_X-7Cx7f7DtR3R3VsywDXOeNmHQ-DqiKmaOtxOYFgKh9hyeQR9QSJ2V5rM3VILn4Ffb21hbrPARxNml9zhtTU4653e4Ir4J5WEJB50YSIRJX71o48qQ
Content-Type: application/json
x-tenant-code: jint
{
  "extension": "9001",
  "name": "test-queue-api-1",
  "ringStrategy": "RING_ALL",
  "staticAgentIds": {
    "values": [
      "366488799060709376"
    ]
  }
}

Response example

HTTP/1.1 200 OK
{
  "requestId": "1c71b3e02aef06d1acb94843ab438784",
  "code": "200",
  "message": "SUCCESS",
  "detailMessage": "",
  "result": {
    "id": "368362813322379264",
    "extension": "9001",
    "name": "test-queue-api-1",
    "ringStrategy": "RING_ALL",
    "maxWaitTime": 1800,
    "failoverDestination": {
      "type": "HANGUP",
      "value": "",
      "prefix": "",
      "repeatCount": 0
    },
    "alertInfo": "",
    "ringTimeout": 30,
    "retryInterval": 30,
    "wrapUpTime": 30,
    "ringInUse": false,
    "agentAutoPause": false,
    "maxMissedCalls": 3,
    "joinAnnouncement": "",
    "playJoinBeforeRing": true,
    "musicOnWait": "330931373987872768",
    "positionAnnouncement": true,
    "periodicAnnouncement": "",
    "waitingAnnouncementInterval": 30,
    "connectionAnnouncement": "",
    "agentIdAnnouncement": false,
    "musicOnHold": "330931373987872768",
    "customPromptLanguage": false,
    "promptLanguage": "",
    "staticAgents": [
      {
        "userId": "366488799060709376",
        "extension": "1001",
        "name": "qq Hu"
      }
    ],
    "dynamicAgents": [],
    "managers": [],
    "notifyNoAnswer": true,
    "notifyAbandoned": true,
    "maxCallers": 0,
    "endWaitingWhenNoAgents": false,
    "endWaitingNoAgentConditions": [],
    "blockCallsWhenNoAgents": false,
    "blockCallsNoAgentConditions": [],
    "keyPressEventKey": "[None]",
    "keyPressEventDestination": {
      "type": "HANGUP",
      "value": "",
      "prefix": "",
      "repeatCount": 0
    },
    "timeBasedRoutingEnabled": false,
    "timeBasedRoutingProfileId": "",
    "timeBasedRoutingConfig": null,
    "version": 1,
    "createdAt": "1791891738566",
    "updatedAt": "1791891738566",
    "directDidNumbers": []
  }
}