Page tree
Skip to end of metadata
Go to start of metadata

Prerequisites

The latest version of the PHP API client is available on github.com.

Kayako

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.

PHP

The PHP API client requires version 5.3.0 or later of PHP environment with enabled support for: libXML, cURL, hash, fileinfo and date/time.

Getting Started

To use Kayako REST API you will need API URL, API key and Secret key. API URL and both keys can be obtained through Admin Control Panel - in Options panel on the right choose REST API and then API Information.

Initializing the client

To set up the PHP API client, first you need to load the kyIncludes.php file. Then, you must initialize the client with API URL, API Key and Secret Key. The following code presents these two steps.

Remember to change <API URL>, <API key> and <Secret key> to the values from your Kayako installation.

Default parameters for ticket creation

This step is optional. If the client will be used to create new tickets it’s recommended to set default status, priority and type of new tickets:

In order to discover proper identifiers for your installation you can get all objects and print them:

You can also use filtering to find status, priority and type by their title:

Advanced initialization settings

Date/time and date formatting

All date/time and date values returned by the client are formatted according to the specified format. Default format of date/time values is Y-m-d H:i:s (ex. 2011-06-19 17:16:00) and default format of date values is Y-m-d (ex. 2011-06-19). The date/time and date format can be changed in the configuration:

Refer to PHP manual for explanation of date/time formatting options.

Request URL type

The most important part of REST request URL is information about controller (and module as a part of it) to use (ex. /Base/User). There are two methods of providing controller name in request: standard and with an "e" parameter. The default is to use the standard way of constructing request URL. If you want to use an "e" parameter you can change this behaviour in the configuration:

At the time of writing this (2012-09-28) Kayako OnDemand environment requires the standard request URL type.

Debugging the client

Sometimes it's helpful to examine what requests are sent to Kayako server and what is the server's response. The client supports debug mode in which all requests (URL and body) and all responses (body) are logged using PHP logging mechanism (error_log). You can enable debug mode in configuration:

Basic Concepts

The key concept of the client is Object. Object can be one of the following types:

  • CustomFieldDefinition
  • Department
  • Staff
  • StaffGroup
  • Ticket
  • TicketAttachment
  • TicketCustomFieldGroup
  • TicketNote
  • TicketPost
  • TicketPriority
  • TicketStatus
  • TicketTimeTrack
  • TicketType
  • User
  • UserGroup
  • UserOrganization

In the following chapters ObjectType in kyObjectType means one of the above object types.

Objects can be loaded (HTTP GET) from server (one object, all objects of certain type or filtered list of objects). An object can be created (HTTP POST), updated (HTTP PUT) and deleted (HTTP DELETE). Not all object types support all these actions. Refer to supported methods table and REST API Reference for information on actions available for each object type.

All files and classes of the client are prefixed with "ky", ex. kyDepartment.

Getting objects

The most basic ways to load objects of certain type from server are getting them all or getting them one by one using their identifiers. Identifier may be a single value or may consist of multiple values (composite identifier). Sometimes you can pass additional parameters to methods getting all objects or use some special methods.

Getting an object using its identifier (where possible)

Getting an object using composite identifier (where needed)


Getting all objects of certain type (where possible)

Getting list of objects filtered by server (where possible)

Searching for objects (where possible)

Refer to supported methods table for information on load methods available for each object type.

Result sets

Result sets are lists of objects of certain type and are returned by client methods when more than one object can be returned, for example:

Result sets can be iterated, counted and accessed like ordinary PHP arrays:

