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:
- Create a new global OAuth client as described below, or use a pre-existing client.
- Set the
push_client_idvalue in the manifest of your service to the unique identifier of your global client.
- When an administrator uses your UI to create a new integration account, record the subdomain and access token that are passed to your service.
- Use the subdomain and access token to call the push endpoint as appropriate.
Creating a global OAuth client
- 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
- 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.
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
HTTP/1.1 400 Bad Request
"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#"