Queue

Manage call queues with configurable routing strategies and automatic agent matching for inbound call distribution.

API Reference: Queue endpoints

Overview

Note

AI Context

  • Complexity: High – Queues require coordinating agents, tags, flows, and calls. Set up agents and tags first.

  • Cost: No direct charge for queue operations. Underlying calls are chargeable per call minute.

  • Async: Yes. POST /queues creates the queue synchronously, but calls entering a queue via the queue_join flow action are processed asynchronously. Poll GET /queues/{id} to monitor queue state, or use GET /queuecalls to track individual call progress.

Call queueing allows calls to be placed on hold without handling the actual inquiries or transferring callers to the desired party. While in the call queue, the caller is played pre-recorded music or messages. Call queues are often used in call centers when there are not enough staff to handle a large number of calls. Call center operators generally receive information about the number of callers in the call queue and the duration of the waiting time. This allows them to respond flexibly to peak demand by deploying extra call center staff.

With the VoIPBIN’s queueing feature, businesses and call centers can effectively manage inbound calls, provide a smooth waiting experience for callers, and ensure that calls are efficiently distributed to available agents, improving overall customer service and call center performance.

The purpose of call queueing

Call queueing is intended to prevent callers from being turned away in the case of insufficient staff capacity. The purpose of the pre-recorded music or messages is to shorten the subjective waiting time. At the same time, call queues can be used for advertising products or services. As soon as the call can be dealt with, the caller is automatically transferred from the call queue to the member of staff responsible. If customer or contract data has to be requested in several stages, multiple downstream call queues can be used.

How Queue Routing Works

When a call joins a queue, a coordinated process begins to match the caller with an available agent.

The Queue Journey

+-------------------------------------------------------------------------+
|                       Call's Journey Through Queue                      |
+-------------------------------------------------------------------------+

1. Call Joins Queue          2. Wait Flow Plays         3. Agent Search
+-----------------+         +-----------------+        +-----------------+
|                 |         |  # Hold music   |        |  Check for      |
|  queue_join     |-------->|  "Please wait"  |------->|  available      |
|  action         |         |  announcements  |        |  agents         |
+-----------------+         +-----------------+        +--------+--------+
                                    ^                          |
                                    |                    +-----+-----+
                                    |                    |           |
                                    |               No agents    Agent found!
                                    |                    |           |
                                    +--------------------+           |
                                      Retry every 1 second           |
                                                                     v
                                                          +-----------------+
                                                          |  4. Connect     |
                                                          |  agent to call  |
                                                          +--------+--------+
                                                                   |
                                                                   v
                                                          +-----------------+
                                                          |  5. Caller and  |
                                                          |  agent talking  |
                                                          +-----------------+

What Happens Step by Step

  1. Call Joins Queue: When your flow executes a queue_join action, a queuecall is created

  2. Conference Bridge Created: A private conference room is set up for this call

  3. Wait Flow Starts: The caller hears music and announcements from your configured wait flow

  4. Agent Search Begins: The system immediately starts looking for available agents

  5. Continuous Checking: Every second, the system checks if any matching agents are now available

  6. Agent Found: When an agent matches, they’re invited to join the conference

  7. Service Begins: Both parties are connected and can talk

Queuecall Lifecycle

Every call in a queue moves through a series of states:

+--------------------------------------------------------------------------+
|                      Queuecall State Machine                             |
+--------------------------------------------------------------------------+

                            +------------+
                            | initiating |
                            |  (brief)   |
                            +-----+------+
                                  |
                                  v
                       +------------------+
       wait_timeout--->|     waiting      |
       exceeded        | (in wait flow)   |
           |           +--------+---------+
           |                    | agent found
           |                    v
           |           +------------------+
           |           |    connecting    |
           |           |  (dialing agent) |
           |           +--------+---------+
           |                    | agent joins
           |                    v
           |           +------------------+         service_timeout
           |           |     service      |<---------- exceeded
           |           | (agent on call)  |                |
           |           +--------+---------+                |
           |                    |                          |
           |           +--------+--------+                 |
           |           v                 v                 v
           |    +------------+    +-------------+
           +--->|  abandoned |    |    done     |
                |  (failed)  |    | (success)   |
                +------------+    +-------------+

