Queueing Calls

Overview

This guide will explain how to use Twilio's Queue feature to create a simple call queueing system. A Queue stores incoming calls in order. You can then connect the first call in the queue to another call easily. The complete code sample will show you how to accept an incoming call, place it into a queue and then connect a live agent to the first call in the queue.

For this demonstration we'll be using two Twilio phone numbers, so if you'd like to try the code out live, you'll need to buy two phone numbers. For more help getting setup with Voice be sure to read our Getting Started guide.

Putting the Caller in a Queue

When our first number is called, Twilio will make a request to our server to place the caller in the Queue.

Queue a Caller
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
SDK Version:
  • 4.x
  • 5.x
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

$response = new Services_Twilio_Twiml;
$response->enqueue('Queue Demo');
print $response;
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using Twilio.TwiML;
using Twilio.TwiML.Mvc;

private static TwiMLResult QueueCaller()
{
    var twiml = new TwilioResponse();
    twiml.Enqueue("Queue Demo");
    return new TwiMLResult(twiml);
}
// Install the Java helper library from twilio.com/docs/java/install
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.twilio.sdk.verbs.Enqueue;
import com.twilio.sdk.verbs.TwiMLException;
import com.twilio.sdk.verbs.TwiMLResponse;

public class Example extends HttpServlet {

  @Override
  public void service(final HttpServletRequest request, final HttpServletResponse response) throws IOException {
    final TwiMLResponse twiml = new TwiMLResponse();
    final Enqueue enqueue = new Enqueue("Queue Demo");

    try {
      twiml.append(enqueue);
    } catch (final TwiMLException e) {
        e.printStackTrace();
    }

    return twiml.toXML();
  }
}
// Download the Node helper library from twilio.com/docs/node/install
var twilio = require('twilio');
var twiml = new twilio.TwimlResponse();

twiml.enqueue('Queue Demo');

console.log(twiml.toString());
# Download the Python helper library from twilio.com/docs/python/install
from twilio import twiml

r = twiml.Response()
r.enqueue("Queue Demo")
print(str(r))
require 'sinatra'
require 'twilio-ruby'

# Handles the POST request from Twilio and generates the TwiML that puts caller in a queue.
post '/caller/?' do
  response = Twilio::TwiML::Response.new do |r|
    # Use <Enqueue> verb to place caller in a <Queue>
    r.Enqueue "Queue Demo"
  end
  response.text
end
<?php
// NOTE: This example uses the next generation Twilio helper library - for more
// information on how to download and install this version, visit
// https://www.twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php';

use Twilio\Twiml;

$response = new Twiml();
$response->enqueue('Queue Demo');

echo $response;
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Enqueue>Queue Demo</Queue>
</Response>

We start by creating a creating a TwiML response that uses the Enqueue verb to create a new Queue and place the caller into it.

You can learn more about how to serve TwiML from your own application in our webhook guides. You can explore all the available TwiML functionality in our TwiML reference docs.

Connecting the Agent to the Queue

When our second number is called, Twilio will make a request to our server to connect the agent to the Queue.

Connect an Agent
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
SDK Version:
  • 4.x
  • 5.x
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require("Services/Twilio.php");
$response = new Services_Twilio_Twiml;
$dial = $response->dial();
$dial->queue('Queue Demo');
print $response;
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using Twilio.TwiML;
using Twilio.TwiML.Mvc;

private static TwiMLResult ConnectAgent()
{
    var twiml = new TwilioResponse();
    twiml.BeginDial()
          .Queue("Queue Demo")
          .EndDial();
    return new TwiMLResult(twiml);
}
// Install the Java helper library from twilio.com/docs/java/install
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.twilio.sdk.verbs.Dial;
import com.twilio.sdk.verbs.Queue;
import com.twilio.sdk.verbs.TwiMLException;
import com.twilio.sdk.verbs.TwiMLResponse;

public class Example extends HttpServlet {

  @Override
  public void service(final HttpServletRequest request, final HttpServletResponse response) throws IOException {
    TwiMLResponse twiml = new TwiMLResponse();
    Dial dial = new Dial();
    Queue queueInDial = new Queue("Queue Demo");

    try {
      twiml.append(dial);
      dial.append(queueInDial);
    } catch (final TwiMLException e) {
        e.printStackTrace();
    }

    return twiml.toXML();
  }
}
// Download the Node helper library from twilio.com/docs/node/install
var twilio = require('twilio');
var twiml = new twilio.TwimlResponse();

twiml.dial({}, function() {
    this.queue('Queue Demo');
})
console.log(twiml.toString());
# Download the Python helper library from twilio.com/docs/python/install
from twilio import twiml

r = twiml.Response()
with r.dial() as d:
    d.queue("Queue Demo")
