Zendesk Integration
Escalate Chatsby AI conversations to Zendesk support tickets. Covers setup, escalation rules, ticket data mapping, two-way sync, and troubleshooting.
Zendesk Integration
The Chatsby Zendesk integration bridges the gap between AI-powered first-line support and your human support team. When your AI agent encounters a question it cannot resolve, or when a customer explicitly requests human assistance, Chatsby automatically creates a Zendesk ticket with the full conversation history, contact information, and relevant metadata. This ensures your support agents have complete context from the very first interaction, eliminating the need for customers to repeat themselves.
Overview
The integration supports the following capabilities:
| Capability | Description |
|---|---|
| Automatic ticket creation | Create Zendesk tickets when the AI cannot resolve an issue or a customer requests escalation |
| Full conversation history | The complete chat transcript is attached to the ticket as an internal note |
| Contact mapping | Visitor name, email, and phone number are mapped to Zendesk requester fields |
| Custom field mapping | Map Chatsby metadata to custom Zendesk ticket fields |
| Two-way status sync | Ticket status updates in Zendesk are reflected in the Chatsby dashboard |
| Agent handoff | Seamlessly transfer the conversation from AI to a human agent |
Prerequisites
| Requirement | Details |
|---|---|
| Zendesk account | A Zendesk Support account (Team plan or above recommended for API access) |
| Zendesk admin access | You need permission to create API tokens and manage integrations |
| Chatsby agent | A trained agent with escalation capabilities configured |
Setup
Generate a Zendesk API Token
Log in to your Zendesk admin panel. Navigate to Admin Center > Apps and Integrations > Zendesk API. Under the Settings tab, enable Token Access if it is not already enabled. Click Add API Token, give it a descriptive name (e.g., "Chatsby Integration"), and copy the generated token. Save it securely --- you will need it in the next step.
Open the Chatsby Integration Settings
In your Chatsby dashboard, navigate to the agent you want to connect. Go to Settings > Integrations and find the Zendesk section.
Enter Your Zendesk Credentials
Click Connect Zendesk and provide the following information:
- Zendesk Subdomain: Your Zendesk subdomain (e.g.,
yourcompanyif your Zendesk URL isyourcompany.zendesk.com) - Admin Email: The email address of the Zendesk user associated with the API token
- API Token: The token you generated in Step 1
Click Authenticate to verify the connection.
Configure Escalation Rules
After authentication, configure when Zendesk tickets should be created. See the Escalation Rules section below for detailed options.
Map Data Fields
Configure how Chatsby conversation data maps to Zendesk ticket fields. See the Ticket Data Mapping section below.
Save and Test
Click Save to activate the integration. Trigger a test escalation by sending a message like "I want to speak to a human" to your agent and verify that a ticket appears in Zendesk.
Escalation Rules
You can configure multiple conditions that trigger Zendesk ticket creation. When any of these conditions are met, Chatsby creates a ticket automatically.
| Rule | Description | Configuration |
|---|---|---|
| Explicit escalation request | Visitor says something like "talk to a human" or "I need help from a person" | Enabled by default. The AI detects escalation intent and triggers ticket creation |
| Low confidence response | The AI agent's confidence in its response falls below a threshold | Set a confidence threshold (e.g., below 60%) in the escalation settings |
| Low rating | Visitor gives the conversation a thumbs-down or low star rating | Enable the "Create ticket on low rating" toggle |
| Action-triggered | A specific Chatsby Action fires during the conversation | Select which Actions should trigger ticket creation |
| Manual escalation | A team member manually escalates from the Chatsby dashboard | Always available in the conversation view |
You can combine multiple rules. For example, enable both "Explicit escalation request" and "Low rating" to ensure tickets are created in both scenarios. Each rule can be independently toggled on or off.
Ticket Data Mapping
When a ticket is created, Chatsby populates it with data from the conversation. Here is the default mapping:
| Chatsby Data | Zendesk Field | Notes |
|---|---|---|
| Visitor name | Requester Name | Falls back to "Anonymous Visitor" if not captured |
| Visitor email | Requester Email | Required for Zendesk to create a requester record. If not captured, a placeholder is used |
| Conversation transcript | Internal Note | The full conversation history is added as the first internal note on the ticket |
| Last visitor message | Ticket Description | The most recent visitor message becomes the ticket subject/description |
| Agent name | Tag | The Chatsby agent name is added as a ticket tag for filtering |
| Conversation URL | Custom Field (optional) | A link back to the conversation in the Chatsby dashboard |
| Conversation rating | Custom Field (optional) | The visitor's rating, if provided |
You can customize this mapping in the Integrations > Zendesk > Field Mapping section of your agent settings. Add or remove mappings, and map Chatsby data to any custom Zendesk ticket fields your organization uses.
Two-Way Status Sync
The Chatsby Zendesk integration supports bidirectional status synchronization:
- Chatsby to Zendesk: When a conversation is escalated, the status in Chatsby updates to "Escalated" and a corresponding Zendesk ticket is created with "New" or "Open" status.
- Zendesk to Chatsby: When a Zendesk agent resolves or closes the ticket, the corresponding conversation in Chatsby is updated to reflect the resolution.
This sync ensures both systems stay in alignment without requiring your team to update statuses in two places.
Agent Handoff Flow
The complete escalation and handoff flow works as follows:
- AI detects escalation need --- The agent determines it cannot resolve the issue or the visitor requests a human.
- Visitor is informed --- The AI sends a message like "I'm connecting you with a support agent who can help further. A ticket has been created for your request."
- Zendesk ticket is created --- Chatsby creates a ticket with the full conversation transcript, visitor contact information, and relevant metadata.
- Human agent picks up the ticket --- Your Zendesk support agent sees the new ticket in their queue, reads the AI conversation history, and responds to the customer through Zendesk's normal workflow.
- Status syncs back --- When the Zendesk agent resolves the ticket, the Chatsby conversation is updated.
The handoff is designed to be seamless for the customer. They receive a clear message that a human agent will follow up, and the human agent has the complete context of what was discussed with the AI.
Troubleshooting
Tickets Not Being Created
| Possible Cause | Solution |
|---|---|
| Invalid API token | Regenerate the API token in Zendesk and update it in Chatsby |
| Wrong subdomain | Verify your Zendesk subdomain is correct (just the subdomain, not the full URL) |
| Escalation rules not configured | Ensure at least one escalation rule is enabled in the integration settings |
| Agent not Public | The agent must be active and set to Public for the integration to function |
Missing Conversation Data in Tickets
If tickets are created but lack conversation history or contact information:
- Verify the field mapping in Integrations > Zendesk > Field Mapping.
- Ensure your agent is configured to capture contact information via Actions.
- Check that custom Zendesk fields referenced in the mapping actually exist in your Zendesk account.
Authentication Errors
If you see a "401 Unauthorized" error during setup:
- Confirm that the email address you entered matches the Zendesk user who owns the API token.
- Ensure Token Access is enabled in Zendesk Admin Center > Apps and Integrations > Zendesk API > Settings.
- Verify your Zendesk plan supports API access (some legacy plans have restrictions).
Duplicate Tickets
If multiple tickets are created for the same conversation:
- Review your escalation rules to ensure they are not overlapping (e.g., both "Low rating" and "Action triggered" firing for the same event).
- Chatsby includes deduplication logic, but rapid sequential escalation events within the same conversation may occasionally create duplicates. Merge them in Zendesk if needed.
Security and Data Handling
The Chatsby Zendesk integration handles customer data with care:
- Data in transit --- All communication between Chatsby and Zendesk uses encrypted HTTPS connections.
- Credentials --- Your Zendesk API token is stored encrypted on Chatsby's servers and is never exposed in the dashboard after initial configuration.
- Data shared --- Only the conversation transcript, visitor contact information, and configured metadata are sent to Zendesk. No other Chatsby account data is shared.
- Revocation --- You can disconnect the integration at any time. Disconnecting stops ticket creation but does not delete tickets already created in Zendesk.
- Compliance --- The integration is compatible with Zendesk's GDPR and data retention policies. You retain full control over ticket data within Zendesk.