State Descriptions

Agent Searching

While the call is in the queue, the queue continuously searches for available agents to handle the call. Each queue has tags associated with it that determine which agents can receive calls from that queue.

How Agent Matching Works

+--------------------------------------------------------------------------+
|                      Agent Matching Process                              |
+--------------------------------------------------------------------------+

Queue Configuration:                    Agent Pool:
+------------------------+             +--------------------------------+
| Tag IDs:               |             | Agent A                        |
|  * "english"           |             |  Tags: english, billing, vip   |
|  * "billing"           |             |  Status: available             |
|                        |             |  --------------------------    |
+------------------------+             | Agent B                        |
          |                            |  Tags: english                 |
          |                            |  Status: available             |
          |                            |  --------------------------    |
          v                            | Agent C                        |
+------------------------+             |  Tags: english, billing        |
| Search for agents with |             |  Status: busy                  |
| ALL of these tags:     |             |  --------------------------    |
|  * english [x]         |             | Agent D                        |
|  * billing [x]         |             |  Tags: spanish, billing        |
+------------------------+             |  Status: available             |
          |                            +--------------------------------+
          |
          v
+--------------------------------------------------------------------------+
| Results:                                                                 |
|  [x] Agent A - Has english + billing + vip, is available                 |
|  [ ] Agent B - Missing "billing" tag                                     |
|  [ ] Agent C - Has tags but is busy                                      |
|  [ ] Agent D - Missing "english" tag                                     |
|                                                                          |
|  -> Agent A is selected!                                                 |
+--------------------------------------------------------------------------+
_images/queue_overview_agent.png

Tag Requirements

Tags work as a skill-based filter:

  • Agents must have ALL tags the queue requires (AND logic)

  • Having extra tags is fine (Agent A has “vip” but queue doesn’t require it)

  • If an agent is missing even one required tag, they’re excluded

  • Tags define skills, languages, departments, or any grouping you need

Note

AI Implementation Hint

Before creating a queue, you must have tags and agents already set up. Create tags via POST /tags, assign them to agents via PUT /agents/{id}, then reference the tag IDs in the queue’s tag_ids field. Agents must have all tags the queue requires (AND logic), so verify agent tags with GET /agents/{id} before expecting queue routing to work.

Agent Status

The agent’s status must be “available” to receive queue calls:

Agent Statuses and Queue Eligibility:
+----------------+---------------------------------------------+
| Status         | Can receive queue calls?                    |
+----------------+---------------------------------------------+
| available      | [x] Yes - Agent is ready to take calls      |
| busy           | [ ] No - Agent is handling another call     |
| wrap-up        | [ ] No - Agent is finishing previous call   |
| away           | [ ] No - Agent is temporarily away          |
| offline        | [ ] No - Agent is not logged in             |
+----------------+---------------------------------------------+

Selection Method

When multiple agents match, the system uses random selection:

Multiple agents available:
+------------+   +------------+   +------------+
|  Agent A   |   |  Agent C   |   |  Agent E   |
| (matches)  |   | (matches)  |   | (matches)  |
+------------+   +------------+   +------------+
      |               |               |
      +---------------+---------------+
                      |
                      v
                Random Selection
                      |
                      v
               One agent picked

Agent Status Transitions

Agents move through a lifecycle as they handle queue calls.

Status Transition Diagram

+----------+                        +----------+
|  offline |-------- login -------->| available|
+----------+                        +-----+----+
     ^                                    |
     |                              receive call
     |                                    |
     |                                    v
     |                              +----------+
     +--------- logout -------------|   busy   |
     |                              +-----+----+
     |                                    |
     |                               call ends
     |                                    |
     |                                    v
     |                              +----------+
     +--------- logout -------------|  wrap-up |
                                    +-----+----+
                                          |
                                     wrap-up done
                                          |
                                          v
                                    +----------+
                                    | available|
                                    +----------+

Status Behaviors

Transition

What happens

login

Agent becomes available to receive queue calls

receive call

Queue connects agent to caller; status becomes busy

