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": "",  ...}

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.

NameTypeMax charsComments
messagestring65535The agent's reply
parent_idstring511Describes a 'reply to' relationship. Unique ID of the external resource for which this is a response
recipient_idstring255Unique identifier of the user that should receive this message in the origin service. May be null if ticket requester has been edited in Zendesk.
metadatastring5000Stringified data about the integration instance. See Metadata and state
request_unique_identifierstring255A 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_urlsarrayArray 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_idstring511Arbitrary identifier of the thread to which this item belongs. See Conversation threads


Decoded string:

file_urls[]= 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.

NameTypeMax charsMandatoryComments
external_idstring511yesUnique identifier of the external resource that was created (string). The value cannot be empty or null
allow_channelbackbooleannoIf false, prevents the agent from making additional comments on the message in the Zendesk Support interface
metadata_needs_updatebooleannoShould the Zendesk Support administrator be asked to revisit the UI for the integration account to reset the metadata?
metadatastring5000noStringified data about the integration instance. See Metadata and state


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.1Host: sample.zendesk.comContent-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#"    ]  }}