Zendesk Integration
Relevant source files
The following files were used as context for generating this wiki page:The Zendesk integration for Quix enables the AI agent to interact directly with the Zendesk API. This allows users to manage support tickets—including creating, searching, viewing, and updating them—from within Slack. The integration uses a token-based authentication method and provides a suite of tools for the LLM to perform various ticket and user management operations.
This integration is identified by the value zendesk within the system and does not use OAuth for authentication. Its primary function is to "Create, update, and view tickets in Zendesk".
Sources: src/lib/constants.ts:11, 100-109, agent-packages/packages/zendesk/src/tools.ts
Architecture
The Zendesk integration is built upon a service-oriented architecture. The ToolService dynamically provides the Zendesk tools to the LLM agent if a valid configuration is found for the Slack workspace. The tools are created by createZendeskToolsExport, which instantiates a ZendeskService with the necessary credentials. This service then uses the node-zendesk client library to communicate with the Zendesk REST API.
Sources: src/llm/tool.service.ts:74-85, agent-packages/packages/zendesk/src/tools.ts:31, agent-packages/packages/zendesk/package.json:16
The following diagram illustrates the high-level component interaction:
Configuration
The Zendesk integration is configured via a Slack modal, not OAuth. A user provides their Zendesk subdomain, email, and an API token. The system validates these credentials by making a test API call to the Zendesk /api/v2/users/me.json endpoint.
Sources: src/integrations/integrations-install.service.ts:602-646, src/lib/constants.ts:106
Configuration Flow
The sequence diagram below shows the process of configuring the Zendesk integration.
Data Model
The configuration is stored in the zendesk_configs table, which is represented by the ZendeskConfig model. This model has a direct relationship with the SlackWorkspace model.
Sources: src/database/models/zendesk-config.model.ts
The diagram below shows the schema for the ZendeskConfig model and its relation to SlackWorkspace.
The fields for the ZendeskConfig model are detailed below:
| Field | Type | Constraints | Description |
|---|---|---|---|
id | UUID | Primary Key | Unique identifier for the configuration record. |
team_id | STRING | Foreign Key | References the associated SlackWorkspace. |
access_token | TEXT | Not Null | The encrypted Zendesk API token. |
subdomain | STRING | Not Null | The subdomain of the Zendesk instance. |
email | STRING | Not Null | The email address used for API authentication. |
default_prompt | TEXT | A custom default prompt for this integration. |
Sources: src/database/models/zendesk-config.model.ts:14-41
Available Tools
The integration exposes a set of tools for the LLM agent to interact with Zendesk. These tools cover creating tickets, searching, retrieving details, and managing comments.
Sources: agent-packages/packages/zendesk/src/tools.ts:33-195
| Tool Name | Description | Operations |
|---|---|---|
search_zendesk_tickets | Search Zendesk tickets using a query string. | READ |
get_zendesk_ticket | Retrieve a Zendesk ticket by its ID. | READ |
get_zendesk_ticket_with_comments | Retrieve a Zendesk ticket along with all its public comments and internal notes. | READ |
add_zendesk_ticket_public_comment | Add a public comment to a Zendesk ticket. | CREATE |
add_zendesk_ticket_internal_note | Add an internal note (private comment) to a Zendesk ticket. | CREATE |
get_zendesk_ticket_internal_notes | Retrieve all internal notes (private comments) from a Zendesk ticket. | READ |
get_zendesk_ticket_public_comments | Retrieve all public comments from a Zendesk ticket. | READ |
create_zendesk_ticket | Create a new Zendesk ticket with subject, description, and optional properties. | CREATE |
search_zendesk_users_by_name | Search for Zendesk users (agents or end users) by name. | READ |
Sources: agent-packages/packages/zendesk/src/tools.ts:33-195
Tool Schemas
Each tool has a defined input schema using zod for validation.
create_zendesk_ticket
This tool allows for the creation of a new ticket with several optional properties.
| Parameter | Type | Description |
|---|---|---|
subject | string | Subject or title of the support ticket. |
description | string | Detailed description of the issue or request. |
requesterEmail | string (email) | Email address of the requester. (Optional) |
priority | enum | Priority level: low, normal, high, urgent. (Optional) |
assigneeId | number | Zendesk agent ID to assign the ticket to. (Optional) |
tags | array<string> | List of tags to categorize the ticket. (Optional) |
Sources: agent-packages/packages/zendesk/src/tools.ts:149-178
search_zendesk_tickets
This tool enables searching for tickets based on a query string.
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | - | Keywords to filter tickets by subject, description, or metadata. |
limit | number | 10 | Maximum number of tickets to return (1-100). |
Sources: agent-packages/packages/zendesk/src/tools.ts:37-53
LLM Prompts
To guide the LLM in using the Zendesk tools effectively, the integration provides specific prompts for tool selection and response generation.
Tool Selection Prompt
This prompt helps the LLM decide when to use Zendesk tools.
For Zendesk-related queries, consider using Zendesk tools when the user wants to:
- Search for tickets or customer support issues
- View ticket status and details
- Create new support tickets
- Update ticket information
- Access customer support history
Sources: agent-packages/packages/zendesk/src/tools.ts:11-18
Response Generation Prompt
This prompt instructs the LLM on how to format the output after using a Zendesk tool.
When formatting Zendesk responses:
- Always include ticket numbers/IDs
- Format ticket status and priority in bold
- Include relevant customer information
- Show ticket creation and update times in human-readable format
- Format ticket descriptions maintaining proper markdown
- List assignees and requesters clearly
Sources: agent-packages/packages/zendesk/src/tools.ts:20-28
Summary
The Zendesk integration provides a robust mechanism for Quix to perform ticket management tasks directly from Slack. It relies on a secure, token-based configuration stored per workspace. A comprehensive set of tools, guided by specific LLM prompts, allows for a wide range of actions, from creating and searching tickets to adding comments and retrieving user information, making it a powerful addition to the Quix agent's capabilities.
Sources: src/lib/constants.ts:100-109, agent-packages/packages/zendesk/src/tools.ts