Creating Tasks and Accepting Reservations: Set up the Assignment Callback URL

The basic lifecycle of a [successful] TaskRouter Task is as follows:

Task Created → eligible Worker becomes available → Worker reserved → Reservation accepted → Task assigned to Worker.

In this part of the tutorial, we'll create Tasks and observe them through each of these stages. We start by creating a Task using the Tasks REST API. First time around we accept the Task using the Reservations REST API, then we create another Task and accept it using assignment callback instructions.

(information)

Info

Both the Reservations REST API and assignment callback instructions are valid methods for accepting a Reservation; it's likely that you'll choose one or the other based on the amount of background work that must be performed by your server before it accepts or rejects a Reservation. For example, due to the amount of time required, if you were to build a user interface that allowed human agents to inspect a Task before accepting it, you would need to accept the Reservation asynchronously using the Reservations REST API.

Set up the Assignment Callback URL

Whether we accept Reservations via the REST API or via assignment callback instructions, we always need an Assignment Callback URL that is reachable by TaskRouter. This is the URL at which TaskRouter will notify us when a Worker is reserved to perform a Task. Before creating any Tasks, let's get the Assignment Callback URL up and running.

Finally time to write some (albeit minimalist!) code.

We are going to write a Java servlet to respond to HTTP requests, so we can tell Twilio what to do when we receive an assignment callback.

First set up the Java servlet class that will respond to incoming requests.

TwilioTaskRouterServlet.java

1import java.io.IOException;
2
3import javax.servlet.http.HttpServlet;
4import javax.servlet.http.HttpServletRequest;
5import javax.servlet.http.HttpServletResponse;
6
7public class TwilioTaskRouterServlet extends HttpServlet {
8  // service() responds to both GET and POST requests.
9  // You can also use doGet() or doPost()
10  @Override
11  public void service(final HttpServletRequest request, final HttpServletResponse response)
12      throws IOException {
13    if (request.getPathInfo() == null || request.getPathInfo().isEmpty()) {
14      return;
15    }
16
17    if (request.getPathInfo().equals("/assignment_callback")) {
18      response.setContentType("application/json");
19      response.getWriter().print("{}");
20    }
21  }
22}
23

taskrouter/WEB-INF/web.xml

1<?xml version="1.0" encoding="ISO-8859-1"?>
2<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
3    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
5    version="2.4">
6
7    <display-name>Twilio TaskRouter App</display-name>
8
9    <servlet>
10        <servlet-name>TwilioTaskRouterServlet</servlet-name>
11        <servlet-class>com.twilio.TwilioTaskRouterServlet</servlet-class>
12    </servlet>
13
14    <servlet-mapping>
15        <servlet-name>TwilioTaskRouterServlet</servlet-name>
16        <url-pattern>/taskrouter/*</url-pattern>
17    </servlet-mapping>
18
19</web-app>

This returns an empty JSON document to TaskRouter with a 200 (OK) response code. This tells TaskRouter that the assignment callback was successfully received and parsed, but that we don't want to take any action on the Reservation right now. Instead, it's implied that we will use the REST API to accept or reject the Reservation when we are ready.

Make sure your Java server is running (Tomcat, Jetty, JBoss, etc.). Your servlet will be available here: http://yourwebserver.com/<path-to-servlet>/taskrouter.

Let Twilio find your server

At this point in the tutorial, you will need to find a way to expose your server to the public Internet for Twilio to interact with your development server. Here are some helpful tools:

For this tutorial, we'll use ngrok. After installing ngrok to your $PATH, run the following command at your terminal to start listening for requests from the outside world:

ngrok http 8080

Your local Java server is now accessible to anyone (including Twilio's servers) at your ngrok URL.

With those things working, edit your "Incoming Customer Care Requests" Workflow to point at the newly implemented Assignment Callback URL:

http://yourngrokserver.com/<path-to-servlet>/taskrouter/assignment_callback

Excellent. We're ready to create Tasks and accept Reservations.

Next: Create a Task using the REST API »