Administrative interface

Zendesk Support administrators need a way to configure the settings of an integration instance. Examples of settings include the authorization information for the origin service, how many comments per post to import into Zendesk Support, or a whitelist of users on the origin service.

You need to build this interface in HTML and host it remotely. Specify the URL of the interface as the admin_ui in the integration manifest. The interface is displayed in an iframe in Zendesk Support.

The admin_ui URL doubles as an endpoint to store data in Zendesk Support and retrieve it. We recommend storing the settings of integration instances in Zendesk Support rather than in your system. See Metadata and state. Use the admin_ui endpoint to exchange the data between your integration service and Zendesk Support. See Data exchange example below.

An admin_ui endpoint is required for each integration service.

Example manifest entry:

...
"urls": {
  "admin_ui": "https://zendesk_experts.com/integrations/instagram/admin_ui",
  ...
}

Data exchange example

1. A Zendesk Support administrator navigates to a page in Zendesk Support to create an integration account. The event triggers a POST request to your admin_ui endpoint with the following information:

   • a return URL
   • the subdomain of the Zendesk Support instance
   • the locale of the Zendesk Support administrator

2. Your integration service uses the information to dynamically change the content of the administrative interface to be iframed in the Zendesk Support instance. For example, it can use the locale to provide a localized version of the interface.

3. The administrator uses the customized admin interface in Zendesk Support to configure the new integration account and submit the values to your integration service. For example, the administrator specifies that their Instagram username is 'omniwear'. This information is called the metadata of the integration account.

4. Your integration service passes the values back to Zendesk Support for storage by returning HTML that POSTs a form containing the relevant data to the return URL provided by Zendesk Support in step 1. Zendesk Support stores the data. It doesn't parse or use it in any way.

5. Later, the Zendesk Support administrator decides to make a change to the integration account. The admin navigates to a page in Zendesk Support to edit the account. The browser makes a POST request to your admin_ui endpoint. The POST body provides the following information to your integration service:

   • the metadata stored in Zendesk Support
   • the integration account's name
   • the state information stored in Zendesk Support, if any
   • the return URL
   • the subdomain of the Zendesk Support instance
   • the locale of the Zendesk Support administrator

6. Your integration service uses the information to dynamically change the administrative interface. For example, it populates the username field with 'omniwear'.

7. The administrator uses the customized admin interface to change the username to 'omniwear_beta' and submits the information to your integration service.

8. Your integration service passes the updated metadata back to Zendesk Support for storage by rendering an HTML form which makes a POST request to the return URL.

Dynamically changing the administrative interface

When an administrator creates or edits an integration account in Zendesk Support, their browser makes a POST request in URL-encoded form post format with the following data to the admin_ui endpoint specified in your integration manifest. Use the information to dynamically adapt the administrative interface for the integration account.

POST format

Name	Type	Comment
metadata	string	Stringified data about the integration instance. Blank for new integration instances. See Metadata and state
state	string	Stringified data about the current state. See Metadata and state
name	string	The name is used to let the user identify this particular instance of the integration in the Zendesk Support interface. Blank for new integration instances
return_url	string	The URL in Zendesk Support to which new values should be posted. See Storing data in Zendesk Support
subdomain	string	Subdomain for invoking the Zendesk API
locale	string	RFC-1766 compatible locale string of the administrator viewing the UI

Examples

Administrator wants to edit an existing account:

name:       Omniwear Instagram
metadata:   {"instagram_username":"omniwear","instagram_oauth_token":"xyzabc"}
state:      {"last_msg":"1234"}"
return_url: https://omniwear.zendesk.com/zendesk/channels/integration_service_instances/editor_finalizer
subdomain:  omniwear.zendesk.com
locale:     zh-TW

Administrator wants to create an integration account:

name:
metadata:
state:
return_url: https://omniwear.zendesk.com/zendesk/channels/integration_service_instances/editor_finalizer
subdomain:  omniwear.zendesk.com
locale:     zh-TW

Storing data in Zendesk Support

You can send admin data back to Zendesk Support for storage by creating an HTML form that POSTs data to the URL specified by the return_url parameter sent by Zendesk Support. For an example of how to POST data, see the admin_ui_2 method in the sample integration on Github.

You can send a name, metadata, and state information. The metadata and state are stored in Zendesk Support. Zendesk doesn't parse or use them in any way. Metadata and state values must be strings. See Metadata and state.

POST format

Zendesk Support expects POST requests containing the following properties. The metadata and state properties must be strings, not JSON objects.

Name	Type	Max chars	Comments
name	string	255	Name of the integration
metadata	string	5000	Stringified data about the integration instance. See Metadata and state
state	string	5000	Stringified data about the current state. See Metadata and state

Example

name:     Omniwear
metadata: {"instagram_username":"omniwear","instagram_oauth_token":"xyzabc","max_comments_per_message":"120","whitelisted_users":"robert,simon"}
state:    {"last_msg":"1234"}