An App Engine application can send and receive chat messages to and from any XMPP-compatible chat messaging service, such as Google Talk. An app can send and receive chat messages, send chat invites, request a user's chat presence and status, and provide a chat status. Incoming XMPP messages are handled by request handlers, similar to web requests.
Some possible uses of chat messages include automated chat participants ("chat bots"), chat notifications, and chat interfaces to services. A rich client with a connection to an XMPP server (such as Google Talk) can use XMPP to interact with an App Engine application in real time, including receiving messages initiated by the app. (Note that such a client using Google Talk must use the user's password to make an XMPP connection, and cannot use a Google Accounts cookie.)
Currently, an app cannot participate in group chats. An app can only receive messages of types "chat" and "normal". An app can send messages of any type defined in RFC 3921.
- Sending chat messages
- Handling incoming calls
- XMPP addresses
- JIDs and resources
- Sending invitations
- Sending the application's chat status
- Quotas and limits
Sending chat messages
An app can send chat messages to any XMPP address by calling the XMPP service API. A chat message can be of any of the five types defined in RFC 3921. Note that an app can only receive two types of messages:
- chat messages via
- normal messages via
For the body of the message, an app can provide plain text that is displayed to the user, or it can provide an XML stanza that is included in the XMPP XML data. You can use XML message data to communicate structured data to a custom client.
The following example tests for a user's availability, then sends a chat message.
from google.appengine.api import xmpp # ... user_address = 'email@example.com' chat_message_sent = False msg = "Someone has sent you a gift on Example.com. To view: http://example.com/gifts/" status_code = xmpp.send_message(user_address, msg) chat_message_sent = (status_code == xmpp.NO_ERROR) if not chat_message_sent: # Send an email message instead...
When an app running in the development server sends an XMPP message, the fields of the message are printed to the console, and no message is sent. The development server cannot send XMPP messages on behalf of the app.
Handling incoming calls
App Engine provides three inbound services to manage messages, subscriptions, and presence:
xmpp_messageallows your application to receive chat messages from XMPP-compliant chat services.
xmpp_subscribeallows subscriptions between users and your application for the purpose of exchanging data, such as chat messages, presence information, and status messages.
xmpp_presenceallows your application to determine a user's chat presence (available or unavailable).
xmpp_errorallows your application to receive error stanzas.
You can enable these inbound services in
inbound_services: - xmpp_message - xmpp_presence - xmpp_subscribe - xmpp_error
The following sections show you how to handle these inbound services in your application:
Receiving chat messages
Users of XMPP-compliant chat services can send chat messages to App Engine applications. For an app to receive chat messages, the XMPP message service must be enabled in the app's configuration.
To enable the XMPP service for a Python app, edit the
app.yaml file and include the following lines:
inbound_services: - xmpp_message
With the XMPP service enabled, App Engine makes an HTTP POST request to the following URL path when your app receives a chat message:
To handle incoming messages, you simply create a request handler that accepts POST requests at this URL path.
This URL path is restricted to app administrators automatically. The XMPP service connects to the app with "administrator" status for the purposes of accessing this URL path. You can configure the path to have this restriction explicitly if you like, but this is not necessary. Only the XMPP service and clients authenticated as administrators using Google Accounts can access this URL path.
The POST request data represents the message as a MIME multipart message (RFC 2388). Each part is a named POST parameter:
from, the address of the sender of the message
to, the address of the recipient as described by the sender (see below)
body, the body of the message
stanza, the full XMPP message in its original XML form
An app can receive messages of two XMPP types: "chat" and "normal." If App Engine receives an XMPP message of an unsupported type, the message is ignored and the request handler is not called.
The Python API includes several features to make it even easier to parse XMPP messages. The constructor for the Message class takes a dict-like object with the fields
body, which for most web application frameworks is simply an object representing the request. You can use the Message object to access these fields, and to reply to the message conveniently.
Here is an example handler script using the webapp2 framework:
import webapp2 from google.appengine.api import xmpp class XMPPHandler(webapp2.RequestHandler): def post(self): message = xmpp.Message(self.request.POST) if message.body[0:5].lower() == 'hello': message.reply("Greetings!") app = webapp2.WSGIApplication([('/_ah/xmpp/message/chat/', XMPPHandler)], debug=True)
The webapp framework includes classes that makes it easy to handle incoming XMPP messages, especially for implementing chat robots that accept commands. See
google.appengine.ext.webapp.xmpp_handlers in the SDK for more information on these classes.
A Python app can also just use
self.request.get() to access the MIME multipart parameters. For example, to access the full XML of the message, you can call
xmpp_subscribe inbound service allows your application to receive updates to a user's subscription information via POSTs to the following URL paths:
- POSTs to
/_ah/xmpp/subscription/subscribe/signal that the user wishes to subscribe to the application's presence.
- POSTs to
/_ah/xmpp/subscription/subscribed/signal that the user has allowed the application to receive its presence.
- POSTs to
/_ah/xmpp/subscription/unsubscribe/signal that the user is unsubscribing from the application's presence.
- POSTs to
/_ah/xmpp/subscription/unsubscribed/signal that the user has denied the application's subscription request, or cancelled a previously granted subscription.
These URLs correspond to the stanzas used for managing subscriptions described in the XMPP Instant Messages and Presence Protocol.
The following code sample demonstrates how to track subscriptions using webhooks to the above handlers. The following code sample uses POSTs to the above handlers to maintain a roster of subscribed users in the datastore:
# In the handler for _ah/xmpp/presence/subscribe # Split the bare XMPP address (e.g., firstname.lastname@example.org) # from the resource (e.g., gmail), and then add the # address to the roster. sender = self.request.get('from').split('/') roster.add_contact(sender)
Handling user presence
xmpp_presence inbound service allows your application to detect changes to a user's chat presence. When you enable
xmpp_presence, your application receives POSTs to the following URL paths:
- POSTs to
/_ah/xmpp/presence/available/signal that the user is available and provide the user's chat status.
- POSTs to
/_ah/xmpp/presence/unavailable/signal that the user is unavailable.
- POSTs to
/_ah/xmpp/presence/probe/request a user's current presence.
Your application can register handlers to these paths in order to receive notifications. You can use these notifications to track which users are currently online. If you wish to check the most current status, you can use the
send_presence method with the
presence_type parameter set to
PRESENCE_TYPE_PROBE. This will result in POSTs to the above paths reflecting the user's
If a Google talk user has subscribed to an app (has accepted an invitation or has invited the app to chat), the app can discover the user's availability by looking for a POST to
/_ah/xmpp/presence/available. If the user is subscribed and available, you can send them your application's presence and status:
# In the handler for _ah/xmpp/presence/available # Split the bare XMPP address (e.g., email@example.com) # from the resource (e.g., gmail.CD6EBC4A), and then send the # application's presence to the user. sender = self.request.get('from').split('/') xmpp.send_presence(sender, status=self.request.get('status'), presence_show=self.request.get('show'))
Handling error stanzas
xmpp_error inbound service allows your application to receive XMPP error stanzas. Error stanzas are most commonly sent as a result of sending a message to a user who's offline.
With the error service enabled, App Engine makes an HTTP POST request to the following path when your app receives an error stanza:
You can register a handler at this address to be notified of XMPP errors. This handler may be responsible for eg. diagnostics or logging.
# In the handler for _ah/xmpp/error # Log an error error_sender = self.request.get('from') error_stanza = self.request.get('stanza') logging.error('XMPP error received from %s (%s)', error_sender, error_stanza)
An application can send and receive messages using several kinds of addresses, or "JIDs." One kind of address uses the application ID and the
appspot.com domain, as follows:
An app can also use a custom address in the following format, where
anything is any string containing letters, numbers and hyphens:
The use of Google Apps domains in XMPP addresses is not yet supported for apps. Of course, users with Google accounts on your domain can use the domain for their Google Talk addresses, as usual.
The app can choose which address is used as the sender address when sending a message. All messages sent to any address in the supported formats are routed to the application.
Addresses and app versions
@appspot.com address and the
@your_app_id.appspotchat.com addresses all refer to the default version of the app. Messages sent to these addresses are routed to the default version. When the default version of an app sends a message, the requested address is used as the sender of the message. Replies to the app's messages are routed to the default version, even if the default version has changed since the original message was sent.
Each version of an app has its own set of XMPP addresses in the following format:
If App Engine receives a message for an address in this format, it is routed to the corresponding version of the app (if that version still exists).
If a version of an app sends a message and that version is not the default, the sender address of the message is changed to an address in this format. If the sender is
firstname.lastname@example.org, the sender address becomes
email@example.com_app_id.appspotchat.com. This ensures that replies to a message sent by a specific non-default version of the app are routed back to that version.
JIDs and resources
An XMPP address, also known as a "JID," has several components: a node (such as the name of a user of a chat service), a domain (the domain name of the service), and an optional resource. These components are separated by punctuation:
When establishing a chat conversation with a human user of a chat service, you typically use just the node and domain parts of the JID. Each chat client the user has connected to the service may have its own resource, and sending a message to the JID without the resource sends it to all of the user's clients.
A JID without a resource is known as a "bare JID". A JID with a resource is a "full JID". App Engine's XMPP service supports both bare and full JIDs for recipient and sender addresses of messages.
When sending a message, if you use a bare JID as the sender address, the XMPP service automatically uses the resource
/bot. If another XMPP user sends a message to the app using a full JID with a custom resource, the app can see which resource was used by inspecting the
to field of the incoming message.
Google Talk and other chat servers only accept messages for users that are "subscribed" to the sender, either because the user invited the sender to chat or because the user accepted an invitation to chat sent by the sender. An App Engine app can send chat invitations using
As with sending email, a best practice is to send a chat invitation only when the user asks, such as by clicking a button on a web page. Alternatively, the app can ask the user to send an invitation to the app's XMPP address to enable receiving of messages.
App Engine accepts all chat invitations and automatically registers subscriptions as described in the Handling Subscriptions section. App Engine routes all chat messages to the application, regardless of whether the sender previously sent an invitation to the app.
Sending the application's chat status
send_presence() API allows the application to send the application's presence, along with an optional status message, to a given JID. By default, the application appears available with no status message. You can set the status message as follows:
xmpp.send_presence(to_jid, status="My app's status")
Quotas and limits
Each XMPP service request counts toward the XMPP API Calls quota.
Each outgoing XMPP chat message counts toward the following quotas:
- XMPP Data Sent
- XMPP Recipients Messaged
- Outgoing Bandwidth (billable)
Each outgoing XMPP chat invitation counts toward the following quotas:
- XMPP Data Sent
- XMPP Invitations Sent
- Outgoing Bandwidth (billable)
Each incoming XMPP message counts toward the following quotas:
- Incoming Bandwidth (billable)
Each incoming presence and subscription message counts as a normal HTTP request.
Computation performed in a request handler for incoming XMPP messages applies toward the same quotas as with web requests and tasks.
In addition to quotas, the following limits apply to the use of the XMPP service:
|incoming message size||100 kilobytes|
|outgoing message size||100 kilobytes|
There is no explicit limit to the number of recipients for a message. However, each message is sent and metered separately for each recipient. A message with 30 recipients consumes 30 times as much of the affected quotas as a message with 1 recipient. Also, the total size of the API call is limited to 1 megabyte, including the total size of the recipient list and the message body.