VoIPBin Documentation
Queue
Overview
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
Call Joins Queue: When your flow executes a
queue_joinaction, a queuecall is createdConference Bridge Created: A private conference room is set up for this call
Wait Flow Starts: The caller hears music and announcements from your configured wait flow
Agent Search Begins: The system immediately starts looking for available agents
Continuous Checking: Every second, the system checks if any matching agents are now available
Agent Found: When an agent matches, they’re invited to join the conference
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! |
+--------------------------------------------------------------------------+
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
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
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 |
+----------------+
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_timeoutfield (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_timeoutfield (milliseconds)0 means no timeout (talk forever)
When exceeded, the call is ended gracefully
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: Queue’s ID.
name: Queue’s name.
detail: Queue’s detail description.
routing_method: Define the queue’s call routing method. See detail here.
tag_ids: List of tags.
wait_actions: List of actions for waiting calls.
wait_timeout: Timeout for waiting(ms). If it sets to 0, no timeout.
service_timeout: Timeout for service(talk with agent. ms). If it sets to 0, no timeout.
wait_queue_call_ids: List of waiting call ids.
service_queue_call_ids: List of service call ids.
total_incoming_count: Number of joined calls.
total_serviced_count: Number of serviced calls.
total_abandoned_count: Number of abandoned calls.
total_waittime: Sum of all call’s waitting time(ms).
total_service_duration: Sum of all call’s service time(ms).
Routing Method
Define the queue’s queued call routing method to the agent if the number of available agent is more than 2.
Type |
Description |
|---|---|
random |
Pick the agent randomly. |
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: Queuecall’s ID.
reference_type: Referenced resource’s type. See detail here.
status: Queuecall’s status. See detail here.
service_agent_id: Connected agent_id.
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
Referenced resource’s type.
Type |
Description |
|---|---|
call |
Call reference resource |
Status
Queuecall’s status.
Type |
Description |
|---|---|
wait |
Queue is looking for an available agent and the queuecall is looping the waiting actions. |
kicking |
A queuecall is being kicked. |
service |
A queuecall is talking with agent. |
done |
A queuecall is done. |
abandoned |
A queuecall has abandoned before connect to the agent. |
Tutorial
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.",
"gender": "female",
"language": "en-US"
}
},
{
"type": "sleep",
"option": {
"duration": 10000
}
}
],
"timeout_wait": 100000,
"timeout_service": 10000000
}'
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.",
"gender": "female",
"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"
}