DeskPRO Developer Documentation...DeskPRO Developer Documentation, Release 1.0 2.1.4Authenticating with the API (API Tokens) An agent’s username and password can be exchanged via

DeskPRO Developer DocumentationRelease 1.0

DeskPRO

August 01, 2017

CONTENTS

1 Developer Overview 1

2 Using the DeskPRO API 22.1 API Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.2 Managing API keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 API browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.4 Token exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.5 PHP SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.6 API: Tickets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.7 API: Ticket Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.8 API: People . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.9 API: Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412.10 API: Contact Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502.11 API: Chats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532.12 API: Knowledgebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562.13 API: Downloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642.14 API: News . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712.15 API: Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782.16 API: Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792.17 API: Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852.18 API: Auth Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

3 Widgets 923.1 Creating widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923.2 Editing widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943.3 Example: Link to CRM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993.4 Example: Consuming an API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

4 Apps 1064.1 Creating full apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064.2 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084.3 More example apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

i

CHAPTER

ONE

DEVELOPER OVERVIEW

There are several ways you can work with DeskPRO as a developer:

The DeskPRO REST API enables you to retrieve, create and modify helpdesk data from your own code, usingHTTP.

Note: If you want to make an HTTP request from DeskPRO to an external system, you can use DeskPRO triggersto execute web hook actions.

DeskPRO widgets: an easy way to add simple widgets to the agent interface using just Javascript and HTML: usefulif you want to pull data from another system and display it on tickets, for example.

DeskPRO apps: you can develop full apps, like the ones you can install from Admin > Apps. These enable moreelaborate integrations or interface changes. Apps can be packaged in ZIP files, enabling convenient distribution toother DeskPRO helpdesks.

1

https://manuals.deskpro.com/html/admin/integration/using-web-hook-actions.html

CHAPTER

TWO

USING THE DESKPRO API

DeskPRO has a full REST API allowing access to the functions of the helpdesk using HTTP requests.

This means you or your software developers can use any modern coding language to automatically retrieve, create ormodify helpdesk data, such as tickets and user records.

You can use the API to import and export data, automate the helpdesk beyond what’s supported by the built-in au-tomation systems, or integrate with external services.

2.1 API Basics

The API takes HTTP requests and returns JSON output.

This section explains how to interact with the API. To see a full list of the available functions, use the API Browser.

2.1.1 Accessing the API

The API is accessible under the root of your DeskPRO installation by appending /api. For example,http://support.example.com/api. Specific routes to data types are available under this base URL, forexample:

http://support.example.com/api/tickets/status

2.1.2 Authenticating with API keys

Accessing the API requires an API key, which can be set up in the Admin Interface, via Apps > API Keys.

Standard API keys are associated with a particular agent in the system, meaning that all API actions will be carriedout using that agent’s account. This affects permissions and action logging etc.

If you want to be able to carry out actions as more than one agent, you need a superuser API key (see below).

The API key will be listed in the Admin Interface in this format: ###:123456ABCDEF. The ### portion is the IDand 123456ABCDEF portion is the code.

The API key must be provided with every API request. It can be provided in one of the following three ways:

Custom HTTP Header

In the request, you can provide the X-DeskPRO-API-Key header with the value being the API key. The headershould be provided in the exact case listed here.

2

DeskPRO Developer Documentation, Release 1.0

X-DeskPRO-API-Key: 1:123456ABCDEF

Request Parameter

The API key may be provided via the request parameter API-KEY:

http://support.example.com/api/tickets?API-KEY=1:123456ABCDEF

HTTP Basic Authentication

Finally, the API can be accessed through HTTP Basic Authentication where the user name is the ID and the pass-word is the code.

For example, the following would access the API via a browser using basic authentication:

http://1:[email protected]/api/tickets

Please note that if you are attempting to access the API of DeskPRO On-Premise, server limitations may preventHTTP basic authentication from functioning properly. You may wish to use another method.

2.1.3 Using Superuser API Keys

A superuser API key is a special type of API key that is not associated with a particular agent. Instead, it is able tomake requests as any agent.

When you create a superuser API key, you can optionally set a default agent that will be used if no agent is specified.If you don’t set a default agent, each request must identify the agent that it is being made on behalf of.

If the provided agent ID is not valid, or if no default has been set and no agent is specified, an error will be returned.

There are two ways to specify the agent ID:

Custom HTTP Header

The ID of the agent making the request can be provided via the X-DeskPRO-Agent-ID header. The header must be inthe exact case listed here:

X-DeskPRO-Agent-ID: 1234

Request Parameter

Alternatively, the ID of the agent can be supplied in the DP-AGENT-ID parameter:

http://support.example.com/api/tickets?DP-AGENT-ID=1234

2.1. API Basics 3

http://en.wikipedia.org/wiki/Basic_access_authentication


2.1.4 Authenticating with the API (API Tokens)

An agent’s username and password can be exchanged via the API to receive an API token, which can then be used toaccess data and API methods based on the agent’s permissions.

See Token exchange section for details.

2.1.5 HTTP methods

The DeskPRO API uses a subset of the HTTP methods to implement its functionality.

• GET is used to retrieve information. These requests never update data in DeskPRO.

• POST is used to update a partial record or create a new record.

• DELETE is used to remove a record.

Example GET Request

This request will search for tickets that have “test” in the subject:

GET /api/tickets?subject=example HTTP/1.1Host: example.comConnection: closeX-DeskPRO-API-Token: 1:123456ABCDEF

The response will look something like this:

HTTP/1.1 200 OKDate: Thu, 31 Jan 2013 09:39:52 GMTServer: Apache/2.2.22X-Powered-By: PHP/5.3.14Cache-Control: no-cacheConnection: closeTransfer-Encoding: chunkedContent-Type: application/json

