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

> Install Voiceflow agent assist for Kustomer. Load approved case context, choose a staff task and review suggestions in the conversation insights card.

## Overview

Add Voiceflow agent assist to Kustomer’s conversation insights panel. Support teammates can find policy, draft a reply, choose a next step or summarize the approved case context while working on a customer request.

The supplied reader loads the conversation’s subject, status, priority and timestamps. It does not load message history; staff add the approved issue facts in the question for a useful draft or recommendation.

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. The staff assistant uses a custom interface powered by Voiceflow; it does not use the customer chat widget.

**Note:** 
**Automating customer requests instead?** Use the [in-app Kustomer integration](/docs/guides/integrations/kustomer/overview). This installation teaches staff assistance: teammates review and copy suggestions, then send through Kustomer themselves.

| Capability | Supplied behavior |
| --- | --- |
| Staff surface | conversation insights card |
| Case selection | The Cards SDK follows the opened conversation; the server separately authorizes its record ID. |
| 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. |

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

From the extracted archive root, save `kustomer-options.json` with the exact Kustomer workspace origin:

```json title="kustomer-options.json"
{"parentOrigin":"https://YOUR_ORG.kustomerapp.com"}
```

Use your HTTPS staff origin without a path:

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

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

Set `ASSIST_PROVIDER_ORIGIN` to the fixed provider origin, `https://YOUR_ORG.api.kustomerapp.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 `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

The build writes `kustomer-app.json`, a private app with a conversation **smartbar-card** KView. Its **DynamicCard** embeds the generated staff panel, which loads Kustomer’s Cards SDK.

Prepare `KUSTOMER_ORG` and a server-held `KUSTOMER_ADMIN_KEY` with **org.admin.apps**. A Kustomer administrator [registers and installs the private app](https://developer.kustomer.com/docs/apps/register-and-install) in a sandbox. Registration and installation are separate operations:

```bash title="Register the private app version"
curl --fail-with-body --silent --show-error --request POST \
  "https://$KUSTOMER_ORG.api.kustomerapp.com/v1/apps/available" \
  --header "Authorization: Bearer $KUSTOMER_ADMIN_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @assist-build/kustomer/kustomer-app.json > kustomer-available.json
```

Use the returned private app name and version for installation:

```bash title="Prepare the installation request"
jq '{app:.data.attributes.name,version:.data.attributes.version}' \
  kustomer-available.json > kustomer-install.json
```

Check both values are populated, then install with the same org's administrator key:

```bash
curl --fail-with-body --silent --show-error --request POST \
  "https://$KUSTOMER_ORG.api.kustomerapp.com/v1/apps/install" \
  --header "Authorization: Bearer $KUSTOMER_ADMIN_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @kustomer-install.json
```

Poll `GET https://YOUR_ORG.api.kustomerapp.com/v1/apps/install-state/{app}-{version}` with that same authorization until its status is `installed`; stop and inspect `install_failed`. Make **Voiceflow agent assist** available in the pilot staff's conversation insights panel. Registration alone does not install the KView.

Keep provider administration keys outside the staff panel. Preserve the SDK’s `parentUrl` and `id` query parameters through sign-in redirects. Allow framing only by the approved workspace origin and verify embedded staff sign-in before enabling the pilot. The card needs a normal conversation context; a custom DynamicCard context must retain that contract.

### 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 can be empty, but this metadata-only reader then lacks the customer’s issue details. Add the approved facts for a useful draft, policy answer or next step; an empty-input summary must explain the missing message history. **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 [Cards SDK](https://developer.kustomer.com/docs/apps/cards-sdk) supplies `context.conversation.id` after initialization and on `context` changes. The starter accepts only conversation contexts and clears its selection for another record type. Opening a different conversation invalidates the old result before the new authorized context loads. Browser context is a selection hint; it does not authenticate a teammate or grant case access.
| Data boundary | Contract |
| --- | --- |
| Approved snapshot | Conversation ID, subject, status, priority and creation/update timestamps from `GET https://YOUR_ORG.api.kustomerapp.com/v1/conversations/{id}`. Message bodies, notes, contact details and custom fields are excluded. This default cannot summarize the complete customer conversation. |
| 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 Kustomer sidebar integration uses SDK context changes rather than a live transcript feed. 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 conversation about an unopened item delivered 12 days ago and an approved 30-day policy. Confirm the visible record ID and approved snapshot. First run every task with an empty question and verify it identifies the missing facts without inventing the conversation. Then supply the approved delivery and condition facts in the question and rerun the relevant tasks. 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

Switch to a second conversation during a pending answer: confirm the old output clears, the new ID/context loads and a late response cannot reappear. Close the conversation or select a customer/company record and check tasks become disabled. 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 SDK initialization, conversation context and stale-response invalidation.

Compare the visible ID with the workspace. Confirm the Cards SDK initializes once and receives `context` events with `type: conversation`. Repeat a switch during a pending response, and check the saved record ID and the starter’s generation guard. Do not pass a customer-level or custom context as a conversation. 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

Disable the Kustomer app or remove its insights card from the pilot workspace. Retain the prior registered version and its installation record; do not assume disabling deletes previously installed components. 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. Use the [Kustomer integration](/docs/guides/integrations/kustomer/overview) for built-in customer/conversation actions, [Import help articles](/docs/guides/integrations/kustomer/overview#help-articles) and [Human agent hand-off](/docs/guides/integrations/kustomer/overview#human-agent-hand-off). Connecting that integration does not install this staff card.
