Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Tagged 'Reply' as a required attribute/node for creating a new ticket

...

Code Block
staffapi/index.php?/Tickets/Push/Index

 

POST arguments

Argument

Value

sessionid

The unique session ID variable dispatched to the client during the login process.

payload

A UTF-8@wikipedia, URL-encoded XML document in the format below

XML Document (payload)

The root node of your XML document must be named 'kayako_staffapi'

...

Code Block
xml
xml
<create staffapiid="...">
    <subject>...</subject>
    <fullname>...</fullname>
    <email>...</email>

    <!-- Begin Ticket Properties -->
    <departmentid>...</departmentid>
    <ticketstatusid>...</ticketstatusid>
    <ticketpriorityid>...</ticketpriorityid>
    <tickettypeid>...</tickettypeid>
    <ownerstaffid>...</ownerstaffid>
    <emailqueueid>...</emailqueueid>

    <!-- Begin Creator Info -->
    <creator>user</creator>
    <userid>0</userid>
    <staffid>0</staffid>

    <!-- Begin Other Info -->
    <type>...</type>
    <phonenumber>...</phonenumber>
    <sendautoresponder>...</sendautoresponder>
    <flagtype>...</flagtype>

    <!-- Tags -->
    <tags>...</tags>
    <tags>...</tags>

    <!-- Recipients -->
    <ccto>...</ccto>
    <bccto>...</bccto>

    <!-- Due Timestamps -->
    <resolutiondue>...</resolutiondue>
    <replydue>...</replydue>

    <reply>
      <contents>...</contents>
      <attachment filename="..." md5="...">
        <!--base-64 encoded file contents -->
      </attachment>
    </reply>

    <watch>...</watch>

    <note type="..." notecolor="...">
      <!-- note contents -->
    </note>

    <billing timeworked="..." timebillable="..." billdate="..." workdate="..." worker="..." notecolor="...">
      <!-- note contents -->
    </billing>

    
  </create>


Node name

Value

Attributes

Required?

create

Contains all information required to create a new ticket in the help desk. The 'staffapiid' attribute should be numerical and is used to identify the newly created ticket records, this value may be repeated in subsequent requests and is considered volatile.

(none)

 

subject

The subject for the new ticket.

(none)

Yes

fullname

The full name of the creator.

(none)

Yes, if userid is omitted

email

The email address of the creator.

(none)

Only when userid is omitted (where type = phone and phonenumber is not blank)

departmentid

The department identifier.

(none)

Yes

ticketstatusid

The ticket status identifier.

(none)

Yes

ticketpriorityid

The ticket priority identifier.

(none)

Yes

tickettypeid

The ticket type identifier.

(none)

Yes

ownerstaffid

The owner of the ticket, this is the unique staff identifier or '0' for unassigned tickets.

(none)

Yes

emailqueueid

The email queue identifier, this value can be used to set the default return email addresses for replies. Send '0' if you do not wish to link this ticket with an email queue.

(none)

Yes

creator

The creator of the ticket, possible values are 'staff' or 'user'.

(none)

Yes

userid

The unique user identifier, if '0' is sent along with creator as 'user' then the system will automatically create or retrieve the user record based on the email address.

(none)

Yes

staffid

The staff identifier if the ticket creator is 'staff'.

(none)

Only if creator = staff

type

The ticket type. Possible values are 'default' (for a regular ticket) and 'phone' (for a phone ticket).

(none)

Yes

phonenumber

The phone number value if the ticket type is 'phone'.

(none)

Only if (type = phone and email = blank)

sendautoresponder

1 if an auto-response confirming the receipt of the ticket should be sent to the client user, 0 otherwise.

(none)

Yes

flagtype

The type of flag to assign to this ticket, or 0 if no flag should be assigned.

(none)

Yes

tags

The tags to link with this ticket, you can send multiple nodes to link a ticket with multiple tags.

(none)

 

ccto

The email address that should be added as carbon-copy recipients for the new ticket. You can send multiple nodes to add multiple recipients to a ticket.

