An App Engine application can send and receive instant messages to and from any XMPP-compatible instant messaging service, such as Google Talk. An app can send and receive chat messages, send chat invites, and request status information. Incoming XMPP messages are handled by request handlers, similar to web requests.
Some possible uses of instant messages include automated chat participants ("chat bots"), instant 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 the "chat" and "normal" types. An app can send messages of any type defined in RFC 3921.
An app can send messages to any XMPP address by calling the XMPP service API. An app can also use the API to send chat invitations, and query a user's status (available to chat, or not available).
A chat message can be of any of the five types defined in RFC 3921. Note that an app can only receive messages of the types "chat" and "normal."
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 = 'example@gmail.com'
chat_message_sent = False
if xmpp.get_presence(user_address):
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.
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, when App Engine receives a chat message for the app, it makes an HTTP POST request to the following URL path:
/_ah/xmpp/message/chat/
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 messageto, the address of the recipient as described by the sender (see below)body, the body of the messagestanza, the full XMPP message in its original XML formAn 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 from, to and 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 webapp framework:
from google.appengine.api import xmpp
from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
class XMPPHandler(webapp.RequestHandler):
def post(self):
message = xmpp.Message(self.request.POST)
if message.body[0:5].lower() == 'hello':
message.reply("Greetings!")
application = webapp.WSGIApplication([('/_ah/xmpp/message/chat/', XMPPHandler)],
debug=True)
def main():
run_wsgi_app(application)
if __name__ == "__main__":
main()
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 self.request.get('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:
app-id@appspot.com
An app can also use a custom address in the following format, where anything is any string containing letters, numbers and hyphens:
anything@app-id.appspotchat.com
(Notice the different domain name for custom addresses: appspotchat.com)
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.
The @appspot.com address and the @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:
anything@version.latest.app-id.appspotchat.com
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 app-id@appspot.com, the sender address becomes app-id@version.latest.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.
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: node@domain/resource
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 will 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 the service API. 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 automatically, and does not communicate invitations to the application. App Engine will route all chat messages to the application, regardless of whether the sender previously sent an invitation to the app.
If a user has "subscribed" to an app (has accepted an invitation or has invited the app to chat), the app can query whether a Google Talk user has a chat client running using the XMPP service API. The app can detect two possible status values: the user is connected, or the user is not connected. The app cannot determine the "away" status, nor can it determine the user's status message.
An app can only query the status of Google Talk users, and only those that have "subscribed" to the app. There is no way for an XMPP service to query the status of users on other XMPP services.
App Engine reports a status of connected and available for all applications, regardless of whether the app supports receiving XMPP messages. There is no way to set a status message for an app.
Each XMPP service request counts toward the XMPP API Calls quota.
Each outgoing XMPP chat message counts toward the following quotas:
Each outgoing XMPP chat invitation counts toward the following quotas:
Each incoming XMPP message counts toward the following quotas:
Computation performed in a request handler for incoming XMPP messages applies toward the same quotas as with web requests and tasks.
For more information on quotas, see Quotas, and the "Quota Details" section of the Admin Console.
In addition to quotas, the following limits apply to the use of the XMPP service:
| Limit | Amount |
|---|---|
| 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.