Skip to content
Blackbird docs

Zendesk

View on Github

Zendesk is a customer service solution provider. Its feature set includes ticketing, chat, helpdesk articles and a Sales CRM. This Zendesk app primarily focusses on helpdesk articles and its localization features. It also includes actions for tickets.

Before setting up

Before you can connect you need to make sure that:

  • You have a Zendesk account on the instance you want to connect to.
  • Your Zendesk account has the right permissions. It is recommended that you have the admin role for Zendesk guide. Furthermore, if you want to setup event triggers you will need to have either the admin role for Zendesk suppport or you need to have a custom role with permission to manage webhooks.

Connecting

  1. Navigate to apps and search for Zendesk.
  2. Click Add Connection.
  3. Name your connection for future reference e.g. ‘My client’.
  4. Fill in the Base URL to the Zendesk instance you want to connect to. The base URL is of shape https://<instance name>.zendesk.com. You can usually copy this part of the URL when you are logged into your Zendesk instance. Note: for different brands see disclaimer below.
  5. Click Authorize connection.
  6. Follow the instructions that Zendesk gives you, authorizing Blackbird.io to act on your behalf.
  7. When you return to Blackbird, confirm that the connection has appeared and the status is Connected.

Connecting

Connecting to different brands: If your Zendesk has multiple brands, you need to create a different connection for each separate brand. Brands are distinct by their base URL. You can find the base URL by going to Settings > Account > Brand management > Brands and viewing the Subdomain attribute of each brand. Use the Subdomain attribute in the Base URL connection input.

1738163882548

Actions

General

  • Search helpcenter locales returns both the default locale of the helpcenter, as well as the list of locales that have been configured in Zendesk. You can find these settings in the Zendesk help center > Settings > Language settings.

Articles

  • Search articles search articles using various filter parameters
  • Get/create/update/archive article (metadata) used to configure metadata variables such as section, author, position, permission group, user segment, etc.
  • Search article missing locales returns a list of locales that have been configured in Zendesk but are not present for this article. It can be used to create the missing translations.
  • Download article content downloads the translatable content of an article as a file. Use this action in conjunction with some translation app and ‘Upload article content’.
  • Upload article content updates the translation for an article, creates a new translation if there is none. Takes a translated file (HTML) as input. As the article ID is included in the head of the HTML file, it will update the correct article, but you can specify the Article ID in the action as well.
  • Add label to article on a professional or enterprise plan, it adds a label to an article.
  • Delete label from article on a professional or enterprise plan, it deletes a label from an article.

HTML articles

Categories

  • Get all categories returns all categories on this Zendesk instance. You can also specify the Missing translation in variable, in which case this action will only return categories that are actually missing translations in that language.
  • Get category articles returns all articles in this category.
  • Create/update/delete category.
  • Get category missing translations returns a list of locales that have been configured in Zendesk but are not present for this category. It can be used to create the missing translations.
  • Update category translation creates a translation if there is none, or updates the translation if it already exists.

Sections

  • Get all sections returns all sections on this Zendesk instance. Optionally you can also specify the category, which will limit the search to that specific category. You can also specify the Missing translation in variable, in which case this action will only return sections that are actually missing translations in that language.
  • Create/update/delete section.
  • Get section missing translations returns a list of locales that have been configured in Zendesk but are not present for this section. It can be used to create the missing translations.
  • Update section translation creates a translation if there is none, or updates the translation if it already exists.

Tickets

  • Create/update/delete ticket.

Events

  • On article published is the most useful event. This event is triggered when any article is published and could be the perfect trigger for sending the article for translation based on the missing translations (see example). It has an optional parameter Only source articles which, if true, will only trigger the bird if the source locale of the article is published. This is helpful to not create infinite publish loops of translations.
  • Other events for article comments, subscriptions, votes and user events.

Example

example This example shows one of many use cases. Here, whenever an article is published we fetch the missing translations and retrieve the article as an HTML file. Then we create a new Lokalise project with the missing locales as the target languages and upload the article. Then we send a Slack message to notify the project manager.

Missing features

Most content related actions exist. However, in the future we can add actions for:

  • Article attachments
  • Topics and Posts
  • Comments
  • Subscriptions
  • Votes
  • In depth tickets

Let us know if you’re interested!

Feedback

Feedback to our implementation of Zendesk is always very welcome. Reach out to us using the established channels or create an issue.