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

# Use agent assist with Freshchat

> Add Voiceflow agent assist to Freshchat's conversation sidebar. Load approved case context and review suggestions in a protected staff panel.

## Overview

Open the staff panel inside a Freshchat conversation sidebar. The packaged host reads the current conversation through the Freshworks SDK, follows activation changes and offers an explicit action to replace the reply-editor text.

Your team hosts the staff interface and case-access checks; Voiceflow runs the published read-only assistant. Tasks run only on a staff action. Automatic selection loads a snapshot, not a live transcript or a customer-send action.

| Capability | Supplied behavior |
| --- | --- |
| Staff surface | packaged conversation sidebar with the protected staff panel |
| Case selection | Workspace/SDK binding with server authorization. |
| Tasks | Find policy, Draft reply, Suggest next step, Summarize and a question form. |
| Draft delivery | Explicit composer replacement after human confirmation; no submit or customer send. |

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

## Prepare the staff deployment

Collect the assistant, verified identity and platform configuration once.

| Requirement | Owner and handoff |
| --- | --- |
| Published staff assistant | Voiceflow owner supplies approved Knowledge, project ID, Published test Environment alias and server API credential. Keep tools read-only. |
| Staff host | Application owner supplies Node.js 22+, HTTPS, verified staff/tenant sign-in, CSRF, body/rate limits and bounded provider reads. |
| Case access | Case-service owner approves the fields, checks staff/record access on every request and supplies the exact provider-to-case mapping. |
| Pilot platform | Administrator supplies the named app/launcher surface, test staff with allowed/denied records and the actual sandbox record IDs. |
| Direct parent origin | Developer records the packaged Freshchat app document that directly contains the staff iframe; pin that exact HTTPS origin in the build options. A top-level platform URL is not necessarily the direct parent. |

Download the [starter bundle](/docs/examples/support-platforms-starter.zip). Keep `support-platforms`, `contact-center-assist` and `amazon-connect` as sibling directories. [Shared agent-assist setup](/docs/guides/integrations/contact-centers/agent-assist) owns the host/session contracts; [build the staff assistant](/docs/guides/agent-assist) before installing the platform entry.

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

## Install the staff entry

Generate the platform files, connect authorized data and activate the pilot surface.

### 1. Build the platform files

Create a local `staff-ui.json` with the direct parent’s real HTTPS origin:

```json title="Pin the actual direct parent"
{"parentOrigin":"https://workspace.example"}
```

From the extracted archive root, use your HTTPS staff origin without a path:

```bash title="Build the Freshchat staff app"
npm install --prefix support-platforms
node support-platforms/setup.mjs freshchat https://staff.example ./assist-build/freshchat ./staff-ui.json
```

Serve the generated `panel.html`, `panel.css` and `panel.bundle.mjs` together at `https://staff.example/support-platforms/freshchat/panel.html`. The command also writes `SETUP.md` and the applicable platform artifacts. Keep credentials on the server. It refuses an existing output directory; append a new directory after the origin when rebuilding. Configure no-store, approved iframe ancestors and embedded SSO.

### 2. Connect the authorized case reader

Use the supplied read adapter rather than writing the provider fetch/allowlist yourself:

```js title="Connect the authorized Freshchat reader"
import {createRecordRoutes} from './support-platforms/providers.mjs';
import {requireStaff,verifyCsrf,authorizeRecord,authorizationForStaff} from './staff-adapters.mjs';
export const handleAssistRequest=createRecordRoutes({
  projectID:process.env.VF_PROJECT_ID,
  environmentAlias:process.env.VF_ENVIRONMENT_ALIAS,
  apiKey:process.env.VF_API_KEY,
  requireStaff,verifyCsrf,
  recordSource:{
    platform:'freshchat',
    origin:process.env.ASSIST_PROVIDER_ORIGIN,
    authorizeRecord,authorizationForStaff,
  },
});
```

Set `ASSIST_PROVIDER_ORIGIN` to the fixed provider origin, such as `https://api.freshchat.com` (choose the correct Freshchat API Region). `authorizeRecord(staff, id, {platform, signal})` must return **true** only after checking staff membership, tenant and record/field access for that configured instance. The reader checks this before retrieving credentials or reading the provider.

`authorizationForStaff(staff, {platform, signal})` returns the server-held `Bearer …` authorization value for that approved account. A shared integration credential does not establish a staff member’s entitlement. Review the reader’s fixed field allowlist before use; token consent, storage, expiry and rotation remain in your identity service.

Mount the handler at **both** same-origin POST paths, `/api/agent-assist` and `/api/agent-assist/context`. Apply the host’s CSRF policy to both, a 32 KiB body limit, staff rate/concurrency limits and bounded identity/provider reads. Honor the supplied cancellation signal. The context route starts no Voiceflow session; every later task reauthorizes and reloads the record.

### 3. Activate the platform surface

Generate a **Freshworks Platform 3.0** app for the `chat_conversation` module. Merge the generated `freshchat-app/index.html`, `host.bundle.mjs` and `location.json` into its app assets/location settings. Retain the generated icon, platform/product/runtime declarations and other required app files. The HTML loads the documented `{{{appclient}}}` SDK resource; do not replace it with a guessed CDN URL.

