The Blog

The what's what of the Flowdock atmosphere.

Blog Archives

Flowdock API Changes

May 7th, 2013

Mikael Roos

At Flowdock, we are changing the way we handle flow IDs in our API. If you are a Flowdock API user, this may affect your integration, and if you are using Hubot with Flowdock, you’ll have to upgrade before the change comes into effect.
The changes will take effect on Monday, May 27th, 2013.

For more information, see our new API Changes page.

Keeping Track Of API Changes

To stay up-to-date with up-and-coming changes and additions to the Flowdock API, frequent the API Changes page or follow the API Changes Atom feed.

Contributing & Discussions

In case you bump into any bugs, problems or inconveniences with the API, feel free to create an issue in our open Flowdock API documentation GitHub repository. If you find anything remiss in the documentation, correcting pull requests will be received with open arms.

Leave a comment

Flowdock API And Files

March 19th, 2012

Antti Pitkänen

We are excited to present you yet another extension to our Flowdock APIs: uploading, listing and downloading files through the Flowdock REST API.

Uploading a file

The REST API supports two ways of attaching files: encoding them with Base64 in a JSON request or sending them as form data. The details of both approaches are described in the new Files page of the API documentation.

Here’s a quick curl example of using multipart/form-data to upload a file:

curl -v -X POST -F "event=file" -F "content=@path/to/file.png" https://BASIC-AUTH@api.flowdock.com/flows/ORG/FLOW/messages

Finding files

Messages containing files can be fetched by filtering messages by the file event or the :file tag. The difference is that filtering by the :file tag will match any type of message that contains files, eg. team inbox messages with attachments.

For example, here’s how you would fetch the 10 latest files uploaded to your flow:

GET https://BASIC-AUTH@api.flowdock.com/flows/ORG/FLOW/messages?event=file&limit=10

Downloading a file

Once you’ve got some messages with files attached to them, you will probably want to download them for viewing as well. The REST API path of a file is stored in the path field of each attachment. For reference, see the file message section of Message Types documentation.

The path can be used to download the file by appending it to the API URL https://api.flowdock.com/:

GET https://BASIC-AUTH@api.flowdock.com/flows/ORG/FLOW/files/deadbeefdeadbeef/screenshot.png

That’s all for now, stay tuned for more API updates!

Leave a comment

GET The Message! (via API)

February 29th, 2012

Mikael Roos

That’s right, you can now GET messages. It is an obvious extension to the Flowdock API, the ability to fetch messages of a flow given certain filters. You can fetch up to or starting from a specific ID, filter by event or tags and so on.

Read the docs ➝

A basic example of filter use:

GET /messages?until_id=3456&limit=20&event=message

This request will get you 20 plain chat messages leading up to the message with ID 3456 (which will not be included).

Searching With Tags

The new API lets you also search messages by tags. Getting all the messages tagged with the tags #feedback and #todo is as simple as

GET /messages?&limit=20&tags=feedback,todo

Tags are used to a lot of things internally in Flowdock. Filtering by tags gives you access to several features, such as fetching all the comments of a team inbox item with ID 12345

GET /messages?&limit=20&tags=:influx:12345

or listing messages that contain links or files:

GET /messages?&limit=20&tags=:url
GET /messages?&limit=20&tags=:file

Check out the tags documentation for specifics.

Message Types

We started documenting the different Message Types. There’s still a lot to be done on that front. We haven’t covered much of the team inbox events in the docs and we are going to be changing some of the events’ structure.

Leave a comment

Introduction to Push API

February 22nd, 2012

Antti Pitkänen

Push API button

The Flowdock Push API is for posting chat or team inbox messages into a specific flow without user authentication. It uses the flow’s API token for authentication, making it a quick and easy way to get started using our APIs. If you need more than just anonymous posting capabilities, use the REST API.

Flowdock API Gem

The Flowdock API gem now supports posting chat messages and handles JSON responses from the API. The major update in the APIs required us to do some refactoring for the gem. However, it still works the same way as before and deprecated features are documented in the README.

Here’s an example of posting a chat message with the gem:

# use the flow's API token and set your nick for Chat posting
flow = Flowdock::Flow.new(:api_token => "deadbeefdeadbeef", :external_user_name => "Accounting")

# send message to Chat
flow.push_to_chat(:content => "@everyone This is an automatic reminder to fill in your hours for this month!", :tags => ["hours", "accounting"])

API Responses

Besides adding Chat posting to the Push API, we also decided to unify the responses of our APIs. Now the responses are always in JSON format and follow a simple pattern so that you know what to expect as a response in error situations. See General Information for details about the format.

What’s next?

Releasing the new API was just a start. In addition to improving our skills in nano-brewing, we are planning and implementing new features to the APIs. In the Push API you can expect to see support for message attachments very soon.

Leave a comment

API Documentation & Indian Pale Ale

February 17th, 2012

Mikael Roos

Commemorative beer for the launch: Flowdock API IPA

We launched the new Flowdock API a couple of days ago. Now, we have released the API documentation source on GitHub. The source consists of Markdown files which are used to render the official docs at www.flowdock.com/api. If you notice any errors in the docs or wish to improve them in any way feel free to issue a pull request.

Yesterday we posted an intro to the streaming API and we’ll continue the write-ups next week, but this Friday we are reserving for celebrations.

