Channelback

Channelback allows an agent working in Zendesk Support to reply to a comment received from an origin service and have the reply appear in the origin service. For example, in an Instagram integration, the agent's reply would appear as an additional comment on a photo in Instagram.

To enable the feature, you must build a channelback endpoint and specify its url in the integration manifest. Example:

"urls": {
  "channelback_url": "https://omniwear.com/integrations/instagram/channelback",
  ...
}

Zendesk Support will make a POST request to the endpoint with the agent's reply. The endpoint must implement the request and response formats described in this document. Your endpoint is responsible for creating the external resource -- for example, for posting the agent's comment on Instagram.

Request format

Zendesk Support makes a POST request in URL-encoded form post format with the following information to the channelback_url endpoint specified in your integration manifest.

Name	Type	Max chars	Comments
message	string	65535	The agent's reply
parent_id	string	511	Describes a 'reply to' relationship. Unique ID of the external resource for which this is a response
recipient_id	string	255	Unique identifier of the user that should receive this message in the origin service. May be null if ticket requester has been edited in Zendesk.
metadata	string	5000	Stringified data about the integration instance. See Metadata and state
request_unique_identifier	string	255	A unique identifier for this request. If Zendesk needs to remake the request due to network errors, it will include the same request_unique_identifier.
file_urls	array		Array of URLs to file attachments to the Zendesk reply. Files can be downloaded using the push access token. Only relevant if the manifest indicates support for channelback files.
thread_id	string	511	Arbitrary identifier of the thread to which this item belongs. See Conversation threads

Example

file_urls%5B%5D=https%3A%2F%2Fendgames.zendesk.com%2Fattachments%2Ftoken%2FABCD1234%2F%3Fname%3Dlens.png&message=Please+check+your+camera+lens&metadata=%7B%22instagram_username%22%3A%22endgames_improv%22%2C%22instagram_oauth_token%22%3A%22xyzabc%22%2C%22last_message_id%22%3A%2220151210093200-ben%22%7D&parent_id=20151210093000-ben&recipient_id=b3489&request_unique_identifier=30624700-ACED-4069-BEAD-534202139424&thread_id=234

Decoded string:

file_urls[]=https://endgames.zendesk.com/attachments/token/ABCD1234/?name=lens.png&
message=Please check your camera lens&
metadata={
    "instagram_username":"endgames_improv",
    "instagram_oauth_token":"xyzabc",
    "last_message_id":"20151210093200-ben"
}&
parent_id=20151210093000-ben&
recipient_id=b3489&
request_unique_identifier=30624700-ACED-4069-BEAD-534202139424&
thread_id=234

Response format

If your endpoint successfully creates the external resource, send a response with an HTTP status of 200 and a JSON object that contains the external id of the newly created resource. Zendesk Support uses the external id to prevent duplicate comments.

Name	Type	Max chars	Mandatory	Comments
external_id	string	511	yes	Unique identifier of the external resource that was created (string). The value cannot be empty or null
allow_channelback	boolean		no	If false, prevents the agent from making additional comments on the message in the Zendesk Support interface
metadata_needs_update	boolean		no	Should the Zendesk Support administrator be asked to revisit the UI for the integration account to reset the metadata?
metadata	string	5000	no	Stringified data about the integration instance. See Metadata and state

Example

200 OK
{
  "external_id": "20151210123400-omniwear",
  "allow_channelback": false
}

Reporting channelback errors

When your endpoint is unable to correctly process a channelback POST, you should respond with an HTTP status code in the 500-599 range. Zendesk Support recognizes these responses and informs the Zendesk user about the problem.

If your endpoint accepts the POST and returns a 200 HTTP status code, but you subsequently discover that you cannot fulfill the Channelback response, you may call the channelback error endpoint to report the exception. You should use the same access token that you use to call the push endpoint. See Obtaining an access token.

Invalid requests

The channelback error 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/channelback/report_error.json HTTP/1.1
Host: sample.zendesk.com
Content-Type: application/json

HTTP/1.1 400 Bad Request

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