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.
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.
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
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.
Sweet! You’re now ready to start making API calls and building out your integration 🎉!
Here’s a quick summary of some important things to know about the Zendesk API:
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 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:
Here's an example of how to make a GET request to fetch tickets using the Zendesk API:
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:
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.
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.
Here's an example of how to make a POST request to add a new ticket:
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:
Again, we can use the unified API to avoid having to build this out for multiple ticketing integrations.
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.
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.
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 email@example.com. 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 firstname.lastname@example.org. I’ll be more than happy to personally help.