call ends

Conversation finished; agent enters wrap-up for post-call work

wrap-up done

Agent returns to available; ready for next call

logout

Agent goes offline; removed from queue matching

Multi-Queue Agent Scenarios

Agents can belong to multiple queues simultaneously based on their tags.

Single Agent, Multiple Queues

Agent A's Tags: [english, billing, tech_support]

+------------------------+     +------------------------+
| Queue: English Billing |     | Queue: Tech Support    |
| Required: english,     |     | Required: tech_support |
|           billing      |     |                        |
+------------------------+     +------------------------+
          |                              |
          +--------- Agent A ------------+
          |     (matches both)           |
          v                              v
Agent A can receive calls from EITHER queue

Priority Handling

When an agent matches multiple queues, the system picks the longest-waiting caller across all matching queues:

Queue A: 3 callers waiting (oldest: 2 min)
Queue B: 1 caller waiting (oldest: 5 min)   <-- This caller gets Agent A
Queue C: 5 callers waiting (oldest: 30 sec)

Tag Strategy for Multi-Queue

+-------------------------------------------------------------------------+
|                     Multi-Queue Tag Strategy                            |
+-------------------------------------------------------------------------+

Tier 1 Agent (handles simple issues):
Tags: [english, tier1, billing_basic, tech_basic]
     |
     +---> Matches: Basic Billing Queue, Basic Tech Queue

Tier 2 Agent (handles complex issues):
Tags: [english, tier2, billing_advanced, tech_advanced]
     |
     +---> Matches: Advanced Billing Queue, Advanced Tech Queue

Supervisor (handles escalations):
Tags: [english, supervisor, billing_basic, billing_advanced,
       tech_basic, tech_advanced]
     |
     +---> Matches: ALL queues (can help anywhere)

Flow Execution

A call placed in the queue will progress through the queue’s waiting actions, continuing through pre-defined steps until an available agent is located. These waiting actions may involve playing pre-recorded music, messages, or custom actions, enhancing the caller’s experience while awaiting assistance in the queue.

Wait Flow Structure

+--------------------------------------------------------------------------+
|                          Wait Flow Execution                             |
+--------------------------------------------------------------------------+

Caller enters queue
       |
       v
+-----------------------------------------------------------------------+
|                            Wait Flow Loop                             |
|                                                                       |
|    +----------+     +----------+     +----------+     +----------+    |
|    | "Please  |---->|  # Hold  |---->| "Your    |---->|  # Hold  |    |
|    |  hold"   |     |  music   |     | position |     |  music   |    |
|    |  (talk)  |     |  (play)  |     |  is 3"   |     |  (play)  |    |
|    +----------+     +----------+     +----------+     +----------+    |
|         ^                                                    |        |
|         |                                                    |        |
|         +----------------------------------------------------+        |
|                        (loops until agent found)                      |
+-----------------------------------------------------------------------+
       |
       | Agent found!
       v
+----------------+
| Wait flow ends |
| Service begins |
+----------------+
_images/queue_overview_flow.png

Wait Flow Features

  • Looping: The wait flow automatically repeats until the call is answered or times out

  • Custom Actions: You can use any flow action that makes sense while waiting

  • Announcements: Play position updates, estimated wait time, or promotional messages

  • Music: Play hold music to make the wait feel shorter

Timeout Handling

Queues have two distinct timeout mechanisms to prevent calls from being stuck indefinitely:

Wait Timeout

Controls how long a caller can wait before being removed from the queue:

+--------------------------------------------------------------------------+
|                          Wait Timeout                                    |
+--------------------------------------------------------------------------+

Call joins queue                                     Wait timeout reached
     |                                                     |
     v                                                     v
-----o-----------------------------------------------------o------------->
     |<--------------- wait_timeout (ms) ----------------->|    Time
     |                                                     |
     | Caller hears wait flow                              | Call is kicked
     | System searches for agents                          | Status: abandoned
     |                                                     |
  • Set via queue’s wait_timeout field (milliseconds)

  • 0 means no timeout (wait forever)

  • When exceeded, the call is removed with status “abandoned”

Service Timeout

