DocumentationAPI Reference

Channel Framework

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

Push Content to Support

  • POST /api/v2/any_channel/push

Pushes Channel framework content to Zendesk.

Allowed For

  • Admins

Request parameters

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

NameTypeRequiredComments
instance_push_idstringyesThe account ID where data will be pushed. This was passed to the integration service when the administrator set up the account
request_idstringnoA unique identifier for the push request
external_resourcesarrayyesThe resources to push

external_resource object

NameTypeMax lengthMandatoryComments
external_idstring255yesUnique identifier of the external resource. Must be ASCII characters
internal_notebooleannoIf true creates a new internal note comment
messagestring65535yesText to be converted to a ticket or comment
html_messagestring65535noHTML version of message
parent_idstring511noUnique identifier of the external resource for which this is a response. Used to choose the correct thread. Responses may include parent_id or thread_id, but not both. See Conversation threads
thread_idstring255noArbitrary identifier of the thread to which this item should belong. Responses may include parent_id or thread_id, but not both. See Conversation threads
created_atstringyesWhen the resource was created in the origin system, as an ISO 8601 extended format date-time. Example: '2015-09-08T22:48:09Z'
authorobjectyesSee author object below
display_infoarraynoArray of integration-specific data used by apps to modify the agent UI. See display_info object below
allow_channelbackbooleannoIf false, prevents the agent from making additional comments on the message in the Zendesk interface
fieldsarraynoArray of ticket fields to set in Zendesk and their values. See fields array
file_urlsarray10noArray of files to be imported into Zendesk. See file urls in the Channel framework docs

author object

NameTypeMax charsMandatoryComments
external_idstring255yesUnique identifier of the user in the origin service
namestring255noIf not supplied, defaults to external id
image_urlstring255noURL to an image for the user
localeString255noThe user's locale. Must be one of the supported locales in Zendesk
fieldsarraynoArray of items containing user field identifier ('id') and value of field ('value'.) For system fields ('notes' or 'details'), the identifier is the English name. For custom fields, the identifier may be the ID or the name

display_info object

NameTypeMax charsMandatoryComments
typestring255yesGlobally unique type identifier defined by the integration origin service. Examples: a GUID or URI
datastring65535yesJSON data containing display hints

fields array

The fields array lists ticket fields to set in Zendesk and their values. Each item consists of a field identifier (id) and a value (value) for the field. For Zendesk system fields such as subject, the identifier is the English name. For custom fields, the identifier may be a field ID or a name. See Ticket Fields.

The fields array can only set ticket values on ticket creation, not on ticket updates.

Response format

The response is a JSON object containing a single key:

NameTypeComments
resultsarrayAn array of result objects

The results array contains 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

NameTypeComments
external_resource_idstringThe external ID of the resource, as passed in
statusobjectThe status of the import for the indicated resource. See status object

status object

NameTypeComments
codestringA code indicating the status of the import of the resource, as described in status codes
descriptionstringIn the case of an exception, a description of the exception. Otherwise, not present.

status codes

KeyDescription
successThe external resource was successfully converted to a ticket or comment
already_importedReimport of the external resource was skipped due to a pre-existing ticket or comment for the resource
could_not_locate_parent_external_resourceThe 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_errorAn internal exception occurred while processing the resource. See description in the status object
haltedThis resource was not processed because processing of previous resources failed

Code Samples

curl 
curl -X "POST" "https://company.zendesk.com/api/v2/any_channel/push" \  -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      }    ]  }'
Go 
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/any_channel/push"	method := "POST"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java 
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/any_channel/push")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs 
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://example.zendesk.com/api/v2/any_channel/push',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console