{"page":1,"per_page":25,"total":5,"cache_id":4684,"tickets":...

Example POST Request

This request will create a ticket in department 1:

POST /api/tickets HTTP/1.1Host: example.comConnection: closeContent-Type: application/x-www-form-urlencodedContent-Length: 67X-DeskPRO-API-Token: 1:123456ABCDEF

subject=example&message=example+message&person_id=1&department_id=1


2.1. API Basics 4


HTTP/1.1 201 CreatedDate: Thu, 31 Jan 2013 09:39:52 GMTServer: Apache/2.2.22 (Win32)X-Powered-By: PHP/5.3.14Cache-Control: no-cacheLocation: http://example.com/api/tickets/1234Connection: closeContent-Type: application/json

{"ticket_id":1234}

Example DELETE Request

This request will delete the ticket with ID 1234:

DELETE /api/tickets/218269 HTTP/1.1Host: example.comConnection: closeContent-Type: application/x-www-form-urlencodedX-DeskPRO-API-Token: 1:123456ABCDEF


HTTP/1.1 200 OKDate: Thu, 31 Jan 2013 09:39:52 GMTServer: Apache/2.2.22 (Win32)X-Powered-By: PHP/5.3.14Cache-Control: no-cacheConnection: closeContent-Type: application/json

{"success":true}

2.1.6 API Errors

If the API returns an error, it is indicated in both the response code and the JSON output.

If the response code is 4xx or 5xx, then an error has occurred. The body may provide more information beyond themeaning of the status code.

If the JSON includes an error_code element, then an error has occurred. If error_code is “multiple”, then alist of errors may be found in the errors element. Each entry in errors represents an error, with the first valuebeing the specific code and the second being a human-readable message. If the error_code is anything other than“multiple”, then error_message contains the human-readable error message.

403 errors when trying to use an API function

NotFound response for existing items on a new ticket

2.1.7 Uploading Files

Certain parameters of the API can accept uploaded files. These are documented with a type file on the specificAPI endpoint page.

2.1. API Basics 5

https://support.deskpro.com/kb/articles/506

https://support.deskpro.com/kb/articles/420


Files are uploaded by using the same method that the browsers themselves use to upload files: an encoding ofmultipart/form-data.

We recommend that you use a helper library to build your request such as our PHP API wrapper or Zend Frame-work’s HTTP client.

2.2 Managing API keys

For external code to access the DeskPRO API, it will need to use a DeskPRO API key.

Bear in mind that anyone with access to one of your API keys can change data in your helpdesk, so you should bevery careful about sharing or publishing them.

When you create an API key, you must select what privilege level it has:

• Superuser Key: can act as any agent, as specified in the API request - optionally, you can choose a defaultagent that will be used if no agent is specified. If you don’t set a default agent, you will have to specify theagent to use for each request. You can also choose to give a superuser key access to use admin functions: thisincludes the use of GET /api/api_keys

• Normal Key: API requests are treated as if they were performed by a specific agent.

Unless your code is designed to act on behalf of human agents, you may want to create a dedicated agent account touse for API calls, to make it more obvious what is being carried out automatically.

2.2.1 Admin endpoints

When you generate a superuser key, you can optionally select the Enable administration API endpoints option.

This means the key can be used for operations that an administrator would need to carry out, like adding or deletingagents.

If you are getting a 403 response when you try to use a function with a normal API key, or a superuser key withoutadmin endpoints enabled, then the solution is to use a superuser key with the administration option selected.

Warning: Be very careful with API keys with this option enabled! Anyone with such an API key essentially hascomplete admin access to the helpdesk.

2.2. Managing API keys 6

http://tools.ietf.org/html/rfc2388

https://github.com/DeskPRO/deskpro-api-php


2.2.2 Generating an API key

To generate a key:

1. Go to Apps > API Keys.

2. Click + New API Key.

3. Enter a brief Description which explains what the key will be used for.

4. Set if you want the API Key to be a Superuser Key or a Specific Agent key.

5. Click Save. Click on the key in the list at the left to view the API key

You should make a separate key for each external service/app that will be accessing your helpdesk through the API.

An API key is in the format: ###:123456ABCDEF.

The ### portion is the key’s ID, and the 123456ABCDEF portion is the code.

Note that you can test which API key has been used in the criteria for a trigger or other automated action.

To help with app development and monitoring API usage, you can see a log of the last 50 API requests in the APIKey Logs tab.

If you think a key has become known to somebody you don’t trust, you can Delete or Regenerate it. Regenerating akey means its description is kept, but the key code is changed and the old one will no longer work.

2.2. Managing API keys 7


2.3 API browser

You can explore the DeskPRO API and try out the available operations using your API browser. This gives you aconvenient web interface to quickly learn how the API works and test the different calls.

Go to yourhelpdesk/api/api.html to see your API browser.

2.3. API browser 8


2.3.1 Entering an API key

To be able to execute API operations, you need to enter an API key for your helpdesk into the browser.

If you’re just exploring what the API can do, we suggest creating a new key for the API browser so it’s easy to trackany changes you make via the browser.

If you’re trying to troubleshoot existing code, you should use the same key so that you can be sure you’re reproduc-ing the problem.

To generate and enter a new key:

2.3. API browser 9


1. Go to Admin > Apps > API Keys.

2. Click New API Key.

3. Enter a Description (e.g. “API Browser”).

4. Select Normal API Key.

5. Set the agent that this key will act as.

6. Paste the API key in the input field at the top right of the API browser, and press Enter.

Note: You can enter a Superuser key, but any operations will always be carried out as the default agent for that key.If there is no default agent, no operations will work.

2.3.2 Exploring the API

Click Show/Hide on the section you’re interested in to expand the list of operations.

You can see which kind of HTTP request each operation uses.

Click on the operation’s name to see the list of parameters it takes, and HTTP status codes it can return.

To carry out an operation, just enter some parameters and click the Try it out! button.

Warning: Remember, POST and DELETE operations can change the data in your helpdesk. Be careful!

When you carry out an operation, the browser will show you:

• the Request URL that your query is sent to

• the Response Body (JSON encoded) that is returned

• the HTTP Response Code

2.3. API browser 10


• the Response Headers

Note that requests from the API browser will be subject to the same permissions as the agent that the API key acts as- if the agent doesn’t have permission to do a certain operation, you can’t do it via the API browser.

There are some DeskPRO API functions which are not yet available through the API browser:

• Get an API token from an agent’s login details as documented here.

• Check user/agent login credentials.

2.3. API browser 11


2.4 Token exchange

An agent’s username and password can be exchanged via the API to receive an API token, which can then be usedto access data and API methods using the agent’s permissions. The API token can be retrieved by using the /token-exchange end point.

2.4.1 POST /token-exchange - Exchange a valid login for an API token

Input• email - Email address• password - Password

Output • success: true• api_token: string. Token that can be used

with other API calls.

Using the API token

There are two ways to use the resulting API token to authenticate a request:

Custom HTTP Header

In the request, you can provide the X-DeskPRO-API-Token header with the value being the API token. The headershould be provided in the exact case listed here.

X-DeskPRO-API-Token: 1:123456ABCDEF

Request Parameter

The API token may be provided via the request parameter API-TOKEN:

http://example.com/deskpro/api/tickets?API-TOKEN=1:123456ABCDEF

2.5 PHP SDK

The DeskPRO PHP SDK is a simple class to access and interact with the DeskPRO API. It wraps the actual requestsup in an easy-to-use API of simple PHP calls.

The SDK requires PHP 5.2 or later, with the cURL extension.

Go to https://github.com/DeskPRO/deskpro-api-php to get the SDK, including simple examples of how to use eachAPI call.

There are also two larger example projects available on GitHub:

• Ticket form - this demonstrates how you can create a custom HTML form to submit tickets to the helpdesk.

• Download tickets as PDF - demonstrates how to download all tickets from a helpdesk and convert them toPDF format.

2.4. Token exchange 12

https://github.com/DeskPRO/deskpro-api-php

https://github.com/DeskPRO/api-app-ticket-form

https://github.com/DeskPRO/api-app-ticket-pdfs


2.5.1 Setting agent with a superuser key

If you are using a superuser API key with the SDK, you must specify which agent credentials to use when you createthe instance of the API class:

$agent_id = 3; //id of agent to use$api = new \DeskPRO\Api('http://example.com/deskpro', '123:XYZ', $agent_id);

2.6 API: Tickets

All API URLs listed here must be prefixed by the root API URL for your helpdesk, e.g.http://support.example.com/api.

The parameters for each function should be appended as query strings; for example:

http://support.example.com/api/tickets?agent_id[]=4

2.6.1 GET /tickets - Search for tickets matching criteria

Input

Constraints

All constraints are optional. Multiple constraints are AND’d together; multiple values for a single constraint areOR’d.

• agent_id[] - integer. Requires ticket to be assigned to the specified agent ID.

• agent_team_id[] - integer. Requires ticket to be assigned to an agent in the specified team.

• category_id[] - integer. Requires ticket to be in the specified category ID.

• department_id[] - integer. Requires ticket to be in the specified department ID.

• field[#][] - string. Requires ticket custom field to have the specified value.

• label[] - string. Requires ticket to be have the specified label.

• language_id[] - integer. Requires ticket to be in the specified language ID.

• organization_id[] - integer. Requires ticket to be for the specified organization ID.

• participant[] - integer. Requires ticket to be followed by or copied to the specified person ID.

• person_id[] - integer. Requires ticket to be created by the specified person ID.

• priority_id[] - integer. Requires ticket to be have the specified priority ID.

• product_id[] - integer. Requires ticket to be for the specified product ID.

• query - string. Requires ticket to contain the specified text within it.

• status[] - string. Requires ticket to be in the specified status. Possible values are awaiting_user, await-ing_agent, closed (=archived), hidden, resolved.

• sla_completed - boolean (0/1). If specified, requires the ticket to have the SLA requirement completed (1)or incomplete (0).

• sla_id[] - integer. Requires ticket to be have the specified SLA.

2.6. API: Tickets 13


• sla_status[] - string. Requires ticket to be have the specified SLA status. Possible values: ok, warning,fail.

• subject[] - string. Requires ticket subject to match the string provided.

• urgency[] - integer. Requires ticket to be have the specified urgency (1-10).

• workflow_id[] - integer. Requires ticket to be have the specified workflow ID.

• id_min specify min ticket ID

• id_max specify max ticket ID

• ref - string. Specify a ref or the beginning characters of a ref (since build 315)

Dates

• date_created - DateSearch. Constrains results based on the date the ticket was created.

• date_resolved - DateSearch. Constrains results based on the date the ticket was first resolved. Unresolvedtickets are not included.

• date_archived - DateSearch. Constrains results based on the date the ticket was first archived. Unar-chived tickets are not included.

• date_status - DateSearch. Constrains results based on the date of the last status change.

• date_last_agent_reply - DateSearch. Constrains results based on the date of the last agent reply. Tick-ets without an agent reply are not included.

• date_last_user_reply - DateSearch. Constrains results based on the date of the last user reply.

• date_last_reply - DateSearch. Constrains results based on the date of the last reply (either a user oragent reply, whichever was latest).

‘DateSearch’ is a search parameter you can express in three ways:

• Greater than: =>2013-08-23

• Less than: =<2013-08-23

• Between: 2013-08-20/2013-08-23

• Equal to: =2013-08-23

DeskPRO will accept four types of date formats:

• A unix timestamp: 1377242918

• A ISO 8601 date string: 2013-08-23T12:00:00+0000

• A string of Y-m-d (UTC): 2013-08-23

• A string of Y-m-d H:i:s (UTC): 2013-08-23 08:30:00

Other

• order - string. Order of the results. Defaults to accessing person’s preference orticket.date_created:desc.

• cache_id - integer. If provided, cached results from this result set are used. If it cannot be found or used, theother constraints provided will be used to create a new result set.

• page - integer. The page number of the results to fetch.



Output

• page - page number requested

• per_page - number of results per page

• total - total number of results that match this criteria

• cache_id - the ID of the cache set to use to retrieve cached results

• tickets - list of tickets that matched the criteria on the requested page

2.6.2 POST /tickets - Create a new ticket

Input

• person_id - integer. ID of person to create ticket for.

• person_email - string. If no person_id is given, the ticket is created for a person with this email. If no per-son is found with this email, one is created.

• person_name - string. If a person is being created, use this as their name.

• person_organization - string. If a person is being created, user this as their organization. If no organi-zation is found with this name, one is created.

• person_organization_position - string. If a person is being created and they belong to an organiza-tion, select this as their position.

• subject - string. Subject of the ticket. Required.

• message - string. First message of the ticket. Required.

• message_as_agent - boolean (0/1). If true, the message is considered to be written by the API agentrather than the ticket owner. Defaults to false.

• message_is_html - boolean (0/1). If true, the message parameter is treated as HTML.

• agent_id - integer. Agent assigned to the ticket. Defaults to unassigned.

• agent_team_id - integer. Agent team the ticket belongs to.

• attach[] - file. If you wish to upload a file with the ticket, you may send the request as multipart/form-datawith the file data going to this parameter.

• attach_id[] - integer. The ID of an already uploaded file to include with the ticket.

• category_id - integer. Category the ticket is in.

• department_id - integer. Department the ticket is in. If not specified, uses the default ticket department.

• field[#] - mixed. Value for the specified field.

• label[] - string. Label to apply to the ticket.

• language_id - integer. Language the ticket is in.

• priority_id - integer. Priority of the ticket.

• product_id - integer. Product the ticket relates to.

• status - string. Status the ticket is in. Possible values are awaiting_user, awaiting_agent, closed, hidden,resolved. Defaults to awaiting_agent

• sla_id[] - integer. Adds the SLA to the ticket. Can only add SLAs that agents may manually add.



• urgency - integer. Urgency of the ticket (1-10).

• workflow_id - integer. Workflow for the ticket.

Output

Outputs a 201 Created status with a Location header that points to the created resource. Also returns JSON outputwith a ticket_id value with the ID of the newly created ticket.

2.6.3 GET /tickets/<ticket_id> - Gets information about a ticket

Input

None.

Output

Gets information about the given ticket under the ticket key.

2.6.4 POST /tickets/<ticket_id> - Updates a ticket

Input

If input is omitted, the value is not updated.

• agent_id - integer. Agent assigned to the ticket. 0 may be used to unassign the ticket.

• agent_team_id - integer. Agent team the ticket belongs to.

• category_id - integer. Category the ticket is in.

• department_id - integer. Department the ticket is in. If not specified, uses the default ticket department.

• field[#] - mixed. Value for the specified field.

• flag - string. Sets the color of the flag for the this ticket for the API user. Use none to remove the flag.

• is_hold - boolean (0/1). Sets the hold status of the ticket.

• is_locked - boolean (0/1). Sets the locked status of the ticket.

• language_id - integer. Language the ticket is in.

• person_id - integer. Changes the ticket owner to this person.

• priority_id - integer. Priority of the ticket.

• product_id - integer. Product the ticket relates to.

• status - string. Status the ticket is in. Possible values are awaiting_user, awaiting_agent, closed, hidden,resolved. Defaults to awaiting_agent

• subject - string. A new subject for the ticket.

• urgency - integer. Urgency of the ticket (1-10).

• workflow_id - integer. Workflow for the ticket.



Output

A success key.

2.6.5 DELETE /tickets/<ticket_id> - Deletes a ticket

Input

ban - boolean. If true, bans the email of the person that created the ticket. Defaults to false.

Output

A success key.

2.6.6 POST /tickets/<ticket_id>/undelete - Undeletes a ticket

Input

None.

Output

A success key.

2.6.7 POST /tickets/<ticket_id>/spam - Marks a ticket as spam

Input

ban - boolean. If true, bans the email of the person that created the ticket. Defaults to false.

Output

A success key.

2.6.8 POST /tickets/<ticket_id>/unspam - Removes spam indicator from a ticket

Input

None.

Output

A success key.



2.6.9 POST /tickets/<ticket_id>/claim - Assigns a ticket to the API user

Input

None.

Output

A success key.

2.6.10 POST /tickets/<ticket_id>/lock - Locks a ticket

Input

None.

Output

A success key.

2.6.11 POST /tickets/<ticket_id>/unlock - Unlocks a ticket

Input

None.

Output

A success key.

2.6.12 POST /tickets/<ticket_id>/merge/<merge_ticket_id> - Merges the two tickets

The two tickets are merged into ticket_id. Ticket merge_ticket_id will be removed.

Input

None.

Output

A success key.



2.6.13 POST /tickets/<ticket_id>/split - Splits messages from a ticket into a newone

Input

• message_ids[] - integer. ID of a message to split. Specify this parameter multiple times to split multiplemessages.

• subject - string. Subject of the new ticket.

Output

success, ticket_id and old_ticket_deleted keys.

2.6.14 GET /tickets/<ticket_id>/log - Gets all logs in a ticket

Input

None.

Output

Gets a list of logs under the logs and tracker_logs keys.

2.6.15 GET /tickets/<ticket_id>/messages - Gets all messages in a ticket

Input

None.

Output

Gets a list of messages under the messages key.

2.6.16 POST /tickets/<ticket_id>/messages - Replies to a ticket

Input

• message - string. Message reply text.

• attach[] - file. If you wish to upload a file with the ticket, you may send the request as multipart/form-datawith the file data going to this parameter.

• attach_id[] - integer. The ID of an already uploaded file to include with the ticket.

• is_note - boolean (0/1). If true, sets the reply as a note, rather than a public reply. Defaults to false.

• message_as_agent - boolean (0/1). If true, the message is considered to be written by the API agentrather than the ticket owner. Defaults to false.

• message_is_html - boolean (0/1). If true, the message parameter is treated as HTML.



• suppress_user_notify - boolean (0/1). If true, suppresses user notification of the reply. Defaults tofalse.

Output

If the message is detected as a duplicate:

• dupe_message - true.

• messsage_id - integer. ID of the message that was determined to be the original.

Otherwise, outputs a 201 Created status with a Location header that points to the created resource. Also returnsJSON output with a message_id value with the ID of the newly created message.

2.6.17 GET /tickets/<ticket_id>/messages/<message_id> - Gets the specific mes-sage

Input

None.

Output

Information about the message inside the message key.

2.6.18 GET /tickets/<ticket_id>/messages/<message_id>/details - Gets a specificmessage’s details

Input

None.

Output

Information about the details inside the unformatted, email_source, and email_log keys.

2.6.19 GET /tickets/<ticket_id>/tasks - Gets the tasks for a ticket

Input

None.

Output

Information about the tasks inside the tasks key.



2.6.20 POST /tickets/<ticket_id>/tasks - Create a task for a ticket

Input

• title - string. Title of the task being added.

Output

Outputs a 201 Created status with a Location header that points to the created resource. Also returns JSON outputwith a id value with the ID of the task that was added.

2.6.21 GET /tickets/<ticket_id>/billing-charges - Gets the billing charges for aticket

Input

None.

Output

• total_charge_time - integer. Length of time charged, in seconds.

• total_charge_amount - integer. Amount charged, in admin-specified currency.

• total - integer. Total number of charge records.

• charges - array. List of charges for the ticket.

2.6.22 POST /tickets/<ticket_id>/billing-charges - Adds a billing charge for a ticket

Input

• time - integer. Time in seconds to bill. Required if there is no amount.

• amount - float. Amount (in admin-specified currency) to bill. Required if there is no time.

• comment - string. Comment or reason for the charge.

Output

Outputs a 201 Created status with a Location header that points to the created resource. Also returns JSON outputwith a id value with the ID of the charge that was added.

2.6.23 GET /tickets/<ticket_id>/billing-charge/<charge_id> - Determines if a chargeexists for a ticket

Input

None.



Output

An exists key with a true or false value.

2.6.24 DELETE /tickets/<ticket_id>/billing-charge/<charge_id> - Deletes a chargefor a ticket

Input

None.

Output

A success key.

2.6.25 GET /tickets/<ticket_id>/slas - Gets the SLAs for a ticket

Input

None.

Output

A list of ticket SLAs inside the ticket_slas key.

2.6.26 POST /tickets/<ticket_id>/slas - Adds an SLA to a ticket

Input

• sla_id - integer. ID of the SLA to add. Must allow manual management by agents.

Output

Outputs a 201 Created status with a Location header that points to the created resource. Also returns JSON outputwith a id value with the ID of the ticket SLA that was added.

2.6.27 GET /tickets/<ticket_id>/slas/<ticket_sla_id> - Determines if a ticket SLAexists for a ticket

Input

None.

Output




2.6.28 DELETE /tickets/<ticket_id>/slas/<ticket_sla_id> - Deletes a ticket SLA for aticket

Input

None.

Output

A success key.

2.6.29 GET /tickets/<ticket_id>/participants - Gets the participants in a ticket

Participants are people who are CCed or following the ticket, not the ticket creator or primary assigned agent.

Input

None.

Output

A list of participant people inside the participants key.

2.6.30 POST /tickets/<ticket_id>/participants - Adds a participant to a ticket

Input

• person_id - integer. ID of the person to add to the ticket.

• email - string. Email address of the person to add to the ticket. If no person can be found with this email, onewill be created.

Output

Outputs a 201 Created status with a Location header that points to the created resource. Also returns JSON outputwith a person_id value with the ID of the person that was added.

2.6.31 GET /tickets/<ticket_id>/participants/<person_id> - Determines if a personis participating in a ticket

Input

None.

Output




2.6.32 DELETE /tickets/<ticket_id>/participants/<person_id> - Removes a partici-pant from a ticket

Input

None.

Output

A success key.

2.6.33 GET /tickets/<ticket_id>/labels - Gets the labels for a ticket

Input

None.

Output

A list of labels inside the labels key.

2.6.34 POST /tickets/<ticket_id>/labels - Adds a label to a ticket

Input

label - string. Label to add.

Output

Outputs a 201 Created status with a Location header that points to the created resource. Also returns JSON outputwith a label value with the label that was added.

2.6.35 GET /tickets/<ticket_id>/labels/<label> - Determines if the ticket has thelabel

Input

None.

Output




2.6.36 DELETE /tickets/<ticket_id>/labels/<label> - Removes a label from a ticket

Input

None.

Output

A success key.

2.6.37 GET /tickets/fields - Gets available custom ticket fields

Warning: This function has been replaced by GET /ticket_fields.

2.6.38 GET /tickets/departments - Gets available ticket departments

Input

None.

Output —— List of departments in the departments key.

2.6.39 GET /tickets/products - Gets available ticket products

Input

None.

Output —— List of products in the products key.

2.6.40 GET /tickets/categories - Gets available ticket categories

Input

None.

Output

List of categories in the categories key.

2.6.41 GET /tickets/priorities - Gets available ticket priorities

Input

None.



Output

List of priorities in the priorities key.

2.6.42 GET /tickets/workflows - Gets available ticket workflows

Input

None.

Output

List of workflows in the workflows key.

2.6.43 GET /tickets/slas - Gets available SLAs

Input

None.

Output

List of SLAs in the slas key.

2.6.44 GET /tickets/slas/<sla_id> - Gets an SLA

Input

None.

Output

SLA information in the sla key.

2.6.45 GET /tickets/slas/<sla_id>/people - Gets list of people that automaticallyapply this SLA

Input

None.

Output

List of people that automatically receive this SLA in the people key.



2.6.46 GET /tickets/slas/<sla_id>/organizations - Gets list of organizations thatautomatically apply this SLA

Input

None.

Output

List of people that automatically receive this SLA in the organizations key.

2.6.47 GET /tickets/filters - Gets available ticket filters

Input

None.

Output

List of filters in the filters key.

2.6.48 GET /tickets/filters/<filter_id> - Executes the ticket filter

Input

page integer. Page number of the results to fetch. Defaults to 1.

Output

• page - page number requested

• per_page - number of results per page

• total - total number of results that match this criteria

• tickets - list of tickets matching tickets

2.7 API: Ticket Fields

All API URLs listed here must be prefixed by the root API URL for your helpdesk, e.g.http://support.example.com/api.

The parameters for each function should be appended as query strings; for example:

http://support.example.com/api/tickets?agent_id[]=4

Ticket field operations require the use of a superuser key with administration endpoints enabled.

Note: Full documentation to come.

2.7. API: Ticket Fields 27


2.7.1 GET /ticket_fields - Search for custom ticket fields

2.7.2 PUT /ticket_fields

2.7.3 POST /ticket_fields/set-enabled/{field_id}/{is_enabled}

2.7.4 GET /ticket_fields/{id}

2.7.5 POST /ticket_fields/{id}

2.7.6 DELETE /ticket_fields/{id}

2.8 API: People

All API URLs listed here must be prefixed by the root API URL, such ashttp://example.com/deskpro/api.

2.8. API: People 28


2.8. API: People 29


2.8.1 GET /people - Search for people matching criteria

Input Constraints

All constraints are optional.Multiple constraints are AND’dtogether; multiple values for asingle constraint are OR’d.

• address[] - string. Requires a person’s ad-dress to contain this value.

• agent_team_id[] - integer. Requires a per-son to be a member of this agent team.

• alpha[] - string. Requires a person’s last nameto start with this letter.

• date_created_end - integer. Requires aperson’s account to have been created before thisdate. Must be specified as a Unix timestamp.

• date_created_start - integer. Requires aperson’s account to have been created after thisdate. Must be specified as a Unix timestamp.

• email[] - string. Requires a person to have anemail that contains this value.

• email_domain[] - string. Requires a personto have an email with a domain that contains thisvalue.

• field[#][] - string. Requires person customfield to have the specified value in the listed field.

• im[] - string. Requires a person to have an in-stant messenger contact that contains this value.

• is_agent - boolean (0/1). True to search onagents instead of users.

• is_agent_confirmed - boolean (0/1). Re-quires the person to be confirmed by an agent ornot.

• label[] - string. Requires person to be havethe specified label.

• name[] - string. Requires a person to have aname that contains this value.

• language_id[] - integer. Requires person tohave chosen this language.

• organization_id[] - integer. Requiresperson to be a member of this organization.

• phone[] - integer. Requires person to have aphone number that contains this value.

• usergroup_id[] - integer. Requires personto be a member of this usergroup.

Other• order - string. Order of the results. De-

faults to accessing person’s preference orpeople.id:asc.

• cache_id - integer. If provided, cached resultsfrom this result set are used. If it cannot be foundor used, the other constraints provided will beused to create a new result set.

• page - integer. The page number of the resultsto fetch.

Output• page - page number requested• per_page - number of results per page• total - total number of results that match this

criteria• cache_id - the ID of the cache set to use to

retrieve cached results• people - list of people that matched the criteria

on the requested page

2.8. API: People 30


2.8.2 POST /people - Create a new person

Input• name - string. Name of the person.• password - string. Set the password for the

person so they can log in. (As of #309)• email - string. Primary email of the person.

This cannot already exist.• contact_data[#] - array. Components of a

contact detail to add.• disable_autoresponses - boolean (0/1).

If true, disables sending this person automaticnotifications when actions are applied to theirtickets.

• field[#] - mixed. Value for the specified cus-tom person field.

• group_id[] - integer. ID of a usergroup toadd this person to.

• label[] - string. Label to apply to the ticket.• is_disabled - boolean (0/1). If true, sets this

person to be disabled (can’t login or interact withtickets/chat).

• organization - string. Name of the organi-zation this person should belong to. If this doesnot exist, one will be created.

• organization_id - integer. ID of the orga-nization this person should belong to.

• organization_position - string. If theperson belongs to an organization, their positionwithin it.

• summary - string. Summary of the person’sdetails.

• timezone - string. Olson time zone stringidentifier.

• send_email - string. boolean (0/1). Send theuser a welcome email (false by default). (As of#309)

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdperson.

2.8.3 GET /people/<person_id> - Gets information about a person

Input None.Output Gets information about the given person under the person key.

2.8.4 GET /people/<person_id>/phone_numbers - Gets person’s phone numbers

Input person_idOutput JSON output

2.8. API: People 31


Example output:

[{"id": 1,"number": "+12015555555","ext": null,"label": null,"region": "US","guessed_type": 2,"date_created": "2016-01-18 13:39:19","date_created_ts": 1453124359,"date_created_ts_ms": 1453124359000

}]

2.8.5 GET /people/{person_id}/phone_numbers/{number_id} - Get specific phoneno.

Input• person_id• number_id

Output JSON

2.8.6 POST /people/{person_id}/phone_numbers - Add phone number to person

Input• person_id• phone_number In E.164 string format, e.g.

+19021111111• label (optional)

Output A success key.

2.8.7 POST /people/{person_id}/phone_numbers/{number_id} - Update phonenumber

Input• person_id• number_id• label

Output JSON

2.8. API: People 32


2.8.8 DELETE /people/{person_id}/phone_numbers/{number_id} - Delete phonenumber

Input• person_id• number_id


2.8.9 POST /people/<person_id> - Updates a person

Input If input is omitted, the value is not updated.• disable_autoresponses - boolean (0/1).

If true, disables sending this person automaticnotifications when actions are applied to theirtickets.

• field[#] - mixed. Value for the specified cus-tom person field.

• is_disabled - boolean (0/1). If true, sets thisperson to be disabled (can’t login or interact withtickets/chat).

• name - string. Name of the person.• organization - string. Name of the organi-

zation this person should belong to. If this doesnot exist, one will be created.

• organization_id - integer. ID of the orga-nization this person should belong to.

• organization_position - string. If theperson belongs to an organization, their positionwithin it.

• primary_email - string. Primary email of theperson. This cannot already exist.

• summary - string. Summary of the person’sdetails.

• timezone - string. Olson time zone stringidentifier.


2.8.10 DELETE /people/<person_id> - Deletes a person

Input None.Output A success key.

2.8. API: People 33


2.8.11 POST /people/<person_id>/reset-password - Resets a person’s password

Input• password - string. New password to set for

this person.• send_email - boolean (0/1). If specified, con-

trols whether the person will be emailed. De-faults to true.


2.8.12 POST /people/<person_id>/clear-session - Resets a person’s password

Clears all sessions for the user, forcing them to log in again. (Only available in DeskPRO #293 and later.)

2.8.13 GET /people/<person_id>/slas - Gets a list of automatically applied SLAsfor a person

Input None.Output Gets a list of SLAs under the slas key.

2.8.14 POST /people/<person_id>/slas - Adds an SLA to the automatically appliedSLAs for a person

Input• sla_id - integer. ID of SLA to add.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the SLA added.

2.8.15 GET /people/<person_id>/slas/<sla_id> - Determines if an SLA exists for aperson

Input None.Output An exists key with a true or false value.

2.8.16 DELETE /people/<person_id>/slas/<sla_id> - Removes an SLA from a per-son


2.8. API: People 34


2.8.17 GET /people/<person_id>/picture - Gets a link to a person’s picture

Input• size - integer. The maximum size (in pixels)

that the picture should be. Defaults to 80.

Output• has_picture - boolean• picture_url - string. URL to get the per-

son’s picture (may come from Gravatar).• size - integer. Maximum size (in pixels) of the

picture

2.8.18 POST /people/<person_id>/picture - Updates a person’s picture

Input• file - file. An uploaded image. Required if no

blob_id is provided.• blob_id - integer. ID of a blob record that

holds the picture already. Required if no file isprovided.


2.8.19 DELETE /people/<person_id>/picture - Deletes a person’s picture


2.8.20 GET /people/<person_id>/emails - Gets email records for a person

Input None.Output Gets a list of emails under the emails key.

2.8.21 POST /people/<person_id>/emails - Adds an email for a person

Input• email - string. Email address to add to this per-

son. May not be associated with another person.• comment - string. A comment or label for the

email.• set_primary - boolean (0/1). If non-0, this

email is set as the person’s primary email ad-dress.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdemail record.

2.8. API: People 35


2.8.22 GET /people/<person_id>/emails/<email_id> - Gets information about anemail ID for a person

Input None.Output Gets a list of email information under the email key.

2.8.23 POST /people/<person_id>/emails/<email_id> - Updates an email record fora person

Input• comment - string. A comment or label for the

email.• set_primary - boolean (0/1). If non-0, this

email is set as the person’s primary email ad-dress.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdemail record.

2.8.24 DELETE /people/<person_id>/emails/<email_id> - Deletes an email recordfor a person


2.8.25 GET /people/<person_id>/vcard - Gets the vCard for a person

Input NoneOutput The vCard data for this person. This does not return JSON.

2.8. API: People 36


2.8.26 GET /people/<person_id>/tickets - Gets tickets by a person

Input• order - string. Order of the results. De-

faults to accessing person’s preference orpeople.id:asc.





retrieve cached results• tickets - list of tickets that matched the crite-

ria on the requested page

2.8.27 GET /people/<person_id>/chats - Gets chats by a person

Input• cache_id - integer. If provided, cached results

from this result set are used. If it cannot be foundor used, the other constraints provided will beused to create a new result set.




retrieve cached results• chats - list of chats that matched the criteria on

the requested page

2.8. API: People 37


2.8.28 GET /people/<person_id>/activity-stream - Gets activity stream for a person

Input• page - integer. The page number of the results

to fetch.


criteria• activity - list of activity for this organization


2.8.29 GET /people/<person_id>/notes - Gets notes for a person

Input None.Output Gets a list of notes under the notes key.

2.8.30 POST /people/<person_id>/notes - Creates a note for a person

Input• note - string. Text of the note to create.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly creatednote.

2.8.31 GET /people/<person_id>/billing-charges - Gets billing charges for a per-son

Input• page - integer. Page number to retrieve.

Output• total_charge_time - integer. Length of

time charged, in seconds.• total_charge_amount - integer. Amount

charged, in admin-specified currency.• total - integer. Total number of charge

records.• per_page - integer. Number of records per

page.• page - integer. Current page number.• charges - array. List of charges on the current

page.

2.8. API: People 38


2.8.32 GET /people/<person_id>/contact-details - Gets contact details for a person

Input None.Output Gets a list of contacts under the details key.

2.8.33 POST /people/<person_id>/contact-details - Creates a contact detail for aperson

Input• type - string. Type of contact detail to add.• comment - string. Comment or label for the

contact detail.• data - array. Contact detail-specific data.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdcontact detail.

See the API: Contact Data article for more information.

2.8.34 GET /people/<person_id>/contact-details/<contact_id> - Determines if con-tact ID exists for person


2.8.35 DELETE /people/<person_id>/contact-details/<contact_id> - Deletes a con-tact for a person


2.8.36 GET /people/<person_id>/groups - Gets the groups for a person

Input None.Output Gets a list of contacts under the groups key.

2.8.37 POST /people/<person_id>/groups - Adds a person to a group

Input• id - integer. ID of the group to add this person

to.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the group thatwas added.

2.8. API: People 39


2.8.38 GET /people/<person_id>/groups/<group_id> - Determines if a person is amember of a group


2.8.39 DELETE /people/<person_id>/groups/<group_id> - Removes a person froma group


2.8.40 GET /people/<person_id>/labels - Gets the labels for a person

Input None.Output Gets a list of labels under the labels key.

2.8.41 POST /people/<person_id>/labels - Add a label for a person

Input• label - string. Label to add.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a label value with the label that wasadded.

2.8.42 GET /people/<person_id>/labels/<label> - Determines if a person has a la-bel


2.8.43 DELETE /people/<person_id>/labels/<label> - Removes a label from a per-son


2.8.44 GET /people/fields - Gets available custom person fields

Input None.Output List of fields in the fields key.

2.8. API: People 40


2.8.45 GET /people/groups - Gets available usergroups

Input None.Output List of groups in the groups key.

2.9 API: Organizations

All API URLs listed here must be prefixed by the root API URL, such ashttp://support.example.com/api

2.9. API: Organizations 41


2.9.1 GET /organizations - Search for organizations matching criteria

Input Constraints


• address[] - string. Requires an organization’saddress to contain this value.

• field[#][] - string. Requires organizationcustom field to have the specified value in thelisted field.

• im[] - string. Requires an organization to havean instant messenger contact that contains thisvalue.

• label[] - string. Requires organization to behave the specified label.

• name[] - string. Requires an organization tohave a name that contains this value.

• phone[] - integer. Requires organization tohave a phone number that contains this value.

• parent_id[] - integer. ID of parent org.Other

• order - string. Order of the results. De-faults to accessing organization’s preference ororganizations.id:asc.





retrieve cached results• organizations - list of organizations that

matched the criteria on the requested page



2.9.2 POST /organizations - Create a new organization

Input• name - string. Name of the organization.• contact_data[#] - array. Components of a

contact detail to add.• field[#] - mixed. Value for the specified cus-

tom organization field.• group_id[] - integer. ID of a usergroup to

add this organization to.• label[] - string. Label to apply to the ticket.• summary - string. Summary of the organiza-

tion’s details.• parent_id - ID of parent org (optional)

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdorganization.

2.9.3 GET /organizations/<organization_id> - Gets information about an organiza-tion

Input None.Output Gets information about the given organization under the organization key.

2.9.4 POST /organizations/<organization_id> - Updates an organization

Input If input is omitted, the value is not updated.• name - string. Name of the organization.• field[#] - mixed. Value for the specified cus-

tom organization field.• summary - string. Summary of the organiza-

tion’s details.• parent_id - ID of org to become this org’s

parent


2.9.5 DELETE /organizations/<organization_id> - Deletes an organization




2.9.6 GET /organizations/<organization_id>/picture - Gets a link to an organiza-tion’s picture

Input• size - integer. The maximum size (in pixels)

that the picture should be. Defaults to 80.

Output• has_picture - boolean• picture_url - string. URL to get the per-

son’s picture (may come from Gravatar).• size - integer. Maximum size (in pixels) of the

picture.

2.9.7 POST /organizations/<organization_id>/picture - Updates an organization’spicture

Input• file - file. An uploaded image. Required if no

blob_id is provided.• blob_id - integer. ID of a blob record that

holds the picture already. Required if no file isprovided.


2.9.8 DELETE /organizations/<organization_id>/picture - Deletes an organization’spicture




2.9.9 GET /organizations/<organization_id>/members - Gets members of an orga-nization

Input• order - string. Order of the results. Defaults toperson.name:asc.

• cache - integer. The number of seconds tocache the result for. Defaults to 3600. Use 0 todisable the cache.



criteria• people - list of people in this organization on

the requested page

2.9.10 GET /organizations/<organization_id>/tickets - Gets tickets by an organiza-tion

Input• order - string. Order of the results. Defaults toticket.date_created:desc.





retrieve cached results• tickets - list of tickets for this organization on

the requested page



2.9.11 GET /organizations/<organization_id>/chats - Gets chats by a organization

Input• cache_id - integer. If provided, cached results






the requested page

2.9.12 GET /organizations/<organization_id>/activity-stream - Gets activity streamfor an organization

Input• page - integer. The page number of the results

to fetch.


criteria• activity - list of activity for this organization


2.9.13 GET /organizations/<organization_id>/slas - Gets a list of automaticallyapplied SLAs for an organization

Input None.Output Gets a list of SLAs under the slas key.

2.9.14 POST /organizations/<organization_id>/slas - Adds an SLA to the automati-cally applied SLAs for an organization

Input• sla_id - integer. ID of SLA to add.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the SLA added.



2.9.15 GET /organizations/<organization_id>/slas/<sla_id> - Determines if an SLAexists for an organization


2.9.16 DELETE /organizations/<organization_id>/slas/<sla_id> - Removes an SLAfrom an organization


2.9.17 GET /organizations/<organization_id>/billing-charges - Gets billing chargesfor an organization

Input• page - integer. Page number to retrieve.

Output• total_charge_time - integer. Length of

time charged, in seconds.• total_charge_amount - integer. Amount

charged, in admin-specified currency.• total - integer. Total number of charge

records.• per_page - integer. Number of records per

page.• page - integer. Current page number.• charges - array. List of charges on the current

page.

2.9.18 GET /organizations/<organization_id>/email-domains - Gets associatedemail domains for an organization

Input None.Output Gets a list of domains under the domains key.

2.9.19 POST /organizations/<organization_id>/email-domains - Adds an email do-main for an organization

Input• domain - string. Domain name to associate.

May not already be in use.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a domain value of the created domain.



2.9.20 GET /organizations/<organization_id>/email-domains/<domain> - Deter-mines if a domain is associated with an organization


2.9.21 DELETE /organizations/<organization_id>/email-domains/<domain> -Deletes a domain association for an organization

Input• remove_users - boolean (0/1). If true, re-

moves users in this email domain from the orga-nization.


2.9.22 POST /organizations/<organization_id>/email-domains/<domain>/move-users - Moves users to an organization (if they have no organization)


2.9.23 POST /organizations/<organization_id>/email-domains/<domain>/move-taken-users - Moves users to an organization (if they have another organi-zation)


2.9.24 GET /organizations/<organization_id>/contact-details - Gets contact detailsfor an organization

Input None.Output Gets a list of contacts under the details key.

2.9.25 POST /organizations/<organization_id>/contact-details - Creates a contactdetail for an organization

Input• type - string. Type of contact detail to add.• comment - string. Comment or label for the

contact detail.• data - array. Contact detail-specific data.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdcontact detail.



2.9.26 GET /organizations/<organization_id>/contact-details/<contact_id> - Deter-mines if contact ID exists for organization


2.9.27 DELETE /organizations/<organization_id>/contact-details/<contact_id> -Deletes a contact for an organization


2.9.28 GET /organizations/<organization_id>/groups - Gets the groups for an or-ganization

Input None.Output Gets a list of contacts under the groups key.

2.9.29 POST /organizations/<organization_id>/groups - Adds an organization to agroup

Input• id - integer. ID of the group to add this organi-

zation to.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the group thatwas added.

2.9.30 GET /organizations/<organization_id>/groups/<group_id> - Determines ifan organization is a member of a group


2.9.31 DELETE /organizations/<organization_id>/groups/<group_id> - Removesan organization from a group


2.9.32 GET /organizations/<organization_id>/labels - Gets the labels for an organi-zation




2.9.33 POST /organizations/<organization_id>/labels - Add a label for an organiza-tion



2.9.34 GET /organizations/<organization_id>/labels/<label> - Determines if an or-ganization has a label


2.9.35 DELETE /organizations/<organization_id>/labels/<label> - Removes a labelfrom an organization


2.9.36 GET /organizations/fields - Gets available custom organization fields


2.9.37 GET /organizations/groups - Gets available usergroups

Input None.Output List of groups in the groups key.

2.10 API: Contact Data

People and organizations can have multiple types of contact data set for them. These can be set when creating a per-son or organization or by calling a specific end point to add contact data to an existing person or organization. Seethe specific content pages for the URLs to access contact data.

Each type of contact data accepts different arguments. This page serves as general documentation for setting contactdata.

2.10.1 Data Structure for saving and updating contact data

The general data structure for setting a single contact data record is as follows:

• type - string. The type of contact data. This is discussed in more detail in the sections below.

2.10. API: Contact Data 50


• comment - string. An optional comment or label for the contact data. For example, you might label an ad-dress as “home” or “business”.

• data - array. This is an array of data that makes up the contact data record. The structure of this is specific toeach contact data type. Specific components are discussed in the sections below.

Note that to pass the individual parts of an array, square brackets are used (such as data[username]). For exam-ple, as a PHP array this might look like:

array('type' => 'im','comment' => 'label','data[service]' => 'aim','data[username]' => 'example',

)

2.10.2 Creating a new person or organisation

When creating a new person or organization, you can specify multiple contact data records by passing arraysof contact_data[#]. The # should be replaced with a number that is the same for each part of a single contactdata record. The number itself is arbitrary, it’s only used to group data values of the same contact record. Multiplerecords can be created by using different numbers. For example:

array('contact_data[1][type]' => 'im','contact_data[1][comment]' => 'label','contact_data[1][data][service]' => 'aim','contact_data[1][data][username]' => 'example','contact_data[2][type]' => 'website','contact_data[2][comment]' => 'person','contact_data[2][data][url]' => 'http://example.com'

)

2.10.3 Contact Data Types

Address

Type addressdata

• address - string. Street address.• city - string. City.• state - string. State, if there is one.• zip - string. Zip or postal code.• country - string. Country name.

Facebook

Type facebookData

• profile_url - string. URL to the Facebookprofile.



Instant Message

Type instant_messagedata

• service - string. Name of the IM service.Valid services: aim, msn, yim, icq, skype, gtalk,other.

• username - string. User name for the service.

LinkedIn

Type linked_indata

• profile_url - string. URL to the LinkedInprofile.

Phone

Warning: This function was replaced by POST /people/{person_id}/phone_numbers and no longer workswith the current DeskPRO version.If your code relies on this method, you should change it to use POST /people/{person_id}/phone_numbers be-fore updating DeskPRO. See API: People for the functions you can use to retrieve and change phone numbers.For all other non-phone number contact data, you should still use the existing functions.

Type phonedata

• country_calling_code - integer. Countrydialing code.

• number - string. The phone number.• type - string. Type of number. Valid types:

phone, mobile, fax.

Skype

Type skypedata

• username - string. Skype user name.

Twitter

Type twitterdata

• username - string. Twitter user name.



Website

Type websitedata

• url - string. Website URL.

2.11 API: Chats


2.11.1 GET /chats - Search for chats matching criteria

Input ConstraintsAll constraints are optional. Multiple constraints areAND’d together; multiple values for a single constraintare OR’d.

• agent_id[] - integer. Requires chat to be as-signed to the specified agent ID.

• department_id[] - integer. Requires chat tobe in the specified department ID.

• label[] - string. Requires chat to be have thespecified label.

• person_id[] - integer. Requires chat to becreated by the specified person ID.

• status[] - string. Requires chat to be in thespecified status. Possible values are ended andopen.

Other• order - string. Order of the results. Defaults to

newest chats. This parameter is not used yet.• cache_id - integer. If provided, cached results






the requested page

2.11. API: Chats 53


2.11.2 GET /chats/<chat_id> - Gets information about a chat

Input None.Output Gets information about the given chat under the chat key.

2.11.3 POST /chats/<chat_id> - Updates a chat

Input If input is omitted, the value is not updated.• department_id - integer. Department the

chat is in.


2.11.4 POST /chats/<chat_id>/leave - Leaves a chat

Input• action - string. If the chat is open, an addi-

tional action to take. Options are unassign orend.


2.11.5 POST /chats/<chat_id>/end - Ends a chat


2.11.6 GET /chats/<chat_id>/messages - Gets all messages in a chat

Input None.Output Gets a list of messages under the messages key.

2.11.7 POST /chats/<chat_id>/messages - Replies to a chat as the API user

Input• message - string. Message reply text.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a message_id value with the ID of thenewly created message.

2.11.8 GET /chats/<chat_id>/participants - Gets the participants in a chat

Participants are people who are CCed or following the chat, not the chat creator or primary assigned agent.

Input None.Output A list of participant people inside the participants key.

2.11. API: Chats 54


2.11.9 POST /chats/<chat_id>/participants - Adds a participant to a chat

Input• person_id - integer. ID of the person to add to

the chat.• /li>

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a person_id value with the ID of theperson that was added.

2.11.10 GET /chats/<chat_id>/participants/<person_id> - Determines if a person isparticipating in a chat


2.11.11 DELETE /chats/<chat_id>/participants/<person_id> - Removes a partici-pant from a chat


2.11.12 GET /chats/<chat_id>//labels - Gets the labels for a chat

Input None.Output A list of labels inside the labels key.

2.11.13 POST /chats/<chat_id>/labels - Adds a label to a chat



2.11.14 GET /chats/<chat_id>/labels/<label> - Determines if the chat has the label


2.11.15 DELETE /chats/<chat_id>/labels/<label> - Removes a label from a chat


2.11. API: Chats 55


2.12 API: Knowledgebase


2.12. API: Knowledgebase 56


2.12.1 GET /kb - Search for articles matching criteria

Input Constraints


• category_id[] - integer. Requires the articleto be in this category or a child category.

• category_id_specific[] - integer. Re-quires the article to be in this category.

• date_created_end - integer. Requires thearticle to have been created before this date.Must be specified as a Unix timestamp.

• date_created_start - integer. Requiresthe article to have been created after this date.Must be specified as a Unix timestamp.

• label[] - string. Requires the article to behave the specified label.

• new - boolean (0/1). If non-0, requires the articleto be considered new (created within the lastmonth). If 0, this does nothing.

• popular - boolean (0/1). If non-0, requiresthe article to be considered popular (3 or moreviews). If 0, this does nothing.

• status[] - string. Requires the article to behave the specified status. Possible values include:published, archived, hidden.


the publishing date.• cache_id - integer. If provided, cached results





retrieve cached results• articles - list of articles that matched the

criteria on the requested page



2.12.2 POST /kb - Creates a new article

Input• attach[] - file. Attached file to include with

the article.• attach_id[] - integer. The ID of an already

uploaded file to include with the article.• category_id[] - integer. ID of the category

the article is in. At least one is required.• content - string. HTML content of the article.

Required.• date - integer. If provided, changes the cre-

ation/publishing date of the article to the givenUnix timestamp. If not provided, defaults to thecurrent time.

• date_end - integer. If provided, sets the Unixtimestamp when an action should be taken.

• date_published - integer. If provided andthe article is not published, sets the Unix times-tamp when an article should be published.

• end_action - string. If provided with adate_end, the action that should be taken whendate_end is reached. Possible values are delete orarchive.

• field[#] - mixed. Value for the specified cus-tom field.

• label[] - string. Label to apply to the article.• product_id[] - integer. ID of product this

article is associated with.• status - string. Status of the article. If not

specified, defaults to published.• title - string. Title of the article. Required.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdarticle.

2.12.3 GET /kb/<article_id> - Gets information about an article

Input None.Output Gets information about the given article under the article key.



2.12.4 POST /kb/<article_id> - Updates an article

Input If input is omitted, the value is not updated.• attach[] - file. Attached file to include with

the article.• attach_id[] - integer. The ID of an already

uploaded file to include with the article.• category_id[] - integer. ID of the category

the article is in. At least one is required.• content - string. HTML content of the article.• date - integer. If provided, changes the cre-

ation/publishing date of the article to the givenUnix timestamp. If not provided, defaults to thecurrent time.

• date_end - integer. If provided, sets the Unixtimestamp when an action should be taken.

• date_published - integer. If provided andthe article is not published, sets the Unix times-tamp when an article should be published.

• end_action - string. If provided with adate_end, the action that should be taken whendate_end is reached. Possible values are delete orarchive.

• field[#] - mixed. Value for the specified cus-tom field.

• product_id[] - integer. ID of product thisarticle is associated with.

• status - string. Status of the article.• title - string. Title of the article.


2.12.5 DELETE /kb/<article_id> - Deletes an article


2.12.6 GET /kb/<article_id>/attachments - Gets information about an article’s at-tachments

Input None.Output Gets information about the attachments under the attachments key.



2.12.7 POST /kb/<article_id>/attachments - Adds an attachment to an article

Input• attach - file. Attached file to include with the

article. Required if no attach_id is provided. Re-quired if no attach_id is provided.

• attach_id - integer. The ID of an already up-loaded file to include with the article. Required ifno attach value is provided.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdattachment.

2.12.8 GET /kb/<article_id>/attachments/<attachment_id> - Determines if an arti-cle has an attachment


2.12.9 DELETE /kb/<article_id>/attachments/<attachment_id> - Removes an arti-cle attachment


2.12.10 GET /kb/<article_id>/votes - Gets the votes for an article

Input None.Output Gets a list of votes under the votes key.

2.12.11 GET /kb/<article_id>/comments - Gets the comments for an article

Input None.Output Gets a list of comments under the comments key.



2.12.12 POST /kb/<article_id>/comments - Add a comment for an article

Input• content - string. Text of the comment.• person_id - integer. ID of the person that

owns the comment. If not provided, defaults tothe agent making the request.

• status - string. Status of the comment. De-faults to visible.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the comment ID that wasadded.

2.12.13 GET /kb/<article_id>/comments/<comment_id> - Gets info about a specificarticle comment

Input None.Output Information about the comment under a comment key.

2.12.14 POST /kb/<article_id>/comments/<comment_id> - Updates an article com-ment

Input• content - string. Text of the comment.• status - string. Status of the comment.


2.12.15 DELETE /kb/<article_id>/comments/<comment_id> - Deletes an articlecomment


2.12.16 GET /kb/<article_id>/labels - Gets the labels for an article




2.12.17 POST /kb/<article_id>/labels - Add a label for an article



2.12.18 GET /kb/<article_id>/labels/<label> - Determines if an article has a label


2.12.19 DELETE /kb/<article_id>/labels/<label> - Removes a label from an article


2.12.20 GET /kb/validating-comments - Gets article comments that are awaitingvalidation

Input None.Output List of comments in the comments key.

2.12.21 GET /kb/categories - Gets available article categories

Input None.Output List of categories in the categories key.

2.12.22 POST /kb/categories - Creates an article category

Input• title - string. Title of the category.• parent_id - integer. ID of the category’s par-

ent. Use 0 for no parent.• display_order - integer. Order of display

of categories. Lower numbers will be displayedfirst.

• usergroup_id[] - integer. ID of user groupthat has access. If not provided, defaults to allusers.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the category wasadded.



2.12.23 GET /kb/categories/<category_id> - Gets an article category

Input None.Output Category data in the category key.

2.12.24 POST /kb/categories/<category_id> - Updates an article category





2.12.25 DELETE /kb/categories/<category_id> - Deletes an article category

Note: categories can only be deleted when empty.


2.12.26 GET /kb/categories/<category_id>/articles - Gets articles within an articlecategory

Input• order - string. Order of the results. Defaults to






retrieve cached results• articles - list of articles that matched the




2.12.27 GET /kb/categories/<category_id>/groups - Gets groups with access to anarticle category

Input None.Output List of groups with access in the groups key.

2.12.28 POST /kb/categories/<category_id>/groups - Adds a group to an articlecategory

Input• id - integer. ID of the group to add access for.


2.12.29 GET /kb/categories/<category_id>/groups/<group_id> - Determines if agroup has access to an article category


2.12.30 DELETE /kb/categories/<category_id>/groups/<group_id> - Removes agroup’s access to an article category


2.12.31 GET /kb/fields - Gets available article fields


2.12.32 GET /kb/products - Gets available products

Input None.Output List of products in the products key.

2.13 API: Downloads


2.13. API: Downloads 64


2.13.1 GET /downloads - Search for downloads matching criteria

Input Constraints


• category_id[] - integer. Requires the down-load to be in this category or a child category.

• category_id_specific[] - integer. Re-quires the download to be in this category.

• date_created_end - integer. Requires thedownload to have been created before this date.Must be specified as a Unix timestamp.

• date_created_start - integer. Requiresthe download to have been created after this date.Must be specified as a Unix timestamp.

• label[] - string. Requires the download to behave the specified label.

• new - boolean (0/1). If non-0, requires the down-load to be considered new (created within the lastmonth). If 0, this does nothing.

• popular - boolean (0/1). If non-0, requires thedownload to be considered popular (50 or moredownloads). If 0, this does nothing.

• status[] - string. Requires the download tobe have the specified status. Possible values in-clude: published, archived, hidden.







retrieve cached results• downloads - list of downloads that matched

the criteria on the requested page



2.13.2 POST /downloads - Creates a new download

Input• attach - file. Attached file that represents the

download. See article on Basic API usage formore information on sending files to the API.Required if no attach_id is provided.

• attach_id - integer. ID of an already up-loaded file (blob). Required if no attach valueis provided.

• category_id - integer. ID of the category thedownload is in. Required.

• content - string. HTML content/descriptionfor the download.

• label[] - string. Label to apply to the down-load.

• status - string. Status of the download. If notspecified, defaults to published.

• title - string. Title of the download. If notspecified, defaults to the filename of the providedfile.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createddownload.

2.13.3 GET /downloads/<download_id> - Gets information about a download

Input None.Output Gets information about the given download under the download key.

2.13.4 POST /downloads/<download_id> - Updates a download

Input If input is omitted, the value is not updated.• attach - file. A new attached file that repre-

sents the download. See API Basics for moreinformation on sending files to the API.

• attach_id - integer. ID of an already up-loaded file (blob).

• category_id - integer. ID of the category thedownload is in.

• content - string. HTML content/descriptionfor the download.

• status - string. Status of the download.• title - string. Updates the title of the down-

load. If not specified and a new file is provided,defaults to the filename of the provided file.




2.13.5 DELETE /downloads/<download_id> - Deletes a download


2.13.6 GET /downloads/<download_id>/comments - Gets the comments for adownload


2.13.7 POST /downloads/<download_id>/comments - Add a comment for a down-load





2.13.8 GET /downloads/<download_id>/comments/<comment_id> - Gets infoabout a specific download comment


2.13.9 POST /downloads/<download_id>/comments/<comment_id> - Updates adownload comment



2.13.10 DELETE /downloads/<download_id>/comments/<comment_id> - Deletes adownload comment




2.13.11 GET /downloads/<download_id>/labels - Gets the labels for a download


2.13.12 POST /downloads/<download_id>/labels - Add a label for a download



2.13.13 GET /downloads/<download_id>/labels/<label> - Determines if a downloadhas a label


2.13.14 DELETE /downloads/<download_id>/labels/<label> - Removes a label froma download


2.13.15 GET /downloads/validating-comments - Gets download comments thatare awaiting validation


2.13.16 GET /downloads/categories - Gets available download categories




2.13.17 POST /downloads/categories - Creates a download category






2.13.18 GET /downloads/categories/<category_id> - Gets a download category


2.13.19 POST /downloads/categories/<category_id> - Updates a download cate-gory





2.13.20 DELETE /downloads/categories/<category_id> - Deletes a download cate-gory





2.13.21 GET /downloads/categories/<category_id>/downloads - Gets downloadswithin a download category







retrieve cached results• downloads - list of articles that matched the


2.13.22 GET /downloads/categories/<category_id>/groups - Gets groups with ac-cess to a download category


2.13.23 POST /downloads/categories/<category_id>/groups - Adds a group to adownload category



2.13.24 GET /downloads/categories/<category_id>/groups/<group_id> - Deter-mines if a group has access to a download category




2.13.25 DELETE /downloads/categories/<category_id>/groups/<group_id> - Re-moves a group’s access to a download category


2.14 API: News


2.14. API: News 71


2.14.1 GET /news - Search for news posts matching criteria

Input Constraints


• category_id[] - integer. Requires the newspost to be in this category or a child category.

• category_id_specific[] - integer. Re-quires the news post to be in this category.

• date_created_end - integer. Requires thenews post to have been created before this date.Must be specified as a Unix timestamp.

• date_created_start - integer. Requiresthe news post to have been created after this date.Must be specified as a Unix timestamp.

• label[] - string. Requires the news post to behave the specified label.

• status[] - string. Requires the news post tobe have the specified status. Possible values in-clude: published, archived, hidden.







retrieve cached results• news - list of news posts that matched the crite-

ria on the requested page

2.14. API: News 72


2.14.2 POST /news - Creates a news post

Input• category_id - integer. ID of the category the

news post is in. Required.• content - string. HTML content/description

for the news post. Required.• date - integer. If provided, changes the cre-

ation/publishing date of the news post to thegiven Unix timestamp. If not provided, defaultsto the current time.

• label[] - string. Label to apply to the newspost.

• status - string. Status of the news post. If notspecified, defaults to published.

• title - string. Title of the news post. If notspecified, defaults to the filename of the providedfile. Required.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly creatednews post.

2.14.3 GET /news/<news_id> - Gets information about a news post

Input None.Output Gets information about the given news post under the news key.

2.14.4 POST /news/<news_id> - Updates a news post

Input If input is omitted, the value is not updated.• category_id - integer. ID of the category the

news post is in.• content - string. HTML content/description

for the news post.• date_published - integer. If provided,

changes the publishing date of the news post tothe given Unix timestamp.

• status - string. Status of the news post.• title - string. Title of the news post.


2.14.5 DELETE /news/<news_id> - Deletes a news post


2.14. API: News 73


2.14.6 GET /news/<news_id>/comments - Gets the comments for a news entry


2.14.7 POST /news/<news_id>/comments - Add a comment for a news entry





2.14.8 GET /news/<news_id>/comments/<comment_id> - Gets info about a spe-cific news comment


2.14.9 POST /news/<news_id>/comments/<comment_id> - Updates a news com-ment



2.14.10 DELETE /news/<news_id>/comments/<comment_id> - Deletes a newscomment


2.14.11 GET /news/<news_id>/labels - Gets the labels for a news post


2.14. API: News 74


2.14.12 POST /news/<news_id>/labels - Add a label for a news post



2.14.13 GET /news/<news_id>/labels/<label> - Determines if a news post has alabel


2.14.14 DELETE /news/<news_id>/labels/<label> - Removes a label from a newspost


2.14.15 GET /news/validating-comments - Gets news comments that are awaitingvalidation


2.14.16 GET /news/categories - Gets available news categories


2.14. API: News 75


2.14.17 POST /news/categories - Creates a new category






2.14.18 GET /news/categories/<category_id> - Gets a news category


2.14.19 POST /news/categories/<category_id> - Updates a news category





2.14.20 DELETE /news/categories/<category_id> - Deletes a news category



2.14. API: News 76


2.14.21 GET /news/categories/<category_id>/news - Gets news within a news cat-egory







retrieve cached results• news - list of news that matched the criteria on

the requested page

2.14.22 GET /news/categories/<category_id>/groups - Gets groups with access toa news category


2.14.23 POST /news/categories/<category_id>/groups - Adds a group to a newscategory



2.14.24 GET /news/categories/<category_id>/groups/<group_id> - Determines if agroup has access to a news category


2.14. API: News 77


2.14.25 DELETE /news/categories/<category_id>/groups/<group_id> - Removes agroup’s access to a news category


2.15 API: Glossary


2.15.1 GET /glossary - List glossary words

Input• word - string. If specified, gets words containing

this string.

Output• words - list of words that matched

2.15.2 POST /glossary - Add a glossary word

Input• definition- string. Definition of given

words.• word[] - string. List of words to associate with

this definition.

Output• ids - list of words IDs created• definition_id - definition ID created

2.15.3 GET /glossary/lookup - Looks up a specific glossary word

Input• word - string. If specified, gets this word.

Output• word - Information about the word, if in the

glossary.

2.15.4 GET /glossary/<word_id> - Gets a glossary word

Input None.Output Glossary word information under the word key.

2.15. API: Glossary 78


2.15.5 DELETE /glossary/<word_id> - Deletes a glossary word


2.15.6 GET /glossary/definitions/<definition_id> - Gets a glossary word definition

Input None.Output Glossary definition information under the definition key.

2.15.7 POST /glossary/definitions/<definition_id> - Updates a glossary word defi-nition

Input• definition - string. Definition text.• word[] - string. If specified, a word to add.


2.15.8 DELETE /glossary/definitions/<definition_id> - Deletes a glossary worddefinition


2.16 API: Feedback


2.16. API: Feedback 79


2.16.1 GET /feedback - Search for feedback matching criteria

Input Constraints


• category_id[] - integer. Requires the feed-back to be in this category or a child category.

• category_id_specific[] - integer. Re-quires the feedback to be in this category or achild category.

• date_created_end - integer. Requires thefeedback to have been created before this date.Must be specified as a Unix timestamp.

• date_created_start - integer. Requiresthe feedback to have been created after this date.Must be specified as a Unix timestamp.

• label[] - string. Requires the feedback tohave this label.

• status[] - integer. Requires the feedback tobe in this status. Possible values: new, active,closed, hidden.

• status_category_id[] - integer. Requiresthe feedback to be in this status category.

Other• order - string. Order of the results. De-

faults to accessing person’s preference ordate_created:desc.





retrieve cached results• feedback - list of feedback that matched the




2.16.2 POST /feedback - Create new feedback

Input• title - string. Title of the feedback. Required.• content - string. Content of the feedback.

Marked up using HTML. Required.• category_id - string. Category of the feed-

back.• label[] - string. Label for the feedback.• status - string. Status of the feedback. De-

faults to new if not overridden by this or sta-tus_category_id.

• status_category_id - string. Status cate-gory of the feedback.

• user_category_id - string. User categoryof the feedback.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdfeedback.

2.16.3 GET /feedback/<feedback_id> - Gets information about specific feedback

Input None.Output Gets information about the given feedback under the feedback key.

2.16.4 POST /feedback/<feedback_id> - Updates feedback

Input• category_id - string. Category of the feed-

back.• content - string. Content of the feedback.

Marked up using HTML.• status - string. Status of the feedback. De-

faults to new if not overridden by this or sta-tus_category_id.

• status_category_id - string. Status cate-gory of the feedback.

• title - string. Title of the feedback.• user_category_id - string. User category

of the feedback.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdfeedback.



2.16.5 DELETE /feedback/<feedback_id> - Deletes feedback


2.16.6 POST /feedback/<feedback_id>/merge/<other_feedback_id> - Merges thetwo feedback records

The two feedback records are merged into feedback_id. Feedback feedback_id will be removed.


2.16.7 GET /feedback/<feedback_id>/attachments - Gets information about a feed-back record’s attachments

Input None.Output Gets information about the attachments under the attachments key.

2.16.8 POST /feedback/<feedback_id>/attachments - Adds an attachment to afeedback record

Input• attach - file. Attached file to include with the

feedback. Required if no attach_id is provided.Required if no attach_id is provided.

• attach_id - integer. The ID of an alreadyuploaded file to include with the feedback. Re-quired if no attach value is provided.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdattachment.

2.16.9 GET /feedback/<feedback_id>/attachments/<attachment_id> - Determines ifa feedback record has an attachment


2.16.10 DELETE /feedback/<feedback_id>/attachments/<attachment_id> - Re-moves a feedback attachment




2.16.11 GET /feedback/<feedback_id>/votes - Gets the votes for feedback

Input None.Output Gets a list of votes under the votes key.

2.16.12 GET /feedback/<feedback_id>/comments - Gets the comments for a feed-back entry


2.16.13 POST /feedback/<feedback_id>/comments - Add a comment for a feed-back entry





2.16.14 GET /feedback/<feedback_id>/comments/<comment_id> - Gets info abouta specific feedback comment


2.16.15 POST /feedback/<feedback_id>/comments/<comment_id> - Updates afeedback comment



2.16.16 DELETE /feedback/<feedback_id>/comments/<comment_id> - Deletes afeedback comment




2.16.17 GET /feedback/<feedback_id>/labels - Gets the labels for feedback


2.16.18 POST /feedback/<feedback_id>/labels - Add a label for feedback

In-put

label - string. Label to add.

Out-put

Outputs a 201 Created status with a Location header that points to the created resource. Also returnsJSON output with a label value with the label that was added.

2.16.19 GET /feedback/<feedback_id>/<label> - Determines if feedback has a label


2.16.20 DELETE /feedback/<feedback_id>/labels/<label> - Removes a label fromfeedback


2.16.21 GET /feedback/validating-comments - Gets feedback comments that areawaiting validation


2.16.22 GET /feedback/categories - Gets available feedback categories

Note that these are “feedback types” in the admin interface.


2.16.23 GET /feedback/status-categories - Gets available feedback status cate-gories

Note that these are “statuses” in the admin interface.




2.16.24 GET /feedback/user-categories - Gets available feedback user categories

Note that these are “categories” in the admin interface.


2.17 API: Tasks


2.17. API: Tasks 85


2.17. API: Tasks 86


2.17.1 GET /tasks - Search for tasks matching criteria

Input Constraints


• assigned_agent_id[] - integer. ID of theagent assigned to the task.

• assigned_agent_team_id[] - integer. IDof the agent team assigned to the task.

• date_completed_end - integer. MaximumUnix timestamp for when the task was com-pleted.

• date_completed_start - integer. Min-imum Unix timestamp for when the task wascompleted.

• date_created_end - integer. MaximumUnix timestamp for when the task was created.

• date_created_start - integer. MinimumUnix timestamp for when the task was created.

• date_due_end - integer. Maximum Unixtimestamp for when the task is due.

• date_due_start - integer. Minimum Unixtimestamp for when the task is due.

• is_completed - boolean (1/0). 1 to get com-pleted tasks only, 0 to get incomplete tasks only.

• person_id[] - integer. ID of the person thatcreated the task.

• title[] - string. Text that must be containedin the task title.

• visibility - boolean (1/0). 1 to get publictasks only, 0 to get private tasks only.

Other• order - string. Order of the results. Defaults totask.name:asc.





retrieve cached results• tasks - list of tasks that matched the criteria on

the requested page

2.17. API: Tasks 87


2.17.2 POST /tasks - Creates a new task

Input• assigned_agent_id - integer. ID of agent

assigned to the task.• assigned_agent_team_id - integer. ID of

agent team assigned to the task.• date_due - integer. Unix timestamp of when

the task is due.• label[] - string. Label to apply to the task.• ticket_id - integer. If specified, the ID of the

ticket this task should be associated with.• title - string. Title of the task.• visibility - integer. 0 for private, 1 for pub-

lic.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdtask.

2.17.3 GET /tasks/<task_id> - Gets a task

Input None.Output Gets information about the given task under the task key.

2.17.4 POST /tasks/<task_id> - Updates a task

Input• assigned_agent_id - integer. ID of agent

assigned to the task.• assigned_agent_team_id - integer. ID of

agent team assigned to the task.• completed - boolean (1/0). Sets the completed

state for the task.• date_due - integer. Unix timestamp of when

the task is due.• title - string. Title of the task.• visibility - integer. 0 for private, 1 for pub-

lic.


2.17.5 DELETE /tasks/<task_id> - Deletes a task

Note: only tasks created by you can be deleted.


2.17. API: Tasks 88


2.17.6 GET /tasks/<task_id>/associations - Gets task associations

Input None.Output Gets information about the task associations under the associations key.

2.17.7 POST /tasks/<task_id>/associations - Creates a task association

Input• ticket_id - integer. ID of ticket to create as-

sociation with.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdassociation.

2.17.8 GET /tasks/<task_id>/associations/<association_id> - Determines if a taskassociation exists


2.17.9 DELETE /tasks/<task_id>/associations/<association_id> - Deletes a taskassociation


2.17.10 GET /tasks/<task_id>/comments - Gets task comments

Input None.Output Gets information about the task comments under the comments key.

2.17.11 POST /tasks/<task_id>/comments - Creates a task comment

Input• comment - string. Text of the comment.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a id value with the ID of the newly createdcomment.

2.17.12 GET /tasks/<task_id>/comments/<comment_id> - Determines if a taskcomment exists


2.17. API: Tasks 89


2.17.13 DELETE /tasks/<task_id>/comments/<comment_id> - Deletes a task com-ment

Note: only comments created by you can be deleted.


2.17.14 GET /tasks/<task_id>/labels - Gets task labels

Input None.Output Gets information about the task labels under the labels key.

2.17.15 POST /tasks/<task_id>/labels - Creates a task label

Input• label - string. Text of the label.

Output Outputs a 201 Created status with a Location headerthat points to the created resource. Also returns JSONoutput with a labe value with the label that was cre-ated.

2.17.16 GET /tasks/<task_id>/labels/<label> - Determines if a task label exists


2.17.17 DELETE /tasks/<task_id>/labels/<labe> - Deletes a task label


2.18 API: Auth Login

Note: This is a new API function. If it is not yet available on your helpdesk, update to build #430 if using On-Premise, or wait until the update is rolled out to your Cloud helpdesk.


Use this function to check if a user’s/agent’s credentials (email and password) enable them to log in or not. This doesnot start a session or set cookies, it simply returns success or failure, and on success, provides user/agent details.

You must be using a superuser API key to use this function.

2.18. API: Auth Login 90


2.18.1 POST /api/people/auth-login - Exchange a valid login for an API token

Input (sent in request body)

{ “email”: “[email protected]”, “password”:“password” }OR{ “username”: “[email protected]”, “password”:“password” }username should be treated as an alias for email;there is no difference other than the propertyname

Output on success

{ “success”: true, “person”: { ... } }The person property is the full person object(including custom fields)of the person who matched

Output on failure

401 response{ “error_code”: “invalid_credentials”,“error_message”: “Invalid email address or password.”}

2.18. API: Auth Login 91

mailto:[email protected]

mailto:[email protected]

CHAPTER

THREE

WIDGETS

Widgets are a simple way to modify DeskPRO.

Widgets let you inject HTML and JavaScript into predefined locations within the agent interface.

You can edit HTML and Javascript files from the admin interface, so you don’t have to go through the trouble ofpackaging and distributing a ZIP file.

Creating widgets is the simplest way to add features to your helpdesk quickly, with a shallow learning curve.

There are two disadvantages of widgets compared to full apps:

• You can only make relatively simple changes with a widget, compared to what’s possible with apps.

• You can’t conveniently distribute a widget for installation on other DeskPRO helpdesks.

3.1 Creating widgets

Creating and managing widgets is done entirely from the Admin Interface. Go to the Apps sections and then clickthe Create Widget button.

You will see the New Widget form which is where you define the properties of your widget. To start with, give yourwidget a meaningful title that describes its purpose. The title is only used in the Admin Interface so it’s mainly just areminder to yourself.

The next sections, Tickets, Users, and Organizations, let you define where you want to add your HTML andJavascript to.

92


In the above screenshot, a single Ticket location is selected “A new tab in the properties box”. This renders theHTML template into a new tab at the top of the Ticket view:

3.1. Creating widgets 93


You can select as many locations as you want to.

3.2 Editing widgets

After you have created a widget, select it from the “Your Widgets” section of the Apps area in the Admin Interface.

The first thing you see is this App Definition. It looks a little scary, but you can ignore this section entirely. It wasautomatically generated by DeskPRO and you will probably never need to edit it.

Note: The fact is that Widgets are actually fully-feautred Apps under-the-covers, and the App Definition is how anapp configures itself. It tells DeskPRO which templates you have defined and where to put them.

Ignore the first App Definition tab and switch to any of the other tabs which contain the HTML and Javascript tem-plates you can edit to actually add content to your widget.

3.2. Editing widgets 94


For every location you checked during the widget creation step, you will have two files: A Javascript controller andan HTML template.

3.2.1 Javascript controller

The Javascript file is what we call a controller. Here is where you can add custom Javascript code like AJAX calls orevent handlers. All of your JS code should live within that one function controller.

You’ll notice that the default JS controller accepts a number of paramaters. The next section goes into more detailabout how JS controllers work, but briefly:

• $scope is a special object that lets you connect your JS controller to your HTML template. Any value youassign to $scope will be available from your template. We’ll go over a few examples in a moment.

• $ticket is an object containing all of the current ticket information including things like the ticket ID, thesubject, the user, the user email etc. There is a lot of information here. To view the available values, the easiestthing to do is use console.log($ticket) and then view your browser console (e.g., Chrome DeveloperConsole).

– If you specified a different tab type, such as a user or organization profile, you won’t see $ticket. In-stead you’ll have $person or $org which are user info and org info, respectively.

• $person is also available on tickets, it’s an alias for $ticket.person.

• $http is a service for performing AJAX requests. We’ll go over a few examples below.

• $el contains a jQuery-wrapped element that is the outer container for your HTML template. You can use thisto fine specific elements in your HTML template. For example, $el.find(’input’) to find an input box.

– Note that there are much better ways than using jQuery for connecting your JS controller to your tem-plate. The next section goes into more detail.


https://developer.chrome.com/devtools/docs/console

https://developer.chrome.com/devtools/docs/console


• $app is a reference to the Javascript object that represents your widget app. It includes things like your appID. You probably will never need to use this.

3.2.2 HTML template

Below the JS file is the HTML template file. This HTML template has special features attached to it that makes iteasy to interact with the JS controller. We go into more detail in the next section, but here are a few examples.

Binding variables

Perhaps the most common thing you will want to do is to render values from your JS controller in your HTML tem-plate. For example, perhaps you have done an AJAX lookup and want to render the results.

To do this, just assign values to the $scope variable in your controller:

$scope.name = 'Christopher'

Then within your HTML template, use the variable syntax:

Hello, {{name}}

You can even use variables to generate things like links:

<a href="http://example.com/script?name={{name}}">Hello, {{name}}</a>

Attaching click events

You could use jQuery and the $el variable to manually attach events. But there is a much cleaner way to do it.

First, define a function callback on your $scope:

$scope.submitForm = function() {alert("Hello!");

}

Then in your HTML template, use the special ng-click attribute on an element:

<button ng-click="submitForm()">Submit</button>

Conditionally showing an element

Use the special ng-if attribute on an element to conditionally show an element based on a Javascript expression:

<div ng-if="name">Hello, {{name}}</div><div ng-if="!name">You have no name</div>



Binding form controls

Binding form values can be done with the special ng-model attribute. When the form input changes, the targetvariable will be set on your Javascript $scope variable.

Enter your name: <input type="text" ng-model="name" /><button ng-click="submitForm()">Submit</button>

// Javascript$scope.submitForm = function() {

alert("Hello, " + $scope.name + "!");}

Iterating over a collection

If you have an array of data in your Javascript controller:

$scope.family = [{ name: "John", age: 38 },{ name: "Jane", age: 36 },{ name: "Jesse", age: 12 }

];

... then you can iterate over those values in your template with ng-repeat:

<ul><li ng-repeat="p in family">

{{p.name}} is {{p.age}}</li>

</ul>

Using data from the ticket

Use the $ticket object. Here are some commonly used values:

• $ticket.id - The ticket ID

• $ticket.subject - The ticket subject

• $ticket.agent - Is an object containing information for the currently assigned agent:

– $ticket.agent.id - The agent ID

– $ticket.agent.display_name - The agent name

– $ticket.agent.primary_email.email - The agent’s primary email address

– $ticket.agent.picture_url_80 - The agent’s profile picture scaled to 80x80. Replace ‘80’with any of these standard sizes: 80, 64, 50, 45, 32, 22, 16

• $ticket.agent_team.name - The name of the currently assigned team

• $ticket.department.name - The name of the assigned department

• $ticket.status - The current status

• $ticket.urgency - The current urgency



• $ticket.person - An object containing information about the user who opened the ticket:

– $ticket.person.id - The user ID

– $ticket.person.display_name - The user’s name

– $ticket.person.primary_email.email - The user’s primary email address

– $ticket.person.picture_url_80 - The user’s profile picture scaled to 80x80. Replace ‘80’with any of these standard sizes: 80, 64, 50, 45, 32, 22, 16

To use these values in your HTML template, you need to assign them to the $scope:

// Javascript$scope.user_name = $ticket.person.display_name;

// HTMLHello, {{user_name}}

Or you could assign the entire ticket object to the scope:

// Javascript$scope.ticket = $ticket;

// HTMLSubject: {{ticket.subject}}<br/>User Name: {{ticket.person.display_name}}<br/>User Email: <a href="mailto:{{ticket.person.primary_email.email}}">{{ticket.person.primary_email.email}}</a>

Performing AJAX requests

Use the $http service to perform AJAX requests.

Note: The Apps system is powered by a framework called AngularJS, and $http is a built-in service. You canrefer to the official documentation for detailed API information: https://docs.angularjs.org/api/ng/service/$http

Here’s an example of using $http to perform an AJAX call to a web-service. After the result comes back, see howwe assign the value to $scope which we use in the template:

// Javascript$scope.is_loading = true;

$http.get('/web-service').success(function(data) {$scope.is_loading = false;$scope.customer = data.customer;

});

// HTML<div ng-if="is_loading">Loading results, please wait...</div><div ng-if="!is_loading">

Customer ID: {{customer.id}}</div>

Note that due to a browser security feature called same-origin policy, you cannot use AJAX to load web servicesfrom external domains. For example, if your helpdesk is on support.example.com you cannot use $http to


https://docs.angularjs.org/api/ng/service/\protect \T1\textdollar http

http://en.wikipedia.org/wiki/Same-origin_policy


perform AJAX requests against other-domain.com because the domain is different and the browser will rejectthe request.

If your API supports JSONP, you can use that method instead via $http.jsonp. Otherwise, you can use theDeskPRO proxy service which allows you to proxy a AJAX requests through DeskPRO to make remote API calls:

var params = {url: 'http://other-domain.com/api/some-service',email_address: $ticket.person.primary_email.email,other_params: 'example',something: 'these other params will be passed as-is to your remote service'

};$http.get('DP_URL/agent/misc/proxy', {params: params}).siccess(function(data) {

// ...});

Note that the special DP_URL prefix in the URL will be automatically replaced to the URL of your helpdesk.

Much more...

There is much much more you can do with your Javascript and HTML templates that we will go over in the nextsection.

3.3 Example: Link to CRM

One of the simplest examples would be to create a widget that displays a link to an external system, such as a CRM.

Most CRMs offer a way to look-up a user based on criteria like an email address. In this example, we use an app thatoutputs a link with the users email address in it.

3.3.1 Create your widget

First, create your app from Admin > Apps > Create Widget like described in the previous section. Select where youwant your link to appear. In this example, we’ll create a new section under the properties box:

3.3. Example: Link to CRM 99

http://en.wikipedia.org/wiki/JSONP


3.3.2 Widget code

Switch to the Tickets tab to see the two inputs for our Javascript controller and HTML template. In this exam-ple, we’ll be using the users email address to generate a simple HTML link. So in the first box we need to assign theemail address variable to the $scope so it becomes available to the HTML template:

define(function() {return function($scope, $ticket, $person, $http, $el, $app) {

$scope.user_email = $person.primary_email.email;

3.3. Example: Link to CRM 100


};});

Then we are free to use the new user_email variable in our HTML template. Here’s an example template. It has abit of styling around the outer div to make it a bit prettier on the view-ticket screen.

<div style="margin-top: 10px; padding: 5px; background: #fff; border: 1px solid #ccc; border-radius: 4px;"><a href="http://example.com/crm/find-user?email={{user_email}}" target="_blank">Look up {{user_email}} in CRM</a>

</div>

This is what it looks like when we view a ticket in the Agent Interface:

3.4 Example: Consuming an API

Another common use-case for widgets is to consume an API and display data directly in the Agent Interface. Forexample, maybe you run an online store and you want to show the users recent purchases.

3.4.1 Create your widget

First step is to create your app like we’ve done before from Admin > Apps > Create Widget.

In this example, we’ll create a new tab in the properties box:

3.4. Example: Consuming an API 101


3.4.2 Widget code: Javascript

Switch to the Tickets tab so we can edit the Javascript controller code.

We can make AJAX requests with the $http service.

Note: Full documentation on the $http service can be found on the official AngularJS website:https://docs.angularjs.org/api/ng/service/$http


https://docs.angularjs.org/api/ng/service/\protect \T1\textdollar http


Note that due to browser security features, you cannot make AJAX calls to services on a different domain from thecurrent domain. To get around this limitation, DeskPRO has a special proxy script we can use that will pass-througha request to a remote service.

Here’s an example using $http to perform an AJAX request to a remote web service through the DeskPRO proxy:

define(function() {return function($scope, $ticket, $person, $http, $el, $app) {

// Setting a loading indicator like this means we// can show a loading message in our HTML template$scope.is_loading = true;

var params = {url: "http://api.example.com/lookup-orders",

// Any other parameters will be sent as-is// to your remote web service.// For example, here we are sending an 'email' parameter:email: $person.primary_email.email

};

$http.get('DP_URL/agent/misc/proxy', {params: params}).success(function(data) {$scope.is_loading = false;$scope.orders = data.orders;

});};

});

For the sake of our example, let’s pretend our web service returned the following data:

[{ id: 1, title: "iPhone", total: 649.00 },{ id: 2, title: "Headphones", total: 32.99 },{ id: 4, title: "USB Cable", total: 3.99 },{ id: 5, title: "Phone Case", total: 24.99 },

]

In our controller we assigned those results to the scope with this line:

$scope.orders = data.orders;

Next we’ll see how to show those results in our template.

3.4.3 Widget code: HTML

We have two goals with this HTML template;

1. We want to show a loading message while the results are loaded. This means we need some kind of if/elselogic in our template based on the is_loading variable we set in our Javascript controller.

2. We want to show a list of orders from our orders array. This means we need some kind of looping feature toloop through the results.



3.4.4 Loading Indicator

To show content based on a value, we can use a special HTML attribute ng-if:

<div ng-if="is_loading">Loading results, please wait...</div><div ng-if="!is_loading">Results are in!</div>

The value of ng-if can be any Javascript expression. In this case, we are just taking the value of our is_loadingvaraible. But we could use any valid expression. For example:

<div ng-if="1 + 1 == 2">Yes, 1+1 does equal 2</div>

3.4.5 Iterating over results

The next thing we want to do is iterate over the orders array so we can list the results we got from our web service.We can do this with another special HTML attribute called ng-repeat:

<ul><li ng-repeat="order in orders">

<a href="http://example.com/admin/order?id={{order.id}}">{{order.title}} - ${{order.total}}

</a></li>

</ul>

ng-repeat syntax is <local variable> in <collection> and repeats the HTML element for each itemin the collection. In our example, we repeated a <li> for each order in our orders array.

3.4.6 The full template

Putting it all together, our template looks something like this:

<div ng-if="is_loading">Loading results, please wait...</div><div ng-if="!is_loading">

<div ng-if="orders.length == 0">This user has no orders.

</div><div ng-if="orders.length > 0">

<ul style="margin: 10px"><li ng-repeat="order in orders">

<a href="http://example.com/admin/order?id={{order.id}}">{{order.title}} - ${{order.total}}

</a></li>

</ul></div>

</div>

And here’s what it looks like in the Agent Interface:




CHAPTER

FOUR

APPS

If widgets are too simple for you, you need to create a full-fledged app. A full app lets you define multiple sourcefiles, organize source files and even add additional resources like images or data files.

Apps are packaged as ZIP archives. To install an app, you upload it to your helpdesk from the admin interface. Ifyou’d like to make your changes available for use with other DeskPRO helpdesk - for example, if you’re integratinga software product you make with DeskPRO - you need to develop an app.

Most apps are fairly simple and are just a few HTML and Javascript files. But they can get pretty advanced: theycan have multiple source files (e.g. modular Javascript code), external data files, images, and even settings and aninstaller.

We’ll go over how to create and package apps later in this manual.

You can distribute the finished .ZIP file so that other DeskPRO helpdesks can install it.

4.1 Creating full apps

4.1.1 Preparation

To be able to create your own apps (or to add a native app that includes PHP code), you need to edit your DeskPROconfig.php file and add the following lines:

$DP_CONFIG['app_paths'] = array('prefix' => '/path/to/apps'

);

• replace prefix with a unique name that you will use to name your native apps. You can use any alphanu-meric string. Generally you will use your organization name or something generic. For example, acme andcustom are suitable prefix names.

• path is the absolute path on the filesystem where DeskPRO will find all apps that use the prefix. Even ifyou have only one app, it needs to be in this main wrapper directory.

For example:

$DP_CONFIG['app_paths'] = array('acme' => '/opt/deskpro-apps/acme-apps'

);

106


4.1.2 Creating a new app

Inside of one of the paths you defined above, create a new directory named prefix_something. That is:

• The same prefix as defined in the app_paths configuration value.

• An underscore character

• Followed by any alphanumeric string.

For example, if we had this app paths configuration:

$DP_CONFIG['app_paths'] = array('acme' => '/opt/deskpro-apps/acme-apps'

);

... and we wanted to create a new app that showed customer information, we would begin by creating a directory at/opt/deskpro-apps/acme-apps/acme_custinfo.

4.1.3 Directory layout

Your app directory must follow a standard directory format:

acme_custinfo/|- html/|- js/|- native/|- res/

|- icons/|- app_512.png

|- app.js|- manifest.json

Note: The ‘native’ folder is just a placeholder and is not used.

Path Descriptionhtml/ This is where you will place HTML template files used by your app.js/ This is where you will place Javascript files (mainly AngularJS controllers).res/ This is where you should place any other resources your app needs, such as images or data files.res/icons DeskPRO will look in this directory for icon files named app_XXX.png where XXX is a size: 16,

24, 32, 48, 64, 96, 128, 192, 256 or 512. DeskPRO will use these icons as the main app icon (e.g.,in the admin interface). DeskPRO will automatically scale icons if you are missing a certain size,so for most cases you can just specify one large icon and have DeskPRO scale it down for othersizes.

app.js This is a special Javascript file that “bootstraps” your app in the Agent Interface. This is howDeskPRO knows where to initialize your controllers and render templates. Without app.js, yourapp will have no interface.

manifest.jsonThis is a special file that describes the properties of your app. The manifest file is the only requiredfile.

4.1.4 manifest.json

Every app must have a manifest. Here is the format:

4.1. Creating full apps 107


{"package_name": "app_name","is_native": true,"title": "App Name","description": "App Description","tags": ["widget"],"api_version": 1,"version": 1,"version_name": "1.0.0","is_single": true,"author": {

"name": "DeskPRO","email": "[email protected]","link": "https://www.deskpro.com/"

},"settings_def": []

}

Property Descriptionpackage_nameThis must be the same name as the app directory. In our running example, this would be

acme_custinfois_native This must be true. If you later decide you want to package the app up as a ZIP, you would set

this to false before zipping.title Your app title. This is displayed in the admin interface.description A short description of your app. This is also displayed in the admin interface.tags Give your app at least one tag to help categorize it (unused at the moment)api_version This should always be 1version This is the version of your app as an integer. As you update your app, increate the integer.version_nameThis is the “readable” version for your app.author This is information about you. This information is displayed in the admin interface.settings_defThis is an array of settings that your app should use. We will talk more about settings later.

4.2 Components

Apps are made up of:

• An app.js file

• Widgets

• And widgets have HTML templates and Javascript controllers

We’ll go over each of these briefly, and later sections will go in to more detail.

4.2.1 app.js

Your app.js file is how DeskPRO “bootstraps” your app. This is how you define which templates you want to ren-der where and load controllers and do anything else your app might need.

Here is an empty app.js file:

define(function() {return {

init: function() {

4.2. Components 108


console.log("Hello, world");}

}});

The init method is called once the DeskPRO app platform is ready. This is where you will register your widgets.

Note: The object you define and return in app.js is “mixed in” to a system class called AppContext whichdefines a number of useful methods that we’ll go over later. We mention this now because you may be wonderinghow calls to this.someMethod work below if you don’t define them. It’s because these are defined in the systemAppContext.

4.2.2 Widgets

Widgets are Javascript controllers that you register for certain types of tabs in DeskPRO. For example, the tab typeticket will run on all tickets. The type org runs on Organization profiles.

Most widgets also define a template that is rendered to a specific location within the tab. For example, tickets have apre-defined location called header.bottom that renders your template near the top of the ticket tab.

Note: Refer to the glossary for a list of types and pre-defined locations.

Most of your app will be defined as “widgets” because this is how you will tie functionality to a specific place inDeskPRO. For example, by creating a ticket widget, you are able to easily work with data on the ticket, render tem-plates to the ticket view, etc.

4.2.3 Registering widgets

There are three ways to register widgets:

• this.registerAppWidget(type, templateName, controller):

• this.registerWidget(type, location, templateName, controller)

• this.registerWidgetTab(type, location, tabTitle, templateName, controller)

Param Descriptiontype This is the tab type you want to register on. For example, if you want the widget to show on tickets,

the tab type would be ticket. Refer to the glossary for a full list of tab types.templateNameThis is the name of your template file in the html/ directory. For example, if you had an HTML

file called html/Foo/bar.html, then templateName would be Foo/bar.html (so youdrop the ‘html/’ prefix).

controllerThis is a Javascript controller. A new instance of this controller will be created every time yourwidget is rendered. We’ll have examples of controllers later.

location This is where in the tab to render your widget. There are many pre-defined locations. Refer to theglossary for a list.

tabTitle If you are registering a widget that adds a tab to a tabbed box, this is the title of the tab.

Here’s an app.js that registers a template that renders a template in a ticket header:

define(function() {return {

init: function() {this.registerWidget('ticket', '@header.bottom', 'Foo/bar.html');

4.2. Components 109


}}

});

• ticket is the tab type

• @header.bottom is a pre-defined location in tickets

• Foo/bar.html is the name of the template to render (this would need to exist on the filesystem athtml/Foo/bar.html).

• There was no controller specified in this example.

4.2.4 Templates

Templates are just HTML files you save to the html/ directory. Templates are loaded by passing the filename as thetemplateName paramter when registering a widget.

Templates and controllers work hand-in-hand. Refer to the Templates section for details.

4.2.5 Controllers

Controllers are how you interact with your templates: for example, rendering variables, reading form input, etc.

Here is the source for an example controller:

define(function() {return function($scope, $ticket, $el, $app) {

console.log("Hello, world");}

});

Your controller source must return a function as shown above. The paramaters your function receives are important.The names must match values that DeskPRO “knows” about. For example, $ticket is an object representing thecurrent ticket. You could NOT rename this to something else because DeskPRO would not know what it is.

Note: Refer to the glossary for a list of available parameters for each tab type.

4.2.6 Loading Javascript source files

DeskPRO uses RequireJS to define and load script files. This is why all the Javascript you’ve seen so far is written asdefine() functions that return some kind of value.

You can define your Javascript controllers in separate files and then use RequireJS to load them. For example, here isan app.js file that defines two controllers and itself all in one file:

define(function() {var ControllerA = function($scope) {

$scope.hello = 'world';};var ControllerB = function($scope, $ticket) {

$scope.foo = 'bar';};

4.2. Components 110


return {init: function() {

this.registerWidget('ticket', '@header.bottom', 'hello.html', ControllerA);this.registerWidget('ticket', '@header.bottom', 'Foo/bar.html', ControllerB);

}}

});

As you can imagine, if those controllers were very long, your app.js file would become very big and overly com-plicated. So it’s good practice to separate the source files:

// This would be saved at js/Controllers/ControllerA.jsdefine(function() {

return function($scope) {$scope.hello = 'world';

};);

// This would be saved at js/Controllers/ControllerB.jsdefine(function() {

function($scope, $ticket) {$scope.foo = 'bar';

};);

// This is app.js, but notice how we are adding dependencies// to the define() call to load the other source files.define(['Controllers/ControllerA', 'Controllers/ControllerB'], function(ControllerA, ControllerB) {

return {init: function() {

this.registerWidget('ticket', '@header.bottom', 'hello.html', ControllerA);this.registerWidget('ticket', '@header.bottom', 'Foo/bar.html', ControllerB);

}}

});

4.3 More example apps

See the DeskPRO Apps GitHub repository at https://github.com/DeskPRO/DeskPRO-Apps for code samples andsome complete example apps.

4.3. More example apps 111

https://github.com/DeskPRO/DeskPRO-Apps

Documents

DeskPRO Developer Documentation...DeskPRO Developer Documentation, Release 1.0 2.1.4Authenticating with the API (API Tokens) An agent’s username and password can be exchanged via