How to

Zendesk

On this page

An app with the Zendesk integration creates a Zendesk ticket for every ticket opened in the app, and it keeps the two in step. This page is for the builder who switches it on, and it says what travels each way. Adding the account is an Admin console task, and the Zendesk quickstart covers it.

Enable the integration

Select Zendesk on the app’s Integrations tab. The tab exists for installed apps only, not for templates.

When the organization has a Zendesk account under Admin console > Apps > Integrations , the panel shows Integrate with Zendesk. Tick that, and a Zendesk Subdomain list appears. Otherwise the panel tells you to add an account. The subdomain is the part of the Zendesk URL before .zendesk.com.

In YAML the settings are the zendesk: block, described in the connector reference. The block has these keys:

  • subdomain (required) must match an account added in the Admin console
  • tag is applied to every Zendesk ticket the app creates. Empty means conclude. The value none applies no tag. A comma-separated list applies several tags. Conclude drops every character other than a letter, a digit, - and _
  • attributeMap entries pair a Zendesk custom field ID (external) with an attribute name (internal). Values are cut at 3000 characters. When you clear an attribute, Conclude clears the field
  • triage.channel names the channel that receives Zendesk internal notes. triage.display is an optional display macro for those notes

What syncs

Opening a ticket in the app creates a Zendesk ticket. Conclude fills it in like this:

  • The title becomes the subject
  • The owner becomes the assignee
  • The acting user becomes the requester. When the ticket has an initiator attribute, that user becomes the requester instead
  • Severity becomes priority. Critical becomes urgent, and the other levels follow in order as high, normal and low. A severity option’s external: value overrides this
  • Conclude also adds the tag, the mapped custom fields, and a private first comment that links to the chat thread

The ID and URL land in the attributes zendesk.id and zendesk.url. Conclude does not import tickets that originate in Zendesk.

From the app to Zendesk, Conclude sends the title, description, owner, initiator, severity, status and mapped custom fields. It also sends comments and files, posted as public comments. Deleting a ticket deletes its Zendesk twin.

From Zendesk to the app, Conclude brings back the subject, assignee, status, priority, mapped custom fields and comments. It brings back the requester only when the ticket has an initiator attribute. Public comments arrive with their attachments. Internal notes become private comments, and Conclude also posts them to the triage channel when one is set. Changes to the ticket type and the tag are not synced.

Status mapping

Concluding a ticket sends Zendesk solved. Reopening it sends pending. Zendesk’s closed is terminal, so a customer reply then spawns a follow-up ticket instead of reopening the old one. Mapping conclude to solved therefore keeps the reopen window intact. In the other direction both solved and closed conclude the ticket.

Changes to the status attribute use the table in the status reference. A status option’s external: value overrides that table.

Next steps

The Zendesk quickstart adds the account and installs the template. Jira is the other two-way integration. Integrations compares the kinds.