LC - Logging in

Table of contents
1 Client request 1.1 URL 1.2 POST arguments 2 Server response 2.1 Root node 2.2 Two Factor Key Request 2.3 Session data 2.4 Permissions 2.5 Variables 2.6 Departments 2.7 Staff groups 2.8 Chat skills 2.9 Staff data 2.10 Avatar data 2.11 Canned responses 2.12 OnSite

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:

<SWIFT_URL>/winapp/index.php?/Core/Default/Login

Where <SWIFT_URL> is the base URL to the Kayako installation (e.g. 'http://support.mycompany.com/')

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.

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.

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.

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.

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.

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)

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.

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.

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.

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.

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.

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)

OnSite

Settings and version information related to the OnSite feature in this section. If the server uses a version older than the one supported by the client, the OnSite feature should be disabled.

Node name	Value	Attributes
`onsite`	Container for all OnSite-related data	`version`: The numeric version of the OnSite feature supported by the SWIFT server (e.g., '2').
`server_cfg`	Contains information about one usable OnSite server configuration. Note: There may be several `server_cfg` nodes; it is the client's responsibility to choose one at random at the start of each OnSite session.	`id`: A unique identifier for this server configuration. The client and server will use this to identify configurations during OnSite sessions.
`xmpp`	(none)	`host`: The FQDN (or IP address) of the XMPP server for this configuration (e.g. *xmpp.kayako.com*) `port`: The numeric port number that the XMPP daemon is serving on.
`stun`	(none)	`host`: The FQDN (or IP address) of the STUN server for this configuration (e.g. *stun.kayako.com*) `port`: The numeric port number that the STUN daemon is serving on.
`turn`	(none)	`host`: The FQDN (or IP address) of the TURN server for this configuration (e.g. *turn.kayako.com*) `udp`: The numeric port number that the TURN server uses for UDP. `tcp`: The numeric port number that the TURN server uses for TCP.