Run the generated project’s FDK validation and packaging commands, install the private app for the pilot account, and open it in `conversation_user_info`. Confirm the direct app iframe origin matches the configured `parentOrigin`; it can differ from the main Freshchat inbox origin. Verify nested iframe SSO before acceptance.

### 4. Load context and choose a task

Open the installed entry for an allowed sandbox record; confirm the selected ID without typing. Wait for **Case context ready** and inspect **Approved case context**. Denial keeps tasks disabled. Opening a record or loading context does not ask the model.

Choose **Find policy**, **Draft reply**, **Suggest next step** or **Summarize**. The question box is optional for these four actions; use it to focus the result. **Ask assistant** requires a question. Configure the assistant to return customer wording only for Draft reply and staff evidence/missing facts for the other tasks. Review model output before using it.

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

## Configure case context

Treat workspace IDs as selection hints and keep approved data on the server.

The host reads `client.data.get("conversation")` and uses `conversation.conversation_id`, not the numeric display ID. Activation refreshes selection; deactivation clears it. The protected panel asks its host to recheck selection before a task, and the host checks the conversation again immediately before setting editor text. Only the ID crosses the selection bridge; the backend reads approved data independently.

| Data boundary | Contract |
| --- | --- |
| Approved snapshot | Conversation identifiers, status, timestamps and up to ten normal text messages returned with the conversation; private/bot-private/restricted messages and non-text parts are excluded. |
| Staff identity | Verified host session and tenant mapping; browser agent objects are not authentication. |
| Question and result | Render text safely; treat case text as reference data, not permission to run actions. |
| History | Fresh runtime conversation per task; no automatic case memory or full-history guarantee. |

After a completed **Draft reply**, review its wording and select **Replace existing composer text with this reviewed draft**. Then choose **Replace composer with draft**. This is explicit replacement, not append: preserve any existing text yourself before consenting. The action is unavailable for policy, next-step and summary results, incomplete streams, changed records or expired staff access. The host checks the record again and escapes draft text before setting the editor. Inspect the composer after an uncertain result; no automatic retry or submit/customer send is performed.

The host must reset/unload on logout and account changes. Browser abort stops consumption; it does not prove remote execution stopped or transcripts were deleted. Set expiry and retention with the owning teams. A snapshot above the starter’s 16,000-code-unit limit is rejected; narrow the approved fields instead of silently dropping conversation coverage.

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

## Test the staff workflow

Check tasks, record changes, denial and the exact human delivery action.

### 1. Check the selected record and all four tasks

Use a sandbox case with an unopened item delivered 12 days ago and an approved 30-day policy. Confirm the visible record ID and approved snapshot. Run every task with an empty question, then add a focus. Verify policy conditions, missing facts and source references. Summaries must state gaps when the snapshot is metadata or a limited excerpt rather than a complete interaction.

### 2. Prove record isolation and access denial

Start a reply, then switch the selected workspace record before it completes. The old result must clear and never return. Clear/end the interaction where the surface supports it; test idle/non-record state as well. Use a second staff account for a denied record: no snapshot/answer may appear and no model request may start. Test logout, account switch and session expiry.

### 3. Review delivery and recover from failure

With existing sandbox composer text present, confirm replacement is disabled until the checkbox is checked. Insert one reviewed reply, verify the expected replacement and no submit or customer send. A second click must not repeat the write. Policy/summary tasks must never enable insertion; switching records or losing staff access during the check must block it. Interrupt the stream and deny the provider read; the prior/partial result must clear. Restore the service and retry manually while keeping the normal support workspace usable.

### The entry or context does not load

Check platform assignment, direct origins and staff/provider access.

Verify the generated URL/artifacts, platform assignment and embedded sign-in. For parent messaging, verify both the direct source window and configured HTTPS origin; never use a wildcard. A 401 requires sign-in; 403 requires CSRF/tenant/record checks; 413 needs a narrower approved snapshot. Inspect redacted server diagnostics for provider/runtime failure. Reopen/reload after recovery without exposing the staff service publicly.

### The result belongs to an old record

Check whether this surface follows selection or opens a pinned companion.

Compare the visible ID with the workspace. For a pinned launch, open a new launcher for the current record; a separate tab cannot follow the original workspace. For SDK/property binding, repeat the switch during the pending response and check the direct parent/SDK events and generation guard. Do not rely on a network abort alone. Discard an uncertain result before continuing.

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

## Release and maintain assistance

Record the accepted app, permissions and rollback before expanding access.

### 1. Release to the pilot staff

Record the staff-host build, provider field allowlist/mapping, platform configuration and Voiceflow Environment/release. Repeat allowed/denied cases through the actual installed entry with a fresh staff session. Assign owners for policy freshness, identity/token lifecycle, SDK/app updates and incidents; rerun [quality evaluation](/docs/guides/channels/agent-assist/evaluate-assistance) after changes.

### 2. Restore the reviewed deployment

Uninstall the pilot custom app or restore its previous package; keep the shared staff service available only to permitted users. Restore the recorded staff-host build and reviewed Voiceflow release, then repeat a fresh-session check.

Local review uses the starter’s labelled fictional fixtures; no SDK fixture or successful bundle proves provider installation, SSO, account permissions or real-model quality. Complete sandbox acceptance for this exact surface before release. For business-system tools, [Import help articles](/docs/guides/integrations/contact-centers) and Human agent hand-off, keep the canonical Integration manuals.
