Today we’re introducing a new Streaming API, which we hope will ease the process of building your own Flowdock clients and bots. Streaming API allows real-time access to everything that happens inside a flow.

Using the API

Streaming API comes in two flavours: carriage-return delimited JSON stream and HTML5 Event-Stream.

If you have used the Twitter Streaming API, you should be familiar with our JSON Stream. You can try it out using curl.

$ curl -i -H "Accept: application/json" https://<token>@stream.flowdock.com/flows/<organization>/<flow>
HTTP/1.1 200 OK
Server: Florence
Cache-Control: no-cache
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive


{"event":"message","tags":[],"uuid":"pWkb-CPeyFG66ns-","id":142790,"flow":"example:main","content":"hello world","sent":1329307314476,"app":"chat","attachments":[],"user":"1"}
{"event":"message","tags":[],"uuid":"uk7TFsf75WEJbWsy","id":142791,"flow":"example:main","content":"test","sent":1329307316726,"app":"chat","attachments":[],"user":"1"}
...

Event-Stream is part of HTML5 Server-Sent Events specification. In our streaming API each event contains a JSON encoded message as data. To use Event-Stream, set Accept header to text/event-stream. If this isn’t possible, you can also use accept query parameter. In addition to support in modern browsers, there are client libraries, and it isn’t hard to roll your own.

Under the hood

We built a HTTP server using CoffeeScript and NodeJS to run our Streaming API. Combined with a little Redis and authentication magic, we were ready to go.

As a new message is sent to Flowdock, we process the message and publish it to the corresponding flow’s Redis pub/sub channel. When a new client connects, our server subscribes to flow channels the client wishes to listen to. Every time a subscriber receives a new message, we will check if there are any connected clients for that flow, and if so we will dispatch the message down to existing connection in the appropriate JSON/Event-Stream format.

We’re looking forward to see what amazing applications can be built on top of the Streaming API. If you have any issues or feedback, feel free to contact us.