Manifest reference

Manifest reference

The manifest.json file is used to configure your app. Example:

{  "name": "My App",  "author": {    "name": "Jean Thompson",    "email": "[email protected]",    "url": "https://www.omniwear.com/profiles/jthompson"  },  "defaultLocale": "en",  "private": false,  "location": {    "support": {      "background": "assets/iframe.html",      "ticket_sidebar": {        "autoLoad": false,        "flexible": true      },      "top_bar": {        "autoHide": true,        "url": "assets/top_bar.html",        "size": {          "width": "450px",          "height": "500px"        }      }    }  },  "domainWhitelist": ["omniwear.com"],  "parameters": [    {      "name": "token",      "type": "text",      "secure": true,      "required": true    }  ],  "version": "1.0",  "frameworkVersion": "2.0"}

Manifest properties

• name
• author
• version
• frameworkVersion
• location
• gaID
• defaultLocale
• parameters
• domainWhitelist
• private
• requirementsOnly
• singleInstall
• signedUrls
• termsConditionsURL
• experiments
• marketingOnly
• oauth

name

Specifies a name for the app. The name is used in the header of the app when it's visible when running the app locally on a ZCLI server.

author

Required. Specifies the author of the app. The property contains a JSON object with values for "name", "email", and "url".

"author": {  "name": "The Mentor",  "email": "[email protected]",  "url": "http://www.company.com/profiles/mentor"},

The name can be an individual or a company name. The email should be the address where users of the app can send support requests. The url can point to a page about the author or the app.

version

Specifies a version number for the app. The version number will be displayed alongside your app details in the Zendesk Marketplace.

frameworkVersion

Required. Specifies the framework version used to build your app. See Understanding framework versions.

"frameworkVersion": "2.0",

location

Required. Specifies where the app appears in the product interface, and per-location options. See Setting the app location. Locations vary by product. For the locations in Zendesk Support, see:

• Support Apps API
• Chat Apps API
• Sell Apps API

You can specify multiple locations for an app. Also, some framework APIs are available only to apps in certain locations. For example, only apps appearing on the ticket page in Zendesk Support can get and set ticket properties, and listen for changes to the ticket.

Properties that may be specified for each location:

• autoHide specifies whether the app starts as hidden on first load
• autoLoad specifies whether the iframe is automatically loaded (defaults to true)
• flexible specifies whether the iframe is responsive. This property only applies to apps in the ticket_sidebar and new_ticket_sidebar locations. If true, the iframe automatically resizes to match the apps tray's width as it changes. If false, the iframe stays fixed to the default width of 320px. Defaults to true.
• signed specifies whether to use signed URLs
• url specifies the URL of the page to display in the iframe at that location
• size specifies the initial size of the app to display in the iframe at that location. Some locations have size restrictions that override this property. For example, the width of an app in the ticket sidebar is restricted to 320px and can't be changed.

Example:

"location": {  "support": {    "ticket_sidebar": {      "autoHide": true,      "flexible": true,      "signed": true,      "url": "https://myapp.example.org/",      "size": {        "height": "220px"      }    }  }},

Optionally, to leave all other options as defaults, you can specify only the url property as a string. Example:

"location": {  "support": {    "ticket_sidebar": "assets/iframe.html"  }},

You can also specify multiple locations across Zendesk products in your manifest file (currently only Zendesk Support and Zendesk Chat are supported). Example:

"location": {  "support": {    "ticket_sidebar": "assets/iframe.html"  },  "chat": {    "chat_sidebar": "assets/chat_iframe.html"  }},

It is also possible to use any setting in the url (except for secure settings).

"location": {  "support": {    "ticket_sidebar": "http://{{setting.domain}}.my_server.com/iframe.html"  },  "chat": {    "chat_sidebar": {      "url": "{{setting.url}}"    }  }},

gaID

Specifies a Google Analytics tracking id if you want to analyze how many visitors view your app's detail page on the Zendesk Marketplace.

You may only use one of the following options:

Option 1

If you’re using Universal Analytics (UA), provide your UA code:

"gaID": "ua-12345"

Option 2

If you’re using Google Analytics 4 (GA4), provide your GA4 code:

"gaID": "G-12345",

If using GA4, you also need to turn off the ignore duplicates setting in your GA4 property as follows.

1. Go to your Google Analytics account.
2. Navigate to GA4 Property Settings > Data Streams > Data Stream Details.
3. On the Data Stream Details page, select Google Tag - Configure Tag Settings > Admin > Manage Google Tag - Additional Settings.
4. Uncheck the ignore duplicate setting.

defaultLocale

Required. Sets the default locale of the app. While still required, this value is not actively used in the Zendesk Apps framework v2. It is up to you to determine how internationalization tasks are implemented and managed.

The value must be a two- or three-letter ISO 639 language code.

"defaultLocale": "en",

The app can support any number of additional languages. If the agent selects a language the app doesn't support, the app is displayed in the default locale. For details, see Internationalization.

parameters

