Zendesk Case Management Integration

Overview

This integration enables Agents to create and retrieve Zendesk tickets (cases) directly from a Bot. It streamlines ticket workflows by allowing the Agent to interact with Zendesk via a small set of well-defined tools.

Primary workflows supported:

Create a new Zendesk ticket
Check the status and comments for an existing ticket

The recommended approach mirrors our Salesforce pattern:

Collect structured data through forms (do not ask for open-text case details in chat)
Create a ticket when required using collected form data
Use ticketId plus email to verify and fetch an existing ticket
Add explicit workflow rules to the ReAct system prompt so the model chooses the correct form and Zendesk tool

Current Tool Map

Use these tool keys and function calls as configured in your Agent:

Tool key	Function call	Purpose
`zendeskCaseManagement`	`zendesk_ticket_info`	Retrieve ticket details and comments using `ticketId` and `email`
`zendeskCaseCreation`	`zendesk_ticket_creation`	Create a new Zendesk ticket using a `context` object

What the Integration Should Do

Ticket Creation

Call a form to collect the required fields (subject, description, priority) and then call zendesk_ticket_creation. The Create_zendesk_ticket form defined below is the canonical source of these fields; map its fields to the tool context as shown in the ReAct payload example.

Ticket Status Lookup

Call a form to collect ticketId and email, then call zendesk_ticket_info to return status and recent comments.

Zendesk Configuration

Prerequisites

A Zendesk account with API access
An API token (required) — OAuth is not supported for this integration
A Zendesk user with permission to read and create tickets

Configure the Integration

Open your Agent or project configuration.
Go to the Zendesk Case Management integration settings.
Enter the following values:

