> ## 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.

# Add agent assist to Zendesk Agent Workspace

> Deploy Voiceflow agent assist for human support staff using Zendesk. Install the remote ticket-sidebar application, authorize case context and review suggested answers.

## Overview

Embed the staff panel in the Zendesk Support ticket sidebar. It follows the saved ticket automatically, checks staff access and loads approved context. Staff choose a task, review the result and can append a completed reply draft to the existing Zendesk composer.

Both the interface and server remain in your staff host; Voiceflow runs the published read-only assistant. This walkthrough is on demand. It does not listen to calls, ingest a live transcript or send a customer reply automatically.

<a id="requirements"></a>

## Prepare the staff deployment

Gather the assistant, staff identity and provider permissions once.

| Requirement | Owner and readiness check |
| --- | --- |
| Published read-only assistant | Voiceflow owner supplies approved Knowledge, project ID, Published test Environment alias and a server API credential. Start with [Build an agent assist assistant](/docs/guides/agent-assist). |
| Protected staff host | Developer supplies HTTPS, existing staff sign-in, CSRF, body/rate limits and iframe-compatible SSO. [Shared setup](/docs/guides/integrations/contact-centers/agent-assist#connect-the-staff-assistant) defines these adapters. |
| Saved Support tickets and a private ZAF 2.0 app | Zendesk administrator supplies installation access and pilot roles/groups. Unsaved tickets are excluded. |
| Delegated Zendesk access | Staff-host owner supplies each signed-in agent’s server-held OAuth token with read access, plus a trusted `zendeskSubdomain` and numeric `zendeskUserId` on the staff principal. No shared administrator token. |
| Acceptance cases | Administrator supplies two sandbox staff accounts with different access and two known cases/contacts. Use fictional data. |

Download and extract the [starter bundle](/docs/examples/support-platforms-starter.zip). Keep `support-platforms`, `contact-center-assist` and `amazon-connect` as sibling directories. The app reuses your host’s verified staff session; platform registration alone does not create one. Test SSO in the actual embedded browser.

<a id="installation"></a>

## Install the staff entry

Connect the server, generate the platform app and open a sandbox interaction.

### 1. Connect the provider reader

Use the supplied Zendesk factory in your existing Node.js 22+ staff host:

```js title="Mount the Zendesk staff routes"
import { createZendeskRoutes } from './support-platforms/providers.mjs';
import { requireStaff, verifyCsrf, accessTokenForStaff } from './staff-adapters.mjs';

export const handleAssistRequest = createZendeskRoutes({
  projectID: process.env.VF_PROJECT_ID,
  environmentAlias: process.env.VF_ENVIRONMENT_ALIAS,
  apiKey: process.env.VF_API_KEY,
  subdomain: process.env.ZENDESK_SUBDOMAIN,
  requireStaff, verifyCsrf, accessTokenForStaff,
});
```

`requireStaff` verifies the host session and supplies the trusted Zendesk user/account mapping. `accessTokenForStaff(staff, { signal })` retrieves that agent’s OAuth token from server storage. The loader checks [the authenticated Zendesk user](https://developer.zendesk.com/api-reference/ticketing/users/users/#show-self) against the principal before reading a ticket with that token. A missing/mismatched identity or denied ticket stops the request. Complete OAuth consent/token lifecycle in your existing identity system; the SDK’s browser user object does not sign staff into this host.

Mount `handleAssistRequest` at both same-origin POST paths: `/api/agent-assist` and `/api/agent-assist/context`. Apply a 32 KiB body limit, bounded authentication/provider reads and staff rate/concurrency limits. `verifyCsrf` applies the host’s policy to both routes. Keep Voiceflow and provider credentials on the server.

### 2. Build and install the platform app

Replace `https://staff.example` with your staff host’s HTTPS origin, without a path. From the extracted archive root:

```bash title="Build the Zendesk page and manifest"
npm install --prefix support-platforms
node support-platforms/setup.mjs zendesk https://staff.example
```

The command creates `assist-build/zendesk/`: `panel.html`, `panel.css`, the browser bundle, `SETUP.md` and `zendesk-app/manifest.json` with the exact remote URL. It includes the ZAF SDK script and automatic ticket binding; no HTML edits are needed. Serve the three panel files together at `https://staff.example/support-platforms/zendesk/panel.html`, behind staff sign-in.

Review the generated manifest’s author details. From the archive root, validate and package its app directory using [ZCLI](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/). Validation requires the administrator’s authorized Zendesk sandbox session (`zcli login`); this is separate from the host’s per-agent read token:

```bash title="Validate and package the private app"
zcli apps:validate assist-build/zendesk/zendesk-app
zcli apps:package assist-build/zendesk/zendesk-app
```

Keep only `ticket_sidebar`, not `new_ticket_sidebar`. In **Admin Center → Apps and integrations → Apps → Zendesk Support apps**, upload the private app package and restrict it to pilot roles/groups. Open a saved sandbox ticket, expand the apps tray and complete embedded staff sign-in.

Use `Cache-Control: no-store` and a restrictive CSP permitting the actual workspace and SSO ancestors. The Zendesk build also needs the documented SDK script origin. The setup command refuses to overwrite an existing build directory; append a new output directory after the origin when rebuilding.

### 3. Check context and choose a task

The saved ticket/contact ID appears automatically. Wait for **Case context ready** and inspect **Approved case context**. A denied context check leaves tasks disabled and starts no Voiceflow request. Each later task reloads its snapshot on the server.

| Task | Expected result |
| --- | --- |
| **Find policy** | Policy source, applicable conditions and missing facts for staff. |
| **Draft reply** | Customer-facing wording only, for human review; no invented approval or completed action. |
| **Suggest next step** | One useful check, its reason and any escalation condition. |
| **Summarize** | Facts, recorded actions and unresolved work from the available snapshot. |

The question box is optional for these four actions. Use it to focus a task, or enter a question and choose **Ask assistant**. No task runs just because a ticket/contact opens. Configure the assistant to honor the selected task’s output format; if a reply contains internal guidance, edit or regenerate it before using it.

<a id="case-context"></a>

## Configure case context

Follow the workspace selection while keeping authorization on the server.

The browser entry obtains [`ticket.id`](https://developer.zendesk.com/api-reference/apps/apps-support-api/ticket_sidebar/#ticketid) from its own sidebar instance. On activation it checks the saved ticket; on tab deactivation, submission or ticket update it clears the previous result. No ticket ID entry or **Finish case** step is required.

The server reader includes the ticket ID, subject, status, priority and update time, plus public comments among the latest five comment records. Private notes, attachments, requester details and custom fields are excluded. This is a limited saved-record snapshot, not the complete conversation or unsaved composer text. Review the allowlist before use and extend it only with approved fields.

**Insert draft into Zendesk** is enabled only after a complete **Draft reply** result. Clicking it rechecks staff/case access and the current ticket, then invokes `comment.appendText` on that same sidebar instance. It appends plain text without replacing existing composer content. Review the recipient, channel and wording before using Zendesk’s normal send/submit control. If insertion cannot be confirmed, inspect the composer before copying or generating another draft; the button does not retry an uncertain append.

| Boundary | Required behavior |
| --- | --- |
| Workspace ID | Automatic selection only; never permission to read the record. |
| Server snapshot | Check staff/tenant access before the preview and every answer. |
| Result | Discard late output after a switch; enable copy only after completion. |

Changing the case or task focus clears the previous result. Every task starts a fresh Voiceflow conversation; follow-up facts must come from the refreshed snapshot or current question. The host must unload/reset the panel on logout and account changes. Aborting browser consumption does not prove remote work stopped or transcripts were deleted; set expiry and retention with the owning teams.

<a id="testing"></a>

## Test the staff workflow

Prove automatic context, human review and recovery before expanding the pilot.

### 1. Verify the automatic context and all four tasks

Open an allowed sandbox interaction without typing an ID. Use an unopened-item case delivered 12 days ago with an approved 30-day policy. Confirm the visible ID and approved snapshot, then run each task with an empty question. Check facts, policy sources and explicit missing information. Summaries must not claim coverage beyond the loaded snapshot.

### 2. Test the platform lifecycle and draft action

Choose **Draft reply**, inspect the customer wording, then choose **Insert draft into Zendesk**. With existing composer text present, confirm both texts remain and no comment is sent. **Find policy**, **Suggest next step** and **Summarize** must never enable insertion. Change tickets while a reply is streaming and while insertion is checking the current ticket; the old result must not be appended.

### 3. Prove denial and recover from failure

Use the second staff account for a record it cannot access: no context or answer may appear and no runtime request may start. Test an expired session, denied provider read, interrupted stream and unavailable assistant. Partial output must disappear and remain unavailable for copying or insertion. Restore the service and retry manually; normal support must remain usable.

### The panel or context does not load

Check installation, embedded sign-in and the approved provider reader.

Confirm the generated URL, app assignment, exact iframe ancestors and staff session. For 401, sign in again. For 403, check CSRF, tenant mapping and record access without weakening them. For 413, narrow the approved snapshot. For 502, inspect a redacted server correlation record for provider/runtime failures. Retry context by reopening/reloading the app after recovery; do not expose the panel publicly to bypass SSO.

### The suggestion is incomplete or uses the wrong case

Check the loaded snapshot and current workspace instance before using the result.

Compare the visible ID and approved fields with the actual interaction. Reopen the app to obtain a fresh binding. Check the server’s account/instance configuration and published Voiceflow Environment. Test the switch during a response again; a successful network abort alone does not prove late results are discarded. Review model output against sources before using it.

<a id="release-and-maintenance"></a>

## Release and maintain assistance

Record the accepted build, permissions and rollback before broadening access.

### 1. Release to the pilot group

Release first to the pilot group. Record the staff-host build, field allowlist, platform registration, tested staff identities and Voiceflow Environment/release. Repeat the allowed/denied interaction check through that released entry. Assign owners for policy freshness, identity/token lifecycle, app/SDK updates, retention and incidents; rerun [quality evaluation](/docs/guides/channels/agent-assist/evaluate-assistance) after changes.

### 2. Restore the reviewed deployment

Disable or uninstall the pilot Support app. Restore the recorded host build and reviewed Voiceflow release, then repeat a fresh-session check.

Local review can use `node support-platforms/fixture-server.mjs` and `http://127.0.0.1:4397/fixture-sign-in?platform=zendesk`. These clearly labelled fictional SDK/model fixtures exercise binding, task buttons and cleanup plus the simulated composer; they do not establish live installation, provider permissions, SSO or answer quality. Complete those checks in the actual sandbox before release.

For business-system tools, [Import help articles](/docs/guides/integrations/contact-centers) and Human agent hand-off, use the canonical Integration manuals.
