The latest version of the Ruby API library is available on github.com.
To use Kayako REST API, first you need to enable it in your Kayako installation. To enable the API, login to Admin Control Panel and in Options panel on the right choose REST API, and then Settings. Next, set Enable API Interface to Yes and confirm the change by clicking Update button.
The Ruby API client requires version 1.8 or later of Ruby. For better performance it is recommended to install HTTPClient and LibXML libraries. The Ruby API client tries to load these libraries and falls back to Ruby's core Net::HTTP and REXML in case of failure.
Before you can start using the Ruby Kayako REST API client you need to load kayako_client by adding the following line to your Ruby code:
Configuring the client
To perform network operations the Ruby REST API client requires API URL, API Key and Secret Key. You can obtain their values in Admin Control Panel - in Options panel on the right choose REST API and then API Information. Specify obtained values in the global configuration of the library:
The Ruby REST API client was designed to be as close to the Kayako REST API specification as possible making its usage very intuitive. Thus the library's classes were named after the REST API objects:
Except TicketSearch which is available as :search method of the KayakoClient::Ticket class.
The main class and instance methods are also named after the REST API methods:
- :get for GET method
- :put for PUT method
- :post for POST method
- :delete for DELETE method
Special method :all is used to retrieve all objects (a.k.a. ListAll).
For user convenience special Rails-style aliases were added:
- :find for :get
- :update for :put
- :save for :post
- :destroy for :delete
Ruby method aliases are widely used by the library to improve comprehension and preserve similarity with the REST API. For example, REST object properties setter and getter methods in the library have underscores (e.g. :creator_staff_name) while REST XML properties do not contain ones. The library provides setter and getter method aliases identical to the names used in REST XML (e.g. :creatorstaffname).
All classes are used in very much the same way.
Getting all objects
The Class#all method always returns array of class instances:
Getting an object
The Class#get method returns a class intance or nil:
Creating an object
An instance of a class is created as usual:
Object properies can be changed using setter methods:
Upload is done using Object#post method which returns true on success and false on failure:
As an alternative you can use Class#post which returns either a class instance or nil:
Modifying an object
To change object properties use setter methods:
Then use Object#put to update. The Object#put method returns either true (on success) or false:
Deleting an object
To delete an object use Object#delete method:
As an alternative you can use Class#delete method which requires object ID:
In addition to setter and getter methods described above the library also support Hash-like accessors:
Similar accessor is also available for KayakoClient::TicketCustomField instances:
Setting custom fields
At the moment the only way to set custom fields is to use POST. In the POST request you need to specify all values for all custom fields.
Check the sample code:
You can also set values without fetching current ones:
The full list of available custom fields can be fetched this way:
The Ruby REST API library supports file uploads/downloads for KayakoClient::TicketAttachment and KayakoClient::TicketCustomFieldValue (only download) objects.
To upload a file as an attachment you can do:
The :file accessor accepts a path to file (String) or a File/Tempfile instance:
The :file accessor can also be used to access a downloaded file:
The Tempfile instance is created on first call to the :file accessor.
For user convenience the Ruby REST API library also provides instance methods for getting associated object. Thus most of objects having a property :<something>_id also have a method :<something>. When such method is called the library transparently fetches and returns the corresponding object.
The associated object is received only once and gets cached.
Specifying HTTP backend
Currently the Ruby REST API library supports HTTPClient and Net::HTTP. By default it tries to load HTTPClient and switches to Net::HTTP if failed. But it's possible to specify HTTP backend explicitly:
You can also pass the instance of KayakoClient::NetHTTP class as a HTTP backend:
Specifying XML backend
Currently the Ruby REST API library supports LibXML and REXML::Document. By default it tries to load LibXML and switches to REXML::Document if failed. But it's possible to specify XML backend explicitly:
Instead of specifying global configuration you can configure a client instance and then use it to access Kayako, e.g.:
The full list of client instance methods can be found below.
To enable logging you need to pass a Logger object as follows:
Under Rails you can use Rails.logger:
The following exceptions can be raised when an error occurs:
XML parsing error
Wrong environment, configuration or corruption
Network or server error
An argument passed to a method is invalid
A method cannot be called for this object
The ArgumentError is raised when e.g. required properties where not supplied. In cases when a value is invalid (not an allowed value etc) nothing is raised. Instead the corresponding method (:put or :post) returns false. In this case the errors can be fetched by calling to :errors method:
For this reason it is recommended to always use Object#post instead of Class#post.
It is assumed that the REST API client has been configured properly as described above.
Creating a department
Creating a staff user
Creating a user
Creating a ticket and adding a ticket note
Performing a ticket search
Ticket#all(departmentid, ticketstatusid=-1, ownerstaffid=-1, userid=-1)