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