Push

If the pull support offered by Zendesk Support is not timely enough for your use case, you can also write code that calls a Zendesk API directly to push content to Zendesk Support. Supporting push is considerably more work than supporting pull so it should only be attempted if you're sure you need it.

Elements of push

You push data to Zendesk Support by making POST requests to a Zendesk API push endpoint. The POST requests must be authenticated by an OAuth token generated by the Channel framework. You must register a client ID with Zendesk Support before the Channel framework can generate tokens on your behalf.

To use push:

1. Create a new global OAuth client as described below, or use a pre-existing client.
2. Set the push_client_id value in the manifest of your service to the unique identifier of your global client.
3. When an administrator uses your UI to create a new integration account, record the subdomain and access token that are passed to your service.
4. Use the subdomain and access token to call the push endpoint as appropriate.

Creating a global OAuth client

1. Create or obtain an OAuth client in Zendesk Support, as described in Using OAuth authentication with your application.
   • The description may not be empty
   • Record the unique identifier and the secret
2. Get your OAuth client promoted to a "global" client by completing the request form as described in Set up a global OAuth client.

Obtaining an access token

When a Zendesk Support administrator sets up or edits an integration account, Zendesk Support will invoke your administrative interface. If your manifest includes a push_client_id entry, Zendesk Support will generate an access token and pass it to your interface. In particular, the following data will be POSTed to your service:

Post field name	Type	Comments
subdomain	string	The subdomain of the Zendesk Support account that's setting up an account with your service
instance_push_id	string	The ID of the account that's being set up. You'll use this when calling the push endpoint
zendesk_access_token	string	The OAuth token to be used when calling the push endpoint. This token cannot be used with other endpoints, and other tokens cannot be used to access the push endpoint

Note that this information is only available to your administrative interface. You should record this information in a secure manner for subsequent use.

Calling the push endpoint

Once you've obtained a subdomain, instance push id, and access token, you can call the push endpoint to synchronously push integration content to Zendesk Support.

Invalid Requests

The push endpoint validates JSON using the Channel Framework schema. Sending the wrong type of JSON values will result in a 400 Bad Request response.

POST /api/v2/any_channel/push.json HTTP/1.1
Host: sample.zendesk.com
Content-Type: application/json

HTTP/1.1 400 Bad Request

{
  "error": {
    "message": [
      "The property '#/external_resources/0' did not contain a required property of 'external_id' in schema file:///bundle/gems/any_channel_json_schemas-0.4.0/json_schemas/external_resource.json#"
    ]
  }
}