Controls how long a conversation can last once connected:

+--------------------------------------------------------------------------+
|                         Service Timeout                                  |
+--------------------------------------------------------------------------+

Agent connects                                    Service timeout reached
     |                                                     |
     v                                                     v
-----o-----------------------------------------------------o------------->
     |<------------- service_timeout (ms) ---------------->|    Time
     |                                                     |
     | Agent and caller talking                            | Call is ended
     | (status: service)                                   | Status: done
     |                                                     |
  • Set via queue’s service_timeout field (milliseconds)

  • 0 means no timeout (talk forever)

  • When exceeded, the call is ended gracefully

Note

AI Implementation Hint

Timeout values are in milliseconds, not seconds. A 5-minute wait timeout is 300000, not 300. Setting 0 disables the timeout entirely (wait/talk forever). If callers are being disconnected unexpectedly, check that timeout values are not set in seconds by mistake.

Timeout Scenarios

Scenario 1: Caller waits too long
+----------+                                        +-----------+
| waiting  |----- wait_timeout exceeded ----------->| abandoned |
+----------+                                        +-----------+

Scenario 2: Caller hangs up while waiting
+----------+                                        +-----------+
| waiting  |----- caller hangup ------------------->| abandoned |
+----------+                                        +-----------+

Scenario 3: Successful call, normal end
+----------+   +-----------+   +---------+         +------+
| waiting  |-->| connecting|-->| service |--hangup>| done |
+----------+   +-----------+   +---------+         +------+

Queue Metrics and Tracking

Queues track detailed metrics for reporting and analysis:

Per-Queue Statistics

+--------------------------------------------------------------------------+
|                        Queue Statistics                                  |
+--------------------------------------------------------------------------+

Queue: "Customer Support"
+---------------------------------+---------------------------------------+
| total_incoming_count            | 1,234 calls entered this queue        |
+---------------------------------+---------------------------------------+
| total_serviced_count            | 1,100 calls reached an agent          |
+---------------------------------+---------------------------------------+
| total_abandoned_count           | 134 calls abandoned (11% abandon rate)|
+---------------------------------+---------------------------------------+

Per-Queuecall Metrics

Each call in the queue tracks:

Queuecall: "abc-123-def"
+---------------------------------+---------------------------------------+
| duration_waiting                | 45,000 ms (45 seconds in wait flow)   |
+---------------------------------+---------------------------------------+
| duration_service                | 180,000 ms (3 minutes with agent)     |
+---------------------------------+---------------------------------------+
| tm_create                       | 2024-01-15 10:30:00 (entered queue)   |
+---------------------------------+---------------------------------------+
| tm_service                      | 2024-01-15 10:30:45 (agent connected) |
+---------------------------------+---------------------------------------+
| tm_end                          | 2024-01-15 10:33:45 (call ended)      |
+---------------------------------+---------------------------------------+

Calculating Service Levels

You can calculate key performance indicators from these metrics:

Service Level     = (total_serviced_count / total_incoming_count) × 100
                  = (1100 / 1234) × 100 = 89.1%

Abandonment Rate  = (total_abandoned_count / total_incoming_count) × 100
                  = (134 / 1234) × 100 = 10.9%

Average Wait Time = Sum of all duration_waiting / total_incoming_count

When No Agents Are Available

If no agents match or all matching agents are busy, the caller waits:

+--------------------------------------------------------------------------+
|                    No Agents Available Scenario                          |
+--------------------------------------------------------------------------+

10:00:00 - Call joins queue, no agents available
     |
     v
+-------------------------------------------------------------------------+
| System checks for agents every 1 second:                                |
|                                                                         |
| 10:00:01 - Check agents... none available                               |
| 10:00:02 - Check agents... none available                               |
| 10:00:03 - Check agents... none available                               |
| 10:00:04 - Check agents... Agent A just became available!               |
|                                                                         |
| Caller hears wait flow the entire time                                  |
+-------------------------------------------------------------------------+
     |
     v
10:00:04 - Agent A is connected

Retry Behavior

  • System retries every 1 second

  • Caller continuously hears the wait flow

  • As soon as any agent becomes available and matches, they’re connected

  • This continues until wait_timeout (if configured) or an agent answers

