The Desk Ruby Gem ==================== A Ruby wrapper for the [Desk.com API](http://dev.desk.com/) Installation ------------ gem install desk What's new in 0.3.3? ------------------ @mtchavez bumped faraday_middleware to 0.9.0 What's new in 0.3.2? ------------------ @tstachl added support for groups and max requests What's new in 0.3.0? ------------------ Renamed to Desk Newer faraday, faraday_middleware and hashie 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 "desk" # All methods require authentication. To get your Desk OAuth credentials, # register an app in the Desk.com admin for your account at http://your-domain.desk.com/admin Desk.configure do |config| config.support_email = "help@example.com" config.subdomain = YOUR_DESK_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 ###### # Cases ###### # List cases Desk.cases Desk.cases(:since_id => 12345) # Get a specific case Desk.case(12345) # Update a specific case Desk.update_case(12345, :subject => "Something Else") # Get a case url Desk.case_url(12345) ###### # Customers ###### # List customers Desk.customers Desk.customers(:since_id => 12345, :count => 5) # Get a specific customer Desk.customer(12345) # Create a customer Desk.create_customer(:name => "Chris Warren", :twitter => "cdwarren") # Update a customer Desk.update_customer(12345, :name => "Christopher Warren") # Add a customer email Desk.create_customer_email(12345, "foo@example.com") Desk.create_customer_email(12345, "foo@example.com", :customer_contact_type => "work") # Update a customer email Desk.update_customer_email(12345, 54321, :email => "foo@example.com") Desk.update_customer_email(12345, 54321, :customer_contact_type => "work") # Add a customer phone number Desk.create_customer_phone(12345, "555-368-7147") Desk.create_customer_phone(12345, "555-368-7147", :customer_contact_type => "work") # Update a customer phone number Desk.update_customer_phone(12345, 54321, :phone => "555-368-7147") Desk.update_customer_phone(12345, 54321, :customer_contact_type => "work") ###### # Interactions ###### # List interactions Desk.interactions Desk.interactions(:since_id => 12345) Desk.interactions(:since_id => 12345, :count => 5) # Create an inbound interaction Desk.create_interaction(:interaction_subject => "help me", :customer_email => "foo@example.com", :interaction_body => "You're my only hope.") Desk.create_inbound_interaction(:interaction_subject => "help me", :customer_email => "foo@example.com", :interaction_body => "You're my only hope.") # Create an outbound interaction # Desk.com's API doesn't support creating outbound communications, so we do this over email with a BCC back to Desk and customer headers. # Desk.support_email must be set to your Desk.com 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.desk.com/customer/portal/articles/4180 # Additional headers can be passed as well http://support.desk.com/customer/portal/articles/6728 # # Email is sent using Pony https://github.com/benprew/pony Desk.create_interaction(:interaction_subject => "Missed Your Call", :customer_email => "foo@example.com", :interaction_body => "Sorry we missed yoru call. What's up?", :direction => "outbound") Desk.create_outbound_interaction("foo@example.com", "Missed Your Call", "Sorry we missed yoru call. What's up?") ###### # Users ###### # List users Desk.users # Get a specific user Desk.user(12345) ###### # Topics ###### # List Topics Desk.topics # Get a specific topic Desk.topic(12345) # Create a new topic Desk.create_topic("name", :description => "description") # Update a topic Desk.update_topic(12345, :subject => "Updated") # Delete a topic Desk.delete_topic(12345) ###### # Articles ###### # List articles for a topic Desk.articles(1) # Get a specific article Desk.article(12345) # Create a new article within a topic Desk.create_article(1, :subject => "API Tips", :main_content => "Tips on using our API") # Update an article Desk.update_article(12345, :subject => "Updated API Tips") # Delete an article Desk.delete_article(12345) ###### # Macros ###### # List Macros Desk.macros # Get a specific macro Desk.macro(12345) # Create a new macro Desk.create_macro("name", :labels => "escalated") # Update a macro Desk.update_macro(12345, :name => "Updated Name") # Delete a macro Desk.delete_macro(12345) # Macro Actions Desk.macro_actions(12345) # Macro Action Desk.macro_action(12345, "set-case-description") # Update Macro Action Desk.update_macro_action(12345, "set-case-description", :value => "New Subject") 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/desk/issues) * by reviewing patches All contributors will be added to the [HISTORY](https://github.com/zencoder/desk/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/desk/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 bundle exec rake doc:yard. If your changes are not 100% documented, go back to step 4. 6. Add specs for your feature or bug fix. 7. Run bundle exec rake spec. 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) 2012 Chris Warren/[Zencoder](http://zencoder.com) See [LICENSE](https://github.com/zencoder/desk/blob/master/LICENSE.mkd) for details.