KayakoMobile™ Protocol Documentation
Applies to SupportSuite™ and eSupport™ 3.20.02 or higher
© 2008 Kayako, All Rights Reserved.

SECTIONS:

  1. Synopsis
  2. SWIFT headers
  3. Login
  4. Push
  5. Synchronization
  6. Logout

1. SYNOPSIS

The KayakoMobile protocol allows a remote device to retrieve, modify and create tickets within the framework of Kayako's web-based help desk software (SupportSuite™ and eSupport™). This document describes the communication protocol used to accomplish this. Technical questions regarding implementation of this protocol should be directed to the Kayako forums.

The KayakoMobile protocol is exclusively executed over HTTP/S with most data sent in XML format.

The following sections are presented in order of execution; that is, any application implementing this protocol must perform these steps in order.

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.
If an error occurs during the processing of a request, the server may respond with one of the following error codes in the data parameter:
'-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

Before any further communication can take place between the client and server, the client must be authenticated. This is done by passing a staff user's credentials to the server by opening a URL in the following format:

Login URL: <path>/mobile/index.php?_ca=login&username=<user>&password=<pass>

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')
The server will then respond with a standard SWIFT header containing either error information or the following UTF-8 encoded XML data if the authentication was successful:

<mobile>
  <sessionid><![CDATA[%sessionid%]]></sessionid>
  <version><![CDATA[%version%]]></version>
sessionid
Represents a unique identifier for this synchronization session. The client should store this for use in all further communication.
version
The version of the server software (e.g. '3.30.01')
  <department>
    <departmentid><![CDATA[%department_id%]]></departmentid>
    <title><![CDATA[%department_title%]]></title>
    <isassigned><![CDATA[%is_assigned%]]></isassigned>
  </department>

One or more department nodes can be present. One is sent for each department in the system.
department_id
Unique numeric identifier for this department.
department_title
The title of the department (e.g. 'General')
is_assigned
Whether or not the staff user authenticated is assigned to this department.

  <status>
    <ticketstatusid><![CDATA[%status_id%]]></ticketstatusid>
    <title><![CDATA[%status_title%]]></title>
    <statuscolor><![CDATA[%status_color%]]></statuscolor>
  </status>

One or more status nodes can be present. One is sent for each status in the system.
status_id
Unique numeric identifier for this status.
status_title
The title of the status (e.g. 'Open')
status_color
The color used to render this status whenever it appears, in web color format (e.g. '#aabbcc')

  <priority>
    <priorityid><![CDATA[%priority_id%]]></priorityid>
    <title><![CDATA[%priority_title%]]></title>
    <prioritycolor><![CDATA[%priority_color%]]></prioritycolor>
  </priority>

One or more priority nodes can be present. One is sent for each priority in the system.
priority_id
Unique numeric identifier for this priority.
priority_title
The title of the priority (e.g. 'Escalated')
priority_color
The color used to render this priority whenever it appears, in web color format (e.g. '#aabbcc')
  <staff>
    <staffid><![CDATA[%staff_id%]]></staffid>
    <fullname><![CDATA[%staff_fullname%]]></fullname>
    <email><![CDATA[%staff_email%]]></email>
  </staff>

One or more staff nodes can be present. One is sent for each staff user in the system.
staff_id
Unique numeric identifier for this staff user.
staff_fullname
The display name for this staff user (e.g. 'Joe Smith')
staff_email
The e-mail address to use for this staff user.
  <tree>
    <department>
      <title><![CDATA[%department_title%]]></title>
      <isnew><![CDATA[%is_new%]]></isnew>
      <departmentid><![CDATA[%department_id%]]></departmentid>
      <status>
        <title><![CDATA[%status_title%]]></title>
        <isnew><![CDATA[%is_new%]]></isnew>
        <count><![CDATA[%status_count%]]></count>
        <ticketstatusid><![CDATA[%status_id%]]></ticketstatusid>
      </status>
    </department>
  </tree>

