Integration manifest
Each integration must present a manifest at a known public URL. The manifest describes the capabilities of the integration and provides information that Zendesk Support needs to interact with the integration.
You specify the manifest's URL in the app you build to install the integration in Zendesk Support. For more information, see Channel installer app.
Changes to your manifest are not applied immediately. Zendesk Support polls your manifest, and changes are applied after a poll. For example, if you change the pull_url for your integration, Zendesk Support may continue to connect to the old URL for multiple hours. To avoid outages, when you make changes to your service, you should maintain backwards compatibility for at least a few days. Zendesk Support will follow 301 Moved Permanently redirects for your manifest URL.
Manifest format
The manifest is represented as a JSON object with the following keys.
| Name | Type | Max chars | Mandatory | Comment |
|---|---|---|---|---|
| name | string | 255 | yes | The name of the integration. Used as the default name of the Channel integration in Zendesk Support |
| id | string | 511 | yes | A unique identifier for the integration. A unique URI or GUID is recommended |
| version | string | 255 | no | Version of this manifest. Zendesk Support uses this to discover if the local cache of manifest data is out of date |
| author | string | 255 | no | Name of the author or owner as a plain text string |
| push_client_id | string | 127 | no | The ID of the OAuth client used to generate a token for push support. See Push |
| channelback_files | boolean | no | Does this integration support Channelbacks with file attachments? | |
| create_followup_tickets | boolean | no | When the integration returns a thread_id that corresponds to an existing closed Zendesk ticket, and Zendesk creates a new ticket, should it be marked as a "followup" ticket? Most integrations should use true, but messaging or chat oriented integrations might use false. Defaults to true | |
| urls | object | yes | See the urls object below |
urls object
URLs are represented as a JSON object with the following keys. All URLs must be SSL. Relative URLs are supported, and will be interpreted as being relative to the URL of the manifest itself.
| Name | Type | Max chars | Mandatory | Comment |
|---|---|---|---|---|
| admin_ui | string | 511 | yes | URL to the HTML interface that Zendesk Support administrators use to configure the integration. See Administrative interface |
| pull_url | string | 511 | no | Zendesk Support makes periodic requests to this endpoint to import new content. See Pull requests |
| channelback_url | string | 511 | no | When an agent adds a response in Zendesk Support, a POST request is made to this endpoint to push the comment back to the origin service. See Channelback |
| clickthrough_url | string | 511 | no | Agents click a link to this endpoint to see the external resource in the origin system. See Clickthrough endpoint |
| about_url | string | 511 | no | Zendesk Support administrators can follow this URL to get a rich description of the service |
| dashboard_url | string | 511 | no | Zendesk Support administrators can follow this URL to see detailed information about the status of the service, such as uptime or recent exceptions |
Not specifying an optional URL disables the feature in the integration.
Example
{"name": "Instagram Integration","id": "zendesk-internal-instagram-integration","author": "Jared Shay","version": "v3.7.5","channelback_files": true,"create_followup_tickets": true,"urls": {"admin_ui": "https://omniwear.com/integrations/instagram/admin_ui","pull_url": "https://omniwear.com/integrations/instagram/pull","channelback_url": "https://omniwear.com/integrations/instagram/channelback","clickthrough_url": "https://omniwear.com/integrations/instagram/clickthrough"}}