Flowdock
¶ ↑
Ruby gem for using the Flowdock
Push API. See the Push API documentation for details.
Build Status¶ ↑
The Flowdock
gem is tested on Ruby 2.1 and JRuby.
Dependencies¶ ↑
-
HTTParty
-
MultiJson
Installing¶ ↑
gem install flowdock
If you’re using JRuby, you’ll also need to install the jruby-openssl
gem.
Usage¶ ↑
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.
REST API¶ ↑
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 = Flowdock::Client.new(api_token: '__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 = Flowdock::Client.new(flow_token: '__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
.
flow_token_client.post_to_thread( event: "activity", author: { name: "anttipitkanen", avatar: "https://avatars.githubusercontent.com/u/946511?v=2", }, 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: "https://example.com/issue/123", 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 client.delete('/flows/acme/my_flow/messages/12345') # Create an invitation client.post('/flows/acme/my_flow/invitations', email: 'user@example.com', 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 = Flowdock::Flow.new(:api_token => "__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 = Flowdock::Flow.new(:api_token => "__FLOW_API_TOKEN__", :source => "myapp", :from => {:name => "John Doe", :address => "john.doe@example.com"}) # 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 => "http://www.flowdock.com/")
Posting to multiple flows¶ ↑
require 'rubygems' require 'flowdock' # create a new Flow object with the API tokens of the target flows flow = Flowdock::Flow.new(:api_token => ["__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:
Changelog¶ ↑
-
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 bothFlow
andClient
so that comments can be made.
Copyright¶ ↑
Copyright © 2012 Flowdock
Ltd. See LICENSE for further details.