Zendesk
Zendesk integration turns your chatbot into a Tier 0 support layer. The bot can file tickets when it can’t help, look up the status of existing tickets, and pull a requester’s last 5 tickets as customer context for personalized answers.
In this guide:
- What the bot can do with Zendesk
- Connect via Zendesk OAuth
- Available chat actions
- Customer context
- Disconnect
What the bot can do
Three chat actions:
| Action | Purpose |
|---|---|
| Create Ticket | File a new ticket with subject, body, and requester info. |
| Get Ticket Status | Look up the current status of a ticket by ID. |
| Get Customer Context | Return a summary of the requester’s last 5 tickets — useful for “I had this issue before” follow-ups. |
Step 1: Connect
On your chatbot detail page, go to Actions → Integrations. Click Connect on the Zendesk card.
Screenshot: The Zendesk integration card and OAuth approval screen.
You’re redirected through Zendesk’s OAuth 2.0 flow. Sign in to your Zendesk subdomain, approve the requested permissions (read and write tickets, read users), and return to Hilal Chatbot.
The card flips to Connected. The Hilal Chatbot backend stores OAuth tokens encrypted and refreshes them automatically.
Step 2: Verify with a test conversation
In the Playground, simulate a flow that should create a ticket:
- “I can’t log in and I’ve tried resetting my password.”
- Bot tries to help; if it can’t, asks “Want me to file a support ticket?”
- User accepts.
- Bot triggers Create Ticket with the conversation summary as the body.
Open Zendesk → confirm the ticket appears with the right subject, body, and requester.
Step 3: Status lookups
For follow-ups, the bot can look up tickets by ID:
- “What’s the status of ticket #1234?” → bot triggers Get Ticket Status → returns “Pending — last updated 2 hours ago by agent Carla.”
The bot only returns information the connected Zendesk user has access to.
Step 4: Customer context
When a returning user starts a conversation, the bot can pull their recent ticket history for context:
- The bot looks up the user’s email in Zendesk.
- Fetches the last 5 tickets (subject + status + last update).
- Includes them as background context when generating replies.
This avoids the dreaded “I’ve already explained this three times” reaction.
To enable, configure the chatbot to pull customer context on session start — controlled per-bot in Actions → Zendesk settings.
Step 5: Disconnect
In Actions → Integrations, click the Zendesk card menu → Disconnect. Tokens are revoked. The chatbot can no longer create or read tickets.
Permissions
ZENDESK_ACTIONS.CREATE_OAUTH/READ_INTEGRATIONS/DELETE_INTEGRATIONS— connect / inspect / disconnect.ZENDESK_ACTIONS.CREATE_TICKET/READ_TICKET_STATUS/READ_CUSTOMER_CONTEXT— per-chat-action.
For public-facing bots, grant CREATE_TICKET and READ_TICKET_STATUS only. READ_CUSTOMER_CONTEXT is more sensitive — it exposes ticket history.
OAuth token refresh
Zendesk OAuth access tokens expire periodically. The Hilal Chatbot backend refreshes them silently using the refresh token; you don’t need to do anything. If a refresh fails (e.g., the OAuth grant was revoked in Zendesk’s admin console), the next chat action returns 403 and you’ll need to reconnect.
Troubleshooting
- OAuth completes but card shows Disconnected. Refresh the page. If still disconnected, check the audit logs for an OAuth callback error.
- Tickets file with the wrong requester email. Make sure your chatbot collects the user’s email before creating a ticket — see Behavior for the user-info collection setting.
- Subdomain confusion. Zendesk’s OAuth redirects through
your-subdomain.zendesk.com. The Hilal Chatbot backend handles subdomain detection — if it picks wrong, contact support with your Zendesk URL.
Out of scope
- Real-time Zendesk → chat sync (an agent reply pushed back into chat) — coming via webhooks.
- Multi-Zendesk support — one chatbot, one Zendesk subdomain. For multiple, use multiple chatbots.