Channel Framework

The Channel framework lets you build two-way ticket-creation services between Zendesk Support and an external system such as Facebook, Twitter, or Instagram -- to give just a few examples. For more information, see the Channel Framework developer docs.

Push Channel framework content to Zendesk Support

POST /api/v2/any_channel/push

Allowed For
  • Admins
Using curl
curl -X "POST" "https://company.zendesk.com/api/v2/any_channel/push.json" \
 -H "User-Agent: Zendesk SDK for Android" \
 -H "Authorization: Bearer 51b8f8c894514abab0cf4705d414ffd2760589a5dcdb9d2bc812ca0635b402ec" \
 -H "Content-Type: application/json" \
 -H "Accept: application/json" \
 -d $'{
   "instance_push_id": "d448ef2f-8f51-4fbd-a5d1-9a53d2c8a3c1",
   "request_id": "my_request_123",
   "external_resources": [
     {
       "external_id": "234",
       "message": "A useful comment",
       "html_message": "A <b>very</b> useful comment",
       "parent_id": "123",
       "created_at": "2015-01-13T08:59:26Z",
       "author": {
         "external_id": "456",
         "name": "Fred",
         "locale" : "de"
       },
       "display_info": [
         {
           "type": "9ef45ff7-4aaa-4a58-8e77-a7c74dfa51c4",
           "data": { "whatever": "I want" }
         }
       ],
       "allow_channelback": true
     }
   ]
 }'
Example Response
Status: 200 OK

{
  "results":[
    {
      "external_resource_id": "234",
      "status":
      {
        "code": "could_not_locate_parent_external_resource",
        "description": "123"
      }
    }
  ]
}
Request parameters

The POST request takes a JSON object parameter which contains data about all of the resources that the client is pushing.

Name Type Required Comments
instance_push_id string yes The ID of the account to which data will be pushed. This was passed to the integration service when the administrator set up the account.
request_id string no A unique identifier for the push request
external_resources array yes The resources to push
external resource object
Name Type Max length Mandatory Comments
external_id string 511 yes Unique identifier of the external resource (string)
message string 65535 yes Text to be converted to a ticket or comment
html_message string 65535 no HTML version of message
parent_id string 511 no Unique identifier of the external resource for which this is a response (string). Used to choose the correct thread. Responses may include parent_id or thread_id, but not both. See Conversation threads
thread_id string 511 no Arbitrary identifier of the thread to which this item should belong (string). Responses may include parent_id or thread_id, but not both. See Conversation threads
created_at datetime string in ISO 8601 format yes When the resource was created in the origin system, as an ISO 8601 extended format date-time. Example: '2015-09-08T22:48:09Z'
author author object yes See author object below
display_info array no Array of integration-specific data used by apps to modify the agent UI. See display_info object below
allow_channelback boolean no Boolean. If false, prevents the agent from making additional comments on the message in the Zendesk Support interface
fields array no Array of items containing field identifier ('id') and value of field ('value'.) For system fields, such as 'subject', the identifier is the English name. For custom fields, the identifier may be the ID or the name.
file_urls array 10 no Array of URL strings. Format of string must be a relative URL or an https URL.
author object
Name Type Max chars Mandatory Comments
external_id string 255 yes Unique identifier of the user in the origin service (string)
name string 255 no If not supplied, defaults to external id
image_url string 255 no URL to an image for the user
locale String 255 no The user's locale. Must be one of the supported locales in Zendesk Support
display_info object
Name Type Max chars Mandatory Comments
type string 255 yes Globally unique type identifier defined by the integration origin service (string). Examples: a GUID or URI
data string 65535 yes JSON data containing display hints
Response format

The response is a JSON object containing a single key:

Name Type Comments
results array An array of result objects

The results array will contain an entry for each item in the incoming external_resources array, in the same order. For example, if you call push with 3 external resources, a successful response will include results with three entries, corresponding to your 3 resources.

result object
Name Type Comments
external_resource_id string The external ID of the resource, as passed in
status status object The status of the import for the indicated resource
status object
Name Type Comments
code string A code indicating the status of the import of the resource, as described in status codes
description string In the case of an exception, a description of the exception. Otherwise, not present.
status codes
Key Description
success The external resource was successfully converted to a ticket or comment
already_imported Reimport of the external resource was skipped due to a pre-existing ticket or comment for the resource
could_not_locate_parent_external_resource The parent resource, as identified by parent_id in the request, could not be found. The unrecognized parent ID is returned in the description of the status
processing_error An internal exception occurred while processing the resource. See the description if the status
halted This resource was not processed because processing of previous resources failed