The Assistly Ruby Gem
====================
A Ruby wrapper for the Assistly API

Installation
------------
    gem install assistly

What's new in 0.1?
------------------
This is the first release of the Assistly gem, based on the [Twitter gem](http://github.com/jnunemaker/twitter). Support for most of the [Assistly API](http://dev.assistly.com/docs/api) are handled.
There is not yet support for Content or Macros.

Help! I'm getting: "Did not recognize your engine specification. Please specify either a symbol or a class. (RuntimeError)"
---------------------------------------------------------------------------------------------------------------------------

You'll need to explicitly require a JSON library. We recommend [yajl-ruby](http://github.com/brianmario/yajl-ruby).

Usage Examples
--------------
    require "rubygems"
    require "assistly"

    # All methods require authentication. To get your Assistly OAuth credentials,
    # register an app in the Assistly admin for your account at http://your-domain.assistly.com/admin
    @assistly = Assistly.configure do |config|
      config.subdomain = YOUR_ASSISTLY_SUBDOMAIN
      config.consumer_key = YOUR_CONSUMER_KEY
      config.consumer_secret = YOUR_CONSUMER_SECRET
      config.oauth_token = YOUR_OAUTH_TOKEN
      config.oauth_token_secret = YOUR_OAUTH_TOKEN_SECRET
    end

    # List cases
    @assistly.cases
    @assistly.cases(:since_id => 12345)

    # Get a specific case
    @assistly.case(12345)

    # Update a specific case
    @assistly.update_case(12345, :subject => "Something Else")

    # Get a case url
    @assistly.case_url(12345)

    # List customers
    @assistly.customers
    @assistly.customers(:since_id => 12345, :count => 5)

    # Get a specific customer
    @assistly.customer(12345)

    # Create a customer
    @assistly.create_customer(:name => "Chris Warren", :twitter => "cdwarren")

    # Update a customer
    @assistly.update_customer(12345, :name => "Christopher Warren")

    # Add a customer email
    @assistly.create_customer_email(12345, "foo@example.com")
    @assistly.create_customer_email(12345, "foo@example.com", :customer_contact_type => "work")

    # Update a customer email
    @assistly.update_customer_email(12345, 54321, :email => "foo@example.com")
    @assistly.update_customer_email(12345, 54321, :customer_contact_type => "work")

    # List interactions
    @assistly.interactions
    @assistly.interactions(:since_id => 12345)
    @assistly.interactions(:since_id => 12345, :count => 5)

    # Create an inbound interaction
    @assistly.create_interaction(:interaction_subject => "help me", :customer_email => "foo@example.com", :interaction_body => "You're my only hope.")
    @assistly.create_inbound_interaction(:interaction_subject => "help me", :customer_email => "foo@example.com", :interaction_body => "You're my only hope.")
    
    # Create an outbound interaction
    # Assistly's API doesn't support creating outbound communications, so we do this over email with a BCC back to Assistly and customer headers.
    # Assistly.support_email must be set to your Assistly email address so that the email can be sent to the account and give the customer someone to respond to.
    # 
    # Read more at http://support.assistly.com/customer/portal/articles/4180
    # Additional headers can be passed as well http://support.assistly.com/customer/portal/articles/6728
    #
    # Email is sent using Pony https://github.com/benprew/pony
    @assistly.create_interaction(:interaction_subject => "Missed Your Call", :customer_email => "foo@example.com", :interaction_body => "Sorry we missed yoru call. What's up?", :direction => "outbound")
    @assistly.create_outbound_interaction("foo@example.com", "Missed Your Call", "Sorry we missed yoru call. What's up?")

    # List users
    @assistly.users

    # Get a specific user
    @assistly.user(12345)

Contributing
------------
In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project.

Here are some ways *you* can contribute:

* by using alpha, beta, and prerelease versions
* by reporting bugs
* by suggesting new features
* by writing or editing documentation
* by writing specifications
* by writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace)
* by refactoring code
* by closing [issues](http://github.com/zencoder/assistly/issues)
* by reviewing patches

All contributors will be added to the [HISTORY](https://github.com/zencoder/assistly/blob/master/HISTORY.mkd)
file and will receive the respect and gratitude of the community.

Submitting an Issue
-------------------
We use the [GitHub issue tracker](http://github.com/zencoder/assistly/issues) to track bugs and
features. Before submitting a bug report or feature request, check to make sure it hasn't already
been submitted. You can indicate support for an existing issuse by voting it up. When submitting a
bug report, please include a [Gist](http://gist.github.com/) that includes a stack trace and any
details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
operating system. Ideally, a bug report should include a pull request with failing specs.

Submitting a Pull Request
-------------------------
1. Fork the project.
2. Create a topic branch.
3. Implement your feature or bug fix.
4. Add documentation for your feature or bug fix.
5. Run <tt>bundle exec rake doc:yard</tt>. If your changes are not 100% documented, go back to step 4.
6. Add specs for your feature or bug fix.
7. Run <tt>bundle exec rake spec</tt>. If your changes are not 100% covered, go back to step 6.
8. Commit and push your changes.
9. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)

Copyright
---------
Copyright (c) 2011 Chris Warren/Zencoder
See [LICENSE](https://github.com/zencoder/assistly/blob/master/LICENSE.mkd) for details.