The tree node contains a hierarchical representation of all available departments and their statuses. The application can use this data to render a navigable tree for filtering tickets, but it is not essential data (i.e. it can be safely ignored if the application does not care to render such a tree)

Each department node contains information about the department, as well as the statuses that are associated with it. There can be one or more department nodes with one or more status nodes underneath them.
department_title
The title of the department (e.g. 'General')
is_new
'1' if the department contains 'new' tickets, or '0' if it doesn't.
department_id
Unique numeric identifier for this department.
status_title
The title of the status (e.g. 'Open')
is_new
'1' if the status contains 'new' tickets, or '0' if it doesn't.
count
The count of new tickets in this status.
status_id
Unique numeric identifier for this status.
  <fromqueue>
    <emailqueueid><![CDATA[%emailqueue_id%]]></emailqueueid>
    <fullname><![CDATA[%emailqueue_fullname%]]></fullname>
    <email><![CDATA[%emailqueue_email%]]></email>
    <departmentid><![CDATA[%emailqueue_departmentid%]]></departmentid>
  </fromqueue>

One or more e-mail queue nodes can be present. One is sent for each e-mail queue configured in the system.
emailqueue_id
Unique numeric identifier for this e-mail queue.
emailqueue_fullname
The display name for the e-mail queue (e.g. 'Sales Department')
emailqueue_email
The e-mail address of the e-mail queue.
emailqueue_departmentid
The identifier of the department that this e-mail queue is associated with.
  <predefined>
    <category>
      <predefinedcategoryid><![CDATA[%predefinedcat_id%]]></predefinedcategoryid>
      <title><![CDATA[%predefinedcat_title%]]></title>
      <category>
        <predefinedcategoryid><![CDATA[%predefinedcat_id%]]></predefinedcategoryid>
        <title><![CDATA[%predefinedcat_title%]]></title>
        <reply>
          <predefinedreplyid><![CDATA[%predefinedreply_id%]]></predefinedreplyid>
          <predefinedcategoryid><![CDATA[%predefinedreply_catid%]]></predefinecategoryid>
          <subject><![CDATA[%predefinedreply_subject%]]></subject>
          <contents><![CDATA[%predefinedreply_contents%]]></contents>
        </reply>
      </category>
    </category>
  </predefined>

The predefined replies node is a hierarchical set of categories containing replies. There can be one or more category nodes, each containing one or more sub-categories.
predefinedcat_id
Unique numeric identifier for this predefined category.
predefinedcat_title
The title of this category (e.g. 'Sales')
predefinedreply_id
Unique numeric identifier for this predefined reply.
predefinedreply_catid
Unique numeric identifier of the category to which this reply belongs.
predefinedreply_subject
The title of this predefined reply (e.g. 'Sales Pitch')
predefinedreply_contents
The text value of the predefined reply
  <staffid><![CDATA[%staffid%]]></staffid>
staffid
Unique numeric identifier for the staff user that was authenticated.
</mobile>

The application should store all login data for the duration of the synchronization session.

4. PUSH

After the login sequence has been completed successfully and the application has stored all the pertinent data for the session, the application should send data related to modifications made to existing tickets as well as new ticket data.

This is done by sending it to the server by opening the following URL:

Push URL: <path>/mobile/index.php?_m=tickets&_a=mobilepush&sessionid=<sessionid>&xml=<xml_payload>

