InstaAlert™ Protocol Documentation Applies to SupportSuite™ and eSupport™ 3.00.00 and higher © 2008 Kayako, All Rights Reserved.

SECTIONS:

1. Synopsis
2. SWIFT headers
3. Login
4. Update
5. Logout

1. SYNOPSIS

The InstaAlert protocol is designed to allow remote applications to receive alerts when certain events occur within the framework of Kayako's web-based help desk software (SupportSuite™ and eSupport™). It is exclusively executed over HTTP/S with most data sent in XML format.

The protocol begins with the client application requesting to begin a new session by authenticating. Once authenticated, the client is responsible for polling the server at an interval for XML alert data. When the client wishes to terminate the session, it should log out.

Technical questions regarding implementation of this protocol should be directed to the Kayako forums.

2. SWIFT HEADERS

Each response sent by the server will begin with a header in the following format:

SWIFT Header: <compression>;<md5 compressed>;<md5 uncompressed>;<size compressed>;<size uncompressed>;<data>

compression

Either the string "compressed" or "uncompressed" determining whether or not data is zlib compressed.

md5 compressed

The MD5 checksum of the zlib compressed data in printed hexadecimal format (e.g. '4FD8E4FD5988E970476E52AD0994EBB0'), or '0' if data is not compressed.

md5 uncompressed

The printed hexadecimal MD5 checksum of data, or '0' if data is zlib compressed.

size compressed

The size, in bytes of the zlib compressed data, or '0' if data is not compressed.

size uncompressed

The size, in bytes of data, or '0' if data is zlib compressed.

data

The data that resulted from the client's query, which may be zlib compressed.

'-1'

The session variable provided by the client is no longer valid and the client must re-authenticate.

'-2'

Authentication has failed; the user name or password provided are not correct.

3. LOGIN

path

The whole path to the installation directory for the help desk (e.g. http://domain.com/support or http://support.domain.com)

user

The URL encoded user name of the staff user's account that should be authenticated. Take special note that the source data being URL encoded should be UTF-8 (or ASCII). If a different character set is used, authentication will fail.

pass

The MD5 checksum of the staff user's plain text password in printed hexadecimal format (e.g. '4FD8E4FD5988E970476E52AD0994EBB0')

session_id

A unique variable representing the authenticated session. This variable is used in all further communication with the server.

swift_version

The human readable version of the server software (e.g. '3.30.02')

4. UPDATE

department_title

The title of this department (e.g. 'Sales')

department_isnew

'1' if any tickets have been created or updated in this department since the last time the client application requested alert data, or '0' otherwise.

department_link

The full URL that can be used to go directly to this department in the help desk.

status_title

The title of this status (e.g. 'Escalated')

status_isnew

'1' if any tickets with this status in the parent department have been created or updated since the last time the client application requested alert data, or '0' otherwise.

status_count

The number of 'new' tickets (see status_isnew).

status_link

The full URL that can be used to view all tickets in the parent department with this status in the help desk.

alert_title

The title of the alert (e.g. 'Sales: Question about product')

alert_link

The full URL that can be used to go directly to the relevant item in the help desk.

5. LOGOUT