How to show a customer health score in Zendesk tickets
By Jake Marsh · Updated
To show customer health in Zendesk, install Heartwell, connect it to Vitally or Planhat with an API key or token, and put each customer's id in the Zendesk organization's External ID. Every ticket then shows the account's health score with a band (At risk, Needs attention, Healthy), a trend arrow, the renewal countdown, ARR, the CSM and the traits you pick. Heartwell reads the score your customer success team keeps; it doesn't compute one from tickets.
Steps
- Get the credential.
- Vitally: Settings > Integrations > REST API. Switch the integration on and copy the secret token of a key named "Heartwell for Zendesk". Note your subdomain and data center.
- Planhat: Settings > Private Apps. Create an app named "Heartwell for Zendesk" with access to companies, end users, users, conversations, tasks and NPS, and copy the API access token.
- Install Heartwell and set Customer success tool to
vitallyorplanhat. - Fill in the connection. Vitally: Vitally API key, plus Vitally subdomain for the US data center, or set Vitally data center to
euand leave the subdomain empty. Planhat: Planhat API access token, and leave Planhat API host asapi. - Set External IDs. In each Zendesk organization, set External ID to the account's external id in Vitally or the company's external id in Planhat.
- Pick what agents see (settings below), then open a ticket.
How Heartwell finds the account
| Order | Match | Notes |
|---|---|---|
| 1 | The Zendesk organization's external id | Matched to the account's id or external id. The most reliable |
| 2 | Up to six emails on the requester's profile | As a Vitally user or Planhat end user |
| 3 | Company domain (Vitally only) | Users at the organization's domains and the requester's email domain. Mailbox providers like gmail.com are skipped |
| 4 | Find another account | Agents type an email or account id |
How the score is shown
| Shown | Rule |
|---|---|
| At risk | Below 45% of the scale |
| Needs attention | From 45% to just under 70% |
| Healthy | 70% and above |
| Scale | Vitally scores are out of 10. Planhat health numbers above 10 are shown out of 100 |
| Trend arrow | Compares the score with your Previous health score field. In Planhat, without that field, Heartwell uses the CSM score log and says so under the arrow |
| Renewal | A countdown, amber within 30 days, red once the date has passed |
Settings that shape the panel
| Setting | What to put in it |
|---|---|
| Key traits to show | Up to 12 Vitally trait keys or Planhat custom field names, such as a tier or support package |
| Previous health score field | A trait or custom field holding the last health score, for the trend arrow |
| Account page link | Your CS tool's account address with {id}, which adds an Open link |
| Match by company domain | Vitally only: look for users at the organization's domains when the requester isn't a Vitally user |
Troubleshooting
| Message | Fix |
|---|---|
| "did not accept the API key / access token" | Paste a current key or token. |
| "host is not in the app's allowed list" | Check the Vitally subdomain and data center. |
| No account found | Add the organization's external id, or use Find another account. |
What it costs
Heartwell has two plans after a 14-day free trial, billed monthly by Zendesk: Team at $100 a month per Zendesk account with up to 12 agents and admins, and Scale at $9 per agent per month from 13 agents. Every feature is on both. The Heartwell documentation lists every setting.
Heartwell
Customer health from Vitally or Planhat on every ticket: score, renewal, ARR and CSM. From $100/mo. From $100 a month per Zendesk account.
Questions
Can Zendesk calculate a health score by itself?
Zendesk's customer context shows Zendesk's own user and organization data. Heartwell shows the score from Vitally or Planhat, where your customer success team maintains it.
Do agents need a Vitally or Planhat login?
No. Heartwell reads the account with the key or token stored as a Zendesk secure setting. Agents never see it.
Our accounts are in Vitally's EU data center. Does that work?
Yes. Set Vitally data center to eu and leave Vitally subdomain empty. Heartwell then calls rest.vitally-eu.io.
Can I show our own fields, like support tier?
Yes. List up to 12 Vitally trait keys or Planhat custom field names in Key traits to show.
More Heartwell guides
More Zendesk guides
- How to make Zendesk agents check before replying outside their groups (Heedwell)
- How to import old emails into Zendesk as tickets (Ferrywell)
- How to create a TeamViewer script token for Zendesk (Helmwell)
- How to cancel a VTEX order from a Zendesk ticket (Feirawell for VTEX)