> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zendesk integration

> Connect Voiceflow to Zendesk so AI agents can manage tickets, answer from Help Center articles and hand off conversations to your support team.

## Overview

<a id="how-voiceflow-works-with-zendesk" />
<a id="build-with-zendesk"></a>
<a id="voiceflow-and-zendesk"></a>

Voiceflow integrates with Zendesk so your AI agents can resolve customer requests using ticket history, customer records and Help Center articles, then bring in your support team when needed.

#### Studio

In Agent studio, choose the connection for your task: ticket tools, Help Center import or Sunshine Conversations handoff.

#### Developer

Use Voiceflow's API or CLI to execute Zendesk actions from your backend or attach them to an agent or Playbook.

Requests use `https://realtime-api.voiceflow.com`, a [Voiceflow API credential](/docs/api-reference/authentication), a project ID and an Environment alias. [Authorize ticket tools and inspect their schemas](#connecting-zendesk) before calling a ticket action. Verify imported Help Center content with a [Knowledge Base diagnostic query](#help-center); asynchronous human replies use the [Chat handoff event contract](/docs/api-reference/agent-runtime/chat/handoff).

Agent studio with Zendesk tools attached to a customer support agent — Attach the Zendesk actions your support agent needs.

### Examples of when to use Zendesk

<a id="available-zendesk-capabilities"></a>
<a id="what-you-can-do"></a>
<a id="common-zendesk-use-cases"></a>

Use the integration to keep customer requests and the information needed to resolve them together:

- **[Import help articles](#help-center)** — import Help Center articles into Knowledge for the agent to use in its answers.
- **[Record a request for follow-up](#creating-tickets)** — collect the customer's details and create a ticket for your support team to handle later.
- **[Continue an existing case](#ticket-updates)** — retrieve a ticket the customer may access, update its status or add an internal note.
- **[Human agent hand-off](#live-agent)** — continue the live conversation in Zendesk Agent Workspace with its customer context.

Choose [ticket tools](#connecting-zendesk) to work with support records, [Help Center import](#help-center) to answer from articles, or [Sunshine Conversations](#live-agent) for live support. Each uses its own authorization; ticket-tool OAuth does not connect the other two.

<a id="connecting-zendesk"></a>

## Connecting ticket tools

Authorize Zendesk actions that read and update support records.

<a id="adding-integration"></a>

<a id="connect-zendesk"></a>
<a id="before-you-connect"></a>
<a id="get-started"></a>
<a id="before-you-start"></a>
<a id="connect-your-account"></a>
<a id="connecting-to-zendesk"></a>

You need a Voiceflow project you can edit and access to the Zendesk resources your actions will use. Ticket tools use Zendesk OAuth and your Zendesk subdomain. Help Center import and Sunshine handoff have their own setup below.

Ticket tools act through the connected account. Before exposing existing tickets to a customer-facing agent, implement the [customer-to-ticket access check](#ticket-access); the connection itself does not verify the chatting customer's access.

### Connect and prepare actions

#### Studio

<a id="studio-setup"></a>

### 1. Open the Zendesk connection

In your project's left sidebar, open **More → Integrations** and click **Connect** on the **Zendesk** card. You can also open **Manage** from an attached Zendesk tool.

Agent studio Integrations workspace with the Integrations sidebar entry spotlighted and the Zendesk Connect card visible — In your project’s left sidebar, open More → Integrations, then select Connect on Zendesk.

### 2. Authorize your Zendesk account

Enter your **Subdomain URL**, select **Connect** and complete the Zendesk authorization in the browser. Use the account containing the tickets, users and organizations you intend to access.

Zendesk connection dialog with the Subdomain URL field and Connect button in the Integrations workspace — Enter your Zendesk subdomain, then select Connect to authorize the account in your browser.

### 3. Add an action to your agent

Return to **Agent**, click **+** beside **Global tools** and select the Zendesk action you need. Open the attached tool to write its **Trigger**, review the inputs and configure **Capture response** when you need the result later.

The tool editor displays **Zendesk is connected** when its connection is available. Run a test action and verify its result before relying on it in a customer conversation.

#### Developer

<a id="developer-setup"></a>

Zendesk ticket tools require browser OAuth before API or CLI execution. Complete this setup in Voiceflow once for the account you intend to use; the generic Connect integration API does not replace it.

<a id="developer-browser-authorization"></a>

### 1. Open Zendesk in Agent studio

Open [**Agent studio**](https://creator.voiceflow.com) in your browser and select the Voiceflow project you'll use with the API or CLI. In the left sidebar, expand **More** if needed, select **Integrations**, then click **Connect** on the **Zendesk** card.

Agent studio Integrations workspace with the Integrations sidebar entry spotlighted and the Zendesk Connect card visible — In your project’s left sidebar, open More → Integrations, then select Connect on Zendesk.

### 2. Authorize the Zendesk account

Enter your **Subdomain URL**, select **Connect** and complete Zendesk's authorization in the browser. Use the account containing the tickets, users and organizations your calls will access.

Zendesk connection dialog with the Subdomain URL field and Connect button in the Integrations workspace — Enter your Zendesk subdomain, then select Connect to authorize the account in your browser.

### 3. Confirm the connection and continue in code

Return to **Integrations** and check Zendesk's **Connected** status. Continue below to prepare the Voiceflow credential and inspect the action schema. A stored connection does not verify an action; check its returned result when you make the first call.

Use a [Voiceflow bearer credential](/docs/api-reference/authentication) with access to the project and Environment. Set these values in your shell before using either interface:

```sh
export VF_TOKEN='YOUR_VOICEFLOW_BEARER_TOKEN'
export PROJECT_ID='YOUR_PROJECT_ID'
export ENVIRONMENT='main'
```

Both curl and the CLI read `VF_TOKEN`; a [CLI sign-in](/docs/api-reference/authentication#cli) is another option for CLI-only work. The CLI examples request JSON output so returned provider fields are retained. Keep this token on your backend or development machine, outside customer-facing browser code.

Standalone action calls need the connection and schema, not a tool attachment or compilation. After discovering the actions, go straight to [Creating tickets](#creating-tickets) or another action. Steps 2–4 below are for making an action available to the agent. Use a current [Voiceflow CLI](/docs/cli/install) with `integration add-tool` and `workflow update-step` support for the CLI procedures.

#### API

### 1. Discover the available actions

Inspect the selected Environment's action schemas before constructing inputs:

```sh
curl --fail-with-body --silent --show-error --request GET "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN"
```

Read `tools[].toolName`, `inputs` and `integrationToolID`. A `null` ID means the catalog action has not been added to this Environment; it can still be executed directly. `connected` reports stored connection keys, not whether Zendesk will accept the current credentials. Standalone execution uses the Environment's Draft and its Draft connection override when present, otherwise the Published connection.

### 2. Add the catalog action

For an agent attachment, if the chosen action's `integrationToolID` is `null`, add it with the API. This example adds Find ticket:

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_find_ticket"
}'
```

Keep the returned `integrationToolID`. Adding the catalog definition does not attach it to the agent or authorize Zendesk.

### 3. Attach and configure the action

Save this test-agent attachment as `zendesk-tool.json`, replacing `YOUR_INTEGRATION_TOOL_ID` with the Find ticket ID from the previous step. Its descriptions guide the agent; they do not enforce ticket access. For customer-facing reads, enforce the [access check](#ticket-access) before executing the action.

```json
{
  "type": "integration",
  "integrationToolID": "YOUR_INTEGRATION_TOOL_ID",
  "target": { "global": true },
  "description": "Read the team's test ticket during integration testing.",
  "inputVariables": {
    "ticketID": {
      "integrationToolVariableName": "ticketID",
      "description": "ID of the team's test ticket in the connected Zendesk account.",
      "required": true,
      "defaultValue": null
    }
  }
}
```

Create the attachment once:

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @zendesk-tool.json
```

`target: {"global": true}` attaches it to the agent. For one Playbook, use `target: {"playbookID": "YOUR_PLAYBOOK_ID"}` instead. Set `description` to explain when to call the action; `inputVariables` configures what the agent must supply. [Create tool](/docs/cli/commands/tool/create) also accepts `captureResponse` when later actions need the result. Inspect a real result before choosing response paths.

### 4. Verify the agent's use of the action

Compile the Environment's Draft after editing the attachment:

```sh
curl --fail-with-body --silent --show-error --request PUT "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  --header "Authorization: Bearer $VF_TOKEN"
```

A successful compile returns `message` and `durationMs`; it does not publish the Environment. Then [run a Draft test conversation](/docs/cli/commands/conversation/send) asking about a ticket you can inspect. Check that the agent calls Find ticket with that ID and uses the returned record. The standalone examples below test individual actions; they do not verify agent routing.

#### CLI

### 1. Discover the available actions

Inspect the selected Environment's action schemas before constructing inputs:

```sh
vf --output-format json integration get-schema --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT"
```

Read `tools[].toolName`, `inputs` and `integrationToolID`. A `null` ID means the catalog action has not been added to this Environment; it can still be executed directly. `connected` reports stored connection keys, not whether Zendesk will accept the current credentials. Standalone execution uses the Environment's Draft and its Draft connection override when present, otherwise the Published connection.

### 2. Add the catalog action

For an agent attachment, if the chosen action's `integrationToolID` is `null`, add it to the catalog. This example adds Find ticket:

```sh
vf --output-format json integration add-tool --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_find_ticket
```

Keep the returned `integrationToolID`. Adding the catalog definition does not attach it to the agent or authorize Zendesk.

### 3. Attach and configure the action

Save this test-agent attachment as `zendesk-tool.json`, replacing `YOUR_INTEGRATION_TOOL_ID` with the Find ticket ID from the previous step. Its descriptions guide the agent; they do not enforce ticket access. For customer-facing reads, enforce the [access check](#ticket-access) before executing the action.

```json
{
  "type": "integration",
  "integrationToolID": "YOUR_INTEGRATION_TOOL_ID",
  "target": { "global": true },
  "description": "Read the team's test ticket during integration testing.",
  "inputVariables": {
    "ticketID": {
      "integrationToolVariableName": "ticketID",
      "description": "ID of the team's test ticket in the connected Zendesk account.",
      "required": true,
      "defaultValue": null
    }
  }
}
```

Create the attachment once:

```sh
vf --output-format json tool create --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" < zendesk-tool.json
```

`target: {"global": true}` attaches it to the agent. For one Playbook, use `target: {"playbookID": "YOUR_PLAYBOOK_ID"}` instead. Set `description` to explain when to call the action; `inputVariables` configures what the agent must supply. [Create tool](/docs/cli/commands/tool/create) also accepts `captureResponse` when later actions need the result. Inspect a real result before choosing response paths.

### 4. Verify the agent's use of the action

Compile the Environment's Draft after editing the attachment:

```sh
vf --output-format json environment compile --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT"
```

A successful compile returns `message` and `durationMs`; it does not publish the Environment. Then [run a Draft test conversation](/docs/cli/commands/conversation/send) asking about a ticket you can inspect. Check that the agent calls Find ticket with that ID and uses the returned record. The standalone examples below test individual actions; they do not verify agent routing.

<a id="tools-and-actions"></a>

### Use the returned data
<a id="use-through-code"></a>
<a id="integration-reference"></a>
<a id="related-resources"></a>

#### Studio

Use **Capture response** on the attached tool to retain a result for later steps. Run the action and inspect its actual result before configuring an object path; the returned fields differ by action.

#### Developer

For standalone calls, check the execution envelope before reading `output`:

- `success` reports whether the action completed without an error; `error` contains the failure reason when it did not.
- `output.data` contains the Zendesk result when `success` is `true` and `truncated` is `false`. On failure, `output` is `null`. The record shape depends on the action.
- `truncated: true` means the output or error exceeded 64 KB. A shortened output arrives as a JSON string rather than an object; do not treat it as a complete structured record.
- `latencyMs` measures execution time around the call.

HTTP 200 and a zero CLI exit status alone do not establish action success. For an agent attachment, use `captureResponse` to map verified result paths into variables. The [Zendesk action reference](/docs/documentation/build/tools/zendesk-tool#supported-actions) and [execution contracts](/docs/developers/tools/execution-behavior) own the exact schemas.

### Test safely

Ticket creation, comments and updates change data in Zendesk. Use a test account or your team's test-data process. After a timeout, inspect Zendesk before retrying: a failed or missing response does not prove the write did not occur. The examples on this page use illustrative Northstar Supply records; replace their IDs and values with your own test data.

### Manage or repair the Zendesk connection

Check the account and reconnect in your Voiceflow project's integration settings.

<a id="limits-and-connection-management"></a>
<a id="troubleshooting"></a>

#### Studio

In the same project, open **More → Integrations**. **Manage** on a connected Zendesk card opens its disconnect confirmation; it does not edit the saved account. To replace the connection, review the affected scope in that confirmation, select **Disconnect**, then **Connect** on Zendesk and authorize the intended account. Actions using the disconnected account fail until it is reconnected. Verify a read such as Find ticket before retrying a write.

For a failed action, check the selected project, required inputs and the actual Zendesk record. Tool authorization and Help Center import are separate; repair the connection used by the failing capability.

#### Developer

- **HTTP failure:** inspect the status and response body before reading an execution envelope. A mismatched integration/tool name is rejected before execution. Unknown brace tokens such as `{customer_id}` are also rejected: a standalone run has no conversation variables. Pass the actual value; only existing project secrets can be substituted in top-level string inputs.
- **HTTP 200 with `success: false`:** inspect `error`; `output` is `null`. Check the required inputs, account-scoped IDs and provider authorization. A timeout does not establish that a write failed—inspect the record before retrying.
- **Unexpected account or record:** verify `PROJECT_ID`, `ENVIRONMENT` and the Draft/Published connection used by the standalone run. A stored-connection flag alone does not validate the credentials.

To replace the ticket connection, open [Agent studio](https://creator.voiceflow.com), choose the project identified by `PROJECT_ID`, then open **More → Integrations**. Select **Manage** on Zendesk, review the disconnect confirmation and affected scope, then select **Disconnect**. This interrupts actions using that connection. Select **Connect** on Zendesk and complete browser authorization for the intended account. Check **Zendesk is connected**, then rerun Find ticket before retrying a write. The [initial connection steps](#developer-browser-authorization) show the navigation and authorization dialog without leaving Code.

The generic disconnect endpoint rejects Zendesk's service-owned credentials. Ticket tools, Knowledge import and Sunshine handoff use distinct connections; repair the one used by the failed operation.

<a id="help-center"></a>

## Import help articles

Import Zendesk articles so your agent can answer from your support knowledge.

<a id="knowledge-tools"></a>

<a id="sync-knowledge"></a>
<a id="more-ways-to-use-zendesk"></a>

Help Center content enters Voiceflow through the Zendesk Knowledge source, separately from ticket-tool authorization. Its import controls let you select a brand and filter articles by language, category, labels and user segments. You can preserve the Zendesk structure and import article metadata.

### Import and check your articles

The Help Center connection requires browser authorization in Agent studio. Complete it once for the Help Center you will import; the ticket-tool OAuth connection does not authorize this import.

### 1. Open Knowledge base in Agent studio

Open [Agent studio](https://creator.voiceflow.com) and choose the project that will use these articles. In Code, this is the project identified by `PROJECT_ID`. In the sidebar, open **Build → Knowledge base**, then **Add data source → Zendesk**.

Knowledge base in the Build sidebar and the Add data source button — Open Knowledge base in the project that will use your Help Center articles.

### 2. Authorize your Help Center

Enter its **Subdomain URL**, select **Connect** and complete Zendesk authorization in the browser. The **Import from Zendesk** dialog is the next configuration screen.

Separate Zendesk Help Center connection dialog with its Subdomain URL field — Authorize the Help Center separately from the ticket tools.

### 3. Choose and import your articles

Select the required **Brand**. Narrow the selection with **Locales**, **Categories**, **Labels** and **User segments**, then check the matching article count on **Import data sources**. A failed count or a zero match prevents importing; correct the connection or filters first. Choose the destination **Folder**, organization and refresh settings described below, then select **Import data sources**.

Import from Zendesk with the selected brand, article filters and matching import count — Select the brand and article filters before starting the import.

#### Studio

Find an expected article in **Knowledge base** and open its content after processing completes. Test a question covered by that article with [Knowledge retrieval](/docs/documentation/build/querying-the-knowledge-base) available to the agent, then compare the answer with Zendesk's source article.

#### Developer

<a id="prepare-help-center-content"></a>

After the browser import, return to your terminal. Verify the imported documents in the same project and Environment before using their content:

#### API

### 1. Find an imported article

List the Knowledge documents and locate an article you selected in the import:

```sh
curl --fail-with-body --silent --show-error --request GET "https://realtime-api.voiceflow.com/v1/stable/document?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN"
```

The response contains `documents[]`. Select the article's `id` and wait for `status.type: "SUCCESS"` before testing retrieval; `PENDING` and `INITIALIZED` are not completion, and `ERROR` needs investigation. Use [Read document](/docs/cli/commands/document/get) for its chunks and metadata.

Set `DOCUMENT_ID` to the returned article ID, then read its content:

```sh
export DOCUMENT_ID='YOUR_DOCUMENT_ID'

curl --fail-with-body --silent --show-error --request GET "https://realtime-api.voiceflow.com/v1/stable/document/$DOCUMENT_ID?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN"
```

Inspect `document.chunks` and `document.metadata`.

### 2. Check retrieval against the source

Ask a question covered by one of the imported articles. This example retrieves Draft chunks without synthesizing an answer:

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/knowledge-base/query?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "version": "draft",
  "question": "What should I do if my order arrives damaged?",
  "synthesis": false,
  "chunkLimit": 3
}'
```

Read `answer.chunks[]` and compare each chunk's `documentID`, `source` and `content` with the imported article. With `synthesis: false`, `answer.output` is `null`; an empty answer string is not the retrieval success check. This query is a build-time diagnostic, not the agent's runtime retrieval endpoint.

#### CLI

### 1. Find an imported article

List the Knowledge documents and locate an article you selected in the import:

```sh
vf --output-format json document list --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT"
```

The response contains `documents[]`. Select the article's `id` and wait for `status.type: "SUCCESS"` before testing retrieval; `PENDING` and `INITIALIZED` are not completion, and `ERROR` needs investigation. Use [Read document](/docs/cli/commands/document/get) for its chunks and metadata.

Set `DOCUMENT_ID` to the returned article ID, then inspect `document.chunks` and `document.metadata`:

```sh
export DOCUMENT_ID='YOUR_DOCUMENT_ID'

vf --output-format json document get --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" --document-id "$DOCUMENT_ID"
```

### 2. Check retrieval against the source

Ask a question covered by one of the imported articles. This example retrieves Draft chunks without synthesizing an answer:

```sh
vf --output-format json knowledge-base query --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" --version-param draft \
  --question "What should I do if my order arrives damaged?" \
  --synthesis=false --chunk-limit 3
```

Read `answer.chunks[]` and compare each chunk's `documentID`, `source` and `content` with the imported article. With `synthesis: false`, `answer.output` is `null`; an empty answer string is not the retrieval success check. This query is a build-time diagnostic, not the agent's runtime retrieval endpoint.

### Choose how imported content is organized

Configure these controls in **Import from Zendesk** before starting the import:

- **Preserve Zendesk structure** groups articles by language, category and section within the selected folder.
- **Import Zendesk metadata** adds article category, section, tags, labels and language. These keys replace matching metadata entered in the import form.
- **LLM chunking strategy** controls preparation for retrieval. For example, **Smart chunking** groups content by topic; **Keep each document in one chunk** retains the article together, except documents over approximately 30,000 characters. Inspect the resulting chunks before relying on a strategy.
- **Refresh rate** defaults to **Never**. **Daily**, **Weekly** and **Monthly** are scheduled alternatives when the workspace has the Knowledge refresh entitlement. The control is disabled without that entitlement.

### Keep imported articles current

A **Zendesk source** entry groups and manages its imported articles. Its filters determine which articles remain in that source: the next sync can remove articles that no longer match. Importing a source also adopts existing Zendesk documents that match its filters. Review the brand and filters before changing them.

If Knowledge base instead lists separately imported articles without a Zendesk source entry, open the individual article to manage its refresh. The source-level **Filters**, **Excluded documents** and **Restore** controls below belong to a Zendesk source entry.

### Update a Zendesk source

Change article filters, sync the source and restore an excluded article.

Open [Agent studio](https://creator.voiceflow.com), choose the same project, then open **Build → Knowledge base** and select its **Zendesk source** entry.

### 1. Review and save the source filters

Open **Settings → Filters**. Select the intended brand, locales, categories, labels and user segments, then close the dropdown to save each selection. They apply on the next sync; check which articles they will retain.

### 2. Sync and inspect the result

Open the source's **More** menu and choose **Re-sync**, or wait for its configured **Refresh rate**. Wait for syncing to finish, then check the document list and open a changed article. A sync failure requires repairing the Knowledge connection before trying again.

### 3. Restore an excluded article

In **Settings → Filters → Excluded documents**, select **Restore** beside the article. Sync again and confirm the article returns if it still matches the filters. Source-level metadata and chunking changes apply to newly added documents; existing documents retain their own metadata and prepared chunks.

#### Developer

The provider's import settings are managed in this GUI. After syncing, return to Code and run the [document and retrieval checks](#import-and-check-your-articles) against the updated content. Keep the document ID returned by Voiceflow; the Zendesk article ID is not interchangeable with it.

### An expected Help Center article is missing

Check the Knowledge connection, selected brand and article filters.

#### Studio

Confirm that the Knowledge connection targets the intended Help Center. Review the brand, languages, categories, labels and user segments used for the import. Find the article in Zendesk, then compare it with the imported content in Voiceflow. A connected ticket tool does not establish that a Knowledge import ran.

If the article is present but the answer is wrong, inspect its actual content and the agent's [Knowledge retrieval](/docs/documentation/build/querying-the-knowledge-base) configuration before importing it again.

#### Developer

List the Knowledge documents in the requested project and Environment and check whether the article was imported. If it exists, inspect its status, chunks and metadata, then run the [retrieval check](#import-and-check-your-articles) against a question covered by the source article.

If it is missing, follow the [Help Center authorization and article-selection steps](#import-and-check-your-articles) in this Code view. Open Agent studio in the same project, then **Build → Knowledge base → Add data source → Zendesk** to repair that Knowledge connection and check the selected brand and filters. A successful ticket action does not establish that Knowledge import ran. Compare the returned chunks with the source before retrying an import.

<a id="creating-tickets"></a>

## Creating tickets

Capture a customer's request as a new Zendesk support ticket.

**Create ticket** requires `subject`, `description`, `requesterName`, `requesterEmail` and `comment`. Put the issue and requested outcome in `comment`, which becomes the first ticket message; `description` does not replace that comment. `priority` and account-specific custom `fields` are optional. The connector creates the ticket with status `new` and returns the created ticket result.

### Configure ticket creation

#### Studio

Zendesk Create ticket editor with the required input variables and connected account — Review the ticket inputs and describe when the agent should create a ticket.

### 1. Add Create ticket

Add **Zendesk → Create ticket** to the agent's **Global tools** or to the relevant Playbook. In its **Trigger**, describe the customer request that should create a ticket and require confirmation before the write.

### 2. Supply the request details

Have the agent collect the requester's name and email, a subject, a description and the initial comment. For a deterministic Workflow, choose **Create ticket** in an **Integration step** and map these inputs from fixed test values or conversation variables.

### 3. Run and verify one ticket

Test a confirmed support request. Open the resulting ticket in Zendesk and check its requester, subject, comment and status. If using **Capture response**, inspect the returned result before selecting the path to the ticket ID.

#### Developer

Use the [prepared project and action schema](#connecting-zendesk). This example creates one ticket with illustrative Northstar Supply details:

#### API

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_create_ticket",
  "inputs": {
    "subject": "Damaged item — Order NS-1042",
    "description": "A ceramic mug arrived broken.",
    "requesterName": "Maya Chen",
    "requesterEmail": "maya@northstar.example",
    "comment": "Order NS-1042 arrived with a broken ceramic mug. Customer requested a replacement."
  }
}'
```

#### CLI

```sh
vf --output-format json integration execute --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_create_ticket \
  --inputs '{
  "subject": "Damaged item — Order NS-1042",
  "description": "A ceramic mug arrived broken.",
  "requesterName": "Maya Chen",
  "requesterEmail": "maya@northstar.example",
  "comment": "Order NS-1042 arrived with a broken ceramic mug. Customer requested a replacement."
}'
```

Check `success: true`, `error: null` and `truncated: false` before reading the created ticket at `output.data`. An illustrative, abridged result looks like this; the IDs and timing are example values:

```json title="Created ticket — abridged example"
{
  "success": true,
  "latencyMs": 320,
  "error": null,
  "truncated": false,
  "output": {
    "data": {
      "id": 8422,
      "subject": "Damaged item — Order NS-1042",
      "status": "new"
    }
  }
}
```

Retain `output.data.id` for later actions. Confirm the record and its first comment in Zendesk once; repeating a successful create call can create another ticket.

### Follow a damaged-item request

Connect the customer's request, ticket reference and later status check.

### 1. Record the confirmed request

Maya asks for a replacement for the broken mug in order NS-1042. Confirm those details, then create the ticket shown above. Creating a ticket records the request; it does not issue a replacement.

### 2. Give the customer the ticket reference

After creation succeeds, confirm the reference to Maya. Have your application retain the actual returned ticket ID with its verified customer record. The example ID `8422` is illustrative.

### 3. Continue the same case

When Maya returns, verify her identity and ticket access before retrieving the ticket. Share the permitted status information; keep internal notes private. If she needs a live exchange with your team, use [Sunshine handoff](#live-agent) rather than creating another follow-up ticket.

### Ticket creation best practices

Collect the details that let a support teammate continue the request.

- Confirm the customer's identity and request before creating the ticket.
- Distinguish a new request from an existing ticket so the agent chooses creation or update deliberately.
- Include the customer's requested outcome in the description and the relevant conversation context in the comment.
- Review any ticket already created before retrying a failed or timed-out call.

<a id="ticket-updates"></a>

## Finding and updating tickets

Retrieve a known ticket and change its status, priority or assignee.

**Find ticket** requires `ticketID` and returns that ticket. It is an ID lookup, not a general ticket search. **Update ticket** requires `ticketID` and accepts optional `status`, `priority`, `comment`, `assignee` and custom `fields`. The assignee is an email address.

### Verify the customer's ticket access

<a id="ticket-access"></a>

These actions use the connected Zendesk account; they do not verify that the chatting customer may access the supplied ticket. A ticket ID, email address or tool Trigger is not an access check.

#### Studio

Have your application's implementing team verify the customer and which ticket they may access. Obtain the permitted ticket ID from that flow before running the Integration step. Do not let an agent-selected ID bypass that check. Use your team's test ticket while configuring the action.

#### Developer

On your backend, authenticate the customer and check their access to the requested ticket before calling Find ticket or Update ticket. Pass the permitted ID to the action; reject an unauthorized request before execution. Use a ticket from your team's test account for the examples below.

### Read before changing a ticket

#### Studio

Zendesk Update ticket editor with ticket ID and optional update fields — Use the existing ticket ID and configure the fields the agent may update.

### 1. Read the existing ticket

Add **Find ticket** to the verified flow and supply its permitted ticket ID. Inspect the found ticket before allowing an update; do not replace that ID with one supplied in chat.

### 2. Configure the intended change

Add **Update ticket** and describe in its **Trigger** when a change is appropriate. Supply the same ticket ID and only the fields you intend to change. For a Workflow, use separate Integration steps to retrieve and update the ticket.

### 3. Verify the update

After testing, open the same ticket in Zendesk and confirm the changed field. Configure **Capture response** if later steps need the current status.

#### Developer

Read the ticket before changing it. Replace the illustrative ID with the permitted ticket ID from your backend's access check:

#### API

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_find_ticket",
  "inputs": {
    "ticketID": 8422
  }
}'
```

Inspect the returned record, then update that same ticket:

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_update_ticket",
  "inputs": {
    "ticketID": 8422,
    "status": "pending"
  }
}'
```

#### CLI

```sh
vf --output-format json integration execute --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_find_ticket \
  --inputs '{
  "ticketID": 8422
}'
```

Inspect the returned record, then update that same ticket:

```sh
vf --output-format json integration execute --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_update_ticket \
  --inputs '{
  "ticketID": 8422,
  "status": "pending"
}'
```

After a successful, untruncated execution, read the ticket at `output.data` and verify its ID and status. Confirm the status on the same ticket in Zendesk. A ticket ID from another account is not interchangeable with one in the connected account.

### Choose the ticket fields to update

Use the accepted status and priority values and the connected account's custom fields.

- `status`: `new`, `open`, `pending`, `hold`, `solved` or `closed`.
- `priority`: `low`, `normal`, `high` or `urgent`.
- `assignee`: the Zendesk assignee's email.
- `comment`: a comment to add as part of the update. The dedicated [Add ticket comment](#ticket-comments) action explicitly creates an internal note.
- `fields`: custom fields for this account. The action schema identifies the `fields` input but does not enumerate Zendesk field IDs or dropdown options.

Zendesk determines whether a requested change is permitted for that record and account. Inspect action errors before reporting success.

#### Developer

For Create ticket or Update ticket, `inputs.fields` is an object whose values are Zendesk custom-field objects, rather than a flat field-name/value map:

```json title="Custom field inside inputs — example"
{
  "fields": {
    "order_number": {
      "id": 123456,
      "value": "NS-1042"
    }
  }
}
```

Replace the example field ID and value with those from the connected account. Use [Zendesk's ticket-field API](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#list-ticket-fields) to discover IDs and options; those requests use Zendesk authorization, not your Voiceflow bearer token. Do not infer provider field IDs from `get-schema`.

<a id="live-agent"></a>

## Human agent hand-off

Pass the conversation and customer context to Zendesk Agent Workspace.

Zendesk live-agent handoff uses **Sunshine Conversations** to pass the conversation to **Zendesk Agent Workspace**. It is a live message exchange, separate from creating a support ticket for later follow-up.

- **Customer identity:** use a stable **End user ID**. Sunshine reuses an existing personal conversation for that identity, so a later handoff can return to the same conversation rather than always creating a new ticket.
- **Context visibility:** a full transcript or custom context is posted as a conversation message attributed to the customer. It is not a private internal note. Include only content suitable for that conversation.
- **Files:** customers and support teammates can exchange attachments during the live handoff. This is separate from the ticket comment tool, which adds an internal text note.

<a id="connect-sunshine-conversations"></a>
<a id="configure-the-handoff"></a>

### Configure the Sunshine reply webhook

Your Sunshine app needs an Agent Workspace switchboard integration and a webhook that sends human replies and conversation-ending events to Voiceflow. Connecting Sunshine in Voiceflow stores credentials; it does not create this webhook. Complete the provider setup before saving the Voiceflow connection in either Studio or Code.

### 1. Open the Sunshine conversations integration

In Zendesk **Admin Center**, open **Apps and integrations → Integrations → Conversations integrations**. Create a conversations integration for Voiceflow, or edit its existing webhook. Use a Sunshine Conversations integration, rather than a Zendesk Support webhook.

### 2. Set the callback and subscriptions

Set **Webhook endpoint URL** to:

```text title="Sunshine callback URL"
https://general-runtime.voiceflow.com/handoff/webhook/sunshine
```

Under **Webhook subscriptions**, select:

- `conversation:message` — delivers the support teammate's messages and attachments.
- `switchboard:releaseControl` — tells Voiceflow that the human conversation has ended.
- `switchboard:passControl:failure` — tells Voiceflow that the handoff could not be completed.

### 3. Copy the webhook's shared secret

Save the conversations integration and copy its generated **Shared secret**. Use this value as **Webhook secret** in the Voiceflow connection below. Sunshine sends it in the `X-Api-Key` header, which Voiceflow checks against the stored value. The Sunshine API **Key secret** is a separate credential.

[Zendesk's conversations integration setup](https://support.zendesk.com/hc/en-us/articles/4576083789850-Creating-conversations-integrations-in-Admin-Center) explains the provider controls. If you manage Zendesk configuration programmatically, register the same callback and subscriptions through the [Sunshine Conversations webhook API](https://developer.zendesk.com/api-reference/conversations/).

### Connect and configure handoff

#### Studio

In your project, open **More → Integrations → Sunshine Conversations**. Enter your Zendesk **Subdomain**, Sunshine **App ID**, **Key ID**, **Key secret** and the **Webhook secret** copied above, then select **Connect**. These credentials belong to the Sunshine connection, not the Zendesk ticket-tool OAuth connection.

Sunshine Conversations connection with Zendesk subdomain, app ID, key ID, key secret and webhook secret — Connect Sunshine Conversations separately from the Zendesk ticket tools.

### 1. Choose the support connection

In **Build → Workflows**, open the [Workflow](/docs/documentation/build/workflows) that will connect the customer to a person. Add or open its **Handoff step**, then select **Sunshine Conversations** as **Handoff provider**.

Sunshine Handoff step with customer identity and Zendesk group, brand and priority settings — Map the customer and Zendesk routing fields in the Handoff step.

### 2. Map customer identity and routing

Set **End user ID** to a stable customer identifier and supply the customer's **User email**, **Customer name** and **Language** as needed. Use **Group ID**, **Brand ID** and **Priority** to populate the Zendesk ticket's routing fields. Group ID identifies a Zendesk group; it does not create a queue or assign a queue position. Accepted priorities are `low`, `normal`, `high` and `urgent`.

### 3. Choose context and continuation

Choose **Handoff context**: **Full transcript**, a **Custom variable** containing a string, or **None**. Connect the **Failure path** to a useful fallback. Enable and connect **Return path** if the customer should be able to return to the AI agent after human support.

#### Developer

The Sunshine connection is independent of Zendesk ticket OAuth. You need its Subdomain, App ID, Key ID, Key secret and the webhook's shared secret from the provider setup above. Use the [Voiceflow bearer credential and project ID](#developer-setup) from setup.

Before the configuration calls below, create a [Workflow](/docs/cli/commands/workflow/create) containing a [Handoff step in a block](/docs/cli/commands/workflow/create-block). The example reads and updates that existing step; it does not create the Workflow, connect its paths or attach it to your agent. Define the customer variables used in the configuration and connect the step's failure and return paths before testing.

Save `sunshine-connection.json` outside your repository and replace the credential placeholders. Set `webhookSecret` to the generated shared secret of the Sunshine webhook, not the API key's secret:

```json
{
  "integration": "sunshine",
  "credentials": {
    "subdomain": "YOUR_ZENDESK_SUBDOMAIN",
    "appId": "YOUR_SUNSHINE_APP_ID",
    "keyId": "YOUR_SUNSHINE_KEY_ID",
    "keySecret": "YOUR_SUNSHINE_KEY_SECRET",
    "webhookSecret": "YOUR_SUNSHINE_WEBHOOK_SECRET"
  }
}
```

This call stores the project's Published connection credentials; it is not scoped by `ENVIRONMENT` and does not publish a Workflow. Connecting reports that credentials were stored, not that a live exchange succeeded. Direct API and CLI clients can make this request; MCP clients must use the browser connection instead.

#### API

### 1. Store the Sunshine connection

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/sunshine?projectID=$PROJECT_ID" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @sunshine-connection.json
```

A successful response reports `Integration sunshine connected.` Verify a real exchange after configuring the Workflow.

### 2. Read the Workflow and Handoff step

List Workflows to find its server-issued ID:

```sh
curl --fail-with-body --silent --show-error --request GET "https://realtime-api.voiceflow.com/v1/stable/workflow?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN"
```

Read the chosen Workflow and locate its existing Handoff step in `blocks[].steps[]`:

```sh
export WORKFLOW_ID='YOUR_WORKFLOW_ID'

curl --fail-with-body --silent --show-error --request GET "https://realtime-api.voiceflow.com/v1/stable/workflow/$WORKFLOW_ID?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN"
```

Workflow lists return `nextCursor`; Workflow reads return `truncated.nextCursor`. Pass the returned value as the next request's `cursor` when more results or blocks remain. Read the step's current content and links before editing.

### 3. Set the Sunshine destination and customer mapping

Save `sunshine-handoff.json`. Replace the sample Zendesk group and brand IDs with your account's IDs. The variable names in braces must already exist in your project; use the names that hold your actual customer identity.

```json
{
  "kind": "handoff",
  "content": {
    "config": {
      "provider": "sunshine",
      "endUserId": "{user_id}",
      "userEmail": "{customer_email}",
      "customerName": "{customer_name}",
      "userLanguage": "en",
      "groupId": "230",
      "brandId": "600",
      "priority": "normal"
    },
    "handoffContext": { "type": "full" }
  }
}
```

```sh
export HANDOFF_STEP_ID='YOUR_HANDOFF_STEP_ID'

curl --fail-with-body --silent --show-error --request PATCH "https://realtime-api.voiceflow.com/v1/stable/workflow/$WORKFLOW_ID/step/$HANDOFF_STEP_ID?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @sunshine-handoff.json
```

Inspect `unresolvedReferences` and read the step back before testing. Unknown variable names can remain literal text. This patch leaves the step's existing return/failure settings and links in place; verify that the Workflow reaches the Handoff step and its enabled exits lead to the intended blocks.

### 4. Compile and verify the configured path

```sh
curl --fail-with-body --silent --show-error --request PUT "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  --header "Authorization: Bearer $VF_TOKEN"
```

Compilation prepares the Environment's Draft; it does not publish it. Run a Draft test, then publish the reviewed configuration before testing the customer connection. Use the exchange checks below with a real support teammate.

#### CLI

### 1. Store the Sunshine connection

```sh
vf --output-format json integration connect --integration sunshine \
  --project-id "$PROJECT_ID" < sunshine-connection.json
```

A successful response reports `Integration sunshine connected.` Verify a real exchange after configuring the Workflow.

### 2. Read the Workflow and Handoff step

List Workflows to find its server-issued ID:

```sh
vf --output-format json workflow list --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT"
```

Read the chosen Workflow and locate its existing Handoff step in `blocks[].steps[]`:

```sh
export WORKFLOW_ID='YOUR_WORKFLOW_ID'

vf --output-format json workflow get --workflow-id "$WORKFLOW_ID" \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT"
```

Workflow lists return `nextCursor`; Workflow reads return `truncated.nextCursor`. Pass the returned value with `--cursor` when more results or blocks remain. Read the step's current content and links before editing.

### 3. Set the Sunshine destination and customer mapping

Save `sunshine-handoff.json`. Replace the sample Zendesk group and brand IDs with your account's IDs. The variable names in braces must already exist in your project; use the names that hold your actual customer identity.

```json
{
  "kind": "handoff",
  "content": {
    "config": {
      "provider": "sunshine",
      "endUserId": "{user_id}",
      "userEmail": "{customer_email}",
      "customerName": "{customer_name}",
      "userLanguage": "en",
      "groupId": "230",
      "brandId": "600",
      "priority": "normal"
    },
    "handoffContext": { "type": "full" }
  }
}
```

```sh
export HANDOFF_STEP_ID='YOUR_HANDOFF_STEP_ID'

vf --output-format json workflow update-step --workflow-id "$WORKFLOW_ID" \
  --step-id "$HANDOFF_STEP_ID" --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT" < sunshine-handoff.json
```

Inspect `unresolvedReferences` and read the step back before testing. Unknown variable names can remain literal text. This patch leaves the step's existing return/failure settings and links in place; verify that the Workflow reaches the Handoff step and its enabled exits lead to the intended blocks.

### 4. Compile and verify the configured path

```sh
vf --output-format json environment compile --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT"
```

Compilation prepares the Environment's Draft; it does not publish it. Run a Draft test, then publish the reviewed configuration before testing the customer connection. Use the exchange checks below with a real support teammate.

<a id="handle-handoff-in-your-chat-client"></a>

### Receive and send support messages

#### Studio

The Voiceflow Chat widget handles sending and receiving human-support messages. The exchange checks below verify the configured customer connection.

For your own Chat interface, switch to [Code](?view=developer#receive-and-send-support-messages) for runtime message handling.

#### Developer

<a id="use-zendesk-handoff-in-a-custom-chat-client"></a>

Implement the [live-agent handoff runtime events](/docs/api-reference/agent-runtime/chat/handoff) in your custom Chat client. Register listeners before connecting and wait for the existing session to resume before sending customer messages.

- Resume the existing Chat session with the Socket.IO connection and wait for `client.started` before sending messages.
- Render incoming `action.trace` events with type `live-agent-handoff` for the active conversation.
- Send customer text with `action.send`, using `action.type: "live-agent-handoff"`, `payload.type: "message"` and the message text.
- Follow the trace's return configuration when offering return-to-AI controls; do not create a replacement session to resume the handoff.

Use the linked runtime reference for the complete connection example, event shapes and terminal states. Voiceflow manages the Sunshine Conversations relay; you do not need to deploy a Custom Handoff service for this connection.

### Share files during handoff

Customer uploads are limited to **25 MB per file** (26,214,400 bytes). Choose a smaller file before uploading if it exceeds that limit.

#### Studio

During the live conversation, use the Chat widget's attachment control to send a file and have the support teammate open it in Agent Workspace. Have the teammate send a file back and check that the customer can open it. The Handoff step's **Configuration** JSON can disable customer uploads with `disableFileUpload: true`; leave it unset or set it to `false` to allow attachments.

#### Developer

A custom client must upload the file before sending its runtime action:

1. Request an upload slot from `POST https://general-runtime.voiceflow.com/v1/handoff/file-storage` with `projectID`, `userID`, `versionID` (the active Environment alias), `fileName` and `fileType`. The session must already have an active handoff.
2. POST a multipart form to the returned `url`, including every returned `fields` entry and the file. Confirm the upload succeeded before sending the action.
3. Send `action.send` with `action.type: "live-agent-handoff"` and `payload.type: "file_upload"`. Its `files` array contains the uploaded object key as `id`, plus `name`, `size` and MIME `type`. Sunshine processes only the first file in that array; send one attachment per action.
4. Render `action.trace` payloads with `event: "file_received"` using their `file.url`, `file.name` and optional `file.type`. Confirm the human can open the customer upload and the customer can open the reply attachment.

Use the [handoff action schema](/docs/api-reference/v4interact/interact-non-stream#streaming-action) for exact file fields. The optional custom-client example below includes the upload sequence. Do not send provider credentials to the customer's browser.

### Verify the exchange

Publish the configured Environment and test through your customer-facing Chat connection. Confirm that the conversation reaches Agent Workspace with the intended requester, group and brand. Have a teammate reply and check that the customer receives the message. Exchange an attachment in each direction and confirm both can open it. Then check closure, the configured return to AI and a failed-connection fallback. If replies or closure never reach the customer, check the Sunshine webhook's callback URL, subscriptions and shared secret. Saving the step or creating a ticket alone does not verify a live handoff.

### Handle handoff in a custom Chat client

Resume the existing session, receive human replies and send customer messages.

#### Studio

The Voiceflow Chat widget handles the runtime connection. For a custom Chat interface, use the Code instructions in this section.

#### Developer

Install `socket.io-client` in your application. Replace the placeholders with the active conversation's project, user, Environment alias and session key. This example assumes public API access. For a private project, use an authorized trusted client and keep the project API credential on your server.

```js title="Resume the existing human conversation"
import { io } from 'socket.io-client';

const socket = io('https://general-runtime.voiceflow.com', {
  path: '/v4/interact/socket',
  autoConnect: false,
});
const projectID = 'YOUR_PROJECT_ID';
const userID = 'YOUR_USER_ID';
const environmentID = 'YOUR_ENVIRONMENT_ALIAS';
let ready = false;

socket.on('connect', () => {
  ready = false;
  socket.emit('client.start', {
    projectID,
    userID,
    environmentID,
    sessionKey: 'CURRENT_SESSION_KEY',
    config: { modality: 'chat' },
  });
});
socket.on('client.started', ({ newSessionRequired }) => {
  ready = !newSessionRequired;
  if (!ready) console.error('The handoff session was not resumed.');
});
socket.on('action.trace', ({ trace }) => {
  if (trace.type === 'live-agent-handoff') console.log(trace.payload);
});
socket.on('session.ended', () => { ready = false; });
socket.on('disconnect', () => { ready = false; });
socket.on('error', error => { console.error(error); });
socket.connect();

// Send only after client.started confirms the session is ready.
function sendSupportMessage(message) {
  if (!ready) return;
  socket.emit('action.send', {
    action: { type: 'live-agent-handoff', payload: { type: 'message', message } },
  });
}

// Call with one browser File, only while this same handoff is active.
const MAX_SUPPORT_FILE_BYTES = 25 * 1024 * 1024;

async function sendSupportFile(file) {
  if (!ready) throw new Error('Wait for the existing session to resume.');
  if (file.size > MAX_SUPPORT_FILE_BYTES) {
    throw new Error('Choose a file no larger than 25 MB (26,214,400 bytes).');
  }
  const slotResponse = await fetch('https://general-runtime.voiceflow.com/v1/handoff/file-storage', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ projectID, userID, versionID: environmentID, fileName: file.name, fileType: file.type }),
  });
  if (!slotResponse.ok) throw new Error(`Upload slot failed: ${slotResponse.status}`);
  const slot = await slotResponse.json();
  const form = new FormData();
  for (const [key, value] of Object.entries(slot.fields)) form.append(key, value);
  form.append('file', file);
  const upload = await fetch(slot.url, { method: 'POST', body: form });
  if (!upload.ok) throw new Error(`File upload failed: ${upload.status}`);
  if (!ready) throw new Error('The support connection ended during upload.');
  socket.emit('action.send', {
    action: {
      type: 'live-agent-handoff',
      payload: { type: 'file_upload', files: [{ id: slot.fields.key, name: file.name, size: file.size, type: file.type }] },
    },
  });
}
```

Replace the log handler with your application's message rendering. Gate return-to-AI controls on the handoff trace's configuration and handle its terminal states using the [Chat handoff event contract](/docs/api-reference/agent-runtime/chat/handoff#customer-controls-and-terminal-states). An SSE turn cannot receive a human reply that arrives after that response has ended.

<a id="ticket-comments"></a>

## Working with ticket comments

Add an internal support note or retrieve the latest ticket comment.

**Add ticket comment** requires `ticketID` and `comment`. It writes an **internal note** (`public: false`) and returns the ticket update result. **Find latest comment** requires `ticketID` and returns the last comment from the ticket's comment list. The note action does not send a public reply to the customer.

Use the [permitted ticket ID](#ticket-access) for both actions. Internal notes can contain staff-only information; customer access to a ticket does not authorize disclosing every comment.

### Add or read a comment

#### Studio

Zendesk Add ticket comment editor showing ticket ID and comment inputs — Add ticket comment writes an internal note to the selected ticket.

### 1. Add the note action

Add **Add ticket comment** to the agent, Playbook or Workflow. Supply the known ticket ID and the note your team needs, such as a confirmed replacement preference. Check that it appears on the correct ticket with internal visibility.

### 2. Retrieve the latest comment

Use **Find latest comment** when the agent needs the most recent ticket comment. Inspect the result before configuring **Capture response**. Internal notes can contain staff-only information; decide which details the agent may share.

#### Developer

Add an internal note to a known ticket:

#### API

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_add_ticket_comment",
  "inputs": {
    "ticketID": 8422,
    "comment": "Customer confirmed that a replacement is preferred."
  }
}'
```

To retrieve the latest comment on that ticket:

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_find_latest_comment",
  "inputs": {
    "ticketID": 8422
  }
}'
```

#### CLI

```sh
vf --output-format json integration execute --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_add_ticket_comment \
  --inputs '{
  "ticketID": 8422,
  "comment": "Customer confirmed that a replacement is preferred."
}'
```

To retrieve the latest comment on that ticket:

```sh
vf --output-format json integration execute --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_find_latest_comment \
  --inputs '{
  "ticketID": 8422
}'
```

After a successful, untruncated execution, `output.data` is the updated ticket for Add ticket comment and the comment object for Find latest comment. Verify the internal note on the correct ticket, and inspect the retrieved comment's `public` value before sharing its text with a customer.

<a id="customer-lookups"></a>

## Finding users and groups

Retrieve a customer by email or a support group by ID.

**Find user** requires `email`. The runtime searches Zendesk with that email and returns the first user in the result. **Find group** requires `groupID` and returns that group. These actions read records; they do not create users or groups.

### Retrieve the matching record

#### Studio

Zendesk Find user editor with the email input — Use the customer's confirmed email for Find user.

### 1. Find the customer

Add **Find user**, collect the customer's confirmed email and map it to **email**. Inspect the returned record before using it for ticket creation or personalization. A lookup result is not proof that the person chatting owns that email.

### 2. Find a support group

Add **Find group** and supply a known **groupID** for support routing. Configure **Capture response** when another step needs the user or group data. Verify the result against a record you can locate in Zendesk.

#### Developer

Look up the customer by their confirmed email:

#### API

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_find_user",
  "inputs": {
    "email": "maya@northstar.example"
  }
}'
```

To retrieve a known support group:

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_find_group",
  "inputs": {
    "groupID": 230
  }
}'
```

#### CLI

```sh
vf --output-format json integration execute --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_find_user \
  --inputs '{
  "email": "maya@northstar.example"
}'
```

To retrieve a known support group:

```sh
vf --output-format json integration execute --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_find_group \
  --inputs '{
  "groupID": 230
}'
```

After a successful, untruncated execution, `output.data` is the matched user or group. No match is an action failure, not a successful empty result. Confirm the returned record in Zendesk. An email lookup does not authenticate the person chatting, and Find group does not create a group.

<a id="organizations"></a>

## Updating organizations

Change an existing organization's details and routing settings.

**Update organization** requires `organizationID`. Optional changes include `name`, `details`, `domainNames`, `externalID`, `groupID`, `notes`, `tags`, `sharedComments`, `sharedTickets`, `url` and custom `fields`. It returns the updated organization result.

Use this action in a staff-controlled administration workflow. Organization routing and ticket-visibility changes affect more than one customer's request; do not expose them as customer-selected changes.

### Apply an organization change

#### Studio

Zendesk Update organization tool editor with organization ID and optional fields — Limit organization updates to the fields your workflow is intended to change.

### 1. Configure the organization update

Add **Update organization** to the relevant agent, Playbook or Workflow. Supply the Zendesk organization ID and only the intended fields. Give the tool a specific **Trigger** so unrelated requests do not change organization-wide settings.

### 2. Check the changed record

Run against an organization you can inspect, then open the same record in Zendesk and confirm the changed fields. Review visibility changes such as **sharedTickets** and **sharedComments** before enabling them.

#### Developer

Update a known organization's notes:

#### API

```sh
curl --fail-with-body --silent --show-error --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/zendesk/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "zendesk_update_organization",
  "inputs": {
    "organizationID": 311,
    "notes": "Route replacement-order questions to Retail support."
  }
}'
```

#### CLI

```sh
vf --output-format json integration execute --integration zendesk \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name zendesk_update_organization \
  --inputs '{
  "organizationID": 311,
  "notes": "Route replacement-order questions to Retail support."
}'
```

After a successful, untruncated execution, inspect the organization at `output.data` and confirm its notes in Zendesk. For `fields`, use the connected account's organization-field IDs and object values; review `sharedTickets` and `sharedComments` before changing organization-wide visibility.