(none)

 

bccto

The email address that should be added as blind carbon-copy recipients for the new ticket. You can send multiple nodes to add multiple recipients to a ticket.

(none)

 

resolutiondue

The Unix timestamp by which the ticket should be resolved completely.

(none)

 

replydue

The Unix timestamp by which a reply from a staff user must be sent.

(none)

 

watch

1 if you wish to watch this ticket, 0 otherwise.

(none)

Yes

note

See

notes

88080890

n/a

 

billing

See

billing

88080890

n/a

 

reply

See

replies

88080890

n/a

 

 Yes

Deleting tickets

To delete a ticket on the server, the following XML node should be added to the root node for each ticket you wish to delete.

Code Block
xml
xml
<delete ticketid="..." />


Node name

Attributes

delete

ticketid: The numeric identifier of the ticket you wish to delete. You must have delete privileges for the department in which the ticket resides.

Anchor
replies
replies

Modifying tickets

...

Code Block
xml
xml
<modify ticketid="...">


Node name

Attributes

modify

ticketid: The numeric identifier of the ticket you wish to modify.

Replying to tickets

To add a reply to a ticket, the following XML should be added to a 'modify' node which specifies a ticket ID. You may add as many replies as you like, and replies can contain multiple file attachments.

...

Code Block
xml
xml
<reply>
    <contents>...</contents>
    <attachment filename="..." md5="...">
      <!-- base-64 encoded file contents -->
    </attachment>
  </reply>


Node name

Value

Attributes

reply

Contains all the data necessary to post a ticket reply

(none)

contents

The textual contents of the ticket reply

(none)

attachment

See attachments

n/a

Anchor
notes
notes

Adding notes to a ticket

...

Code Block
xml
xml
<note type="..." notecolor="...">
    <!-- note contents -->
  </note>


Node name

Value

Attributes

note

The textual contents of the note

type: 'ticket': The note will only be attached to the ticket identified by ticketid.
_'user': The note will be visible on any ticket created by the same client user
_'userorganization': The note will be visible on any ticket created by the same client user organization
notecolor: The numeric identifier of the color used to render the background of this note wherever it is displayed. See note colors

Anchor
billing
billing

Adding billing information to a ticket

...

Code Block
xml
xml
<billing timeworked="..." timebillable="..." billdate="..." workdate="..." worker="..." notecolor="...">
    <!-- note contents -->
  </billing>


Node

Value

Attributes

billing

Textual contents of any note associated with the billing entry

timeworked: The amount of time, in seconds that was spent working on this particular task.
timebillable: The amount of time, in seconds that is actually billable to the client for this particular task.
billdate: The unix time that the client was billed for work performed.
workdate: The unix time that the work for the client began.
worker: The name of the staff user who performed work on this task.
notecolor: The numeric identifier of the color used to render the background of any attached note wherever it is displayed. See note colors

Changing ticket properties

...

Code Block
xml
xml
<departmentid>...</departmentid>
<ticketstatusid>...</ticketstatusid>
<ticketpriorityid>...</ticketpriorityid>
<tickettypeid>...</tickettypeid>
<ownerstaffid>...</ownerstaffid>
<flagtype>...</flagtype>
<replydue>...</replydue>
<resolutiondue>...</resolutiondue>

<!-- Tags -->
<tags>...</tags>
<tags>...</tags>

<!-- Recipients -->
<ccto>...</ccto>
<bccto>...</bccto>

<!-- Due Timestamps -->
<resolutiondue>...</resolutiondue>
<replydue>...</replydue>

<watch>...</watch>



Node

Value

Attributes

departmentid

Numeric identifier of the department to which the ticket should be moved

 

ticketstatusid

Numeric identifier of the new status

 

ticketpriorityid

Numeric identifier of the new priority

 

ownerstaffid

Numeric identifier of the staff user who should take ownership of the ticket

 

flagtype

The type of flag to assign to this ticket, or 0 if no flag should be assigned.

