Multi-Channel Chat with Twilio and Google App Engine

Time to read: 6 minutes

August 06, 2013
Written by
Kevin Whinnery
Twilion

Twilio_Chat

This is a syndicated post from Twilio Developer Evangelist, Kevin Whinnery, originally published on the Google Cloud Platform Blog.

Google App Engine enables developers to focus on their application’s logic by providing a scalable infrastructure and high-level APIs for persistence, file management, and other common web app needs. XMPP and Channels are among these APIs, making it ridiculously easy to write awesome real-time communications apps in the browser.

Today, we’re going to break down an example application (view it live, source code) that integrates these two App Engine services (plus SMS messaging from Twilio) in a group chat application that connects users via SMS, XMPP, and browser-based chat clients.

We won’t go through every line of code, but at a high level, this application is about receiving inbound messages and sending outbound messages. Let’s see how we do this via SMS, XMPP, and Channels.

Twilio SMS

Sending SMS text messages with the Twilio API requires signing up for a Twilio account. Once you’ve signed up for an account, you can use your account SID and auth token to make authenticated requests against the Twilio REST API. You could just use App Engine’s built-in URL fetch service to interact with the Twilio API, but our official helper library for Java makes authenticating requests and serializing data much easier, providing a POJO interface to Twilio resources and functionality. We’ll be using the Twilio helper in this example. If you’re looking for App Engine specific reference examples, our friends at Google included this reference documentation in their doc site.

In our chat application, all outbound communication and message dispatching is handled by the MultichannelChatManager class. In this application, we add subscribers to the chat room to an in-memory set. When it’s time to send out a message, we iterate over the members of this set and send out messages to all subscribers. We send out messages to SMS subscribers using the Twilio helper on line #56:

TwilioRestClient client = new TwilioRestClient("ACCOUNT_SID", "AUTH_TOKEN");

Map<string, string=""> params = new HashMap<string, string="">();
params.put("Body", messageBody);
params.put("To", sub);
params.put("From", "+16122948105");

SmsFactory messageFactory = client.getAccount().getSmsFactory();

try {
	Sms message = messageFactory.create(params);
	System.out.println(message.getSid());
} catch (TwilioRestException e) {
	e.printStackTrace();
}

To receive inbound communication, you will need to purchase a Twilio phone number or use the one given to you when you signed up for a Twilio account. You can configure this phone number to send an HTTP POST to a URL that you choose when an SMS message is received (this callback pattern is called a webhook). In this sample application, we have a Java servlet with a web.xml file configured to accept inbound SMS. In your Twilio number configuration, you would enter https://yourappname.appspot.com/sms, as below

SMSRequestURL

In the actual servlet, we handle inbound SMS messages first by looking for a “STOP” command, which will indicate that this user no longer wants to receive text messages from the app. Then, we confirm that the user is subscribed (by looking for their telephone number). Finally, we send out a message using our MultichannelChatManager class.

When Twilio sends your app the details of an SMS message with an HTTP request, it expects your app to respond with an XML format called TwiML. TwiML is a simple set of fewer than 20 XML tags that tells Twilio how to respond to inbound communication. The output of our SMS servlet is an XML (TwiML) document, which will send an SMS back to a user if they unsubscribe:

public class TwilioSmsServlet extends HttpServlet {
    // Handle Incoming SMS
	public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
		try {
			TwiMLResponse twiml = new TwiMLResponse();

			// parse the body, looking for a command
			String smsBody = request.getParameter("Body");
			String smsFrom = request.getParameter("From");

			// Unsubscribe, if requested
			if (smsBody.startsWith("STOP")) {
				MultichannelChatManager.removeSub(smsFrom);
				com.twilio.sdk.verbs.Sms bye = new com.twilio.sdk.verbs.Sms("You have been unsubscribed.  Thank You!");
				twiml.append(bye);
			} else {
				// If they aren't subscribed, subscribe them
				if (!MultichannelChatManager.isSubscribed(smsFrom)) {
					MultichannelChatManager.addSub(smsFrom);
				}
				MultichannelChatManager.sendMessage(smsBody, "sms");
			}

			response.setContentType("application/xml");
			response.getWriter().print(twiml.toXML());

		} catch (Exception e) {
			e.printStackTrace();
			System.out.println(e);
		}
	}
}

App Engine XMPP Integration

App Engine provides a simple API for sending and receiving XMPP chat messages. Our chat application can receive new messages over XMPP and send them back out to all subscribed clients, similar to how our app behaves for SMS.

