Queueing Calls

| cURL | Python |

---

cURL

In this tutorial you'll learn how to use the Telnyx Call Queue API to create and manage call queues with just a few API requests.

Call Queueing is fully integrated with Call Control, the Telnyx Voice API. This tutorial assumes you've already set up your developer account and environment and you know how to send commands and receive webhooks using Call Control.

Adding a call to a new or existing queue

A call can be placed into a queue using the enqueue command. Use the queue_name parameter to specify a queue into which the call should be placed.

• If the queue_name refers to a queue that already exists, the call will be placed at the end of the queue.
• If the queue_name hasn't been used before, a new queue with this name will be created and the call will be placed into it.

curl -X POST
  --header "Content-Type: application/json"
  --header "Accept: application/json"
  --header "Authorization: Bearer <YOUR_API_KEY>"
  --data '{"queue_name": "support"}'
  https://api.telnyx.com/v2/calls/<CALL_CONTROL_ID>/actions/enqueue

Note: After pasting the above content, Kindly check and remove any new line added

If the call for which the enqueue command was issued is bridged to another call leg (i.e. it is in an active conversation with someone) the call will be unbridged.

Bridging an existing call to a queue

The bridge command can be used to bridge a call to another call waiting in a queue. The queue's queue_name should be used as the bridge command's queue parameter.

For example, a customer support agent can be bridged to the first call from a queue of waiting customer calls. If the customer support agent's active call has a call_control_id 8899ad4a-de6f-11eb-a54c-02420a0d4168 and the support call queue has a name support, the command to bridge the call is as follows:

curl -X POST
  --header "Content-Type: application/json"
  --header "Accept: application/json"
  --header "Authorization: Bearer YOUR_API_KEY"
  --data '{"queue": "support"}'
  https://api.telnyx.com/v2/calls/8899ad4a-de6f-11eb-a54c-02420a0d4168/actions/bridge

Note: After pasting the above content, Kindly check and remove any new line added

When a bridge command is issued, the call at the top of the specified queue will be dequeued and a bridge will be attempted.

Dequeuing calls

Calls can be removed from queues in four ways:

1. Ending the call by any means (e.g. a hangup command, or the call being disconnected by calling parties).
2. Issuing any command that results in the call being bridged elsewhere (e.g. bridge, transfer, conference join, refer).
3. A call is automatically removed from queues if the max_wait_time_secs parameter was used when adding the call to a queue and the specified maximum waiting time has elapsed. The automatically dequeued call will remain in a parked state and await further call commands.
4. Sending the leave_queue command with a call's call_control_id will remove that call from any queue it is in, leaving it parked awaiting further call commands.

curl -X POST
  --header "Content-Type: application/json"
  --header "Accept: application/json"
  --header "Authorization: Bearer <YOUR_API_KEY>"
  https://api.telnyx.com/v2/calls/<CALL_CONTROL_ID>/actions/leave_queue

Note: After pasting the above content, Kindly check and remove any new line added

Inspecting queue state

There are a number of endpoints that let you inspect your queues and enqueued calls:

• Retrieve a queue
• Retrieve a call from a queue
• List calls in a queue

Empty queues will automatically be garbage collected after a period of inactivity.

Receiving webhooks for call queueing events

The Telnyx API will send you a webhook for every major queue event, i.e.

• when a call is put in a queue,
• when a call leaves the queue for some reason.

Webhooks contain information about the call and the queue with which it is associated. Example webhooks are shown in the API reference for the enqueue command.

Next steps

Now that you've set up simple call queueing functionality with the Telnyx Voice API, why not use call queueing to build a contact center?

If you're interested in building something more complex or large-scale, our experts are standing by to help. Contact our team today.

Python

In this guide you'll learn how to use the Telnyx Call Queue API to create and manage call queues with just a few API requests.

Call Queueing is fully integrated with Call Control, the Telnyx Voice API. This guide assumes you've already set up your developer account and environment and you know how to send commands and receive webhooks using Call Control.

Adding a call to a new or existing queue

A call can be placed into a queue using the enqueue command. Use the queue_name parameter to specify a queue into which the call should be placed.

• If the queue_name refers to a queue that already exists, the call will be placed at the end of the queue.
• If the queue_name hasn't been used before, a new queue with this name will be created and the call will be placed into it.

call.enqueue("tier_1_support")

Note: After pasting the above content, Kindly check and remove any new line added

If the call for which the enqueue command was issued is bridged to another call leg (i.e. it is in an active conversation with someone) the call will be unbridged.

Bridging an existing call to a queue

The bridge command can be used to bridge a call to another call waiting in a queue. The queue's queue_name should be used as the bridge command's queue parameter.

For example, a customer support agent can be bridged to the first call from a queue of waiting customer calls. If the customer support agent's active call has a call_control_id 8899ad4a-de6f-11eb-a54c-02420a0d4168 and the support call queue has a name support, the command to bridge the call is as follows:

call.bridge(call_control_id="bridge_uuid", queue="tier_1_support")

Note: After pasting the above content, Kindly check and remove any new line added

When a bridge command is issued, the call at the top of the specified queue will be dequeued and a bridge will be attempted.

Dequeuing calls

Calls can be removed from queues in four ways:

1. Ending the call by any means (e.g. a hangup command, or the call being disconnected by calling parties).
2. Issuing any command that results in the call being bridged elsewhere (e.g. bridge, transfer, conference join, refer).
3. A call is automatically removed from queues if the max_wait_time_secs parameter was used when adding the call to a queue and the specified maximum waiting time has elapsed. The automatically dequeued call will remain in a parked state and await further call commands.
4. Sending the leave_queue command with a call's call_control_id will remove that call from any queue it is in, leaving it parked awaiting further call commands.

call.leave_queue()

Note: After pasting the above content, Kindly check and remove any new line added

Inspecting queue state

There are a number of endpoints that let you inspect your queues and enqueued calls:

• Retrieve a queue
• Retrieve a call from a queue
• List calls in a queue

Empty queues will automatically be garbage collected after a period of inactivity.

Receiving webhooks for call queueing events

The Telnyx API will send you a webhook for every major queue event, i.e.

• when a call is put in a queue,
• when a call leaves the queue for some reason.

Webhooks contain information about the call and the queue with which it is associated. Example webhooks are shown in the API reference for the enqueue command.

Next steps

Now that you've set up simple call queueing functionality with the Telnyx Voice API, why not use call queueing to build a contact center?

If you're interested in building something more complex or large-scale, our experts are standing by to help. Contact our team today.