Google Wave Robots API: Overview

A robot is an automated participant on a wave. A robot can read the contents of a wave in which it participates, modify the wave's contents, add or remove participants, and create new blips and new waves. In short, a robot can perform many of the actions that any other participant can perform. Robots are created and manipulated using the Google Wave Robots API.

You can use the Robots API to perform actions such as the following:

• modify information in a wave
• interact with participants on a wave
• communicate and synchronize information in a wave to the outside world or to other waves
• access or modify state in a third-party system (such as a database)

Robot behavior in the Wave Robots API has been upgraded to version 2, involving a major revision to Wave Robot Wire protocol, and associated client libraries. Please consult the recently updated Java Tutorial and Python Tutorial to get acquainted with the new API. This updated version is a major improvement to the API providing both significant functionality and better performance. Note that while being feature equivalent to the previous API, this new version is not backwards compatible. In particular, significant changes in the Java client library have been implemented. Please migrate your code to use this new version of the API. The older legacy V1 version of the Wave API is deprecated and will be retired on June 30, 2010.

Obtaining a Robot Client Library

Development of Google Wave robots requires an appropriate client library. We currently have client libraries for the Java™ and Python programming languages.

You can find out more information about the client libraries, file issues, and make feature requests on the Google Wave Resources home page on Google Project Hosting. This page also contains download links for the latest client libraries.

We've recently updated both the Python and Java client libraries to version 2 of the API, which has added many new features, while also removing many language dependencies from the API. As a result, both APIs are now quite similar in use and scope. We encourage you to download and utilize these new client libraries. The original Wave API (V1) is now deprecated in favor of V2. V1 will no long function after June 30, 2010.

Robot Troubleshooting

Robots within the Wave API are "versioned" through use of a hash value, which is based on the robot's event signature. When altering the robot's behavior when handling events, the Wave API will generate a new hash value. This allows the Wave system to detect when robots have changed and/or their capabilities have been altered. You can use this value as well to detect that your changes have been properly implemented.

If you have trouble during development of your robot, the following tests may be helpful:

• Is your robot's capabilities.xml file live? You can test whether the file is properly deployed by accessing the robot at http://robotname.appspot.com/_wave/capabilities.xml. If you receive an XML response, you know your robot has been properly deployed to App Engine.
• Has your robot's version changed? If you've changed the capabilities of this robot (by altering the way it handles events), you should see a different hash value stored within the version tag of the automatically generated capabilities.xml file.
• Are you monitoring the right events? Have you set up handlers for each of the events you wish to intercept? Do those handlers make use of the event data and/or context passed within the event properly? You can inspect the capabilities.xml file to ensure that your robot is set up to receive the correct events.
• Is App Engine serving the correct version? App Engine allows you to deploy multiple versions as well. Though you likely should not change this during development, you may wish to do so in production to avoid breaking existing waves and/or clients.
• Is there an error in the App Engine Logs? Consult the App Engine logs at https://appengine.google.com for your robot deployment. If you receive an error, you likely have a coding error.

We welcome your feedback during this developer preview! Please post your comments and suggestions to the Google Wave API group.