DocumentationAPI Reference

Overview

This guide is for developers implementing Zendesk Support Channel integrations. It describes how to build a bi-directional integration service that allows Zendesk Support and an external system to communicate with each other. It also documents the interfaces that an integration service must implement. You may also be interested in the tutorial.

Channel integrations allow Zendesk Support to create tickets and comments from data in external systems such as Facebook, X (formerly Twitter), or Instagram -- to give just a few examples. A channel integration has the following characteristics:

  • The integration mirrors data in an external system to tickets and comments in Zendesk Support.
  • The integration is not hard-coded in Zendesk Support. Zendesk Support calls external services through defined interfaces.
  • The integration is ticket-oriented. It’s not for synchronous communication between agents and their customers, such as chat.

Administrators install a channel integration in Zendesk Support using a Zendesk app that you provide. For more information, see Channel installer app.

Integration workflow

Creating a channel integration generally consists of the following steps:

  • Create the integration service
  • Create a Zendesk app to install the channel integration in Zendesk Support instances
  • Host a manifest file
  • Create and host an HTML administrative interface
  • Create an admin interface endpoint
  • Create a pull endpoint (optional)
  • Create a clickthrough endpoint (optional)
  • Create a channelback endpoint (optional)
  • Create an About page (optional)

Terminology

  • App - A Zendesk app used to package and install a channel in Zendesk Support. Apps are also a delivery mechanism that lets you sell and market your channel in the Marketplace. See Channel installer app.

  • Channelback - Zendesk Support agents may work on tickets that were created from external resources. When they create comments, they may choose to have those comments mirrored to the origin service. This mirroring is called channelback. For example, an agent might be working on a ticket that’s based on an Instagram comment. When the agent makes a comment on the ticket, the system creates a new comment in Instagram containing the text of that Zendesk Support comment. See Channelback.

  • Clickthrough - Links in Zendesk Support tickets that let agents view external resources in the origin system (see below). For example, an Instagram integration might display an Instagram comment in Zendesk Support. The agent can click a link on the comment in Zendesk Support to view the comment in Instagram. See Clickthrough.

  • External resource - Data in the origin service mirrored in Zendesk Support as a ticket or comment. Example: an Instagram comment.

  • Integration service - A service that connects Zendesk Support to an origin service. Think of it as a translator between the origin service's API and the Zendesk API interface described in this doc.

  • Integration instance - A configured integration channel in a Zendesk Support instance. For example, a Zendesk Support admin might install the Instagram integration. Next, they might set up an integration instance for the Instagram user named Omniwear.

  • Metadata - The configuration data for an integration instance. For example, when a Zendesk Support admin sets up an Instagram integration for the Omniwear Instagram account, the Instagram ID for the Omniwear account could be stored in the metadata for that integration instance. See Metadata and state.

  • Origin service - The external system that contains the data to track in tickets in Zendesk Support. Examples: Instagram or Facebook.

  • Pull - A pull request. Zendesk Support makes periodic pull requests to an endpoint in the integration service to find new content. Zendesk Support pulls data from the integration service, not directly from the origin service. See Pull requests.

  • Push - An integration service may push content directly to Zendesk Support, without waiting for it to periodically pull content. See Push.

  • Thread - A set of external resources that go together. Zendesk Support identifies the conversation thread for each external resource when importing it, and uses that information to add the data to the appropriate ticket or comment. A thread roughly corresponds to a ticket in Zendesk Support. See Conversation threads.

Responsibilities and options

When an integration service connects Zendesk Support with an origin service, Zendesk Support will handle scheduling, threading, ticket creation, and event monitoring. Your integration service handles all details of communicating with the origin service.

Third-party data can be integrated by calling Zendesk’s public API. However, the Channel framework handles a lot of details, allowing the integration developer to focus on business logic. It keeps track of state, associates external resources with the correct tickets, allows Zendesk Support agents to send comments back to the origin service, and more.

Security considerations

When making requests to the endpoints provided by your service, Zendesk has no way of knowing how those endpoints are implemented, whether the implementation follows best security practices, or even by whom the implementation was created. Zendesk Support administrators must assess the reliability of an implementation, independent of Zendesk Support, before using it.

Further, Zendesk does not specify how your integration service should validate that requests to your endpoints are actually from Zendesk. You can include secure API tokens in your metadata, include per-integration secrets, or use any other method suitable to your needs. You’re strongly encouraged to carefully consider the security implications of exposing your APIs.

The metadata and state information that Zendesk Support sends with pull and channelback requests could be used by your integration service to determine if the request is legitimate.