ChattyCrow – Ruby library

This library makes easier call ChattyCrow API (http://chattycrow.com/).

Installation

# Gemfile
gem 'chatty_crow'
bundle install

# Manually
gem install chatty_crow

Configuration

Yaml configuration (automatically loaded in Rails)

# 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

Pass block with settings (initializer in Rails?)

# "config/initializers/chatty_crow.rb"

ChattyCrow.configure do |config|
  config.host            = 'https://chattycrow.com/api/v1/'
  config.token           = 'asdfg12345'
  config.default_channel = 'asdfg12345'
end

Usage

Email notification

Rails

Integration with ActionMailer is simple, you don’t have to change your codes anymore.

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

General

# 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!

IOS Push notification

# 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

Android Push notification

# 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

Skype notification

# Send request
response = ChattyCrow.send_skype('Dear users', channel: 'other_than_default', contacts: [ 'new_ios_id1', 'new_ios_id2' ])

# Response
# response  # ChattyCrow::Response::Notification

Jabber notification

# Send request
response = ChattyCrow.send_jabber('Dear users', channel: 'other_than_default', contacts: [ 'new_ios_id1', 'new_ios_id2' ])

# Response
# response  # ChattyCrow::Response::Notification

HipChat notifications

# 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

Slack notifications

# Send request
response = ChattyCrow.send_hipchat('Dear users', channel: 'other_than_default', contacts: [ 'new_ios_id1', 'new_ios_id2' ])

# Response
# response  # ChattyCrow::Response::Notification

SMS notification (only Czech Republic yet)

# Send request
response = ChattyCrow.send_sms 'Dear Users', contacts: [ '+420111222333', '+420222111333']

# Response
# response  # ChattyCrow::Response::Notification

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.

message = response.message
message.refresh_data!
message.status # OK etc..

Working with contacts via API

It’s actually very usable, you can automatically add or remove contacts in your application after user was registered.

Add contact

  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' ]

Remove contact

  response = ChattyCrow.remove_contacts('new1', 'new2exists', 'new3failed', channel: 'other_than_default')
  # Response
  # response.success_count = 1
  # response.failed_count  = 1
  # response.failed = [ 'new2failed' ]

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

  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

Changelog

1.3.0

• Add batch notifications (this is required for Redmine Plugin or Capistrano Plugin)

1.2.2

• Add messages state API
• Remove GET contact list methods
• Add support of change location API
• Add HipChat, Slack and Telegram