The app manifest is a JSON file that resides in the root of an app package. The app manifest describes attributes of your app so that Deskpro may set up and render your app correctly. This information includes where your app appears (targets), how your app is configured (settings), how your app communicates with third parties (app proxy), etc.

Minimal Example

A minimal app manifest is as follows:

# /manifest.json

{
  "name": "my_app",
  "title": "My App",
  "description": "Brief description of my app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": true,
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
    }
  }]
}
 copy

The manifest above describes a simple "ticket sidebar" app with a single entrypoint, index.html. Here's a summary of the manifest properties:

• name - unique name of your app, usually this would be prefixed with your vendor name, e.g. "my-company/my-app" (required)

• title - the app title is what appears in the Deskpro admin section during installation as well as in the default header app itself (required)

• description - brief description of your app. This appears in Deskpro's admin section as the app is installed (required)

• version - an arbitrary semantic version number for the app, this must increment per change of your published app package (required)

• scope - which area of Deskpro this app will appear in, agent or admin (required)

• isSingleInstall - can this app only be installed once? (required)

• targets - an array of targets/entrypoint paths where this app should appear in deskpro (required), target options are:

  • ticket_sidebar

  • user_sidebar

  • organisation_sidebar

  • content_knowledge_base_sidebar

  • content_news_sidebar

  • content_download_sidebar

  • content_guide_topic_sidebar

  • community_topic_sidebar

You can learn more about targets by reading our targets guide.

Settings

The app manifest can also describe a collection of settings for the app. For example, one setting might be an API key, allowing admins to configure this setting as your app is installed. In the following example we'll add "API Key" as a setting:

# /manifest.json

{
  "name": "my_app",
  "title": "My App",
  "description": "Brief description of my app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": true,
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
    }
  }],
  "settings": {
    "api_key": {
      "title": "API Key",
      "description": "Your API key",
      "type": "string",
      "isRequired": true,
      "isBackendOnly": true
    }
  }
}
 copy

The manifest above will add a setting to the app's admin interface, allowing the admin to set a property called api_key on the app. Here's what that setting will look like in Deskpro:

You can learn more about settings by reading our settings guide.

Proxy

The app proxy allows you to control how your app communicates with third party APIs. It does two main things:

• Allows you to control which URLs and HTTP methods your app can communicate with

• Allows you to inject settings and state values into outgoing requests

Let's look at a simple example:

{
  "name": "my_app",
  "title": "My App",
  "description": "Brief description of my app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": true,
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
    }
  }],
  "proxy": {
    "whitelist": [{
      "url": "https://example.com/api/.*",
      "methods": ["GET", "POST"],
      "timeout": 10
    }]
  }
}
 copy

The manifest above will introduce a proxy rule that will allow your app to send requests to any sub-path of the URL https://example.com/api/.* (note that URLs may be regular expressions). It will also restrict requests to the HTTP methods GET and POST with a maximum timeout of 10 seconds.

You can learn more about the app proxy by reading our proxy guide.

Entity Associations

Entity associations allow us to describe links between "things" in our app to entities in Deskpro, like tickets. Here's a simple example of an entity association between tickets and external IDs (or IDs of "things" in your app, like items from a third party API).

{
  "name": "my_app",
  "title": "My App",
  "description": "Brief description of my app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": true,
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
    }
  }],
  "entityAssociations": {
    "linkedThings": {
      "entity": "ticket",
      "type": "external_id"
    }
  }
}
 copy

In the manifest above we describe the entity association by giving it a name, "linkedThings", and entity "ticket" and a type "external_id". We can then later use the association name in our app code to store and recall links to Deskpro tickets.

You can learn more about entity associations by reading our entity associations guide.

Tab Visibility

The initial visibility of the app's tab may be controlled by setting the canHideWithZeroBadgeCount property in the app manifest. If this is set to TRUE and the app badge count is zero, the app tab will be hidden with the app continuing to run in the background.

{
  "name": "my_app",
  "title": "My App",
  "description": "Brief description of my app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": true,
	"canHideWithZeroBadgeCount": true,
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
    }
  }],
}
 copy