App Engine applications have an XMPP username associated with them by default, which takes the form of “appname@appspot.com”. The former part of the username is your unique App Engine app ID and the latter is the appspot domain that your app runs on. To send a message via XMPP to our chat app we need to send a chat message to “twiliosandbox@appspot.com” from a chat client that supports XMPP. If you used the desktop chat client Adium for Google Talk, the interaction might look something like this:

chatexample

For our application to receive inbound XMPP messages, we need to configure an inbound message handler servlet in our web.xml configuration file. This webhook callback design is the same type of event mechanism used by Twilio to deliver SMS messages to our application. In this servlet, we receive an inbound POST request with information about an inbound chat message:

public class XMPPReceiverServlet extends HttpServlet {
    // Handle Incoming XMPP Chat messages
    public void doPost(HttpServletRequest req, HttpServletResponse res) throws IOException {
     XMPPService xmpp = XMPPServiceFactory.getXMPPService();
     Message msg = xmpp.parseMessage(req);

        // The "JID" is the unique ID of this chat client, which we use to subscribe
     JID fromJid = msg.getFromJid();
     String body = msg.getBody();

     // Unsubscribe, if requested
     if (body.startsWith("STOP")) {
      MultichannelChatManager.removeSub(fromJid.getId());
     } else {
      // If they aren't subscribed, subscribe them
      if (!MultichannelChatManager.isSubscribed(fromJid.getId())) {
       MultichannelChatManager.addSub(fromJid.getId());
      }
      MultichannelChatManager.sendMessage(body, "xmpp");
     }
    }
}

To send outbound messages, we use the App Engine platform APIs to send an outbound message to a specific JID, which uniquely identifies a connected XMPP client:

JID jid = new JID(sub);
Message msg = new MessageBuilder().withRecipientJids(jid).withBody(messageBody).build();
XMPPService xmpp = XMPPServiceFactory.getXMPPService();
xmpp.sendMessage(msg);

Channel API

The Channel API allows server-side push to connected clients in an App Engine application. In our chat application, we will utilize this API to push new chat messages to browser-based clients.

In order for our server to push chat messages to a browser, the client needs to be issued an ID by our server. We configure a servlet to handle issuing these IDs (and to handle incoming chat messages created by the browser in JavaScript) in web.xml. The servlet generates a unique ID for a connected client, based on the current system time:

//Generate a client token for the GAE Channel API
public void doGet(HttpServletRequest req, HttpServletResponse res) throws IOException {
ChannelService channelService = ChannelServiceFactory.getChannelService();

//The token must be based on some unique identifier for the client - I am using the current time
//for demo purposes...
String clientId = String.valueOf(System.currentTimeMillis());
String token = channelService.createChannel(clientId);

//Subscribe this client
MultichannelChatManager.addSub(clientId);

//Reply with the token
res.setContentType("text/plain");
res.getWriter().print(token);
}

In the browser, we get an ID for the current user via XHR. First, we include the Channel client JavaScript library by requesting a special URL on the App Engine server. Then we use jQuery to issue a GET request to our server to obtain a client ID:

//Get a client token to use with the channel API
$.ajax('/chat',{
    method:'GET',
    dataType:'text',
    success: function(token) {
        console.log(token);
        var channel = new goog.appengine.Channel(token);
        var socket = channel.open();

        //Assign our handler function to the open socket
        socket.onmessage = onMessage;
    }
});

When we get our client ID, we use that to configure the App Engine channel service in the browser for data pushed from the server. Data pushed from the server is handled in a callback function, which updates the textarea on the page. When the user enters a chat message in the browser, we issue a POST request to our ChatServlet, which uses the MultichannelChatManager class to publish a message to all connected clients. This is where we use the channel API to push data to connected web browsers:

ChannelService channelService = ChannelServiceFactory.getChannelService();
channelService.sendMessage(new ChannelMessage(sub,messageBody));

Wrapping Up

In this walkthrough, we explored three messaging APIs that work nicely on App Engine: Twilio SMS, XMPP, and Channels. Our example used Java, but all three APIs will work with Python and Go as well (Twilio has a helper library you might use for Python also).

Using platforms like Twilio and App Engine, developers can create communications applications, which previously would have required expert knowledge and infrastructure to build, in a fraction of the time. I hope you’ll be able to use these APIs to engage with your users wherever they happen to be.

Application source code is available on GitHub here.

 

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.