README.confluence

{tip:title=Officially maintained API}This API library is officially maintained by Kayako.{tip}

{table-of-contents}

h2. Getting started

h3. Initializing the client

{code:language=Python}
from kayako import KayakoAPI
API_URL = 'http://example.com/api/index.php'
API_KEY = 'abc3r4f-alskcv3-kvj4'
SECRET_KEY = 'vkl239vLKMNvlik42fv9IsflkFJlkckfjs'
api = KayakoAPI(API_URL, API_KEY, SECRET_KEY)
{code}

h3. Creating a department

{code:language=Python}
from kayako import Department

# The following is equivalent to: department = api.create(Department, title='Customer Support Department', type='public', module='tickets'); department.add()
department = api.create(Department)
department.title = 'Customer Support Department'
department.type = 'public'
department.module = 'tickets'
department.add()
print department.id
{code}
{quote}
84
{quote}
{code:language=Python}
# Cool, we now have a ticket department.
# Lets say we want to make it private now

department.type = 'private'
department.save()

# Ok, great.  Lets delete this test object.

department.delete()
print department.id
{code}
{quote}
??
{quote}
{code:language=Python}
# We can re-add it if we want to...

department.add()
print department.id
{code}
{quote}
85
{quote}
{code:language=Python}
# Lets see all of our Departments (yours will vary.)
for dept in api.get_all(Department):
    print dept
{code}
{quote}
<Department (1): General/tickets>
<Department (2): Suggest A Store/tickets>
<Department (3): Report A Bug/tickets>
<Department (4): Sales/livechat>
<Department (5): Commissions/livechat>
<Department (6): Missing Order/livechat>
<Department (7): Suggest A Feature/tickets>
<Department (8): Other/livechat>
<Department (49): Offers/tickets>
<Department (85): Customer Support Department/tickets>
{quote}
{code:language=Python}
# Lets see all of our ticket Departments

for dept in api.filter(Department, module='tickets'):
   print dept
{code}
{quote}
<Department (1): General/tickets>
<Department (2): Suggest A Store/tickets>
<Department (3): Report A Bug/tickets>
<Department (7): Suggest A Feature/tickets>
<Department (49): Offers/tickets>
<Department (85): Customer Support Department/tickets>
{quote}
{code:language=Python}
# We will use this Department in the next example so lets wait to clean up the test data...
# department.delete()
{code}

h3. Creating a staff user

{code:language=Python}
from kayako import Staff, StaffGroup

# You can set parameters in the create method.

staff = api.create(Staff, firstname='John', lastname='Doe', email='foo@example.com', username='explodes', password='easypass332')

# We need to add a Staff member to a staff group.
# Lets make a new StaffGroup titled "General Staff"

staffgroup = api.create(StaffGroup, title="General Staff", isadmin=False)
staffgroup.add()

# Add the new Staff to the new StaffGroup

staff.staffgroupid = staffgroup.id

# And save the new Staff

staff.add()

# We will use this Staff in the next example so lets wait to clean up the test data...
# staff.delete()
{code}

h3. Creating a user

{code:language=Python}
from kayako import User, UserGroup, FOREVER

# What fields can we add to this User?
print User.__add_parameters__
{code}
{quote}
\['fullname', 'usergroupid', 'password', 'email', 'userorganizationid', 'salutation', 'designation', 'phone', 'isenabled', 'userrole', 'timezone', 'enabledst', 'slaplanid', 'slaplanexpiry', 'userexpiry', 'sendwelcomeemail'\]
{quote}
{code:language=Python}
# Lets make a new User, but not send out a welcome email.
# Lets add the User to the "Registered" user group.
registered = api.first(UserGroup, title='Registered')
user = api.create(User, fullname="Ang Gary", password="easypass332", email="bar@example.com", usergroupid=registered.id, sendwelcomeemail=False, phone='1-800-555-5555', userexpiry=FOREVER)
user.add()

# Its that easy.  We will use this user in the next example so lets wait to clean up the test data...
# user.delete()
{code}

h3. Creating a ticket and adding a ticket note

{code:language=Python}
from kayako import Ticket, TicketAttachment, TicketNote, TicketPost, TicketPriority, TicketStatus, TicketType

# Lets add a "Bug" Ticket to any Ticket Department, with "Open" status and "High" priority for a user. Lets use the user and department from above.

bug = api.first(TicketType, title="Bug")
open = api.first(TicketStatus, title="Open")
high = api.first(TicketPriority, title="High")

ticket = api.create(Ticket, tickettypeid=bug.id, ticketstatusid=open.id, ticketpriorityid=high.id, departmentid=department.id, userid=user.id)
ticket.subject = 'I found a bug and its making me very angry.'
ticket.fullname = 'Ang Gary'
ticket.email = 'bar@example.com'
ticket.contents = 'I am an angry customer you need to make me happy.'
ticket.add()

