ChatWork

Ruby bindings of ChatWork API

Installation

Add this line to your application's Gemfile:

gem 'chatwork'

And then execute:

$ bundle

Or install it yourself as:

$ gem install chatwork

Usage

chatwork gem provides class method APIs and instance method APIs

Class method APIs

At first, set ChatWork.api_key or ChatWork.access_token.

ChatWork.api_key = "XXX"
# or
ChatWork.access_token = "XXX"

Another way, you can use ENV["CHATWORK_API_TOKEN"] or ENV["CHATWORK_ACCESS_TOKEN"] instead of ChatWork.api_key or ChatWork.access_token.

Then call class methods.

e.g. post message.

ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
#=> #<Hashie::Mash message_id="1234567890">

All available APIs are followings.

• ChatWork::Contacts
• ChatWork::File
• ChatWork::IncomingRequest
• ChatWork::InvitationLink
• ChatWork::Me
• ChatWork::Member
• ChatWork::Message
• ChatWork::MyStatus
• ChatWork::MyTask
• ChatWork::Room
• ChatWork::Task

When you want to refresh access token, call ChatWork::Token.refresh_access_token.

ChatWork.client_id = "XXX"
ChatWork.client_secret = "XXX"
refresh_token = "XXX"
token = ChatWork::Token.refresh_access_token(refresh_token)
new_access_token = token["access_token"]

# Create message
ChatWork.access_token = new_access_token
ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")

Another way, you can use ENV["CHATWORK_CLIENT_ID"] or ENV["CHATWORK_CLIENT_SECRET"] instead of ChatWork.api_key or ChatWork.access_token.

Instance method APIs

client = ChatWork::Client.new(api_key: "XXX")
#or
client = ChatWork::Client.new(access_token: "XXX")

Then call instance methods.

e.g. post message.

client.create_message(room_id: 1234, body: "Hello, ChatWork!")
#=> #<Hashie::Mash message_id="1234567890">

All available APIs are followings.

http://www.rubydoc.info/gems/chatwork/ChatWork/Client

When you want to refresh access token, call ChatWork::OAuthClient#refresh_access_token.

refresh_token = "XXX"
oauth_client = ChatWork::OAuthClient.new(client_id: "xxx", client_secret: "xxx")
token = oauth_client.refresh_access_token(refresh_token)
new_access_token = token["access_token"]

# Create message
client = ChatWork::Client.new(access_token: new_access_token)
client.create_message(room_id: 1234, body: "Hello, ChatWork!")

Pros/Cons

Class method APIs are simple, but not threadsafe. Instance method APIs are threadsafe.

If you are using multiple api_key or access_token in an app and using multithreaded server (e.g. puma), we recommend instance method APIs.

Tips

Hashie::Mash

All API methods returns Hashie::Mash instance.

https://github.com/intridea/hashie#mash

Hashie::Mash is very useful!

body = ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!")
#=> #<Hashie::Mash message_id="1234567890">

body["message_id"]
#=> "1234567890"

body[:message_id]
#=> "1234567890"

body.message_id
#=> "1234567890"

Block arguments

All API methods supports block argument.

If block was given, return response body and response header through block arguments.

ChatWork::Message.create(room_id: 1234, body: "Hello, ChatWork!") do |body, header|
  body
  #=> #<Hashie::Mash message_id="1234567890">

  header["X-RateLimit-Limit"]
  #=> "100"
  header["X-RateLimit-Remaining"]
  #=> "0"
  header["X-RateLimit-Reset"]
  #=> "1390941626"
end

client.create_message(room_id: 1234, body: "Hello, ChatWork!") do |body, header|
  body
  #=> #<Hashie::Mash message_id="1234567890">

  header["X-RateLimit-Limit"]
  #=> "100"
  header["X-RateLimit-Remaining"]
  #=> "0"
  header["X-RateLimit-Reset"]
  #=> "1390941626"
end

Reference

http://www.rubydoc.info/gems/chatwork

Development

cp .env.example .env
vi .env

./bin/console

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request