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

Client request

'Logging in,' or authenticating the client application is the first step in the client/server session. The client sends authentication credentials and the server will respond either with an error code, or the relevant information required by the client for the rest of the session.

URL

To log in, perform a POST request to the following URL:

POST arguments

Argument

Value

username

The user's account name

password

The user's password.

twofactorkey

Optional: The two factor authentication key (in plaintext). This value should be dispatched only when server requests it, which is when the staff user has enabled two factor authentication.

Server response

The server will respond with a standard SWIFT header containing an XML payload as described here:

Root node

The parent node for the entire XML payload. If you do not locate this node at the top level, it is likely that the server returned an error response. See error codes for further information.

<kayako_livechat>

Two Factor Key Request

The server will request a two factor authentication key if the staff user logging in has enabled two factor authentication. If your application receives this request, it should prompt the user for the two factor key and send the request again with the 'twofactorkey' POST argument as shown above.

<status>2</status>
<error>Please send the two factor authentication key to login.</error>

Node name

Value

status

The server will send '2' as the status value if the two factor authentication is enabled.

error

The error message returned by SWIFT. i.e., "Please send the two factor authentication key to login."

Session data

This section contains status and session information. If the application detects an error (i.e. if status = '-1'), the process should be aborted and the user notified of the error that occurred.

<status>...</status>
<error>...</error>
<sessionid>...</sessionid>
<staffsessionid>...</staffsessionid>
<uniqueid>...</uniqueid>
<version>...</version>
<product>...</product>
<companyname>...</companyname>
<displaytimestamps>...</displaytimestamps>
<recordphonecalls>...</recordphonecalls>
<chatqueuetype>...</chatqueuetype>

Node name

Value

Attributes

status

'1': Successfully logged in
'-1': Failed to log in. Check the error node for a human-readable error description

error

Human-readable error description, if any

sessionid

Live chat session ID. Must be stored; it will be needed for every other request to the server.

staffsessionid

Staff portal session ID; should be stored for later use (e.g. When opening a ticket in a web browser)

uniqueid

Unique identifier for the Kayako product (SWIFT) installation

version

Kayako server (SWIFT) product version number (e.g. '4.0.0').

product

Kayako server (SWIFT) product name (e.g. 'SupportSuite')

companyname

The company name as configured in SWIFT (e.g. 'Acme Co.')

displaytimestamps

Whether or not time stamps should be displayed in chat views ('1' or '0')

recordphonecalls

Whether or not the client should send recordings of phone calls to the server.

chatqueuetype

Type of chat queue in use by the server. One of the following: roundrobin, queue

Permissions

Miscellaneous user permissions can be found in this section.

<permissions>
    <can_observe_chats>...</can_observe_chats>
  </permissions>

Node name

Value

permissions

(Parent node)

can_observe_chats

Whether or not the user can observe chats and see chat observers ('1' or '0')

Variables

Miscellaneous variables can be found in this section.

<variables>
    <max_upload_size>...</max_upload_size>
  </variables>

Node name

Value

Attributes

variables

Contains child nodes that hold information about session variable values

(none)

max_upload_size

The maximum size, in octets, allowed when uploading files. Equivalent to upload_max_filesize in the server's PHP configuration.

(none)

Departments

This section contains a list of departments. The data should be stored for the duration of the client/server session.

Departments can be nested, but only up to one level deep. (i.e. a top-level department can have children, but the child departments cannot)

<departments>
    <department id="..." title="..." assigned="...">
      <department id="..." title="..." assigned="..." parentdepartmentid="..." />
    </department>
  </departments>

Node name

Value

Attributes

departments

May contain one or more department nodes

(none)

department

May contain one or more department nodes

id: Numeric ID of this department
title: String title of this department (e.g. 'Sales')
assigned: Whether or not the user is assigned to this department ('1' or '0')
parentdepartmentid: Parent department's numeric ID, if this is a sub-department

Staff groups

This section contains staff group information.

<staffgroups>
    <staffgroup id="...">...</staffgroup>
  </staffgroups>

Node name

Value

Attributes

staffgroups

May contain one or more staffgroup nodes

(none)

staffgroup

String title of this staff group (e.g. 'Administrators')

id: Numeric ID of this staff group

Chat skills

This section contains chat skill information.

<chatskills>
    <chatskill id="...">...</chatskill>
  </chatskills>

Node name

Value

Attributes

chatskills

May contain one or more chatskill nodes

(none)

chatskill

String title of this chat skill (e.g. 'Unix expert')

id: Numeric ID of this chat skill

Staff data

This section contains information about the currently logged in staff.

<staff>
    <fullname>...</fullname>
    <email>...</email>
    <greeting>...</greeting>
    <mobilenumber>...</mobilenumber>
    <statusmsg>...</statusmsg>
  </staff>

Node name

Value

staff

(Parent node)

fullname

Full name of the staff

email

Email address of the staff

greeting

Personal greeting for the staff

mobilenumber

The staff's mobile telephone number

statusmsg

The last status message

Avatar data

Avatar data should be stored for the duration of the client/server session, but does not need to be saved to permanent storage, since the server dispatches all of this data upon logging in.

<avatarlist>
    <avatar staffid="..." type="...">...</avatar>
  </avatarlist>

Node name

Value

Attributes

avatarlist

May contain one or more avatar nodes

(none)

avatar

Base-64 encoded image data

staffid: Numeric ID of the staff user to whom this avatar belongs
type: Type of image. One of the following: 'gif', 'png', 'jpg'

Canned responses

Canned responses are organized in a tree-like structure. The parent node, as well as child nodes, may contain any number of categories and responses, so the tree should be parsed recursively.

Canned data should be stored for the duration of the client/server session.

<canned>
    <category id="..." title="...">
      <response id="..." title="...">
        <url>...<url>
        <image>...<image>
        <code lang="...">...<code>
        <message>...<message>
      </response>
    </category>
  </canned>

Node name

Value

Attributes

canned

May contain one or more category or response nodes

(none)

category

May contain one or more category or response nodes

id: Numeric ID for this category
title: String title for this category

response

May contain one of each of any of the following nodes: url, image, code, message (canned responses may contain multiple 'actions')

id: Numeric ID for this response
title: String title for this response

url

A URL to be pushed when the response is executed

(none)

image

A URL of an image to be pushed when the response is executed

(none)

code

A code snippet to be sent when the response is executed

lang: Type of code. See Language codes

message

A text message to be sent when the response is executed

(none)