Sometimes (usually when you're sure that result set will contain only one object) you'll want to get the first object from result set:

Accessing object API fields

Available API fields are defined for each object type by Kayako REST API.

There are two possible ways of accessing object API fields. Recommended one, is to use public setters and getters of objects. Another way, is to access API fields directly by their names as they were object properties. Both these ways are described in the following chapters.

Available API fields

You can display available API fields for each object type using getAPIFields() static method.

For example:

will output:

Array
(
    [id] => User group identifier. (getter: getId, setter: no setter, required: no, aliases: none)
    [title] => User group title. (getter: getTitle, setter: setTitle, required: create, update, aliases: none)
    [type] => User group type. (getter: getType, setter: setType, required: create, aliases: grouptype)
    [ismaster] => Whether this user group is master group (built-in). (getter: getIsMaster, setter: no setter, required: no, aliases: none)
)

This means that kyUserGroup objects has four API fields, exactly the same as described in Kayako REST API UserGroup reference:

  1. id: user group identifier
    • it can only be read
    • you can use getId() method to read it
  2. title: user group title
    • it can be read and written
    • you can use getTitle() method to read it and setTitle() to change it
    • you must set it to create or update an object
  3. type: user group type
    • it can be read and written
    • you can use getType() method to read it and setType() to change it
    • you must set it to create an object
    • it's accessible also using grouptype alias
  4. ismaster: whether this user group is master group (built-in)
    • it can only be read
    • you can use getIsMaster() method to read it

Accessing API fields using setters and getters

Setters are object methods beginning with set keyword, and they are used to change object API fields. Getters, on the contrary, are used to read object API fields and they begin with keyword get. Available objects setters and getters names are, in most cases, based on API field names. So for example, to read usergroupid value of User object, getUserGroupId() method should be called on kyUser instance.

There are also some additional setters and getters used for automatic loading of related objects. For example, to get instance of kyUserGroup associated with kyUser instance, getUserGroup() method can be used. In this chapter, however, we're focusing on basic methods used to read or write object API fields.

To discover available methods you can:

  • print available API fields,
  • use some development environment with code completion support (ex. Eclipse PDT),
  • read source code documentation placed in doc subdirectory of Kayako PHP Library package.
  • look inside the source code of Kayako PHP Library, all methods are described there.

When dealing with result sets, you can get API field values of all objects in result set into an array with collect methods. Collect methods names are constructed from get method names of objects within result set - the word get is replaced by word collect:

Examples:

Accessing API fields as properties

For those who still use Notepad for programming or don't feel comfortable with looking through the Library source code, nor reading some additional documentation to find proper setter or getter, there is another way of accessing object API fields. You can read or write object API fields directly as they were object properties. So, for example to read User's usergroupid field value you can get it directly by calling its name on kyUser instance. The Library will silently call proper setter or getter for this property.

If you try to read write-only field or write read-only field the operation will be ignored and User Notice will be issued.

Creating objects

When creating object some of its fields may be mandatory. Please refer to REST API Reference for further information or display API fields available for each object type and their description.

An object can be created in several ways but one thing is common for all of them - you must call object's create() or save() method in the end to actually send the data to your Kayako server.

Creating an object using constructor and bunch of set method calls

Creating an object using methods chaining

Creating an object using shurtcut methods (if defined)

Creating an object using relations between objects (as defined)

Creating an object using other object as template

Updating objects

You can only update objects that exists on server (were created before or loaded from server). To actually send updates to server you must call object's update() or save() method.

Updating an object without methods chaining

Updating an object with methods chaining

Deleting objects

You can only delete objects that exists on server (were created before or loaded from server). To delete an object you must simply call its delete() method. The request is immediately sent to Kayako server.

To delete all objects in result set, call its deleteAll() method. Be careful!.

You can't restore deleted object as-it-was in any way, so use the delete method carefully.

Deleted object is still available in the client until the end of script, so if it's needed you can create a new object with the same parameters as the deleted one by simply calling the object's create() method.

Object relations

Since there are some relations between Kayako objects (ex. user belongs to some group and organization) the client exposes methods which help to load related objects. Calling these methods usually involves sending a request to the server, but the client tries to cache related objects till the end of script.

Below are some examples of loading related objects:

Printing objects

For debugging purposes when developing your software which uses the client, you can print an object and a list of objects:

The output will contain object type, its identifier, basic info about the object and some of its properties.

Filtering, sorting and paging

The client implements client-side filtering, sorting and paging of result sets.

Remember that filtering, sorting and paging described in this chapter are executed by the client, not by the server.

Discovering available filters

Filter names are based on get method names defined in object type. To display available filters for an object type use:

For example calling:

will output:

Array
(
    [0] => filterByTitle
    [1] => filterByDisplayOrder
    [2] => filterByForegroundColor
    [3] => filterByBackgroundColor
    [4] => filterByType
    [5] => filterByUserVisibilityCustom
    [6] => filterByUserGroupId
)

Simple filtering

You can filter result set by calling filter method on it and passing desired value or values. You can also combine multiple filters using methods chaining.

Example:

Advanced filtering

You can also filter using Perl regular expressions or relational operators. This is done by passing array with operator and value instead of simple value:

Available operators are:

~

match to Perl regular expression using filter value as pattern

>

match objects with values greater than filter value

>=

match objects with values greater than or equal to filter value

<

match objects with values lesser than filter value

<=

match objects with values lesser than or equal to filter value

!=

match objects with values other than filter value

Some examples:

Removing filters

You can remove last used filter (one or more) or remove all filters to perform another filtering on the same result set.

Example:

Discovering available sorting

Ordering method names are also based on get method names defined in object type. To display available ordering methods for an object type use:

For example calling:

will output:

Array
(
    [0] => orderByTitle
    [1] => orderByDisplayOrder
    [2] => orderByType
)

Sorting

You can sort objects in result sets by calling available order method. Optionally you can pass parameter indicating direction of sorting (true for ascending, false for descending):

Objects can be sorted using only one order method at once, that is, effectively, only the last order method is used:

Example:

Paging

Result sets include helper methods for paging results. Important parameter in these methods is maximum number of items per page. It's default value is 20 and it must be the same for all calls within paging context.

Page numbering starts from 1.

Usage Examples

Following usage examples assume that proper initialization of the client was performed. Examples were tested on Kayako Fusion On Demand Trial and make use of the basic data automatically created during server installation. Some examples uses data created in previous examples, so it's better to read and run them in presented sequence.

Creating department

It's not currently possible to assign staff groups to departments via API. You must do it using Admin Control Panel.

Creating a staff user

Creating a user

Creating a ticket

Following usage examples assume that ticket creation defaults was set before.

If the user, who wants to report a problem, may not exist in your Kayako server, you can create a ticket only by providing user's name and e-mail.

Ticket processing

Cleanup

Following code deletes all objects created by previous examples. It's better to cleanup, before running these examples again.

Ticket custom fields

Since Ticket custom fields are updated with separate controller, it's not possible to create ticket with custom fields in one request to the server. So, creating ticket with custom fields requires following steps:

  1. Create a ticket (server won't complain about missing required custom fields).
  2. Inspect the ticket custom fields and set their values.
  3. Save the ticket (or save just custom field values).

To work with ticket custom fields, the ticket must exists on the server (it must be fetched from server or saved to server).

You must enabled User Editable field flag if you want to update field's value through API.

The code in following chapters assumes that some ticket is fetched from server into $ticket variable.

Knowing your custom fields

Custom fields are grouped into custom field groups. The easiest way to inspect ticket custom fields is to print them:

The two most important custom field parameters are its type and its name. The Library choose proper class when creating custom field instance based on custom field type. The custom field name is used to load proper field instance from custom fields collection.

It's good idea to inspect the client source code for possible methods which can be used with custom fields. Below are some examples:

Getting custom field value

To get the value of single field you can use one of the following methods:

The interpretation of custom field value while getting it, depends on its type:

kyCustomFieldDefinition::TYPE_TEXT

plain text value

kyCustomFieldDefinition::TYPE_TEXTAREA

plain text value

kyCustomFieldDefinition::TYPE_PASSWORD

plain text value

kyCustomFieldDefinition::TYPE_CUSTOM

plain text value

kyCustomFieldDefinition::TYPE_RADIO

kyCustomFieldOption object

kyCustomFieldDefinition::TYPE_SELECT

kyCustomFieldOption object

kyCustomFieldDefinition::TYPE_LINKED_SELECT

kyCustomFieldOption object

kyCustomFieldDefinition::TYPE_CHECKBOX

array of kyCustomFieldOption objects

kyCustomFieldDefinition::TYPE_MULTI_SELECT

array of kyCustomFieldOption objects

kyCustomFieldDefinition::TYPE_DATE

date formatted according to the configured default date format

kyCustomFieldDefinition::TYPE_FILE

array with file name as the first element and file contents as the second element

It's good idea to inspect the client source code for other possible methods which can be used to get custom fields values. Below are some examples:

Setting custom field value

To update ticket custom field value, the field name is needed. Two main ways of setting custom fields values are:

The interpretation of custom field value while setting it, depends on its type:

kyCustomFieldDefinition::TYPE_TEXT

plain text value

kyCustomFieldDefinition::TYPE_TEXTAREA

plain text value

kyCustomFieldDefinition::TYPE_PASSWORD

plain text value

kyCustomFieldDefinition::TYPE_CUSTOM

plain text value

kyCustomFieldDefinition::TYPE_RADIO

field option value OR field option id OR kyCustomFieldOption object

kyCustomFieldDefinition::TYPE_SELECT

field option value OR field option id OR kyCustomFieldOption object

kyCustomFieldDefinition::TYPE_LINKED_SELECT

field child option value OR field child option id OR kyCustomFieldOption object of child select

kyCustomFieldDefinition::TYPE_CHECKBOX

array of: field option values OR field option identifiers OR kyCustomFieldOption objects

kyCustomFieldDefinition::TYPE_MULTI_SELECT

array of: field option values OR field option identifiers OR kyCustomFieldOption objects

kyCustomFieldDefinition::TYPE_DATE

date in format understood by PHP strtotime

kyCustomFieldDefinition::TYPE_FILE

full path to file

Examples using setValue method:

It's good idea to inspect the client source code for possible methods which can be used to set custom fields values. Below are some examples:

If you created your own form to set or update custom field values then you can use following method to update custom field values using POST data from submitted form:

Saving custom fields to server

To send custom fields values to server you can following methods:

File custom fields will be sent only when changed.

Performing a ticket search

Ticket search using getAll

Ticket search using TicketSearch controller

Ticket search using client-side filtering

Sample HTML form for ticket submission

Sample HTML/PHP script featuring complete ticket submission with custom fields is included with the client in file examples/ticket_form.php. To use it you must set configuration data at the top of this file:

Then upload complete client directory to your web server document root and navigate to

http://<your web server url>/<client directory>/examples/ticket_form.php

.

Common Problems

Creating department

  1. HTTP error: 400
    • You are trying to create subdepartment with different module than parent department.

Creating ticket

  1. HTTP error: 400

Updating or deleting objects

  1. HTTP error: 405 Not Allowed

Custom fields

  1. Custom field value is not updated
    • make sure that User Editable flag is enabled for the custom field.

Other problems

  1. Enable client debug mode and review PHP logs for more information.
  2. Ask for help on Kayako Forums.

Supported Methods

API

Get all

Get (GET)

Create (POST)

Update (POST)

Delete (DELETE)

CustomField

kyCustomFieldDefinition::getAll()

N/A

N/A

N/A

N/A

Department

kyDepartment::getAll()

kyDepartment::get($id)

Yes

Yes

Yes

Staff

kyStaff::getAll()

kyStaff::get($id)

Yes

Yes

Yes

StaffGroup

kyStaffGroup::getAll()

kyStaffGroup::get($id)

Yes

Yes

Yes

Ticket

kyTicket::getAll($departments, $ticket_statuses, $owner_staffs, $users)

kyTicket::get($id)

Yes

Yes

Yes

TicketAttachment

kyTicketAttachment::getAll($ticket_id)

kyTicketAttachment::get($ticket_id, $id)

Yes

N/A

Yes

TicketCustomField

kyTicketCustomFieldGroup::getAll($ticket_id)

N/A

$ticket->updateCustomFields()

N/A

N/A

TicketCount

kyTicket::getStatistics()

N/A

N/A

N/A

N/A

TicketNote

kyTicketNote::getAll($ticket_id)

kyTicketNote::get($ticket_id, $id)

Yes

N/A

Yes

TicketPost

kyTicketPost::getAll($ticket_id)

kyTicketPost::get($ticket_id, $id)

Yes

N/A

Yes

TicketPriority

kyTicketPriority::getAll()

kyTicketPriority::get($id)

N/A

N/A

N/A

TicketSearch

kyTicket::search($query, $areas)

N/A

N/A

N/A

N/A

TicketStatus

kyTicketStatus::getAll()

kyTicketStatus::get($id)

N/A

N/A

N/A

TicketTimeTrack

kyTicketTimeTrack::getAll($ticket_id)

kyTicketTimeTrack::get($ticket_id, $id)

Yes

N/A

Yes

TicketType

kyTicketType::getAll()

kyTicketType::get($id)

N/A

N/A

N/A

User

kyUser::getAll($starting_user_id, $max_items)

kyUser::get($id)

Yes

Yes

Yes

UserGroup

kyUserGroup::getAll()

kyUserGroup::get($id)

Yes

Yes

Yes

UserOrganization

kyUserOrganization::getAll()

kyUserOrganization::get($id)

Yes

Yes

Yes

UserSearch

kyUser::search($query)

N/A

N/A

N/A

N/A

  • No labels