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

> Launch Voiceflow agent assist from Intercom Inbox. Load approved case context and review suggestions in your protected staff application.

## Overview

Launch the staff assistant from Intercom Inbox with the current conversation already selected. The server verifies the Canvas signature and workspace, then returns a fixed-origin staff link containing only an opaque conversation ID.

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 | signed Inbox Canvas launcher → staff application |
| Case selection | Record ID supplied by a pinned launch; server authorization is still required. |
| 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, use your HTTPS staff origin without a path:

```bash title="Build the Intercom staff app"
npm install --prefix support-platforms
node support-platforms/setup.mjs intercom https://staff.example
```

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

Set `ASSIST_PROVIDER_ORIGIN` to the fixed provider origin, such as `https://api.intercom.io`. `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

Mount `createIntercomLauncher` from the starter’s `intercom.mjs` at `POST /intercom/initialize`, preserving the raw request body. Supply the app client secret, expected workspace ID and the generated panel URL as `staffAppURL`. Keep the proxy/body limit at 64 KiB. The handler verifies `X-Body-Signature`, teammate location and workspace before constructing the link.

In **Developer Hub → Configure → Canvas Kit → For teammates**, enable **Add to conversation details** and set that initialize URL. Save, install for the pilot workspace and add the app to the conversation-details pane. Choose **Open agent assist** and sign in to the staff host.

### 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 signed initialize request supplies `conversation.id`; the launcher copies only that ID into the link fragment. Neither the signature nor the browser ID grants record access in the staff service. Every context/answer request rechecks staff workspace and conversation permissions. The external tab is pinned to its launch: switching Intercom conversations produces a new launcher, not an update to an already-open staff tab.

| Data boundary | Contract |
| --- | --- |
| Approved snapshot | Conversation ID/title/state/open flag, timestamps and up to ten comment parts available in the response. Note parts and unrelated contact/admin data are excluded. The reader pins Intercom-Version 2.18. |
| 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

Launch a second record and confirm its ID/context replace the first in that new launch. Existing companion tabs remain pinned to their original record; finish/close them deliberately. For manual selection, edit the ID mid-response and prove tasks stay disabled until the next context load succeeds. 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

Disable the teammate Canvas location or uninstall the pilot app; remove its initialize route when unused. 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.