Conference Bridge Architecture

Each queuecall gets its own private conference bridge:

+--------------------------------------------------------------------------+
|                      Conference Bridge Model                             |
+--------------------------------------------------------------------------+

Queuecall for Caller A                    Queuecall for Caller B
+-------------------------+              +-------------------------+
| Conference Bridge #1    |              | Conference Bridge #2    |
| +---------+ +---------+ |              | +---------+ +---------+ |
| | Caller  | |  Agent  | |              | | Caller  | |  Agent  | |
| |   A     | |   1     | |              | |   B     | |   2     | |
| +---------+ +---------+ |              | +---------+ +---------+ |
+-------------------------+              +-------------------------+

Why This Design?

  • Each call is isolated in its own bridge

  • Caller joins immediately, hears wait flow

  • Agent joins when available, both can talk

  • Clean separation - no cross-talk between calls

Common Queue Scenarios

Scenario 1: Quick Answer

Caller dials -> Enters queue -> Agent available -> Connected in 2 seconds
                                                |
                                                v
                                        duration_waiting: 2000ms
                                        status: done

Scenario 2: Wait Then Connect

Caller dials -> Enters queue -> No agents -> Waits 45 seconds -> Agent available
                                 |                                  |
                                 v                                  v
                          # Hold music plays              Connected!
                          Position announcements          duration_waiting: 45000ms

Scenario 3: Caller Abandons

Caller dials -> Enters queue -> Waits 2 minutes -> Caller hangs up
                                 |                      |
                                 v                      v
                          # Hold music plays      status: abandoned
                                                  duration_waiting: 120000ms

Scenario 4: Wait Timeout

Caller dials -> Enters queue -> Waits 5 minutes -> wait_timeout exceeded
                                 |                      |
                                 v                      v
                          # Hold music plays      Kicked from queue
                                                  status: abandoned

Best Practices

1. Configure Appropriate Timeouts

wait_timeout: 300000    (5 minutes - reasonable for customer service)
service_timeout: 0      (no limit for service - let conversations finish)

2. Design Engaging Wait Flows

  • Mix music with periodic announcements

  • Provide position in queue updates

  • Offer callback options for long waits

  • Keep announcements concise

3. Tag Agents Thoughtfully

Good tag structure:
+-----------------------------------------+
| Language tags: english, spanish, french |
| Skill tags: billing, tech_support, sales|
| Tier tags: tier1, tier2, supervisor     |
+-----------------------------------------+

4. Monitor Key Metrics

  • Track abandonment rates - high rates indicate understaffing or long waits

  • Monitor average wait times - aim for your service level target

  • Review service durations - identify training opportunities

Queue

Queue

Queue struct