print ticket
{code}
{quote}
<Ticket (592): VBQ-173-79628 - I found a bug and its making me very angry.>
{quote}
{code:language=Python}
# The ticket was added, lets let the customer know that everything will be fine.

print 'Thanks, %s, your inquiry with reference number %s will be answered shortly.' % (ticket.fullname, ticket.displayid)
{code}
{quote}
Thanks, Ang Gary, your inquiry with reference number VBQ-173-79628 will be answered shortly.'
{quote}
{code:language=Python}
# Lets add a note to this Ticket, using the Staff member we created above.

note = api.create(TicketNote, ticketid=ticket.id, contents='Customer was hostile. Will pursue anyway as this bug is serious.')
note.staffid = staff.id # Alternatively, we could do: staff.fullname = 'John Doe'
note.add()

# Lets say the bug is fixed, we want to let the User know.

post = api.create(TicketPost, ticketid=ticket.id, subject="We fixed it.", contents="We have a patch that will fix the bug.", staffid=staff.id)
post.add()

# Now lets add an attachment to this TicketPost.

binary_data = '\ufffd\uff23\u8f32\u9301' # This data will fix the bug.

attachment = api.create(TicketAttachment, ticketid=ticket.id, ticketpostid=post.id, filename='foo.diff', filetype='application/octet-stream')
attachment.set_contents(binary_data) # set_contents encodes data into base 64. get_contents decodes base64 contents into the original data.
attachment.add()

# This officially closed the ticket.

closed = api.first(TicketStatus, title='Closed')
ticket.ticketstatusid = closed.id
ticket.save()
{code}

h3. Performing a ticket search

{code:language=Python}
# Lets research what happened with to the ticket with reference number VBQ-173-79628 hasn't been answered yet.
# Lets find out what ticket he's talking about.
tickets = api.ticket_search(ticket.displayid, ticketid=True) # ticket.displayid = VBQ-173-79628, it will vary in your test.
for found_ticket in tickets:
    print found_ticket, api.first(TicketStatus, id=ticket.ticketstatusid).title
    for post in found_ticket.posts:
        print post
    for attachment in api.get_all(TicketAttachment, ticket.id):
        print attachment
{code}
{quote}
<Ticket (592): VBQ-173-79628 - I found a bug and its making me very angry.>
<TicketPost (715): I am an angry custom...>
<TicketPost (716): We have a patch that...>
<TicketAttachment (48): foo.diff>

# We can see that the ticket is actually closed.

{quote}
{code:language=Python}

{code}

h3. Clean up after the tutorial

{code:language=Python}
# Lets clean up finally.
ticket.delete() # This deletes the attachment, post, and note.
user.delete()
staff.delete()
staffgroup.delete()
department.delete()
{code}

{code:language=Python}
# Lets clean up finally.
ticket.delete() # This deletes the attachment, post, and note.
user.delete()
staff.delete()
department.delete()
{code}

h2. Supported methods
{tip:title=API Complete}This library supports all of the presently available API methods.{tip}

|| API || _Get all_ || Get (GET) || Create (POST) || Update (POST) || Delete (DELETE) ||
| Department | Yes | Yes | Yes | Yes | Yes |
| Staff | Yes | Yes | Yes | Yes | Yes |
| StaffGroup | Yes | Yes | Yes | Yes | Yes |
| Ticket | departmentid, ticketstatusid=-1, ownerstaffid=-1, userid=-1 | Yes | Yes | Yes | Yes |
| TicketAttachment | ticketid | ticketid, attachmentid | Yes | No | Yes |
| TicketCustomField | ticketid | No | No | No | No |
| TicketCount | Yes | No | No | No | No |
| TicketNote | ticketid | Yes | Yes | No | Yes |
| TicketPost | ticketid | ticketid, postid | Yes | No | Yes |
| TicketPriority | Yes | Yes | No | No | No |
| TicketStatus | Yes | Yes | No | No | No |
| TicketTimeTrack | ticketid | ticketid, timetrackid | Yes | No | Yes |
| TicketType | Yes | Yes | No | No | No |
| User | marker=1, maxitems=1000 | Yes | Yes | Yes | Yes |
| UserGroup | Yes | Yes | Yes | Yes | Yes |
| UserOrganization | Yes | Yes | Yes | Yes | Yes |

h2. Method documentation

h3. Methods

h4. api.create
{code:language=Python}
api.create(Object, *args, **kwargs)
{code}
Create and return a new {{KayakoObject}} of the type given passing in {{args}} and {{kwargs}}.

h4. api.get_all
{code:language=Python}
api.get_all(Object, *args, **kwargs)
{code}
Get all {{KayakoObjects}} of the given type. In most cases, all items are returned.
{code:language=Python}
api.get_all(Department)
[<Department (24): Books/tickets>, <Department (25): Foods/livechat>]
{code}

