Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation


Ruby gem for using the Flowdock Push API. See the Push API documentation for details.

Build Status

Build Status

The Flowdock gem is tested on Ruby 2.1 and JRuby.


  • HTTParty
  • MultiJson


gem install flowdock

If you're using JRuby, you'll also need to install the jruby-openssl gem.


To post content to a flow's chat or team inbox using Flowdock::Flow, you need to use the target flow's API token or a source's flow_token.

Alternatively, you can use your personal API token and the Flowdock::Client.

Personal and flow's tokens can be found on the tokens page.


To create an API client, you need your personal API token, an OAuth token or a source's flow_token.

Note that a flow_token will only allow you to post thread messages to the flow that the source belongs to.

require 'rubygems'
require 'flowdock'

# Create a client that uses your personal API token to authenticate
api_token_client = '__MY_PERSONAL_API_TOKEN__')

# Create a client that uses a source's flow_token to authenticate. Can only use post_to_thread
flow_token_client = '__FLOW_TOKEN__')

Posting to Chat

To send a chat message or comment, you can use client.chat_message:

flow_id = 'acdcabbacd0123456789'

# Send a simple chat message
api_token_client.chat_message(flow: flow_id, content: "I'm sending a message!", tags: ['foo', 'bar'])

# Send a comment to message 1234
api_token_client.chat_message(flow: flow_id, content: "Now I'm commenting!", message: 1234)

Both methods return the created message as a hash.

Post a threaded messages

You can post activity and discussion events to a threaded conversation in Flowdock.

    event: "activity",
    author: {
        name: "anttipitkanen",
        avatar: "",
    title: "activity title",
    external_thread_id: "your-id-here",
    thread: {
        title: "this is required if you provide a thread field at all",
        body: "<p>some html content</p>",
        external_url: "",
        status: {
            color: "green",
            value: "open"

Arbitary API access

You can use the client to access the Flowdock API in other ways, too. See the REST API documentation for all the resources.

# Fetch all my flows
flows = client.get('/flows')

# Update a flow's name
client.put('/flows/acme/my_flow', name: 'Your flow')

# Delete a message

# Create an invitation'/flows/acme/my_flow/invitations', email: '', message: "I'm inviting you to our flow using api.")

Push API

Note: the Push API is in the process of being deprecated. Creating a source along with a flow_token is recommended instead.

To use the Push API, you need the flow's API token:

Posting to the chat

require 'rubygems'
require 'flowdock'

# create a new Flow object with target flow's API token and external user name (enough for posting to the chat)
flow = => "__FLOW_API_TOKEN__", :external_user_name => "John")

# send message to Chat
flow.push_to_chat(:content => "Hello!", :tags => ["cool", "stuff"])

Posting to the team inbox

# create a new Flow object with the target flow's API token and sender information
flow = => "__FLOW_API_TOKEN__",
  :source => "myapp", :from => {:name => "John Doe", :address => ""})

# send message to Team Inbox
flow.push_to_team_inbox(:subject => "Greetings from the Flowdock API gem!",
  :content => "<h2>It works!</h2><p>Now you can start developing your awesome application for Flowdock.</p>",
  :tags => ["cool", "stuff"], :link => "")

Posting to multiple flows

require 'rubygems'
require 'flowdock'

# create a new Flow object with the API tokens of the target flows
flow = => ["__FLOW_API_TOKEN__", "__ANOTHER_FLOW_API_TOKEN__"], ... )

# see the above examples of posting to the chat or team inbox

API methods

  • Flowdock::Flow methods

    push_to_team_inbox - Send message to the team inbox. See API documentation for details.

    push_to_chat - Send message to the chat. See API documentation for details.

    send_message(params) - Deprecated. Please use push_to_team_inbox instead.

  • Flowdock::Client methods

    chat_message - Send message to chat.

    post_to_thread - Post messages to a team inbox thread.

    post, get, put, delete - Send arbitary api calls. First parameter is the path, second is data. See REST API documentation.

Deployment notifications

There are separate gems for deployment notifications:


  • 0.7.0 - Added post_to_thread
  • 0.5.0 - Added Flowdock::Client that authenticates using user credentials and can be used to interact with the API. Better threads support for both Flow and Client so that comments can be made.


Copyright (c) 2012 Flowdock Ltd. See LICENSE for further details.