Queues

A queue holds inbound calls and rings its agents — extensions, each with a priority and an order — by a ring strategy until one answers or the timeout action fires. This group lists the account's queues (GET /v2/queues, GET /v3/queues), adds and removes agents, and reports on dynamic agents and on today's outbound activity. Queues themselves are created, configured and deleted in the portal. Logging a dynamic agent in or out is POST /v2/extensions/set-dynamic-agent-queue-status in the Extensions group, and routing an IVR key to a queue is described in IVR.

Workflow (what the portal does)#

1. List: GET /v3/queues answers a plain array of {"id", "name", "number", "description"} ordered by number — enough for pickers. GET /v2/queues returns the same queues in full: agents (the member count), agents_description (one entry per member: extension, name, priority, order, is_dynamic), queue_config and can_delete. With basic=true it answers only queue_id, queue_number, queue_name and queue_desc.
2. Agents: POST /v2/account-queue-headset with queue_number, extension_number and optional priority (0–59, default 0), order (0 or more, default 0) and is_dynamic (boolean, default false) adds the extension to the queue, or updates those three settings when it is already a member, and answers 202 with the membership row {"account_id", "queue_id", "extension_number", "priority", "order", "is_dynamic"}. DELETE /v2/account-queue-headset/{account_queue_headset} with queue_number and extension_number in the query string removes it (204). GET /v2/account-queue-headset lists the memberships of the caller's own extension, each with its queue (name, number, description); it answers 400 when the caller has no extension in the account.
3. Dynamic agents: a member with is_dynamic is a dynamic agent — one who logs in to and out of the queue instead of being rung permanently. POST /v2/extensions/set-dynamic-agent-queue-status with queue (queue number), extension (extension number) and action (login or logoff) changes that state. It answers 200 with {"status": "success", "message": "Agent login"}, or 200 with {"error": true, "message": "Agent was not changed", "description": "…"} when the change could not be applied.
4. Dynamic-agent reports:
   • GET /v2/queue-dynamic-agents is the login/logoff log, paginated. page and perPage (15, 25, 50 or 100) are required; sort takes id, ext, queue, action, user_name, platform or date, with a - prefix for descending (-date by default); the filters are filter[ext], filter[queue] (queue number), filter[action] (1 login, 0 logoff), filter[user_name], filter[platform] (1 Wallboard, 2 Apps, 3 Shortcode) and filter[date] as two Unix timestamps from-to. Each row is id, date, account, ext, queue, action, user_id, user_name, platform and platform_name; next to data, links and meta the response adds agents (extension number → extension name) and queues (the queue numbers that appear in the log).
   • GET /v2/queue-dynamic-agents/status is the current state: for every extension-and-queue pair whose latest event is a login, that event, newest first — who is logged in where right now.
5. Related endpoints in other groups: GET /v2/reports/queue-skipped-calls (Reports) lists the calls an agent did not pick up in a queue between from and to, optionally for one agent extension; GET /v2/call-log-queues (Call Logs) lists the queues the caller may filter call logs by, keyed by queue number.

Reading a queue#

queue_config in GET /v2/queues is the queue's behaviour:

• ring_strategy: ringall, leastrecent, fewestcalls, random, rrmemory, linear or wrandom; ring_agent_timeout is the seconds each agent rings before the next one is tried, ring_in_use whether an agent already on a call is rung, wrap_up_time the seconds an agent is left alone after a call.
• timeout_in is the seconds a caller waits before timeout_action fires: 0 ring an outside number, 1 continue, 2 backup call, 3 hang up, 4 option call, 5 option to voicemail, 6 dial an extension or shortcode, 7 voicemail, 8 another queue, 9 an IVR. timeout_action_value is the target (a number, extension, mailbox, queue id or IVR id); backup_type and backup_value describe the backup call.
• callee_announcement, periodic_announcement, announce_position and announce_position_frequency are the caller-side announcements, moh_class the music on hold, show_queue_name whether the queue description is prepended to the caller ID the agent sees.
• can_delete is {"allowed": true} when nothing points at the queue; otherwise message lists the numbers, IVRs, queues, callback widgets, webhooks and after-call-work rules that still use it. Deleting is portal-only.

Numbers and ids#

Every queue has two identifiers: an id (id / queue_id), unique across NUACOM, and a number (number / queue_number), short and unique within the account. Every input in the API takes the number: queue_number in the agent endpoints, queue in the dynamic-agent status endpoint and the skipped-calls report, filter[queue] in the log, the queues filter of the call log, the queues grant in a user's permissions and the "join queue" actions of an IVR (see IVR). The id is only returned, never required.

A queue also has two labels, a short name (sales) and a description (Sales Queue), and the key that carries each differs by endpoint:

Endpoint	id	number	short name	description
GET /v3/queues	id	number	name	description
GET /v2/queues	id (string)	number (string)	—	name
GET /v2/queues?basic=true	queue_id	queue_number	queue_name	queue_desc
GET /v2/account-queue-headset, queue object	–	number	name	description
GET /v2/call-log-queues	–	number	id	name

Roles and access#

• Listing queues and the three reports are open to any authenticated user. An account admin sees every queue; a regular user sees only the queues in the queues grant of their permissions (set by an admin in the portal's Users screen, see Users), and with no grant both lists are empty — [], not 403 — even when the user has full call-log access. The reports are not filtered: they cover the whole account.
• Adding and removing agents requires an account admin (403 otherwise).
• Logging a dynamic agent in or out: an admin for any extension, a regular user for their own extension only (403 otherwise).
• The ISO dates option does not change this group: date in the dynamic-agent reports is always M j Y H:i:s (Jun 15 2020 10:37:51) in the caller's profile timezone, and X-Timezone is ignored there.

Pitfalls#

• name is the description in GET /v2/queues and the short name in GET /v3/queues (table above). Key your data on number or id, never on a label.
• /v2/queues returns id, number, agents and every queue_config value as strings ("600"); /v3/queues returns integers. is_dynamic is 0/1 in agents_description and true/false in the agent endpoints, and agents_description[].id just repeats extension.
• POST /v2/account-queue-headset answers 202 whether it created the membership or updated an existing one, and re-posting overwrites priority, order and is_dynamic, which reset to 0/false when omitted.
• extension_number must be an extension linked to a user; an existing but unlinked extension is rejected with 422.
• The {account_queue_headset} path segment of the DELETE is ignored — any value works — and the parameters go in the query string, not the body.
• perPage=-1 ("all") passes validation on the dynamic-agent log but the query then fails with 500; page with 100 instead.
• filter[date] takes Unix timestamps (1735689600-1738368000) while date in the rows is formatted text; convert before comparing. action is login/logoff on input and 1/0 in the reports.
• When a queue is in use, can_delete is {"success": false, " allowed": false, "message": [...]} — the key carries a leading space — so test for allowed === true rather than for allowed === false.