h5. Special Cases
{code:language=Python}
api.get_all(User, marker=1, maxitems=1000)
{code}
Return all {{Users}} from userid {{marker}} with up to {{maxitems}} results (max 1000).

{code:language=Python}
api.get_all(Ticket, departmentid, ticketstatusid=-1, ownerstaffid=-1, userid=-1)
{code}
Return all {{Tickets}} filtered by the required argument {{departmentid}} and by the optional keyword arguments.

{code:language=Python}
api.get_all(TicketAttachment, ticketid)
{code}
Return all {{TicketAttachments}} for a {{Ticket}} with the given ID.

{code:language=Python}
api.get_all(TicketPost, ticketid)
{code}
Return all {{TicketPosts}} for a {{Ticket}} with the given ID.

{code:language=Python}
api.get_all(TicketCustomField, ticketid)
{code}
Return all {{TicketCustomFieldGroups}} for a {{Ticket}} with the given ID. Returns a {{list}} of {{TicketCustomFieldGroups}}.

{code:language=Python}
api.get_all(TicketCount)
{code}
Returns only one object: {{TicketCount}}, not a {{list}} of objects.

h4. api.filter
{code:language=Python}
api.filter(Object, args=(), kwargs={}, **filter)
{code}
Gets all {{KayakoObjects}} matching a filter.
{code:language=Python}
api.filter(Department, args=(2), module='tickets')
[<Department (24): Books/tickets>]
{code}

h4. api.first
{code:language=Python}
api.first(Object, args=(), kwargs={}, **filter)
{code}
Returns the first {{KayakoObject}} found matching a given filter.
{code:language=Python}
api.filter(Department, args=(2), module='tickets')
<Department module='tickets'>
{code}

h4. api.get
{code:language=Python}
api.get(Object, *args)
{code}
Get a {{KayakoObject}} of the given type by ID.
{code:language=Python}
api.get(User, 112359)
<User (112359)....>
{code}

h5. Special Cases
{code:language=Python}
api.get(TicketAttachment, ticketid, attachmentid)
{code}
Return a {{TicketAttachment}} for a {{Ticket}} with the given {{Ticket}} ID and {{TicketAttachment}} ID. Getting a specific {{TicketAttachment}} gets a {{TicketAttachment}} with the actual attachment contents.

{code:language=Python}
api.get(TicketPost, ticketid, ticketpostid)
{code}
Return a {{TicketPost}} for a ticket with the given {{Ticket}} ID and {{TicketPost}} ID.

{code:language=Python}
api.get(TicketNote, ticketid, ticketnoteid)
{code}
Return a {{TicketNote}} for a ticket with the given {{Ticket}} ID and {{TicketNote}} ID.

h3. Object persistence methods

{code:language=Python}
kayakoobject.add()
{code}
Adds the instance to Kayako.

{code:language=Python}
kayakoobject.save()
{code}
Saves an existing object the instance to Kayako.

{code:language=Python}
kayakoobject.delete()
{code}
Removes the instance from Kayako

h3. Methods that raise exceptions

h4. KayakoRequestError

* The action is not available for that kind of KayakoObject
* A required object parameter is UnsetParameter or None (add/save)
* The API URL cannot be reached

h4. KayakoResponseError

* There is an error with the request (not HTTP 200 Ok)
* The XML is in an unexpected format indicating a possible Kayako version mismatch

h3. Misc API methods

{code:language=Python}
api.ticket_search(query, ticketid=False, contents=False, author=False, email=False, creatoremail=False, fullname=False, notes=False, usergroup=False, userorganization=False, user=False, tags=False)
{code}
Search {{Tickets}} with a query in the specified fields

{code:language=Python}
api.ticket_search_full(query)
{code}
Shorthand for searching all fields with {{api.ticket_search.}}


h2. Changes

h3. 1.1.6
* Added ``api.ticket_search_full`` shorthand function for searching all fields in ``api.ticket_search``

h3. 1.1.5

* Fix {{Staff.\__str__}}
* {{Ticket.\__str__}} includes {{displayid}}
* {{TicketPost.subject}} is not returned in any responses, so it is not always available, removed it from {{TicketPost.\__str__}}

h3. 1.1.4

* Requires Kayako 4.01.240, use 1.1.3 for Kayako 4.01.204
* {{TicketNote}} now supports get and delete
* Added {{api.ticket_search}}, see Misc API Calls for details.
* Refactored ticket module into ticket package. This could cause problems if things were not imported like {{from kayako.objects import X}}
* Added {{TicketCount}} object. Use {{api.get_all(TicketCount)}} to retrieve.
* Added {{TicketTimeTrack}} object. {{api.get_all(TicketTimeTrack, ticket.id)}} or {{api.get(TicketTimeTrack, ticket.id, ticket_time_track_id)}}
* Added {{Ticket.timetracks}}