{
    "id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "routing_method": "<string>",
    "tag_ids": [
        "<string>",
        ...
    ],
    "wait_actions": [
        {
            action...
        }
    ],
    "wait_timeout": <number>,
    "service_timeout": <number>,
    "wait_queue_call_ids": [
        "<string>",
        ...
    ],
    "service_queue_call_ids": [
        "<string>",
        ...
    ],
    "total_incoming_count": <number>,
    "total_serviced_count": <number>,
    "total_abandoned_count": <number>,
    "total_waittime": <number>,
    "total_service_duration": <number>,
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>",
}
  • id (UUID): The queue’s unique identifier. Returned when creating a queue via POST /queues or when listing queues via GET /queues.

  • name (String): Human-readable name for the queue.

  • detail (String): Detailed description of the queue’s purpose.

  • routing_method (enum string): The queue’s call routing method for selecting agents. See Routing Method.

  • tag_ids (Array of UUID): List of tag IDs that agents must match to receive calls from this queue. Each ID is obtained from GET /tags. Agents must have all listed tags (AND logic).

  • wait_actions (Array of Object): List of flow actions executed while callers wait in the queue. Each action follows the Action structure. These loop until an agent is found or the wait timeout is reached.

  • wait_timeout (Integer): Maximum time in milliseconds a caller can wait in the queue before being removed. Set to 0 for no timeout (wait indefinitely).

  • service_timeout (Integer): Maximum time in milliseconds a caller and agent can talk before the call is ended. Set to 0 for no timeout (talk indefinitely).

  • wait_queue_call_ids (Array of UUID): List of queuecall IDs currently in the waiting state. Each ID can be used with GET /queuecalls/{id} to retrieve details. Read-only, managed by the system.

  • service_queue_call_ids (Array of UUID): List of queuecall IDs currently in the service state (connected to an agent). Each ID can be used with GET /queuecalls/{id}. Read-only, managed by the system.

  • total_incoming_count (Integer): Total number of calls that have entered this queue. Read-only.

  • total_serviced_count (Integer): Total number of calls that were successfully connected to an agent. Read-only.

  • total_abandoned_count (Integer): Total number of calls that left the queue without being serviced. Read-only.

  • total_waittime (Integer): Sum of all calls’ waiting time in milliseconds. Read-only.

  • total_service_duration (Integer): Sum of all calls’ service (agent conversation) time in milliseconds. Read-only.

  • tm_create (string, ISO 8601): Timestamp when the queue was created.

  • tm_update (string, ISO 8601): Timestamp of the last update to any queue property.

  • tm_delete (string, ISO 8601): Timestamp when the queue was deleted. Set to 9999-01-01 00:00:00.000000 if not deleted.

Note

AI Implementation Hint

The wait_timeout and service_timeout fields are in milliseconds. A 5-minute wait timeout should be 300000, not 300. Setting either to 0 disables that timeout entirely.

Routing Method

Defines how the queue selects an agent when multiple matching agents are available.

Type

Description

random

Selects a random agent from the pool of available agents that match all required tags.

Queuecall

Queuecall

Queuecall struct

{
    "id": "<string>",
    "reference_type": "<string>",
    "reference_id": "<string>",
    "status": "<string>",
    "service_agent_id": "<string>",
    "tm_create": "<string>",
    "tm_service": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}
  • id (UUID): The queuecall’s unique identifier. Returned when a call enters a queue or when listing queuecalls via GET /queuecalls.

  • reference_type (enum string): The type of the referenced resource. See Reference type.

  • reference_id (UUID): The ID of the referenced resource (e.g., the call). Obtained from GET /calls when reference_type is call.

  • status (enum string): The queuecall’s current status. See Status.

  • service_agent_id (UUID): The ID of the agent connected to this queuecall. Obtained from GET /agents. Set to 00000000-0000-0000-0000-000000000000 if no agent is connected yet.

  • tm_create (string, ISO 8601): Timestamp when the queuecall was created (call entered the queue).

  • tm_service (string, ISO 8601): Timestamp when the agent was connected and service began. Set to 9999-01-01 00:00:00.000000 if service has not started.

  • tm_update (string, ISO 8601): Timestamp of the last update to this queuecall.

  • tm_delete (string, ISO 8601): Timestamp when the queuecall ended. Set to 9999-01-01 00:00:00.000000 if still active.

Note

AI Implementation Hint

To calculate a caller’s wait time, subtract tm_create from tm_service. Timestamps set to 9999-01-01 00:00:00.000000 indicate the event has not yet occurred.

Example

{
    "id": "c7c1e226-8c86-4b43-9606-2d5bb2059a09",
    "reference_type": "call",
    "reference_id": "1fe1356f-3f7f-4ff9-9d33-08136b38f506",
    "status": "done",
    "service_agent_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
    "tm_create": "2022-03-29 15:07:46.111715",
    "tm_service": "2022-03-29 15:08:04.811442",
    "tm_update": "2022-03-29 15:08:25.814885",
    "tm_delete": "2022-03-29 15:08:25.814885"
}

Reference type

The type of the resource that this queuecall references.

Type

Description

call

The queuecall references a call resource. Use the reference_id with GET /calls/{id} to retrieve the associated call.

Status

The queuecall’s current lifecycle status. Transitions follow: wait -> entering -> service -> done (success path) or wait -> abandoned (failure path).

Type

Description

wait

The system is searching for an available agent. The caller hears the queue’s wait actions (hold music, announcements) in a loop.

