Google Wave allows client applications to fetch and modify waves on behalf of
users, using the Wave Data Protocol detailed in this document.
The protocol is based on sending JSON-RPC messages to the Wave server, and
receiving JSON in response.
Instead of using the protocol to create your application, you can use the
existing client libraries, and let them take care of forming and parsing the
However, understanding the protocol can help you debug your application much
more efficiently, allowing you to inspect and understand the messages
which get transmitted and received. As well, understanding the protocol
allows you to directly communicate with Wave without use of a client
library, and could potentially allow you to create your own client library.
- Robot Operations
- Wavelet Operations
- Blip Operations
- Document Operations
All interactions with Wave data require authentication via OAuth.
For information about authentication a user of your application this way,
read OAuth for Web Applications.
When accessing the Wave Data APIs, an authorization token must be authorized
for this scope:
All other parameters, like the endpoints for generating access tokens,
are the same as other Google services and defined in the documentaton linked
To interact with waves, an application can send operations to Wave. These operations
JSON-RPC messages. A simple message which sets a wave's title,
creates a blip, and writes "Hello World" is shown below:
"waveletTitle": "A wavelet title"
"text": "Hello World",
Note that this JSON message contains no root element. Instead it contains a
params array, which in turn contains several
params appropriate to the
particular operation. Operations are ordered by their
even though operations are usually bundled together.
Operation methods operate on the following namespaces within the
Note that all blips contain a document as well, which contains their
actual content, so most
document operations also apply
Robot operations are those operations not tied to a particular element
in the wave (e.g. wavelet, blip, etc.) All operations that operate over
all these elements are attached to the "robot" namespace. You can think
robot operations as global operations.
Some robot operations use a
to pass information about a wavelet back to the Wave server. A
WaveletData object (in JSON) is shown
"content": "n ",
"title": "A wavelet title",
|This operation is automatically prepended to any operation
bundle sent back to the server, passing a hash of the current
capabilities.xml file. This hash identifies
the signature of the robot; if this hash is different from the
version currently on the server, the server can fetch a new
capabilities document before processing the rest of the operations.
robot.createWavelet(waveletData: WaveletData, message: String)
|This operation creates a new wavelet within a new wave.
waveletData parameter specifies the details
of the wavelet. The client should provide the system with temporary
string ids (using a
"TBD_" prefix) in the specified
waveletData object, that the client can use to send
subsequent operations to the created wavelet. Upon creating the
wavelet, the server will immediately generate a
event, containing the passed message parameter. This message allows
you to track the wavelet.
Note: There is not yet an operation for robots to create wavelets within
the current wave ("private replies").
robot.fetchWavelet(waveId: String, waveletId: String, message: String)
|This operation requests a wavelet. Two objects are returned: a
waveletData object of type
WaveletData that describes the wave and
a list of
blips of type
wave.robot.search(query: String, index: Integer, numResults: Integer)
|This operation searches across the user's waves. This first parameter,
query, is the search string, similar to the one that you specify
in the search panel in the client, for example, "in:inbox".
numResults indicates desired number of results, and defaults
to 10 if not specified.
This operation returns a list of search snippets. Each entry contains several
and a list of participants.
expressed in UTC as milliseconds since the epoch (midnight, January 1, 1970).
wave.robot.folderAction(modifyHow: String, waveId: String)
|This operation modifies the state of the given
modifyHow, dictates the action that needs to be
done. Available actions:
archive (Note: this is the default action, if you don't pass
Wavelet operations are operations specific to a particular
wavelet within the wave.
wavelet.appendBlip(waveId: String, waveletId: String, blipData: BlipData)
|Appends a blip to the specified wave.
wavelet.setTitle(waveId: String, waveletId: String, waveletTitle: String)
|Sets the the title of the specified wave.
wavelet.addParticipant(waveId: String, waveletId: String, participantId: String)
|Adds a participant to the wave. The
participantId is the address
of the participant to add.
wavelet.setDatadoc(waveId: String, waveletId: String, datadocName: String, datadocValue: String)
|Sets a data document for a wavelet. Data documents are comparable to normal (blip)
documents but are typically not shown to the user and do not have any
schema applied to them.
Blip operations are operations specific to particular blips
within a wavelet. Note that all blips are also documents as
well, so operations specific to documents are also
applicable to blips (but not vice-versa).
blip.createChild(waveId: String, waveletId: String, blipdId: String, blipData: BlipData)
|Creates a reply to the current blip, taking the data for the new blip from
blip.delete(waveId: String, waveletId: String, blipdId: String)
|Deletes the blip with the specified
Document operations are operations specific to documents (and blips).
document.appendMarkup(waveId: String, waveletId: String, blipdId: String, content: String)
|Appends HTML (or XHTML) markup passed in the
to the current wave. The built-in copy & paste functionality of wave is used to
convert the content to something wavey.
document.modify(range: Range, index: Integer, modifyQuery: DocumentModifyQuery, modifyAction: DocumentModifyAction)
|This operation modifies a document and encodes two parts. Only
one of range, index and modifyQuery can be set. This determines where the
modification will be applied. The
modifyAction parameter specifies
what needs to be done.
There is currently no way for an application using the Wave Data API to
register for events on a user's wave state changes. The only way to
detect changes it to call
and then compare the returned waves to older known versions of the the waves.