Authenticating Proxy

When you create a Zendesk Support Channel integration, you also create a Zendesk app that administrators use to discover and install your integration. That Zendesk app may not have any agent-visible user interface. However, you may choose to empower agents by adding functionality to the app. For example, if you make an Instagram integration, you might want to display a heart icon that indicates if the Instagram user has "liked" the photo. When an agent clicks on the heart icon, your integration "likes" the photo as the Instagram user associated with the account.

The Zendesk app can't call the integration service or the origin service directly, but it can use Zendesk as a proxy to call the integration service on its behalf.

What does the proxy do, and for whom?

This is a bit confusing, as there are a number of interested parties, including:

1. The Zendesk Support agent, who may or may not have an Instagram account

2. The Zendesk Support administrator, who set up the Instagram integration in their Zendesk Support account

3. The Instagram user identified by the Zendesk Support administrator. This is typically an account for a business, such as the Omniwear Instagram account.

4. The Instagram integration, which connects to the Instagram API as a specific user (e.g. as the Omniwear Instagram account)

When the Zendesk Support agent clicks on the "like" button in the Zendesk app, they're not indicating that they personally like the photo. Instead, they're indicating that the photo should be "liked" by the integration on behalf of their Zendesk Support account. For example, the Omniwear Instagram account should be the one doing the liking.

How would the Zendesk app implement this "like" button? It doesn't know which Instagram account it should use, and it certainly doesn't have authentication information, such as the username or password.

The application cannot call through to Instagram directly. It cannot even call through to the integration service directly, as it doesn't have authentication information. However, it can call Zendesk, which can call through to the integration service on its behalf.

The application, acting on behalf of the agent, calls Zendesk. Zendesk then calls the integration service, passing along authentication information that was set up by the Zendesk Support administrator. The integration service uses the authentication information supplied by Zendesk to connect to the Instagram API and perform the appropriate "like" operation.

Of course, setting data isn't the only problem. The application also wants to know if the "like" button should be in the "currently liking" state, or in the "currently not liking" state. The application needs to get that information from Instagram. This also requires authentication -- essentially the same problem as setting the "like" state.

POSTing data to Zendesk for the integration service

Zendesk allows applications to POST JSON to the /api/v2/any_channel/proxy.json endpoint. When calling the endpoint, the application will supply the ticket ID and desired endpoint in as query string parameters. The POSTed body should be JSON that will be passed through to the integration service, and may be blank. The query string parameters are:

Parameter	Type	Max chars	Comments
ticket_id	string		The ID of the Zendesk ticket that the application is displaying to the agent
post_to_path	string	511	The URL in the integration service that the application wishes to POST to. If relative, it is interpreted as relative to the manifest URL. Must be an HTTPS URL hosted on the same domain as the manifest.

Example:

curl -X "POST" 'https://{subdomain}.zendesk.com/api/v2/any_channel/proxy.json?ticket_id=62&post_to_path=/like' \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -d $'{
   "liked": "true"
 }'

What Zendesk passes to the integration service

When an application posts data to the proxy endpoint in Zendesk, Zendesk passes the data through to the integration service. It supplements that data with the metadata from the integration instance. Zendesk POSTs the following parameters to post_to_path in the integration service:

Parameter	Type	Comments
instance_metadata	string	Metadata from the integration instance associated with the ticket ID passed to the proxy endpoint
client_data	string	JSON body of the original POST from the application to the Zendesk proxy endpoint

Any JSON response from the integration service is passed back to the caller.