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)
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#"
    ]
  }
}