README.textile
!https://avatars1.githubusercontent.com/u/9012750?v=3&s=200!
h1. ChattyCrow - Ruby library
!https://travis-ci.org/ChattyCrow/chattycrow_ruby.svg!:https://travis-ci.org/ChattyCrow/chattycrow_ruby !https://coveralls.io/repos/netbrick/chattycrow_ruby/badge.png(Coverage Status)!:https://coveralls.io/r/netbrick/chattycrow_ruby !http://inch-ci.org/github/ChattyCrow/chattycrow_ruby.png?branch=master!:http://inch-ci.org/github/ChattyCrow/chattycrow_ruby !https://codeclimate.com/github/netbrick/chattycrow_ruby/badges/gpa.svg!:https://codeclimate.com/github/ChattyCrow/chattycrow_ruby !https://gemnasium.com/ChattyCrow/chattycrow_ruby.svg(Dependency Status)!:https://gemnasium.com/ChattyCrow/chattycrow_ruby !https://hakiri.io/github/ChattyCrow/chattycrow_ruby/master.svg!:https://hakiri.io/github/ChattyCrow/chattycrow_ruby/master
This library makes easier call ChattyCrow API (http://chattycrow.com/).
h2. Installation
<pre>
# Gemfile
gem 'chatty_crow'
bundle install
# Manually
gem install chatty_crow
</pre>
h2. Configuration
h3. Yaml configuration (automatically loaded in Rails)
<pre>
# config/chatty_crow.yml
global: &global_settings
host: 'https://chattycrow.com/api/v1/'
token: 'asdfg12345'
default_channel: 'asdfg12345'
development:
<<: *global_settings
test:
<<: *global_settings
production:
<<: *global_settings
</pre>
h3. Pass block with settings (initializer in Rails?)
<pre>
# "config/initializers/chatty_crow.rb"
ChattyCrow.configure do |config|
config.host = 'https://chattycrow.com/api/v1/'
config.token = 'asdfg12345'
config.default_channel = 'asdfg12345'
end
</pre>
h2. Usage
h3. Email notification
h4. Rails
Integration with ActionMailer is simple, you don't have to change your codes anymore.
<pre>
class UserMailer < ActionMailer::Base
# Include extension
include ChattyCrow::ActionMailerExtension
# Different channel
chatty_crow_channel 'other_channel'
# Send welcome mail to user
def welcome_mail
mail to: "jan.strnadek@chattycrow.com"
end
end
</pre>
h4. General
<pre>
# Create mail instance
mail = ChattyCrow.create_mail channel: 'other_than_default', subject: 'Test'
mail.text_body = 'Text part of body'
mail.html_body = 'Html body <strong>strong part</strong>'
# Add attachments (File / Tempfile / ActionDispatch::Http:UploadedFile / Base64string)
# Argument :file is required!
mail.add_file file: params[:uploaded_file], filename: 'test2.jpeg'
mail.add_file filename: 'test.jpeg', mime_type: 'image/jpeg', file: 'base64data'
# ...
# Can change contacts!
mail.contacts = %w(test@netbrick.eu test1@netbrick.eu)
# Send mail
mail.deliver!
</pre>
h3. IOS Push notification
<pre>
# Send request
response = ChattyCrow.send_ios(payload: { 'hello' }, channel: 'other_than_default', token: 'other', contacts: [ 'new_ios_id1', 'new_ios_id2' ], time: { start: DateTime.now.to_i, end: DateTime.now.advance(days: 7) }, location: { latitude: 14.302022, longitude: 43.20923, range: 1000 })
# Or simple message
response = ChattyCrow.send_ios('Dear users')
# Response
response
</pre>
h3. Android Push notification
<pre>
# Send request
response = ChattyCrow.send_android(payload: { data: { key: 'key1', key2: 'key2'}, time_to_live: 5 }, channel: 'other_than_default', contacts: [ 'new_ios_id1', 'new_ios_id2' ])
# Response
# response # ChattyCrow::Response::Notification
# response.status = "PERROR"
# response.msg = "Message"
# response.success = 5
# response.failed = 1
# response.failed_contacts = [ 'new_ios_id1' ]
# response.message_id = your created message ID
# response.message = Response::Message instance
</pre>
h3. Skype notification
<pre>
# Send request
response = ChattyCrow.send_skype('Dear users', channel: 'other_than_default', contacts: [ 'new_ios_id1', 'new_ios_id2' ])
# Response
# response # ChattyCrow::Response::Notification
</pre>
h3. Jabber notification
<pre>
# Send request
response = ChattyCrow.send_jabber('Dear users', channel: 'other_than_default', contacts: [ 'new_ios_id1', 'new_ios_id2' ])
# Response
# response # ChattyCrow::Response::Notification
</pre>
h3. HipChat notifications
<pre>
# Send request
# Color (red, yellow, purple, random - yellow is default)
response = ChattyCrow.send_hipchat('Dear users', color: 'red', channel: 'other_than_default', contacts: [ 'new_ios_id1', 'new_ios_id2' ])
# Response
# response # ChattyCrow::Response::Notification
</pre>
h3. Slack notifications
<pre>
# Send request
response = ChattyCrow.send_hipchat('Dear users', channel: 'other_than_default', contacts: [ 'new_ios_id1', 'new_ios_id2' ])
# Response
# response # ChattyCrow::Response::Notification
</pre>
h3. SMS notification (only Czech Republic yet)
<pre>
# Send request
response = ChattyCrow.send_sms 'Dear Users', contacts: [ '+420111222333', '+420222111333']
# Response
# response # ChattyCrow::Response::Notification
</pre>
h2. Message detail and state
We're providing uniq message id to check what's going on with your message. You obtain message instance from successfull response.
<pre>
message = response.message
message.refresh_data!
message.status # OK etc..
</pre>
h2. Working with contacts via API
It's actually very usable, you can automatically add or remove contacts in your application after user was registered.
h3. Add contact
<pre>
response = ChattyCrow.add_contacts('new1', 'new2exists', 'new3failed', channel: 'other_than_default')
# Response
# response.success_count = 1
# response.exists_count = 1
# response.failed_count = 1
# response.exists = [ 'new2exists' ]
# response.failed = [ 'new3failed' ]
</pre>
h3. Remove contact
<pre>
response = ChattyCrow.remove_contacts('new1', 'new2exists', 'new3failed', channel: 'other_than_default')
# Response
# response.success_count = 1
# response.failed_count = 1
# response.failed = [ 'new2failed' ]
</pre>
h2. Batch notifications
Allows sends multiple notifications with serveral restrictions, notifications are immediatelly aborted when:
* Token and channels not matched
* One of channel is suspended
* Times or locations are invalid in any case
<pre>
batch = ChattyCrow.create_batch("different token then default")
# Its almost the same as send_android, but channel is required!
batch.add_jabber 'Dear users', channel: 'channel', contacts: [ 'aa' ]
batch.execute # add '!' to raise error, when something is wrong
</pre>
h2. Changelog
h3. 1.3.0
* Add batch notifications (this is required for Redmine Plugin or Capistrano Plugin)
h3. 1.2.2
* Add messages state API
* Remove GET contact list methods
* Add support of change location API
* Add HipChat, Slack and Telegram