How to Manage Queued Calls

In this guide we will show you how to take advantage of our outbound call queueing capabilities and manage your outbound call queue. Please ensure you have followed our earlier guide on how to make an outbound call with Bandwidth.

Outbound Call Queueing ensures your calls are not rejected if you exceed your calls per second (CPS) limits.

There are a few aspects to consider regarding call queueing:

• There is a calls per second (CPS) rate limit which is the limit of the number of inbound and outbound calls per second your account can process.
• There is a dequeue rate which is the rate the Programmable Voice API system will process calls that are in the outbound call queue.
• The amount of calls that can be in the outbound call queue is 5 minutes based on your provisioned CPS limit. For example, if your CPS limit is 5 CPS, you can have up to 5 calls/sec x 300 seconds = 1500 calls in your queue.

As an example, suppose your CPS limit is 5 CPS and your dequeue rate is 5 CPS. If you place 15 calls in 1 second it will take 3 seconds to process your outbound calls. 5 calls will be processed every second at the dequeue rate.

Using the Outbound Call Queue

Outbound calls are placed in a queue and processed at the dequeue rate for your account. Under conditions where your application does not exceed dequeue rate when making calls, calls will be processed immediately. If calls are made exceeding the dequeue rate then they will be pulled off of the queue and processed at the dequeue rate.

Specifying the Outbound Call Queue Priority

Outbound calls now have a priority 1 to 5 with priority 1 being the highest. If you do not specify priority the default is 5. You can now specify a priority 1 to 5 when making an outbound call so you can make sure that important calls are placed ahead of lower priority calls.

POST https://voice.bandwidth.com/api/v2/accounts/{accountId}/calls

{
    "from": "{FROM_NUMBER}",
    "to": "{TO_NUMBER}",
    "answerUrl": "http://example.com/answer",
    "username": "{APPLICATION_USERNAME},
    "password": "{APPLICATION_PASSWORD}",
    "answerMethod": "POST",
    "disconnectUrl": "http://example.com/hangup",
    "applicationId": "{APPLICATION_ID}",
    "priority": 1
}

Checking Status of the Outbound Call Queue

You can query the outbound call queue to see how many calls are queued up at any point in time. Note that calls are being processed in real time so information received is only accurate for that point in time.

GET https://voice.bandwidth.com/api/v2/accounts/{accountId}/statistics

Response for a max queue of 30 and queue of size 5:

{
    "maxCallQueueSize": "30",
    "currentCallQueueSize": "5"
}

Removing Calls From the Outbound Call Queue

If calls are in the enqueued state and you want to remove the call from the queue you can cancel the call like any other call in progress.

POST https://voice.bandwidth.com/api/v2/accounts/{accountId}/calls/{callId}

{
    "state": "completed",
    "username": "string",
    "password": "string",
}

Where to next?

Now that you have learnt how to manage queued calls, check out some of the available actions in the following guides:

• How to retrieve call information