Zendesk is one of the most well-known customer service tools out there and is used by over 200,000 businesses worldwide. It allows companies to provide customer support via various channels such as text, mobile, phone, email, live chat, and social media, making it an essential tool for effective customer service.

Building a customer-facing Zendesk integration can be a daunting task due to its complex API and the variety of features it offers. Fortunately, we’ve already gone through the headache of building and maintaining a native Zendesk integration and have distilled all of the wisdom and gotchas we’ve picked up over the years into this guide.

If you’re unfamiliar with what native integrations are in the first place, you can reference our previous blog post aptly titled what are native integrations?

Also, please note that this tutorial does not cover Zendesk Sell which is a different product with a different developer account.

I’ll be using the Vessel SDK to build this integration so I don’t have to worry about setting up Auth or handling any Zendesk API quirks. If you don’t want to use Vessel, no worries, I’ve kept this guide as generic as possible and it will be useful regardless of how you decide to build your native Zendesk integration.

Getting Setup For your Zendesk Integration

Before you dive into writing code for your Zendesk integration, there are a few logistical things you’ll want to get out of the way before we can begin making API calls.

Create a Developer Account

To get started, you will need to create a Zendesk Developer Account. A developer account allows you to test out the API without needing to pay and will give you access to demo data.

🔗 For all other Zendesk products see here

🔗 Also be sure to check out the Zendesk Developer community here

Create A Zendesk API Key

While Zendesk does support OAuth2, it’s much quicker to test using API key auth. You can follow the steps below to get an API key.

• Sign up for a trial account and head to the Admin center by clicking the box icon in the top right corner.

• Scroll down to “Zendesk API” in the “Apps and integrations” side bar panel

• Under “Settings” enable Token Access and then click “Add API token”

• Save the token.

Sweet! You’re now ready to start making API calls and building out your integration 🎉!

The Zendesk API at a Glance

Here’s a quick summary of some important things to know about the Zendesk API:

Making an API Call

Now that you’re able to authenticate your user, you can begin making API calls to their Zendesk account. In this section, we’ll explore how to read and write to the Zendesk API in real time.

Reading From the API

Reading data from the Zendesk API is a common use case for integrations. You may need to retrieve ticket information, user details, or organization data to display in your application.

When reading from the Zendesk API, there are a few gotchas to be aware of:

• API Variety: Zendesk has a pretty large variety of API types for each of the APIs support including streaming, firehose, and event APIs which each come with their own set of tradeoffs. We’ll only be using the regular RESTful APIs but you should read over the others in case they fit your use case better.
• Domain prefix: Every Zendesk API call must be prefixed with your customer’s “subdomain”. which can be found at the start of the url in the browser when the user is logged into their Zendesk account.

Through Zendesk API

Here's an example of how to make a GET request to fetch tickets using the Zendesk API:

const domain = "CUSTOMER_ZENDESK_SUBDOMAIN";
const url = `https://${domain}.zendesk.com/api/v2/tickets.json`;
const email = "customer_email@company.com";
const apiKey = "CUSTOMER_API_KEY";
const token = `${email}/token:${apiKey}`;

const response = await fetch(url, {
  headers: {
    'Authorization': `Basic ${Buffer.from(token).toString('base64')}`
  }
});

const data = await response.json();
console.log(data);

With Vessel

If you're using the Vessel SDK, you can simplify the process of making API calls to Zendesk. Here's an example of how to use the Vessel SDK to fetch a list of tickets:

import Vessel from '@vesselapi/sdk';

const vessel = Vessel({
  apiKey: process.env.API_KEY,
  accessToken: "YOUR_CUSTOMERS_ACCESS_TOKEN"
});

const response = await vessel.unifications.zendesk.tickets.list();

Note that we can use the unified API for this call so that we don’t have to rebuild this flow if we want to support other ticketing tools.

Writing to the API

In addition to reading data, you may also need to write data to the Zendesk API. This can include creating new tickets, updating ticket properties, or adding comments to existing tickets.

Through Zendesk API

Here's an example of how to make a POST request to add a new ticket:

const domain = "CUSTOMER_ZENDESK_SUBDOMAIN";
const url = `https://${domain}.zendesk.com/api/v2/tickets.json`;
const email = "customer_email@company.com";
const apiKey = "CUSTOMER_API_KEY";
const token = Buffer.from(`${email}/token:${apiKey}`).toString('base64');

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${token}`,
    'Content-Type': 'application/json'
   },
   body: JSON.stringify({
     ticket: {
       subject: 'My new ticket',
       comment: {
         body: 'The server is on fire.' 
       }
     }
   })
});

const data = await response.json();
console.log(data);

With Vessel

If you're using the Vessel SDK, you can simplify the process of making API calls to the Zendesk API. Here's an example of how to use the Vessel SDK to add a new ticket:

import Vessel from '@vesselapi/sdk';

const vessel = Vessel({ 
  apiKey: process.env.API_KEY,
  accessToken: "YOUR_CUSTOMERS_ACCESS_TOKEN"
})

const response = await vessel.unifications.ticketing.tickets.create({
  subject: 'My new ticket',
  comment: {
    body: 'The server is on fire.'
  }
});

console.log(response);

Again, we can use the unified API to avoid having to build this out for multiple ticketing integrations.

Implementing OAuth

While API key authentication is great for testing, you should always use OAuth for customer-facing integrations when it’s supported.

Unfortunately, building an OAuth application that other Zendesk instances can connect to requires going through an approval process so it’s best to start now. Zendesk calls these OAuth apps “Global OAuth Clients” and you can read about them here.

Before you build a global OAuth client and get your app approved, you’ll need to build out a general OAuth flow.

OAuth is a complicated and nuanced topic, for brevity, I’m not going to touch on how to build out an OAuth flow since it’s not Zendesk-specific.

If you’re new to OAuth and just need to get something going fast or don’t want to deal with the notorious headache of OAuth, you can use a framework like Vessel to handle it for you.

If you’d prefer to do this yourself, you can read the Zendesk OAuth tutorial which is pretty thorough. Forewarning, the tutorial is very Zendesk specific so if you know you’ll need to build other integrations in the future, I’d invest in doing more research so you understand how to build a more generic Auth flow since OAuth is an infamously difficult problem.

Closing Thoughts

Publishing your Application

Once you've completed building your integration, you may want to consider publishing your application. Publishing your application allows other Zendesk customers to discover and use your integration, giving you more exposure and potential users.

To publish your Zendesk application, you'll need to register and submit your integration for review. Once approved, your application will be listed in the Zendesk Marketplace, where users can find and install it.

About Us

Hopefully, you found this article helpful for building out your native Zendesk integration. I know I certainly wish something like this existed when we built out our Zendesk integration.

If you decided to give Vessel a spin while following this tutorial, thank you. If you have any feedback while using the SDK, don’t hesitate to reach out at support@vessel.dev. We’re a team of engineers at heart and take every piece of feedback extremely seriously.

If you’re curious to learn more about why we started Vessel and how we view the future of customer-facing integrations, you can read more in our “what are native integration platforms” post.

On that note, if you ever have any questions about building a Zendesk integration while you’re going through this tutorial, don't hesitate to reach out at zach@vessel.dev. I’ll be more than happy to personally help.