Any self-respecting software team needs some side-projects, things to do in times of frustration or while just waiting for tests or deployments to finish. Well, we’ve recently got going a budding hobby in nano-brewing. And today, we get to taste the second result of our brewing: The Flowdock API IPA.

This unfiltered Indian-style pale ale is rich and strong in color, fruity and seducing in odor and has a brisk, tangy taste with a modern aftertaste.

Only a dozen bottles were produced, so a selected few get to enjoy a tasting.

Thanks to everyone who have already started hacking and mashing up things with the API. We love to hear about all the projects.

Leave a comment

Introduction to the New Streaming API

February 16th, 2012

Ville Lautanala

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.

Leave a comment

New API: Push + REST + Streaming

February 15th, 2012

Mikael Roos

It’s hacking time! The new Flowdock API is out now. We are currently in the process of polishing up the documentation, which will be put onto a public repo on Github a little later for everyone to fine-tune. At this point we are still actively editing and expanding the docs.

Here are the new APIs as of now:

REST API — Read the docs

  • Authenticate as a Flowdock user
  • Get flow data
  • Post to chat or update status
  • Great for Flowdock clients, user-based integrations or two-way bots.

Streaming API — Read the docs

  • Listen to messages
  • Great whenever you want to render the conversation or parse things from what people say.

Push API — Read the docs

  • Post to Team Inbox or Chat without identifying as a user
  • Great for notifications or simple bots which do not need to listen to messages.

Things to come

In the Following days, we will write up the different parts of the API in greater detail. We will also post about these awesome things:

Stay tuned! And tell us what you would like to see next via team@flowdock.com.

Leave a comment

Flowdock API Out Now!

August 11th, 2011

Mikael Roos

Two awesome things are going on at Flowdock today. Number one, we are about to launch a new front page with a new no-BS message: Flowdock – Team Inbox With Chat. The other thing is the Flowdock API. Flowdock thrives on integrations to other tools that the team is using. That’s why we are now launching the Flowdock API.

Version 1!

In the first version we start with a simple API enabling posting new items to Flowdock’s Team Inbox (previously called Influx). » See the API Docs

We’ve also wrapped up a Ruby Gem to get you going in just seconds if Ruby is your choice of language. » Check out the Ruby Gem and install it

Example 1: Custom Feedback Form

Here’s a quick example to get you going. Getting user feedback directly to Flowdock is great. You can talk it over quickly with your team and decide what to do.

This Sinatra app shows a feedback form and sends the feedback to your Flowdock flow using the Flowdock API Ruby Gem.

The view:

The Sinatra controller:

Example 2: FogBugz integration (no coding required!)

The Flowdock Influx API is perfect for use with any service which has web hook / url trigger functionality, such as FogBugz.

Simply by configuring the URL Triggers plugin in Fogbugz (means filling out one form), you can get nicely formatted notifications to Flowdock. We’ve created example instructions for FogBugz Cases, but you can get notifications from wiki changes etc by adding small modifications and creating new triggers.

» Check out the instructions

Example 3: Deployment notifications

Check out our new awesome deployment notification scripts using the Flowdock API.

If you implement an integration using the Flowdock API, let us know, and we’ll spread the good word!

Version 2?

What would you like to see in the Flowdock API? Here’s a few initial ideas:

  • bots! (Check out the awesome Flowdock bot implementation by the guys at MyNewsDesk).
  • fetching messages by tag – slideshow of latest #sketches ?
  • Fetching influx messages
  • Jabber integration to use Flowdock with other chat clients (See this idea/discussion in our UserVoice)

Let us know what you think via UserVoice or in the comments.

Leave a comment

Rails-doc 2.0 is live!

July 18th, 2008

Mikael Roos

Rails-doc 2.0

Our planned schedule and features held! Rails API documentation with versions support! Full search! OpenId support! Gravatarrrrs! Check it out!

Seriously though, the deployment was delayed by a small surge of bugs found right before the intended deployment window, so we are about 20 hours late. It took about four hours because of all the version-specific documentation generation. We are sorry for any inconveniences you may have experienced and we hope you’ll enjoy this installment of Rails-doc.

11 Comments

Rails-doc.org website opens

June 13th, 2008

Mikael Roos

As of right now Rails-doc.org website is opened. There isn’t much content yet, but a lot of promises, including the first release which is scheduled for next week, current target being Thursday, June 19th. Rails-doc is a community powered Ruby on Rails documentation app. It is open and social. It features an intelligent keyword search that is almost as fast as the native search in your browser. We have two clear goals, the second depending on the first:

  1. To provide a highly usable interface for perusing Rails documentation and for contributing with notes and examples and to thus collect a good amount of additional Rails documentation.
  2. To expand the actual documentation of Rails by providing tools to active members of the Rails-doc community for incorporating the notes into creating an extended unified improved documentation.
The first release will be the fruit of three sprints’ work from our core Rails-doc development team consisting of three active members and a few of much less active ones. Rails-doc.org is also the pilot project for APIdock, Nodeta’s new social software documentation app.

Many others have tried to develop a Rails documentation app, but none have succeeded. Regardless of that, I know that…

We can do it!
…we indeed can do it!

Check it out!

Leave a comment