Defines settings you want your users to set for your app during installation. See Defining installation settings. Example:

"parameters": [  {    "name": "subdomain",    "type": "text",    "required": true  },  {    "name": "useSSL",    "type": "checkbox"  }]

domainWhitelist

Specifies a domain whitelist if you make one or more of your app settings secure. For details, see Using secure settings.

"domainWhitelist": ["www.example.com", "api.example.com"],

The setting prevents attackers from hijacking the secure setting to reroute it to another domain and hijack the token or password.

Omit this property if not making secure requests.

The domainWhitelist entries also support interpolation of setting values to customize the whitelist on a per installation basis. To specify a setting value in a domain whitelist entry, use double curly brackets. Example:

"domainWhitelist": ["{{setting.subdomain}}.example.com"],

private

Sets whether the app is private or not. By default, an app without this property is treated as private, and therefore can only be installed in the app developer's account.

"private": true,

When submitting an app to the Zendesk Marketplace, this property must be false.

requirementsOnly

Specifies that the app's only job is to create resources in a Zendesk Support instance. See Creating a requirements-only app.

"requirementsOnly": true,

singleInstall

Specifies that each account can only have one installation of the app at a time.

"singleInstall": true,

If in doubt, omit this property or set it to false.

signedUrls

When true, Zendesk includes a JWT token in the HTTP request it makes for the initial page of a server-side app. The page is specified by the url in the location object. See Authenticating Zendesk in your server-side app. This property doesn't apply to client-side apps.

You can add "signedUrls": true to the top-level manifest object:

{  "name": "My App",  "signedUrls": true,  ...}

The property applies to the app in all locations in the manifest's location object. If you want the feature to be enabled only in a specific location, add "signed": true to the named location in the location object:

..."location": {  "support": {	"ticket_sidebar": {	  "signed": true,	  "url": "https://myapp.example.org/"	}  }},

termsConditionsURL

If you plan on listing a paid app in the Zendesk Marketplace, you must provide a link to your Terms & Conditions.

"termsConditionsURL": "https://www.mycompany.com/terms.html"

experiments

Enables the app to opt-in to various app framework experiments that may be available from time to time. These features are experimental, and their API, usage or definition may change.

Available experiments:

• hashParams - set to true to send the parameters to ZAF SDK using hash urls to improve cacheability

"experiments": {  "hashParams": true}

marketingOnly

Integration apps are built for a third-party product. These apps are discoverable in the Zendesk Marketplace but cannot be installed like regular apps. If you plan on submitting integration apps in the Zendesk Marketplace, you will need to provide a zip file with marketing assets along with a simple manifest that specifies { "marketingOnly": true }. The manifest file doesn't require a frameworkVersion property.

You can also choose which Zendesk products the integration app can be used in by specifying a { "location": {} } object in your manifest.

Note: if you do not specify a { "location": {} } object in your manifest, the default product is Zendesk Support.

For more information see Submitting integration apps.

Example Zendesk Support integration app:

{  "name": "WordPress",  "author": {    "name": "Zendesk",    "email": "[email protected]",    "url": "https://www.zendesk.com"  },  "location": {    "support": {    }  },  "defaultLocale": "en",  "marketingOnly": true,  "private": false}

Example Zendesk Chat integration app:

{  "name": "WordPress",  "author": {    "name": "Zendesk",    "email": "[email protected]",    "url": "https://www.zendesk.com"  },  "location": {    "chat": {    }  },  "defaultLocale": "en",  "marketingOnly": true,  "private": false}

Example Zendesk Sell integration app:

{  "name": "WordPress",  "author": {    "name": "Zendesk",    "email": "[email protected]",    "url": "https://www.zendesk.com"  },  "location": {    "sell": {    }  },  "defaultLocale": "en",  "marketingOnly": true,  "private": false}

Example multi-product integration app:

{  "name": "WordPress",  "author": {    "name": "Zendesk",    "email": "[email protected]",    "url": "https://www.zendesk.com"  },  "location": {    "support": {    },    "chat": {    }  },  "defaultLocale": "en",  "marketingOnly": true,  "private": false}

oauth

If your app uses OAuth to make API requests to a third-party product, you must specify the details using this property and add a parameter of type "oauth".

If this property is specified, users will go through the OAuth authentication flow during installation of the app.

You can then use the parameter to access the OAuth access token in your app code. See Managing third-party OAuth access tokens.

• client_id - Required.
• client_secret - Required.
• authorize_uri - Required. You can use {{oauth_url_subdomain}} as a placeholder if the user's subdomain is required. The user will be asked to enter a subdomain during the OAuth authentication flow.
• access_token_uri - Required. You can use {{oauth_url_subdomain}} as a placeholder if the user's subdomain is required. The user will be asked to enter a subdomain during the OAuth authentication flow.
• scope - Optional.

Note: This feature cannot be used to make API requests using OAuth to other Zendesk Support instances or other brands within an instance. The proxy layer does not allow access to other Zendesk instances.