entering

The queuecall is connecting to an available agent’s conference room. This is a brief transitional state between wait and service.

kicking

The queuecall is being removed from the queue (e.g., due to wait timeout). This is a brief transitional state.

service

An agent has been connected. The caller and agent are in conversation.

done

The queuecall completed successfully. The agent finished helping the caller.

abandoned

The queuecall ended without service. The caller hung up, the wait timeout was exceeded, or the call was otherwise terminated before an agent connected.

Tutorial

Before working with queues, you need:

  • An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.

  • At least one tag ID (UUID). Create tags via POST /tags or obtain existing ones from GET /tags. Tags define the skills required for agents to receive calls from this queue.

  • At least one agent configured with matching tags. Create agents via POST /agents and assign tags via PUT /agents/{id}. Verify agent tags with GET /agents/{id}.

  • (Optional) A wait flow with actions for callers to hear while waiting. Common actions include talk (text-to-speech announcements) and sleep (pause between announcements).

Note

AI Implementation Hint

Queues require tags and agents to function. If you create a queue without any agents having matching tags, calls will wait indefinitely (or until wait_timeout). Always verify that at least one agent has all the tags listed in the queue’s tag_ids before routing calls to the queue.

Create a new queue

Create a new queue

$ curl --location --request POST 'https://api.voipbin.net/v1.0/queues?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Cookie: token=<YOUR_AUTH_TOKEN>' \
--data-raw '{
    "name": "test queue",
    "detail": "test queue detail",
    "routing_method": "random",
    "tag_ids": [
        "d7450dda-21e0-4611-b09a-8d771c50a5e6"
    ],
    "wait_actions": [
        {
            "type": "talk",
            "option": {
                "text": "All of the agents are busy. Thank you for your waiting.",
                "language": "en-US"
            }
        },
        {
            "type": "sleep",
            "option": {
                "duration": 10000
            }
        }

    ],
    "timeout_wait": 100000,
    "timeout_service": 10000000
}'

Note

AI Implementation Hint

The tag_ids field must contain valid tag UUIDs obtained from GET /tags. The wait_actions array defines what callers hear while waiting – use talk for announcements and sleep for pauses. Timeout values (timeout_wait, timeout_service) are in milliseconds: 100000 = 100 seconds, 10000000 = ~2.8 hours.

Get list of queues

Gets the list of created queues.

$ curl --location --request GET 'https://api.voipbin.net/v1.0/queues?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "99bf739a-932f-433c-b1bf-103d33d7e9bb",
            "name": "test queue",
            "detail": "test queue detail",
            "routing_method": "random",
            "tag_ids": [
                "d7450dda-21e0-4611-b09a-8d771c50a5e6"
            ],
            "wait_actions": [
                {
                    "id": "00000000-0000-0000-0000-000000000000",
                    "next_id": "00000000-0000-0000-0000-000000000000",
                    "type": "talk",
                    "option": {
                        "text": "Hello. This is test queue. Please wait.",
                        "language": "en-US"
                    }
                }
            ],
            "wait_timeout": 100000,
            "service_timeout": 10000000,
            "wait_queue_call_ids": [
                "2eb40044-2e5e-4dae-b41e-61968e4febf9",
                "b0aa4639-fea3-4727-8b86-44667d8f4c27",
                "ec590f5b-6de5-477b-905b-1833dde213a0",
                "003e8242-a0ed-4d55-9e4f-59c317c023ad",
                "467fdfc2-fa2b-40f6-82cf-18dcb4c952c3",
                "2973648e-5989-4f75-9bda-b356d7a470dc"
            ],
            "service_queue_call_ids": [],
            "total_incoming_count": 76,
            "total_serviced_count": 70,
            "total_abandoned_count": 21,
            "total_waittime": 338789,
            "total_service_duration": 4050690,
            "tm_create": "2021-12-24 06:33:10.556226",
            "tm_update": "2022-02-20 05:30:31.067539",
            "tm_delete": "9999-01-01 00:00:00.000000"
        }
    ],
    "next_page_token": "2021-12-24 06:33:10.556226"
}