print(str(r))
require 'sinatra'
require 'twilio-ruby'

# Handles the POST request from Twilio and generates the TwiML that connects agent 
# with the first caller in the Queue
post '/agent/?' do
  response = Twilio::TwiML::Response.new do |r|
    r.Dial do |d|
      d.Queue "Queue Demo"
    end
  end
  response.text
end
<?php
// NOTE: This example uses the next generation Twilio helper library - for more
// information on how to download and install this version, visit
// https://www.twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php';

use Twilio\Twiml;

$response = new Twiml();
$response->dial()
    ->queue('Queue Demo');

echo $response;
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Queue>Queue Demo</Queue>
  </Dial>
</Response>

To connect to the first caller in the Queue all we do is Dial the Queue by name.

Automatically Connecting to the next Caller

By default the call will end when the Agent or Caller hang up, but in most cases we'll want to connect to the next Caller automatically.

Automatically Connect to the Next Caller
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
SDK Version:
  • 4.x
  • 5.x
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require("Services/Twilio.php");
$response = new Services_Twilio_Twiml;
$response->say("You will now be connected to the first caller in the queue.");
$dial = $response->dial();
$dial->queue("Queue Demo");
$response->redirect();
print $response;
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using Twilio.TwiML;
using Twilio.TwiML.Mvc;

private static TwiMLResult AutoConnect()
{
    var twiml = new TwilioResponse();
    twiml.Say("You will now be connected to the first caller in the queue.");
    twiml.BeginDial()
          .Queue("Queue Demo")
          .EndDial();
    twiml.Redirect();
    return new TwiMLResult(twiml);
}
// Install the Java helper library from twilio.com/docs/java/install
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.twilio.sdk.verbs.Dial;
import com.twilio.sdk.verbs.Queue;
import com.twilio.sdk.verbs.Redirect;
import com.twilio.sdk.verbs.Say;
import com.twilio.sdk.verbs.TwiMLException;
import com.twilio.sdk.verbs.TwiMLResponse;

public class Example extends HttpServlet {

  @Override
  public void service(final HttpServletRequest request, final HttpServletResponse response) throws IOException {
    TwiMLResponse twiml = new TwiMLResponse();
    Say say = new Say("You will now be connected to the first caller in the queue.");
    Dial dial = new Dial();
    Queue queueInDial = new Queue("Queue Demo");
    Redirect redirect = new Redirect();

    try {
      twiml.append(say);
      twiml.append(dial);
      dial.append(queueInDial);
      twiml.append(redirect);
    } catch (final TwiMLException e) {
        e.printStackTrace();
    }

    return twiml.toXML();
  }
}
// Download the Node helper library from twilio.com/docs/node/install
var twilio = require('twilio');
var twiml = new twilio.TwimlResponse();

twiml.say('You will now be connected to the first caller in the queue.')
    .dial({}, function() {
        this.queue('Queue Demo');
    })
    .redirect();

console.log(twiml.toString());
# Download the Python helper library from twilio.com/docs/python/install
from twilio import twiml

r = twiml.Response()
r.say("You will now be connected to the first caller in the queue.")
with r.dial() as d:
    d.queue("Queue Demo")
r.redirect()
print(str(r))
require 'sinatra'
require 'twilio-ruby'

# Handles the POST request from Twilio and generates the TwiML that connects agent 
# with the first caller in the Queue
post '/agent/?' do
  response = Twilio::TwiML::Response.new do |r|
    r.Say "You will now be connected to the first caller in the queue."
    r.Dial do |d|
      d.Queue "Queue Demo"
    end
    r.Redirect
  end
  response.text
end
<?php
// NOTE: This example uses the next generation Twilio helper library - for more
// information on how to download and install this version, visit
// https://www.twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php';

use Twilio\Twiml;

$response = new Twiml();

$response->say("You will now be connected to the first caller in the queue.");
$dial = $response->dial();
$dial->queue("Queue Demo");
$response->redirect();

echo $response;
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>You will now be connected to the first caller in the queue.</Say>
  <Dial>
    <Queue>Queue Demo</Queue>
  </Dial>
  <Redirect></Redirect>
</Response>

An empty <Redirect> verb will redirect the caller to the beginning of the TwiML, which will then Dial and connect to the next person in the Queue. As a final touch we add a <Say> verb to tell the agent that they are being connected to another caller.

More sophisticated workflows

With Twilio's TaskRouter you can implement very sophisticated call-center workflows like:

  • assigning available Agents to the next caller in the Queue
  • offering tiered support plans, that allow premium customers to skip the queue
  • routing certain callers to different teams based on business logic

Hopefully this guide got you up and running with Twilio Queues. Email us and let us know what features of Queue you would like to know more about.