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 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.

Name Type Required Comments
instance_push_id string yes The account ID where 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 255 yes Unique identifier of the external resource. Must be ASCII characters
internal_note boolean no If true creates a new internal note comment
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. Used to choose the correct thread. Responses may include parent_id or thread_id, but not both. See Conversation threads
thread_id string 255 no Arbitrary 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_at string 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 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 If false, prevents the agent from making additional comments on the message in the Zendesk interface
fields array no Array of ticket fields to set in Zendesk and their values. See fields array
file_urls array 10 no Array of files to be imported into Zendesk. See file urls in the Channel framework docs

author object

Name Type Max chars Mandatory Comments
external_id string 255 yes Unique identifier of the user in the origin service
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
fields array no Array 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

Name Type Max chars Mandatory Comments
type string 255 yes Globally unique type identifier defined by the integration origin service. Examples: a GUID or URI
data string 65535 yes JSON 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:

Name Type Comments
results array An 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

Name Type Comments
external_resource_id string The external ID of the resource, as passed in
status object The status of the import for the indicated resource. See status object

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 description in the status object
halted This 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.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      }    ]  }'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.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 "username:password"
	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://support.zendesk.com/api/v2/any_channel/push")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/v2/any_channel/push',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/any_channel/push"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/any_channel/push")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "results": [    {      "external_resource_id": "234",      "status": {        "code": "could_not_locate_parent_external_resource",        "description": "123"      }    }  ]}

Validate Token

  • POST /api/v2/any_channel/validate_token

Allowed For

  • Admins

Request parameters

The POST request takes a JSON object parameter which contains the token to be validated.

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

Response format

The response body is empty.

Code Samples

curl
curl -X "POST" "https://company.zendesk.com/api/v2/any_channel/validate_token" \  -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"  }'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/any_channel/validate_token"	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 "username:password"
	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://support.zendesk.com/api/v2/any_channel/validate_token")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/v2/any_channel/validate_token',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/any_channel/validate_token"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/any_channel/validate_token")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
null

Report Channelback Error to Zendesk

  • POST /api/v2/any_channel/channelback/report_error

Allowed For

  • Admins

Request parameters

The POST request takes a JSON object parameter which contains information about the problematic channelback.

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
external_id string yes Unique identifier of the external resource from the original channelback (string)
description string no A human readable description of the error
request_id string no A unique identifier for the request

Response format

The response does not include a response body

Code Samples

curl
curl -X "POST" "https://company.zendesk.com/api/v2/any_channel/channelback/report_error" \  -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",    "external_id": "234",    "description": "HTML content is not supported",    "request_id": "my_request_123"  }'
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/any_channel/channelback/report_error"	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 "username:password"
	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://support.zendesk.com/api/v2/any_channel/channelback/report_error")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/v2/any_channel/channelback/report_error',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/any_channel/channelback/report_error"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/any_channel/channelback/report_error")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
null