(none)

tags

The tags to link with this ticket, you can send multiple nodes to link a ticket with multiple tags.

(none)

ccto

The email address that should be added as carbon-copy recipients for the new ticket. You can send multiple nodes to add multiple recipients to a ticket.

(none)

bccto

The email address that should be added as blind carbon-copy recipients for the new ticket. You can send multiple nodes to add multiple recipients to a ticket.

(none)

resolutiondue

The Unix timestamp by which the ticket should be resolved completely.

(none)

replydue

The Unix timestamp by which a reply from a staff user must be sent.

(none)

watch

1 if you wish to watch this ticket, 0 otherwise.

(none)

note

See

notes

88080890

n/a

billing

See

billing

88080890

n/a

reply

See

replies

88080890

n/a

Example Modify Request

Code Block
xml
xml
<modify ticketid="...">
    <departmentid>...</departmentid>
    <ticketstatusid>...</ticketstatusid>
    <ticketpriorityid>...</ticketpriorityid>
    <tickettypeid>...</tickettypeid>
    <ownerstaffid>...</ownerstaffid>
    <flagtype>...</flagtype>

    <!-- Tags -->
    <tags>...</tags>
    <tags>...</tags>

    <!-- Recipients -->
    <ccto>...</ccto>
    <bccto>...</bccto>

    <!-- Due Timestamps -->
    <resolutiondue>...</resolutiondue>
    <replydue>...</replydue>

    <watch>...</watch>

    <reply>
      <contents>...</contents>
      <attachment filename="..." md5="...">
        <!--base-64 encoded file contents -->
      </attachment>
    </reply>

    <note type="..." notecolor="...">
      <!-- note contents -->
    </note>

    <billing timeworked="..." timebillable="..." billdate="..." workdate="..." worker="..." notecolor="...">
      <!-- note contents -->
    </billing>

    
  </modify>

...

Code Block
xml
xml
<kayako_staffapi>
  <status>...</status>
  <error>...</error>

  <tickets>
    <ticket staffapiid="..." id="...">
      <displayid>...</displayid>
      <departmentid>...</departmentid>
      <departmenttitle>...</departmenttitle>
      <statusid>...</statusid>
      <statustitle>...</statustitle>
      <priorityid>...</priorityid>
      <prioritytitle>...</prioritytitle>
      <flagtype>...</flagtype>
      <typeid>...</typeid>
      <typetitle>...</typetitle>
      <userid>...</userid>
      <userorganization>...</userorganization>
      <userorganizationid>...</userorganizationid>
      <ownerstaffid>...</ownerstaffid>
      <ownerstaffname>...</ownerstaffname>
      <fullname>...</fullname>
      <email>...</email>
      <lastreplier>...</lastreplier>
      <subject>...</subject>
      <creationtime>...</creationtime>
      <lastactivity>...</lastactivity>
      <laststaffreply>...</laststaffreply>
      <lastuserreply>...</lastuserreply>
      <slaplanid>...</slaplanid>
      <nextreplydue>...</nextreplydue>
      <resolutiondue>...</resolutiondue>
      <replies>...</replies>
      <ipaddress>...</ipaddress>
      <creator>...</creator>
      <creationmode>...</creationmode>
      <creationtype>...</creationtype>
      <isescalated>...</isescalated>
      <escalationruleid>...</escalationruleid>
      <hasattachments>...</hasattachments>
      <hasnotes>...</hasnotes>
      <hasbilling>...</hasbilling>
      <hasfollowup>...</hasfollowup>
      <hasdraft>...</hasdraft>
      <tags>...</tags>
    </ticket>
  </tickets>
</kayako_staffapi>


Node name

Value

kayako_staffapi

(root node)

status

Contains information about whether or not the requested operation(s) completed successful. A value of '1' indicates success, anything else indicates error.

error

If status does not equal '1', this contains a description of the error, e.g., "Access Denied"

tickets

The list of tickets that were created or modified. The staffapiid is the same identifier received from the client applications