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

> Install Voiceflow agent assist for Chatwoot. Load approved case context, choose a staff task and review suggestions in the Dashboard App.

## Overview

Follow the selected Chatwoot conversation in a Dashboard App. The panel accepts appContext only from the configured parent window and origin, then asks the server for an authorized snapshot.

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 | Dashboard App |
| Case selection | Workspace/SDK binding with server authorization. |
| Tasks | Find policy, Draft reply, Suggest next step, Summarize and a question form. |
| Draft delivery | Copy completed suggestions for human review. |

<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 direct Chatwoot dashboard parent; 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 Chatwoot staff app"
npm install --prefix support-platforms
node support-platforms/setup.mjs chatwoot https://staff.example ./assist-build/chatwoot ./staff-ui.json
```

Serve the generated `panel.html`, `panel.css` and `panel.bundle.mjs` together at `https://staff.example/support-platforms/chatwoot/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 Chatwoot 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:'chatwoot',
    origin:process.env.ASSIST_PROVIDER_ORIGIN,
    accountId:process.env.CHATWOOT_ACCOUNT_ID,
    authorizeRecord,authorizationForStaff,
  },
});
```

Set `ASSIST_PROVIDER_ORIGIN` to the fixed provider origin, such as `https://app.chatwoot.com`. `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 raw `api_access_token` 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

In **Settings → Integrations → Dashboard Apps**, add **Voiceflow agent assist** with the generated panel URL. On self-hosted installations, confirm Dashboard Apps are enabled for the installed release. Open it in a sandbox conversation and complete embedded staff sign-in.

### 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 entry listens for `appContext` and requests `chatwoot-dashboard-app:fetch-info` before a task. A conversation change clears the old answer before loading the next snapshot. Only the conversation ID crosses into the lookup; a posted `currentAgent`, contact object or message body is never staff authentication or trusted case context. Qualify IDs by the server-owned Chatwoot account.

| Data boundary | Contract |
| --- | --- |
| Approved snapshot | Conversation ID, status, priority, timestamps and up to ten public, non-activity messages available in the conversation response. |
| 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. |

Use **Copy suggestion** only after the complete result arrives, then review/edit it in the normal support workspace. This supplied surface has no verified draft-composer insertion action. A provider endpoint that sends a message or saves a note is not used as a substitute.

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

Copy one completed suggestion and review it in the normal composer. No provider send, saved note, refund or call-control request may occur. Verify a partial stream never enables Copy suggestion. 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

Delete or disable the pilot Dashboard App in Integrations; the underlying customer inbox remains usable. 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.
