Creating a widget is easy, and it’s quick to get started. In the Deskpro admin system, in the menu on the left under “Apps & Integrations” you’ll see a link to the “Widgets” section. When you navigate to the widget section you’ll see a list of the widgets you’ve already created as well as a button on the right called “Create Widget”.

Description

Clicking “Create Widget” will slide out the widget creation drawer and on the first tab “Description” you’ll be able to set some information about the widget you’re creating. Here’s a brief overview of what the fields mean:

• Title – The title of your widget, this is the default text that appears in a widget’s title bar as you’re using it. (required)

• Description – Text that explains what the function of the widget is. This text isn’t seen in the app, and is meant as a note to explain what the app is for other Deskpro users. (required)

• App Icon – An icon for the app. This icon will be shown in buttons when the app is displayed in Deskpro. The app icon must be an SVG graphic and if an icon is not provided Deskpro will include a default one (optional)

Settings

The settings screen allows you to do two things; configure where the app is shown in Deskpro as well as a list of settings for the app. For example, settings may include API keys or properties of the app itself.

Targets are places in Deskpro where your widget will appear, e.g. checking "Ticket" will render your widget in the ticket actions sidebar. At least one target is required.

Settings themselves are not required, however when adding settings you’re able to define the following properties:

• Name – The name of the setting that is both used by the app itself and the app proxy when talking to APIs. The name must not contain spaces or special characters, e.g. “api_key” (required)

• Title – A friendly name for the setting, following the example above this would be “API Key” (required)

• Description – Text that might explain how to use the setting, it’s shown below the setting to prompt users accordingly (optional)

• Type – The type of setting this is, commonly this will be “String”, representing a line of text, API key, etc. (required)

• Required? - Is this setting required in order for the widget to work?

• Backend Only? - When communicating securely with APIs, it is necessary to hide these secret values from the app. “Backend Only” settings are only injected into API requests when using the apps proxy

Permissions

On this tab we can define which groups or individual agents can see or use the widget in Deskpro.

Code

This tab is where you’d enter the code that represents the functionality widget. The widget is essentially an HTML file and as such there are two code editors, one allowing you to enter HTML, Javascript and CSS into the head and the other the body.

As an example, a simple app may include jQuery and CSS in the head and some HTML and Javascript in the body to make up the functionality of the app.

Proxy

When integrating a widget or app with APIs, it is necessary to tell Deskpro which API URLs that the app would consume. There are two main reasons for this; security and injecting “backend only” settings.

When adding URLs to the proxy, the following information must be provided:

• URL – A fully qualified URL of the endpoint or a regular expression representing a fully qualified URL, e.g. "https://example.com/api/users" or "https://example.com/api/users/.*/departments" (required)

• Method – The HTTP method used to call the URL, e.g. GET, POST, DELETE, etc. (required)

• Timeout – The number of seconds the proxy will wait before producing a timeout response (required)