Streaming API

Use the streaming API to listen to messages, events and changes in flows. The streaming API allows real-time access to flows. Unlike other APIs, all requests to the streaming API should be made to stream.flowdock.com. 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 CA Flowdock 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 a wait few seconds before trying again.

Content Types

The streaming API supports two different content types: JSON stream and Event-Stream. Applications can use the Accept header or accept query string parameter to choose the content type: application/json for the JSON stream and text/event-stream for Event-Stream. If no content type is specified, the streaming API will use application/json.

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.

Event-Stream (text/event-stream)

Event-Stream follows the HTML5 Server-Sent Events specification. Each event contains a JSON-encoded message.

Each event message contains id string that can sent to server when reconnecting. The server then responds by streaming all messages since the last disconnection.

Resources

GET /flows

Returns all messages from flows specified in the filter query parameter.

For example, to stream the flows example/main and example/flow, a request should be made to https://stream.flowdock.com/flows?filter=example/main,example/flow.

Parameters

Name	Description
filter	Comma separated list of flows, e.g. example/main,example/flow. You can also use flow ids. Either this or user needs to be set.
user	When set to 1, stream private messages that are sent to the user. Either this or filter needs to be set.
accept	Define the content-type if the Accept header cannot be used.
active	Show user as active in CA Flowdock. Defined values true and idle. If not present, user will appear offline.

GET /flows/:organization/:flow

Convenience method to stream messages from a single flow. Uses same parameters as GET /flows.

Browser Example

The EventSource API is implemented in most browsers. Even older browsers can use this interface via a polyfill.

    var stream = new EventSource('https://stream.flowdock.com/flows?filter=<flow-id>&access_token=<oauth-token>')
    stream.onmessage = function(event) {
      var message = JSON.parse(event.data);
      // handle message
    }

Ruby Example (JSON stream)

    require 'eventmachine'
    require 'em-http'
    require 'json'

    # token = your Flowdock access token
    # organization = parametrized organization name
    # flow = name of flow in URL

    http = EM::HttpRequest.new(
      "https://stream.flowdock.com/flows/#{organization}/#{flow}",
      :keepalive => true, :connect_timeout => 0, :inactivity_timeout => 0)
    EventMachine.run do
      s = http.get(:head => { 'Authorization' => [token, ''], 'accept' => 'application/json'})

      buffer = ""
      s.stream do |chunk|
        buffer << chunk
        while line = buffer.slice!(/.+\r\n/)
          puts JSON.parse(line).inspect
        end
      end
    end

Ruby Example (Event-Stream)

Another Ruby example that uses the em-eventsource library and Event-Stream content type: https://github.com/AF83/em-eventsource/blob/master/examples/flowdock.rb