Streaming API

Use the streaming API to listen to messages, events and changes in rooms. The streaming API allows real-time access to rooms. Unlike other APIs, all requests to the streaming API should be made to stream.gitter.im. Authentication is identical to the REST API Authentication.

Connecting

To connect to the Streaming API, form a HTTP request and consume the resulting stream for as long as is practical. The Gitter servers will hold the connection open indefinitely (barring a server-side error, excessive client-side lag, network hiccups or routine server maintenance). If the server returns an unexpected response code, clients should wait a few seconds before trying again.

Content Types

The streaming API supports JSON stream content type.

Content is encoded as UTF-8.

JSON Stream (application/json)

The JSON stream returns messages as JSON objects that are delimited by carriage return (\r). Newline characters (\n) may occur in messages, but carriage returns should not.

Parsers must be tolerant of occasional extra newline characters placed between messages. These characters are sent as periodic "keep-alive" messages to tell clients and NAT firewalls that the connection is still alive during low message volume periods.

Resources

GET /v1/rooms/:roomId/:resource

Available resources are:

  • chatMessages
  • events

Returns rooms messages as they come in.

Try it from the CLI:

$ curl -i -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "https://stream.gitter.im/v1/rooms/:roomId/chatMessages"
https://stream.gitter.im/v1/rooms/:roomId/chatMessages?access_token={{token}}
  • curl
  • http

Node.js Example

You can find a node example client at https://github.com/gitterHQ/gitter-node-stream.

Ruby Example

You can find a ruby example client at https://github.com/gitterHQ/gitter-ruby-stream.