Summary
Data you can sync
Sync Zendesk tickets into Planhat; ticket labels and fields can be included
Display key customer data from Planhat back in Zendesk via separate app
Sync direction
Tickets: Zendesk → Planhat
Company and End User data (display only, via separate app): Planhat → Zendesk
Sync frequency
Zendesk → Planhat: near instantly, on both create and update
Initial manual fetch of 6 months’ history
Planhat → Zendesk (separate app): customer info retrieved when tickets are viewed in Zendesk
Data mapping
See table below
Who is this article for?
All Planhat users
It's particularly relevant to those setting up the Zendesk integration
Series
Setting up the Zendesk integration ⬅️ You are here
Article contents
Extra technical details:
Introduction
Planhat's Zendesk integration makes it really easy for you to sync your tickets into Planhat. After an initial manual sync of historical tickets, new/updated tickets will automatically sync in.
Within Planhat, you can view your tickets alongside other conversations, such as emails and meetings. It's simple to filter your view (e.g. see the highest priority tickets), and to tag in colleagues to collaborate.
You can also visualise and analyse time-series ticket data, making it easy to track changes and trends over time. You can perform calculations on ticket data, and blend with other data types in Planhat for deeper customer insights and to take action on your data. You can display your ticket data in customisable dashboards, and use ticket data to trigger Automations. For example, if the ratio of ticket volume v. contract value crosses a threshold, create a review task.
🚀 Tip:
In addition to the main integration syncing tickets into Planhat, there is also a Planhat app in the Zendesk Marketplace, which enables you to visualise some Company and End User properties alongside your tickets in Zendesk, to enable a better understanding of your customers! When your Support team views a ticket in Zendesk, they can therefore prioritise Companies with poor Health Score or high MRR, for example, which is super useful. To learn more, see here.
Data mapping
Planhat model | Sync direction | Zendesk |
Conversation (type "ticket") | From Zendesk to Planhat | Ticket |
Company and End User * | From Planhat to Zendesk | In Planhat app on ticket view |
* Specific information displayed only
How does the sync work?
Mapping tickets to customers
Tickets are synced into Planhat if they can be mapped to End Users, via their email address (e.g. bob@pendo.com).
If a ticket is received by Planhat and the End User already exists in your Planhat tenant, then the ticket will be synced in and mapped to them.
If the End User doesn't yet exist in your Planhat tenant, but the Company does (e.g. Pendo in this case, as identified by the email domain), Planhat can automatically create the End User on that Company, and then sync in the ticket. It's your choice whether you would like Planhat to create End Users from external conversations like this - it's configured per tenant. You can view your current setting under "Automatic Detection of New Contacts" within "General Settings"; speak to your CSM if you would like to enable or disable this.
Manual sync for historical tickets
There is a button in the integration to manually "Fetch All Tickets". This is typically used when you first set up the integration, in order to sync past tickets into Planhat. The historical sync brings in the previous 6 months of tickets (excluding tickets already solved/closed).
This manual sync may also be used later on, if new End Users are added to Planhat using a different method than the Zendesk integration, and then you want to sync in their historical tickets. However, note that if you have made updates to other tickets in Planhat, these could be overwritten.
Ongoing sync for new/updated tickets
Going forward, tickets that are new or updated in Zendesk will automatically sync into Planhat, in near real time.
Remember that tickets can only sync in if they can be associated with an End User via the email address (as described above).
Setting up the integration
📌 Important to note:
These are instructions for setting up the main Zendesk integration, which syncs tickets into Planhat (one-way). To learn more about how to display some Planhat customer information in Zendesk, see here.
Go to the Zendesk integration in Planhat
Click on the Operations Module (bottom of the left-hand black bar)
Ensure the "INTEGRATE" tab is selected
Search for and click on the Zendesk integration
Click on the "Zendesk integration" toggle switch at the very top of the page, so it goes from "NO" to "YES"
Fill in the authorisation section:
"Zendesk Administrator Username" - this is the email address that you use to log in to your Zendesk account (administrator)
"API Access Token" - paste in an API token from Zendesk, which you can generate as follows:
Log into Zendesk as an administrator
Go to the settings page
From the menu click on the "API" link (under "Channels")
Click "Add API Token"
Give your token a name and press "create"
Zendesk will display your new token
"Zendesk Subdomain" - copy and paste in your Zendesk subdomain. You take this from your URL - https://[yourZendeskSubdomain].zendesk.com - e.g. "planhat". Note that you should enter just the subdomain value in the "Zendesk Subdomain" box, not the whole URL
"Allow fetching labels" toggle switch - click to turn it to "YES" if desired
If enabled, Zendesk tickets will be synced in including their labels, which will be created in Planhat as labels (tags)
Set up custom field mapping if desired - "Custom Fields Match" section
Click "Fetch Fields" to load available custom fields from your Zendesk
Click on "Add a match", then select your chosen Planhat field (from the left-hand dropdown), followed by the Zendesk field that you want to map it to (from the right-hand dropdown)
In Zendesk you can add custom fields under "Manage" and "Ticket Fields"
In Planhat, you would need to create any required custom fields on the Conversation model, before selecting them in the integration. You can apply a condition so a field only shows if the Conversation type is "ticket"
Repeat step b. to add in all the fields you would like to match
Click "Save"
Click "Show Fetch All Section" and then "Fetch All Tickets" to initiate the sync
This will bring in tickets created in the last 6 months (excluding ones already solved/closed); this process can take several minutes
Going forward, new/updated tickets will be synced in automatically
... and that's it! Very straightforward.
Tickets within Planhat
Tickets are stored in Planhat as Conversations of type "ticket".
You can view the tickets themselves on the Company and End User Profiles, as well as in the Conversations Module. It's easy to apply filters, to specifically show tickets (just filter by type is equal to "ticket"), or to look for ticket with a particular tag (e.g. "Tier 1" or "bug"), for example. In the Conversations Module, you can even build more advanced filters based on ticket fields you are syncing in, such as Type or Priority. You can comment on tickets in Planhat, to tag in other colleagues, for instance. (Remember that comments or updates to fields made in Planhat will not sync back to Zendesk.)
In addition, within the "Metrics" tab of the Data Module, ticket volumes can be saved as time-series data (under the "Conversations" category). You can build on this raw time-series data with Calculated Metrics - for example, tracking trends over time, or comparing a Company's number of ticket with the amount of money they are spending with you. In Pages (in the Customer Intelligence Module), you can create graphs to analyse and visualise ticket data, including field data.
Ticket status
Tickets in Zendesk have a default/system field for ticket status, called simply "status". This is automatically synced into Planhat via the integration, and in the ticket UI it's displayed in square brackets after the ticket subject - for example:
If you would like this status to display as a field on the ticket instead of appended to the subject, you can set this up via custom field mapping in the integration (as described above). You'd first need to create the custom field in Planhat (on the Conversation model), and if you use a list field type, the list value options in Planhat need to match the ones in Zendesk.
📌 Important to note:
The language of the "status" field needs to be in English for the sync to work correctly. This is due to a Zendesk issue causing field name mismatches otherwise. (This is also the case for other synced system fields.)
📌 Important to note:
If you have created a custom field in Zendesk for status (e.g. called "Ticket status"), note that this will not automatically be synced into the ticket subject like the default Zendesk "status" field. Also, in our experience, custom field mapping for this may not be possible, as the Zendesk API may not send the Planhat integration the "Ticket status" values for synced tickets (although you may find that other custom field values do successfully sync in). Therefore, we recommend that you stick with the default "status" field for ticket statuses.
Ticket number
The Zendesk ticket number is not displayed on tickets in Planhat as default, but it's easy to make it show.
Each ticket's external ID (a property in Planhat) is the Zendesk ticket number (which is synced in by default, without you needing to specify it in custom mapping). You can display that information on the ticket by using a custom formula field, following the steps outlined below.
📌 Important to note:
You need the "Admin Access" permission to create fields, and your tenant needs the ability to create formula fields enabled. If you don't yet have the ability to create formula fields, please reach out to your CSM.
Hover over your avatar/photo/initial in the bottom-left corner of your Planhat tenant, and click on "Fields"
Click on the "Conversation" model at the top, and then press the "Add New" button in the top-right corner
Name your field, e.g. "Zendesk Ticket Number"
Set the data type to text or number, then select the "Formula" and "Featured" options.
In the "Formula" box, type in
<<externalId>>Click "Show more", and set up a condition where "type is equal to ticket" - this ensures the field will only show on tickets rather than other types of conversation such as emails
Click "Save"
Your field setup will look something like this:
Refresh your page, and then click on a ticket - you will now see the new field you created, populated with the Zendesk ticket number. 😃
Enrich your Zendesk ticket view with Planhat data
⭐ Bonus feature! ⭐ In addition to Planhat's Zendesk integration to sync your tickets to Planhat, as discussed above, there is also a separate Planhat app available in the Zendesk Marketplace, which you can download here: https://www.zendesk.com/marketplace/apps/support/97448/planhat/
Key details
This app enables you to visualise some Planhat Company and End User properties in Zendesk, so you can have better understanding of your customers - prioritise poor Health Score or high MRR Companies, for example
The app retrieves the relevant data from Planhat when you open the ticket view in Zendesk. The data isn't stored in Zendesk
Customer data in the app is view-only - you can't change any data from Zendesk
The particular properties (data fields) displayed are set by Planhat rather than being user customisable
Customer data cannot be shown if the ticket requester (matched by their email address) does not exist in Planhat. If your Planhat tenant is set to automatically create End Users from tickets (if they can be matched to existing Companies), then when a ticket is received from a new End User, wait a few seconds for them to be created, and then reload the ticket view in Zendesk to see the Planhat data
Setup steps
Install the Planhat app from the Zendesk Marketplace (link here) into your Zendesk account
Once installed, add a Planhat API token to the app. To do this, you will need to create a Service Account in Planhat and give it the correct permissions.
You can choose the name of the Service Account, but we recommend "Zendesk"
The Service Account needs to have View access for the Company, End User and License models
Once you have created the API token, copy and paste it into the Zendesk app
In Zendesk, click on the gear icon on the left-hand side ("Admin" section)
Click on the "Manage" option in the "Apps" section
Select "Change settings"
Paste the API token copied from Planhat in the field "Planhat API token"
Click on "Update"
If you need help, reach out to your Planhat TAM or CSM, or our Support team
Further reading
If you have any questions about why a ticket hasn't synced into Planhat, or you need help with the Planhat Zendesk app, check out our troubleshooting tips here.