path
The whole path to the installation directory for the help desk (e.g. http://domain.com/support or http://support.domain.com)
sessionid
The sessionid variable sent in the login sequence; used to authenticate.
xml_payload
The XML payload containing all of the modification and new ticket data. This data should be UTF-8 encoded, then URL encoded before sending to the server. It should be in the following format:
<mobile>
  <delete>
    <ticketid><![CDATA[%ticket_id%]]></ticketid>
  </delete>

For each ticket that should be deleted from the server, the application should send a delete node containing the ticket's unique numeric identifier.
ticket_id
The unique numeric identifier of the ticket to be deleted.
  <reply>
    <ticketid><![CDATA[%ticket_id%]]></ticketid>
    <contents><![CDATA[%contents%]]></contents>
    <attachment>
      <filename><![CDATA[%attachment_filename%]]></filename>
      <contents><![CDATA[%attachment_contents%]]></contents>
      <md5><![CDATA[%attachment_md5%]]></md5>
    </attachment>
  </reply>

Replies to existing tickets in the system contain information about the reply, as well as any file attachments. Attachment nodes are not required, and any number of them can be present. Note that in this version of the protocol, there is a limit of one reply per ticket.
ticket_id
The unique numeric identifer of the ticket this reply should be added to.
contents
The text contents of the reply.
attachment_filename
The short file name of the attachment (e.g. 'CallNotes.txt')
attachment_contents
The contents of the attachment. Must be base64 encoded (and URL encoded) before transfer to the server.
attachment_md5
The MD5 checksum of the file contents, in printed hexadecimal format (e.g. '4FD8E4FD5988E970476E52AD0994EBB0')
  <note>
    <ticketid><![CDATA[%ticket_id%]]></ticketid>
    <staffid><![CDATA[%staff_id%]]></staffid>
    <type><![CDATA[%note_type%]]></type>
    <contents><![CDATA[%note_contents%]]></contents>
  </note>

Adds a note to an existing ticket in the system. Note that in this version of the protocol, there is a limit of one note per ticket.
ticket_id
The unique numeric identifier of the ticket to which the note should be attached.
staff_id
The unique numeric identifier of the staff user who posted the note. This data is sent in the login sequence.
note_type
  • 'user': The note will stick to the client who is associated with the ticket specified in ticket_id.
  • 'ticket': The note will only be added to the ticket specified in ticket_id.
note_contents
The text contents of the note.
  <billing>
    <ticketid><![CDATA[%ticket_id%]]></ticketid>
    <billingid><![CDATA[%billing_id%]]></billingid>
    <workerid><![CDATA[%worker_id%]]></workerid>
    <timespent><![CDATA[%time_spent%]]></timespent>
    <timebillable><![CDATA[%time_billable%]]></timebillable>
    <notes><![CDATA[%billing_notes%]]></notes>
  </billing>

Adds a billing entry to an existing ticket in the system. One or more billing entries can be sent for a single ticket.
ticket_id
The unique numeric identifier of the ticket to which the billing entry should be attached.
billing_id
A unique identifier understood by the client application. This value is used later in the protocol to identify billing entries.
worker_id
The unique numeric identifier of the staff user who is posting the billing entry.
time_spent
The total time, in minutes associated with this billing entry.
time_billable
The time, in minutes that is billable to the customer.
billing_notes
The text contents of any notes that accompany this billing entry.
  <propchange>
    <ticketid><![CDATA[%ticket_id%]]><ticketid>
    <type><![CDATA[%propchange_type%]]></type>
    <data><![CDATA[%propchange_data%]]></data>
  </propchange>

To make modifications to existing tickets in the system, the propchange node is used. Any number of propchanges can be sent, for any ticket in the system.
ticket_id
The unique numeric identifier of the ticket to which modifications should be applied.
propchange_type
propchange_data
Value dependent on propchange_type (see above).
  <ticket>
    <departmentid><![CDATA[%department_id%]]></departmentid>
    <ticketstatusid><![CDATA[%status_id%]]></ticketstatusid>
    <priorityid><![CDATA[%priority_id%]]></priorityid>
    <ownerstaffid><![CDATA[%owner_id%]]></ownerstaffid>
    <type><![CDATA[%ticket_type%]]></type>
    <subject><![CDATA[%ticket_subject%]]></subject>
    <emailqueueid><![CDATA[%emailqueue_id%]]></emailqueueid>
    <fullname><![CDATA[%creator_fullname%]]></fullname>
    <userphone><![CDATA[%creator_phone%]]></userphone>
    <useremail><![CDATA[%creator_email%]]></useremail>
    <duetime><![CDATA[%ticket_duetime%]]></duetime>
    <flagtype><![CDATA[%ticket_flagtype%]]></flagtype>
    <note>
      <type><![CDATA[%note_type%]]></type>
      <contents><![CDATA[%note_contents%]]></contents>
    </note>
    <reply>
      <sendautoresponder><![CDATA[%send_autoresponder%]]></sendautoresponder>
      <sendcontents><![CDATA[%send_replycontents%]]></sendcontents>
      <ccto><![CDATA[%cc_to%]]></ccto>
      <bccto><![CDATA[%bcc_to%]]></bccto>
      <contents><![CDATA[%reply_contents%]]></contents>
      <attachment>
        <filename><![CDATA[%attachment_filename%]]></filename>
        <contents><![CDATA[%attachment_contents%]]></contents>
        <md5><![CDATA[%attachment_md5%]]></md5>
      <attachment>
    </reply>
    <billing>
      <workerid><![CDATA[%billing_worker_id%]]></workerid>
      <timespent><![CDATA[%billing_time_spent%]]></timespent>
      <timebillable><![CDATA[%billing_time_billable%]]></timebillable>
      <notes><![CDATA[%billing_notes%]]></notes>
    </billing>
  </ticket>

Tickets can be created in the system using the syntax above. There is no limit to the number of tickets that can be created in a single synchronization session. Much of the XML used to define new tickets is a repeat of other parts of the protocol already covered.
department_id
The unique numeric identifier of the department in which the new ticket should be created.
status_id
The unique numeric identifier of the target status for the new ticket.
priority_id
The unique numeric identifier of the target priority for the new ticket.
owner_id
The unique numeric identifier of the staff user that should take ownership of the new ticket.
ticket_type
The type of ticket to create:
  • 'phone': The ticket originates from a telephone conversation with a customer and was filed by a staff user.
  • 'email': The ticket originates from an e-mail conversation and was filed by a staff user.
ticket_subject
The title of the new ticket (e.g. 'I need help with XYZ')
emailqueue_id
The unique numeric identifier of the e-mail queue that should be used as the 'from' address when corresponding with the customer (e.g. for the autoresponder message).
creator_fullname
The customer's full name.
creator_phone
The customer's telephone number.
creator_email
The customer's e-mail address.
ticket_duetime
The numeric unix timestamp of the due date for the ticket, or '0' for none.
ticket_flagtype
The flag type to use for the new ticket. See the section on propchanges above for details.
note_type
(optional) The type of note to create. (see the section on notes above for details).
note_contents
(optional) The text contents of the note.
send_autoresponder
'1' if the system should send an automatic receipt confirmation notice to the customer, or '0' if it should not.
send_replycontents
'1' if the system should send an e-mail to the customer containing the ticket's initial contents (i.e. the first reply), or '0' if it should not.
cc_to
(optional) A semi-colon delimited list of e-mail addresses that should be added as CC receipients to the ticket.
bcc_to
(optional) A semi-colon delimited list of e-mail addresses that should be added as BCC recipients to the ticket.
reply_contents
The initial text contents of the ticket. (i.e. the first reply)
attachment_filename
(optional) The short file name of the attachment. (e.g. 'CallNotes.txt')
attachment_contents
(optional) The contents of the attachment. Must be base64 encoded (and URL encoded) before transfer to the server.
attachment_md5
(optional) The MD5 checksum of the file contents, in printed hexadecimal format (e.g. '4FD8E4FD5988E970476E52AD0994EBB0')
billing_worker_id
(optional) The unique numeric identifier of the staff user who is posting the billing entry.
billing_time_spent
(optional) The total time, in minutes associated with this billing entry.
billing_time_billable
(optional) The time, in minutes that is billable to the customer.
billing_notes
(optional) The text contents of any notes that accompany this billing entry.
</mobile>

Server push response: After the receipt of the above XML payload, the server attempts to merge the requested changes and create the new tickets. The XML response from the server is in the following format and contains information about the success/failure state of the requested operations:

<mobile>
  <successes><![CDATA[%success_count%]]></successes>
  <errors><![CDATA[%error_count%]]></errors>
  
  <success>
    <ticketid><![CDATA[%success_ticket_id%]]></ticketid>
    <ticketdisplayid><![CDATA[%success_ticket_displayid%]]></ticketdisplayid>
    <type><![CDATA[%success_type%]]></type>
    <data><![CDATA[%success_data%]]></data>
  </success>
  
  <error>
    <ticketdisplayid><![CDATA[%error_ticket_displayid%]]></ticketdisplayid>
    <type><![CDATA[%error_type%]]></type>
    <message><![CDATA[%error_message%]]></message>
  </error>
</mobile>
success_count
The number of requested operations that were completed successfully for this transaction.
error_count
The number of requested operations that could not be completed due to an error.
success_ticket_id
The unique numeric identifier of the ticket on which this operation was performed.
success_ticket_displayid
The display id of the ticket on which this operation was performed. (e.g. 'ABC-12345')
success_type
The type of operation that this success node refers to:
  • 'reply': A reply was successfully attached to the ticket.
  • 'note': A note was successfully attached to the ticket.
  • 'propchange': A property change was successfully applied to the ticket. success_data contains information about which property was changed.
  • 'billing': A billing entry was successfully attached to the ticket.
  • 'delete': The ticket was successfully deleted.
  • 'newticket': A ticket was successfully created.
success_data
  • If success_type is set to 'reply,' this value is unused.
  • If success_type is set to 'note,' this value is unused.
  • If success_type is set to 'propchange,' this is set to the type of property that was changed:
    • 'owner'
    • 'department'
    • 'status'
    • 'priority'
    • 'flagtype'
    • 'duedate'
  • If success_type is set to 'billing,' the application defined unique identifier sent in the push payload.
  • If success_type is set to 'newticket,' the unique numeric identifier of the newly created ticket.
error_ticket_displayid
The unique numeic identifier of the ticket for which an operation failed to be executed.
error_type
  • 'reply': A reply failed to be attached to the ticket.
  • 'note': A note failed to be attached to the ticket.
  • 'propchange': A property change failed to be executed on the ticket.
  • 'billing': A billing entry failed to be attached to the ticket.
  • 'delete': The ticket failed to be deleted.
  • 'newticket': Failed to create a new ticket.
error_message
An error-specific message generated by the server to display to the user.
The client application should use the response from the server to clean up its local database of modification and new ticket data and display any error messages to the user. Due to design restrictions of the protocol, some items such as notes and replies are limited to one per ticket, as there is no way to identify them in the server's response payload other than by numeric ticket id. Future versions of the protocol will lift this restriction.

5. SYNCHRONIZATION

After modifications are applied and new tickets are created, the client application should then proceed to request a snapshot of the ticket database. This is done by opening the following URL:

Synchronization URL: <path>/mobile/index.php?_m=tickets&_a=syncfetch&sessionid=<sessionid>&xml=<xml_payload>

path
The whole path to the installation directory for the help desk (e.g. http://domain.com/support or http://support.domain.com)
sessionid
The sessionid variable sent in the login sequence; used to authenticate.
xml_payload
The XML payload that sets some optional parameters for the synchronization session. This data should be UTF-8 encoded, then URL encoded before sending to the server. It should be in the following format:
<options>
  <attachments>
    <maxsize><![CDATA[%max_attachment_size%]]></maxsize>
    <ticket>
      <ticketid><![CDATA[%attachment_request_ticket_id%]]></ticketid>
    </ticket>
  </attachments>
</options>
max_attachment_size
The maximum size, in bytes of any attachment that the client application wishes to receive.
attachment_request_ticket_id
The unique numeric identifier of an existing ticket in the system that the client application wishes to receive attachments for.
Attachments are only sent by the server when explicitly requested in order to keep bandwidth and memory requirements low. The client application should send a ticket node (see above) with the ticket's identifier for each ticket it wishes to receive attachments for.

Upon receipt of this XML payload, the server will prepare an XML representation of the tickets to be synchronized to the client application. The XML is in the following format:

<mobile>
  <ticketcount><![CDATA[%ticket_count%]]></ticketcount>
ticket_count
The number of ticket nodes that follow in the payload. The application can use this value to provide meaningful progress to the user while processing.
  <ticket>
    <entry name="ticketid"><![CDATA[%ticket_id%]]></entry>
    <entry name="ticketdisplayid"><![CDATA[%ticket_displayid%]]></entry>
    <entry name="isnew"><![CDATA[%is_new%]]></entry>
    <entry name="departmentid"><![CDATA[%department_id%]]></entry>
    <entry name="ticketstatusid"><![CDATA[%status_id%]]></entry>
    <entry name="priorityid"><![CDATA[%priority_id%]]></entry>
    <entry name="emailqueueid"><![CDATA[%emailqueue_id%]]></entry>
    <entry name="userid"><![CDATA[%user_id%]]></entry>
    <entry name="ownerstaffid"><![CDATA[%owner_id%]]></entry>
    <entry name="fullname"><![CDATA[%creator_fullname%]]></entry>
    <entry name="email"><![CDATA[%creator_email%]]></entry>
    <entry name="lastreplier"><![CDATA[%last_replier%]]></entry>
    <entry name="subject"><![CDATA[%subject%]]></entry>
    <entry name="dateline"><![CDATA[%creation_date%]]></entry>
    <entry name="displaydate"><![CDATA[%creation_displaydate%]]></entry>
    <entry name="lastactivity"><![CDATA[%last_activity%]]></entry>
    <entry name="laststaffreplytime"><![CDATA[%last_staff_reply%]]></entry>
    <entry name="slaplanid"><![CDATA[%sla_planid%]]></entry>
    <entry name="ticketslaplanid"><![CDATA[%ticket_sla_planid%]]></entry>
    <entry name="duetime"><![CDATA[%due_time%]]></entry>
    <entry name="totalreplies"><![CDATA[%total_replies%]]></entry>
    <entry name="ipaddress"><![CDATA[%ip_address%]]></entry>
    <entry name="flagtype"><![CDATA[%flag_type%]]></entry>
    <entry name="hasnotes"><![CDATA[%has_notes%]]></entry>
    <entry name="hasattachments"><![CDATA[%has_attachments%]]></entry>
    <entry name="isemailed"><![CDATA[%is_emailed%]]></entry>
    <entry name="edited"><![CDATA[%is_edited%]]></entry>
    <entry name="editedbystaffid"><![CDATA[%edited_by_staffid%]]></entry>
    <entry name="editeddateline"><![CDATA[%edited_dateline%]]></entry>
    <entry name="creator"><![CDATA[%creator%]]></entry>
    <entry name="hasdraft"><![CDATA[%has_draft%]]></entry>
    <entry name="hasbilling"><![CDATA[%has_billing%]]></entry>
    <entry name="isphonecall"><![CDATA[%is_phonecall%]]></entry>
    <entry name="isescalated"><![CDATA[%is_escalated%]]></entry>
    <entry name="phoneno"><![CDATA[%phone_number%]]></entry>

Each property associated with a ticket is represented by an entry node with its name set to the property that it represents.
ticket_id
The unique numeric identifier for this ticket. The client application should use this to reference the ticket.
ticket_displayid
The human readable identifier for this ticket. (e.g. 'ABC-12345')
is_new
'1' if the ticket is new since the last synchronization, '0' if not.
department_id
The unique numeric identifier of the department in which this ticket resides.
status_id
The unique numeric identifier of this ticket's status.
priority_id
The unique numeric identifier of this ticket's priority.
emailqueue_id
The unique numeric identifier of the e-mail queue associated with this ticket.
user_id
The unique numeric identifier of the client user that created this ticket.
owner_id
The unique numeric identifier of the staff user that owns this ticket.
creator_fullname
The full name of the client or staff user that created this ticket.
creator_email
The e-mail address of the client or staff user that created this ticket.
last_replier
The full name of the last person to reply to this ticket.
subject
The title of the ticket (e.g. 'I need help with XYZ')
creation_date
The numeric unix timestamp of the creation date for this ticket.
creation_displaydate
The human readable creation date for this ticket.
last_activity
The numeric unix timestamp of the last activity for this ticket (i.e. the last time anyone has replied to it)
last_staff_reply
The numeric unix timestamp of the last time a staff user replied to this ticket.
sla_planid
The unique numeric identifier of the SLA plan associated with the client user that created this ticket, if any.
ticket_sla_planid
The unique numeric identifier of the SLA plan associated with this ticket, if any.
due_time
The numeric unix timestamp of the due date for this ticket, or '0' if there is no due date.
total_replies
The total number of posts (replies) that have been made to this ticket.
ip_address
The dotted quad IP address of the client or staff user that created this ticket.
flag_type
The type of flag associated with this ticket; see flag types for more information.
has_notes
'1' if any notes have been attached to this ticket, '0' otherwise.
has_attachments
'1' if this ticket contains any file attachments, '0' otherwise.
is_emailed
'1' if this ticket was created through an e-mail message, '0' otherwise.
is_edited
'1' if modifications have been made to this ticket, '0' otherwise.
edited_by_staffid
If modifications were made, the unique numeric identifier of the staff user that made them.
edited_dateline
If modifications were made, the numeric unix timestamp of the time at which the last modifications occurred.
creator
The type of user that created this ticket:
  • '1': Created by a staff user.
  • '2': Created by a client user.
has_draft
'1' if any posts to this ticket have been saved as a draft, '0' otherwise.
has_billing
'1' if any billing entries have been attached to this ticket, '0' otherwise.
is_phonecall
'1' if this ticket was created by a staff user through the web interface as the result of a telephone call with a customer, '0' otherwise.
is_escalated
'1' if this ticket has been escalated, '0' otherwise.
phone_number
For telephone tickets, the phone number of the customer associated with the ticket.
    <attachment>
      <filename><![CDATA[%attachment_filename%]]></filename>
      <filesize><![CDATA[%attachment_filesize%]]></filesize>
      <md5><![CDATA[%attachment_md5%]]></md5>
      <contents><![CDATA[%attachment_contents%]]></contents>
    </attachment>

If attachments have been explicitly requested for this ticket in the optional synchronization parameters, any attachments are sent in this format (zero or more attachment nodes can be present).
attachment_filename
The short file name of the attachment. (e.g. 'CallNotes.txt')
attachment_filesize
The size, in bytes of the unencoded file contents.
attachment_contents
The contents of the attachment, base64 encoded.
attachment_md5
The MD5 checksum of the unencoded file contents, in printed hexadecimal format (e.g. '4FD8E4FD5988E970476E52AD0994EBB0')
    <post>
      <entry name="ticketpostid"><![CDATA[%post_id%]]></entry>
      <entry name="dateline"><![CDATA[%post_dateline%]]></entry>
      <entry name="displaydate"><![CDATA[%post_display_date%]]></entry>
      <entry name="fullname"><![CDATA[%post_full_name%]]></entry>
      <entry name="email"><![CDATA[%post_email%]]></entry>
      <entry name="hasattachments"><![CDATA[%post_has_attachments%]]></entry>
      <entry name="edited"><![CDATA[%post_is_edited%]]></entry>
      <entry name="editedbystaffid"><![CDATA[%post_edited_by_staffid%]]></entry>
      <entry name="editeddateline"><![CDATA[%post_edited_dateline%]]></entry>
      <entry name="creator"><![CDATA[%post_creator%]]></entry>
      <entry name="isemailed"><![CDATA[%post_isemailed%]]></entry>
      <entry name="staffid"><![CDATA[%post_staffid%]]></entry>
      <entry name="contents"><![CDATA[%post_contents%]]></entry>
    </post>

For each post (reply) attached to this ticket, a post node will be sent.
post_id
A unique numeric identifier for this post.
post_dateline
The numeric unix timestamp of the time at which this post was attached.
post_display_date
The human readable timestamp of the time at which this post was attached.
post_full_name
The full name of the person who created the post.
post_email
The e-mail address of the person who created the post.
post_has_attachments
'1' if any files are attached to this post, '0' otherwise.
post_is_edited
'1' if modifications have been made to this post.
post_edited_by_staffid
If modifications were made, the unique numeric identifier of the staff user that made them.
post_edited_dateline
If modifications were made, the numeric unix timestamp of the time at which the last modifications occurred.
post_creator
The type of user that created this post:
  • '1': Staff user
  • '2': Client user
  • '3': Third party
  • '4': Recipient (CC or BCC)
post_isemailed
'1' if the post was created through an e-mail message, '0' otherwise.
post_staffid
If the post was created by a staff user, their unique numeric identifier, otherwise '0'
post_contents
The text contents of this post.
    <note>
      <entry name="ticketnoteid"><![CDATA[%note_id%]]></entry>
      <entry name="dateline"><![CDATA[%note_dateline%]]></entry>
      <entry name="fullname"><![CDATA[%note_full_name%]]></entry>
      <entry name="contents"><![CDATA[%note_contents%]]></entry>
      <entry name="type"><![CDATA[%note_type%]]></entry>
    </note>

For each note that has been attached to this ticket, a note node will be sent.
note_id
A unique numeric identifier for this note.
note_dateline
The numeric unix timestamp of the time the note was posted.
note_full_name
The full name of the staff user that posted this note.
note_contents
The text contents of this note.
note_type
  • 'user': This note sticks to the client user that is associated with this ticket and appears on all their tickets.
  • 'ticket': This note only exists as a part of this ticket.
    <billing>
      <entry name="timetrackid"><![CDATA[%billing_id%]]></entry>
      <entry name="dateline"><![CDATA[%billing_dateline%]]></entry>
      <entry name="creatorname"><![CDATA[%billing_creator%]]></entry>
      <entry name="timespent"><![CDATA[%billing_timespent%]]></entry>
      <entry name="timebillable"><![CDATA[%billing_timebillable%]]></entry>
      <entry name="notes"><![CDATA[%billing_notes%]]></entry>
    </billing>
  </ticket>  
</mobile>

If any billing entries have been attached to this ticket, a billing node will be sent for each one.
billing_id
A unique numeric identifier for this billing entry.
billing_dateline
The numeric unix timestamp of the time this billing entry was posted.
billing_creator
The full name of the staff user that created this billing entry.
billing_timespent
The amount of work, in minutes that this billing entry represents.
billing_timebilllable
The amount of work, in minutes that was done that is billable to the customer.
billing_notes
The text contents of any notes that accompany this billing entry.

6. LOGOUT

In order to properly close the synchronization session, the client application needs to log out from the server. This is done by opening the following URL:

Logout URL: <path>/mobile/index.php?_ca=logout&username=<user>&password=<pass>&sessionid=<sessionid>

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.
pass
The MD5 checksum of the staff user's plain text password in printed hexadecimal format (e.g. '4FD8E4FD5988E970476E52AD0994EBB0')
sessionid
The sessionid variable sent in the login sequence; used to authenticate.
After successfully opening this URL, the synchronization process is complete.

Back to top