subdomain (required) — your Zendesk subdomain (for example, if your Zendesk URL is https://acme.zendesk.com, the subdomain is acme).
email (required) — the service account email used to authenticate API requests.
apiToken (required) — a Zendesk API token generated for the service account.

Save the settings and run a test ticket creation and lookup.

Note: To create an API token in Zendesk, go to Apps and integrations → APIs → API configuration, enable API Token Access, then create and copy a new token from API tokens section. Treat API tokens like passwords — store them securely.

Required Forms

For the ticket workflow documented here, create forms with these keyName values:

Create_zendesk_ticket
Fetch_status_of_a_zendesk_ticket

These names should match values referenced by the ReAct system prompt and tool wiring.

Why Forms Are Required

Forms collect structured data and avoid feeding unstructured user text into the model when performing ticket operations. Always call the correct form to collect required fields.

SurveyJS JSON: `Fetch_status_of_a_zendesk_ticket`

{
  "title": "Zendesk Ticket Information Lookup",
  "description": "Retrieve details about your Zendesk ticket. Identity verification is required before case details can be shared.",
  "logoPosition": "right",
  "completedHtml": "<h3>Thank you!</h3><p>Your identity is being verified. If your ticket ID and email match our records, the requested ticket information will be returned shortly.</p>",
  "pages": [
    {
      "name": "ticketInfoPage",
      "title": "Ticket Info Page",
      "description": "Please provide your ticket ID and the email address associated with the ticket to verify your identity.",
      "elements": [
        {
          "type": "text",
          "name": "ticketId",
          "title": "Zendesk Ticket ID",
          "description": "Enter the numeric ID of your ticket (e.g., 123456).",
          "isRequired": true,
          "requiredErrorText": "Ticket ID is required to look up your case.",
          "validators": [
            {
              "type": "regex",
              "text": "Ticket ID must contain only numbers.",
              "regex": "^[0-9]+$"
            }
          ],
          "placeholder": "e.g., 123456"
        },
        {
          "type": "text",
          "name": "email",
          "title": "Email Address",
          "description": "Enter the email address you used when submitting the ticket. This will be used to verify your identity.",
          "isRequired": true,
          "requiredErrorText": "Email address is required for identity verification.",
          "validators": [
            {
              "type": "email",
              "text": "Please enter a valid email address."
            }
          ],
          "inputType": "email",
          "autocomplete": "email",
          "placeholder": "name@example.com"
        }
      ]
    }
  ],
  "showProgressBar": true,
  "completeText": "Retrieve Ticket Info"
}

SurveyJS JSON: `Create_zendesk_ticket`

{
  "title": "Create Zendesk Ticket",
  "description": "Fill out the details below to create a new Zendesk ticket.",
  "pages": [
    {
      "name": "ticketPage",
      "title": "Ticket Details",
      "elements": [
        {
          "type": "text",
          "name": "subject",
          "title": "Subject",
          "description": "A short summary of the ticket.",
          "valueName": "ticket.subject",
          "isRequired": true,
          "placeholder": "Enter ticket subject"
        },
        {
          "type": "comment",
          "name": "commentBody",
          "title": "Description",
          "description": "Provide a detailed description of the issue or request.",
          "valueName": "ticket.comment.body",
          "isRequired": true,
          "rows": 5,
          "placeholder": "Describe your issue here..."
        },
        {
          "type": "radiogroup",
          "name": "priority",
          "title": "Priority",
          "description": "Select the urgency level for this ticket.",
          "valueName": "ticket.priority",
          "defaultValue": "normal",
          "isRequired": true,
          "choices": [
            { "value": "low", "text": "Low" },
            { "value": "normal", "text": "Normal" },
            { "value": "high", "text": "High" },
            { "value": "urgent", "text": "Urgent" }
          ]
        }
      ]
    }
  ],
  "completeText": "Create Ticket"
}

Notes

Use the ticketId plus email to verify identity before returning case details to users.

ReAct System Prompt Requirements

Append the following section to your ReAct system prompt when using this Zendesk workflow.

This block tells the model:

which forms to call
when to call each form
when to call Zendesk tools
when not to ask users for ticket details in chat

Available Forms

Use these forms to collect required user data:

Form keyName	When to Use
`Create_zendesk_ticket`	User wants to open a new ticket
`Fetch_status_of_a_zendesk_ticket`	User wants to check the status of an existing ticket

Zendesk Tools

These tools communicate with Zendesk:

zendeskCaseCreation = create a new ticket
zendeskCaseManagement = retrieve or check status of an existing ticket

Definition of History

"History" means the current conversation history only.

Do not assume ticket details from a prior session unless the user provides them again in the current conversation.

General Rules

Use only actual user-provided values, form-provided values, or tool-returned values
Never guess, invent, or hardcode an email, ticket ID, or any ticket field
Validate that the email appears valid before calling a Zendesk tool
If required information is missing, ask only for the missing field(s) or call the correct form
Wait for the tool response before confirming success or giving a final answer
Only confirm ticket creation or ticket status after the tool confirms it
If a tool fails, explain that the request could not be completed and ask the user to retry or verify their information

Ticket Status Requests

When the user says things like:

"Check my ticket status"
"What is the update on my ticket?"
"Get the status of my support ticket"
"Where does my ticket stand?"
"Show me the latest comments on my ticket"

Follow this process:

Call the Fetch_status_of_a_zendesk_ticket form to collect:
- ticketId
- email
Then call zendeskCaseManagement with:
- ticketId
- email
Return the status or latest ticket details from Zendesk

Rules:

Never answer ticket status from memory
Never skip the form if ticketId and email are not already available in the current conversation
If the ticket is not found, tell the user and ask them to verify their information

Ticket Creation Requests

When the user says things like:

"Open a support ticket"
"I need help with an issue"
"Report a problem"
"Submit a ticket for assistance"
"Create a ticket for my issue"

Follow this process:

Call the Create_zendesk_ticket form to collect all required fields
On form submission, call zendeskCaseCreation using this exact structure:

{
  "context": {
    "subject": "<subject>",
    "description": "<commentBody>",
    "priority": "<priority>"
  }
}

Required values from the form:

subject
commentBody (maps to description in the tool payload)
priority

Rules:

Use only actual form-submitted values
Never use placeholder values
Wait for the tool response
Only confirm success after the tool confirms success
If the tool fails, tell the user the ticket could not be submitted and ask them to retry or verify their information

Overview​

Current Tool Map​

What the Integration Should Do​

Ticket Creation​

Ticket Status Lookup​

Zendesk Configuration​

Prerequisites​

Configure the Integration​

Required Forms​

Why Forms Are Required​

SurveyJS JSON: Fetch_status_of_a_zendesk_ticket​

SurveyJS JSON: Create_zendesk_ticket​

Notes​

ReAct System Prompt Requirements​

Available Forms​

Zendesk Tools​

Definition of History​

General Rules​

Ticket Status Requests​

Ticket Creation Requests​