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

# Intercom integration

> Connect Voiceflow to Intercom so AI agents can use customer records, answer from Help Center content and hand off conversations to your support team.

## Overview

Voiceflow integrates with Intercom so your AI agents can look up customers, read support conversations, answer from Help Center articles and bring in your support team.

Choose the setup for your support task: [MCP tools](#connecting-intercom) for Intercom's tool catalog, an [API tool](#find-a-customer-with-an-api-tool) for a request you configure, [Knowledge import](#help-center) for public support articles, or a [handoff relay](#live-agent) for live teammate replies. These paths have separate setup; adding an MCP server does not configure the others.

### Examples of when to use Intercom

- **[Recognize a returning customer](#finding-customers)** — retrieve the verified customer's profile and company before answering an account question.
- **[Understand an open case](#reading-conversations)** — read the relevant support thread so the customer does not have to repeat their issue.
- **[Leave useful context for support](#adding-notes)** — add an internal summary without sending it to the customer.
- **[Import help articles](#help-center)** — look up an article through MCP or import approved public articles into Knowledge.
- **[Human agent hand-off](#live-agent)** — keep the customer in your Voiceflow chat while a teammate replies from Intercom.

#### Studio

Start with an editable Voiceflow project and an Intercom workspace you can authorize. Set up MCP tools, API tools and Knowledge in Agent studio. A developer must build and host the service used for live handoff.

#### Developer

Use Voiceflow's management and execution APIs or CLI for MCP tools and Knowledge, and Intercom's REST API for custom operations. Keep provider tokens on your backend or in Voiceflow Secrets. The live-handoff path requires your own deployed relay.

<a id="connecting-intercom"></a>

## Connecting MCP tools

Authorize Intercom's hosted tool catalog and select the actions your agent needs.

Create a private app in Intercom's **Developer Hub → Configure → Authentication** to obtain an access token for your workspace. Grant **Read and list users and companies** for customer/company lookup and **Read conversations** for threads. Add **Write conversations** for internal notes and **Read and write articles** for MCP article tools. A private-app token accesses your own workspace; use Intercom’s OAuth flow when building an app for other workspaces. See [Intercom authentication](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication).

Intercom hosts MCP at `https://mcp.intercom.com/mcp` for US workspaces and `https://mcp.eu.intercom.com/mcp` for EU workspaces; AU hosting is not supported. Select the endpoint for your workspace's region. This page uses bearer-token setup so the same connection can be prepared in Studio or Code.

Server registration is only required for MCP. For a customer lookup through an API tool, [prepare that request directly](#find-a-customer-with-an-api-tool); for articles or live support, follow the setup in their own sections.

<a id="connect-and-select-tools" />

### Connect through MCP

#### Studio

### 1. Prepare the Intercom secret

Open your project in [Agent studio](https://creator.voiceflow.com). In the left sidebar, open **More → Secrets** and create `intercom_token`. Set its default value to your test Intercom token: MCP tool discovery uses that default. This also sets the value on Main’s Published version, so perform initial setup in a test project. If your test Environment has a Secret override, set that override for its Draft too. Do not place tokens in agent instructions.

### 2. Add the MCP server

Open **Agent**, click **+** beside **Global tools**, choose **MCP**, then **Create MCP tool**. Name the server **Intercom**, enter the regional **Server URL** above, add the header `Authorization` with value `Bearer {intercom_token}` using the Secret reference. Select **Add MCP server**.

Native Add MCP server dialog with Server URL, Server name and Headers controls — Enter Intercom’s regional MCP endpoint and configure its authorization header.

### 3. Choose and test a tool

Select a read tool such as `get_contact`, write a trigger describing when the agent should use it, and configure its inputs. Add only the tools your agent needs. Run a test with a known contact in your own test workspace and compare the returned record with Intercom. A discovered tool list confirms access to the catalog, not that every operation is authorized.

#### Developer

Use a dedicated test project for initial setup. Set `VF_TOKEN` to your Voiceflow bearer token, `PROJECT_ID` to the project ID, `ENVIRONMENT` to a test Environment alias and `INTERCOM_TOKEN` to your private-app token. The examples use the US MCP endpoint; substitute the EU URL when required. Use a current [Voiceflow CLI](/docs/cli/install) with `mcp-server create`, `mcp-tool execute` and `tool create` support. CLI examples read the Voiceflow token from `VF_TOKEN` and preserve JSON output.

#### API

### 1. Create the discovery secret and test override

MCP discovery reads the project default value. Create it with your test token; **this also writes Main’s Published value**, even when your later calls target another Environment:

```sh
jq -n --arg token "$INTERCOM_TOKEN" \
  '{name:"intercom_token",visibility:"restricted",defaultValue:$token}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

Save `secret.id` as `SECRET_ID`. Write the value to your test Environment's Draft:

```sh
jq -n --arg token "$INTERCOM_TOKEN" --arg env "$ENVIRONMENT" \
  '{value:$token,environmentAlias:$env,versionVariant:"draft"}' |
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

### 2. Register the server and list its tools

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/mcp-server?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "name":"Intercom",
    "url":"https://mcp.intercom.com/mcp",
    "headers":[{"key":"Authorization","value":"Bearer {intercom_token}"}]
  }'
```

Keep `mcpServer.id` as `SERVER_ID`. Resolve any `unresolvedReferences` before continuing. Header values returned by a read are redacted; do not write `[redacted]` back as a credential.

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&serverID=$SERVER_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Find the selected operation in `mcpTools[]`; save its `id` as `TOOL_ID` and inspect its `inputSchema`.

#### CLI

### 1. Create the discovery secret and test override

```sh
jq -n --arg token "$INTERCOM_TOKEN" \
  '{name:"intercom_token",visibility:"restricted",defaultValue:$token}' |
vf secret create --project-id "$PROJECT_ID" --output-format json
```

This sets the default used by discovery and Main’s Published value. Use a test project. Save `secret.id` as `SECRET_ID`, then set the test Draft override:

```sh
jq -n --arg token "$INTERCOM_TOKEN" --arg env "$ENVIRONMENT" \
  '{value:$token,environmentAlias:$env,versionVariant:"draft"}' |
vf secret set-value --project-id "$PROJECT_ID" --secret-id "$SECRET_ID" \
  --output-format json
```

### 2. Register the server and list its tools

```sh
vf mcp-server create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --name Intercom --url 'https://mcp.intercom.com/mcp' \
  --headers '[{"key":"Authorization","value":"Bearer {intercom_token}"}]' \
  --output-format json
```

Keep `mcpServer.id` as `SERVER_ID` and resolve any `unresolvedReferences`.

```sh
vf mcp-tool list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --server-id "$SERVER_ID" --output-format json
```

Find the operation in `mcpTools[]`; save its `id` as `TOOL_ID` and inspect `inputSchema`. Discovered IDs belong to your Environment; the upstream name is not a Voiceflow tool ID.

Management and standalone tests use the Environment's **Draft**. The default Secret also configures Main’s Published value; a named Environment’s Draft override does not configure that Environment’s Published value. Before serving live traffic, [set the Secret on the target Published version](/docs/cli/commands/secret/set-value) with `versionVariant: "published"`, then [publish the tested agent](/docs/documentation/deploy/environments/publishing).

<a id="refresh-or-repair-the-connection" />
<a id="refresh-or-repair-the-connection-accordion-title" />

### Refresh or repair the MCP connection

Update discovered tools without confusing synchronization with authorization.

In Studio, manage the server from the MCP tool picker. For Code, run `vf mcp-server sync --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --server-id "$SERVER_ID"` or PUT `/v1/stable/mcp-server/{serverID}/sync` with the same project/Environment query and authorization.

- **401 or authorization error:** check the token, its permissions and the regional endpoint. For a bearer connection, update the Secret’s discovery default and the target Environment’s runtime value, then retry a read. To update discovery with [Set secret value](/docs/cli/commands/secret/set-value), omit `environmentAlias` and use `versionVariant: "published"`; this also changes Main’s Published value. To update a scoped runtime value, specify both the Environment and `versionVariant`. An OAuth connection needs reauthorization when its grant changes.
- **Tool missing:** refresh the server's tools, then inspect the discovered schema. Intercom exposes extra Fin Operator tools only for an eligible workspace, user and OAuth connection; bearer-token setup does not grant them.
- **Removing a server:** inspect its attached tools first. Deleting it removes the connection; it does not migrate the tools that depend on it.

<a id="finding-customers"></a>

## Finding customers

Retrieve the right contact and company before answering account questions.

Choose **MCP** for Intercom’s predefined customer and company tools, or **API tool** to control the customer-search request yourself. Both paths must use an identity verified by your application.

### Prepare customer context

An Intercom token authorizes workspace access; it does not verify the customer chatting with your agent. Have your application's implementing team map the authenticated customer to their Intercom contact ID and verified email before a lookup runs.

#### Studio

In **More → Variables**, create `intercom_contact_id` and, for the email-search API tool, `intercom_customer_email`. Leave their defaults empty. Have your developer populate them for the authenticated customer's session and provide the corresponding test values. Bind tool inputs to these variables; use the developer's test values for editor tests rather than saving one customer's identity as a project default.

#### Developer

Create `intercom_contact_id` and, for email search, `intercom_customer_email` in the selected Environment with the [Variables API](/docs/api-reference/resources/variable#create-variable-post-v2-stable-variable) or [CLI](/docs/cli/commands/variable/create), leaving their defaults empty. Your authenticated backend supplies `variables: {"intercom_contact_id":"VERIFIED_CONTACT_ID","intercom_customer_email":"VERIFIED_CUSTOMER_EMAIL"}` on the first [action request](/docs/api-reference/v4interact/interact-non-stream#streaming-action), before the agent can call a lookup. Session creation alone does not populate them; do not accept an unchecked browser value as the mapping.

### Identify the customer

#### MCP

Use `search_contacts` to find a contact and `get_contact` to retrieve the full record. For company information, use `list_companies` and `get_company`. Intercom's universal `search` and `fetch` tools offer another search-and-retrieve path. [Connect through MCP](#connect-through-mcp) first, then inspect the connected server's schemas before choosing argument names.

#### Studio

### 1. Add a contact lookup

In **Agent → Global tools → + → MCP**, select the Intercom server and `get_contact`. Bind its contact identifier to the ID established by your authenticated application. If you need to locate the contact first, add `search_contacts` and pass the verified email or external identity as its schema specifies.

### 2. Use the returned context

Add a company tool only when the support task needs company information. Have your application establish which company the customer may access and bind that ID to the retrieval tool; keep workspace-wide company listing in your staff or backend workflow. In **Capture response**, map only the fields needed for the answer. Test a known customer and a missing match.

#### Developer

**Execute a lookup**

Select `get_contact` from the discovered catalog and set `TOOL_ID` to its Voiceflow ID. Save its schema-matching inputs as `intercom-inputs.json`; replace `CONTACT_ID_ARGUMENT` with the exact identifier field from that schema:

```json
{"inputs":{"CONTACT_ID_ARGUMENT":"YOUR_INTERCOM_CONTACT_ID"}}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool/$TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool/$TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @intercom-inputs.json
```

#### CLI

```sh
vf mcp-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$TOOL_ID" --output-format json

vf mcp-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$TOOL_ID" --output-format json < intercom-inputs.json
```

Inspect `success`, `error` and `output`. A provider result with `output.isError: true` is a failed operation even when HTTP succeeds. MCP results may contain JSON inside text content; parse the returned representation before selecting customer fields. Treat `truncated: true` as incomplete output.

**Make the lookup available to the agent**

Standalone execution does not attach a tool. Create and populate `intercom_contact_id` as described in [Prepare customer context](#prepare-customer-context) before creating the attachment, so its reference resolves and the session has the verified identity.

Save the body below as `intercom-attachment.json`, replacing both occurrences of `CONTACT_ID_ARGUMENT` with the exact schema field used in the test. POST it to `/v2/stable/tool` with the same project/Environment query and bearer authorization. The CLI equivalent is `vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --output-format json < intercom-attachment.json`:

```json
{
  "type":"mcp",
  "mcpToolID":"YOUR_VOICEFLOW_MCP_TOOL_ID",
  "target":{"global":true},
  "description":"Retrieve the authenticated customer's Intercom profile when an account question needs it.",
  "inputVariables":{
    "CONTACT_ID_ARGUMENT":{"mcpIntegrationVariableName":"CONTACT_ID_ARGUMENT","required":true,"defaultValue":"{intercom_contact_id}"}
  }
}
```

For this MCP input, `required: true` with a nonempty variable default sends the bound identity instead of exposing it as a model-selected parameter. Check `unresolvedReferences` and correct any unresolved variable before running the agent, then publish the tested changes. Use the same create/execute/attach sequence for the other MCP tools on this page, with their discovered IDs and inputs.

#### API tool

<a id="find-a-customer-with-an-api-tool" />
<a id="find-a-customer-with-an-api-tool-accordion-title" />

#### Studio

### 1. Prepare the credential

Prepare `intercom_token` in **More → Secrets** for the Environment you will test. Its default also sets Main’s Published value; use a test project.

### 2. Configure the customer search

In **Agent → Global tools → + → API**, configure **POST** to your regional Intercom API host plus `/contacts/search`. Add `Authorization: Bearer {token}`, `Intercom-Version: 2.18` and `Content-Type: application/json`. Use `{"query":{"field":"email","operator":"=","value":"{email}"}}` as the JSON body.

### 3. Bind the inputs and test

Bind the `token` input’s default to the `intercom_token` Secret and `email` to `intercom_customer_email` from [Prepare customer context](#prepare-customer-context). Test with the developer's verified customer email and inspect the returned `data` records before selecting a contact ID. Handle a missing or ambiguous match explicitly.

Native API tool input editor for a verified-customer Intercom lookup — Bind the lookup input to the customer's verified identity.

#### Developer

Use the [API-tool creation, execution and attachment flow](#give-the-agent-a-customer-update-tool) with these changes for a lookup:

- Set `httpMethod` to `post` and `url` to your regional Intercom API host plus `/contacts/search`.
- Name the tool **Find Intercom customer** and describe when to look up the authenticated customer instead of updating their name.
- Keep the Secret-backed authorization, `Intercom-Version: 2.18` and JSON content-type headers. Prepare the Secret in the same test Environment before executing the tool; the [Secret setup](#connect-through-mcp) also explains its project-default and Published effects. Server registration is only needed for the MCP path.
- Use `{"query":{"field":"email","operator":"=","value":"{email}"}}` as the raw JSON body. Replace the example's `contact_id` and `customer_name` inputs with `email` in the execution inputs and attachment. List its API-tool input ID before attachment, then bind it with `required: false` and `defaultValue: "{intercom_customer_email}"`. [Create and populate that variable](#prepare-customer-context) before attachment; do not let the model choose another customer's email.
- At standalone execution, supply `inputs.token: "{intercom_token}"` and your test customer's verified `inputs.email`. Inspect `success`, `output.status` and `output.body.data`; handle a missing or ambiguous match before using a contact ID.

Verify the selected record against the authenticated customer before publishing. See [Intercom contact search](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/contacts/searchcontacts).

### Match and pagination checks

Do not reveal a record merely because a customer supplied its email address. Establish identity in your application, and handle missing or ambiguous matches explicitly. Contact IDs, company IDs and Voiceflow user IDs are different identifiers.

For company context, check the customer's company access in your application before calling `get_company`. A workspace-wide company list is not a list of companies that a customer is permitted to see.

MCP search tools use cursor pagination; company listing uses page numbers. Keep the original filters when requesting another page. The connected tool's schema and result supply the cursor or page fields. See [Intercom's MCP contract](https://developers.intercom.com/docs/guides/mcp).

<a id="reading-conversations"></a>

## Reading conversations

Use the relevant support thread to understand a customer's existing issue.

Use `search_conversations` to locate the relevant case, then `get_conversation` to retrieve it. `search` also supports queries beginning with `object_type:conversations`; `fetch` accepts the typed IDs returned by that search.

### Verify access to the conversation

<a id="conversation-access" />

Your application must check that the authenticated customer may access the selected conversation. A supplied case ID or an agent's Instructions do not perform that check. Keep broad searches in the implementing team's backend; let the agent retrieve only an authorized case.

#### Studio

Create `intercom_conversation_id` in **More → Variables**, leaving its default empty. Have your implementing team supply the permitted case ID for the verified customer and populate the session variable before retrieval or note actions run. Bind the selected tool's conversation-ID input default to that variable and keep it required. Obtain a permitted test case ID from the team for editor tests.

#### Developer

Create `intercom_conversation_id` using the same [variable setup](#prepare-customer-context). On your backend, search within the verified customer's scope, check the selected conversation's access, then supply its ID in the next action's `variables` before the agent retrieves it. For an MCP attachment, bind the schema's conversation-ID input with `required: true` and `defaultValue: "{intercom_conversation_id}"`, using the [contact attachment pattern](#finding-customers). Reject an unauthorized case before tool execution.

### Retrieve an existing case

#### Studio

### 1. Select the conversation tools

In **Global tools → + → MCP**, select `get_conversation` from Intercom and bind its conversation-ID input to the permitted case variable above. Do not replace it with a model-selected or customer-supplied case ID.

### 2. Check the retrieved case

If the application returns several permitted cases, ask which issue the customer means before selecting one. Run the agent against a permitted test conversation and compare its summary with the thread in Intercom.

#### Developer

Use the [MCP execution procedure](#finding-customers) with the discovered conversation tool ID and its input schema. Pass the permitted case ID from your backend's access check. Consume only the fields your application needs; do not send unrelated customers' threads into the agent's context.

### Interpret the result

A retrieved conversation can contain public replies and internal notes. Treat those as different visibility levels: internal team context must not be quoted back as a customer-facing reply. Reading a thread does not subscribe to future messages or establish a [live handoff](#live-agent).

### Continue a replacement request

Use the existing case and give a teammate the context needed to finish it.

### 1. Find the permitted case

A returning customer says their replacement arrived but they still need a return label. Verify their identity, select the conversation they may access and read its current status instead of asking them to repeat the original issue.

### 2. Check the support answer

Use an approved Help Center article for the return instructions. If the customer still needs help, record their confirmation in an internal note. Keep staff notes out of the customer-facing answer.

### 3. Continue with a teammate when needed

For a live reply, use the configured handoff relay and pass the relevant customer context. Confirm that the customer receives the teammate's reply; reading the thread or saving a note alone does not complete the handoff.

<a id="help-center"></a>

## Import help articles

Look up articles on demand or import public content into Knowledge.

Choose the path that matches how your agent should answer:

| Path | What it does | Content boundary |
| --- | --- | --- |
| Intercom MCP article tools | Find and retrieve an article during a tool call. | Uses the authorized Intercom connection; does not import it into Voiceflow Knowledge. |
| Knowledge Web page import | Index approved public article URLs for Knowledge retrieval. | Only content the public URL importer can access; no automatic Intercom account synchronization. |

### Find an article during a conversation

#### Studio

Add `search_articles` and `get_article` from the Intercom MCP server. Configure the search inputs using the server's schema, restrict customer-facing answers to published, approved content, and retrieve the chosen article before summarizing it. Test a known policy question and a question outside the available content.

#### Developer

Use the [MCP execution flow](#finding-customers) for `search_articles` and `get_article`. The current search supports `phrase` and `state`; use `state: "published"` for customer-facing searches. Follow the returned article ID to retrieve the full body. Do not treat a search snippet as the complete policy.

### Import public articles into Knowledge

#### Studio

### 1. Choose the public article

Open the Intercom article's public URL in a signed-out browser and confirm it contains the approved answer. In your Voiceflow project's left sidebar, open **Knowledge base → Add data source → Web page(s)** and paste that URL.

Native web page import dialog with a public Northstar Help Center article URL — Import a public Help Center article using its public URL.

### 2. Import and check the answer

Import the page, wait for processing to complete and inspect its content. Choose the refresh schedule you need. Enable Knowledge on the agent, then use **Run** to ask a question answered by that article and inspect the retrieved source. A listed URL alone does not prove the article was indexed or used.

#### Developer

POST the approved public URL to the Knowledge API using a project API key in `VF_PROJECT_API_KEY`. Replace the illustrative `.example` URL with your article. This endpoint uses a project API key, separately from your Voiceflow management bearer token and Intercom token.

```sh
jq -n --arg env "$ENVIRONMENT" \
  '{data:{type:"url",url:"https://support.northstar.example/en/articles/shipping",refreshRate:"never",projectEnvironmentIDOrAlias:$env}}' |
curl --fail-with-body --silent --show-error \
  'https://realtime-api.voiceflow.com/v1alpha1/public/knowledge-base/document' \
  -H "Authorization: $VF_PROJECT_API_KEY" -H 'Content-Type: application/json' --data-binary @-
```

Save `data.documentID` as `DOCUMENT_ID` and inspect `data.status`. Check processing with the same project key **and Environment**:

```sh
curl --fail-with-body --silent --show-error --get \
  "https://realtime-api.voiceflow.com/v1alpha1/public/knowledge-base/document/$DOCUMENT_ID" \
  --data-urlencode "projectEnvironmentIDOrAlias=$ENVIRONMENT" \
  -H "Authorization: $VF_PROJECT_API_KEY"
```

Repeat the check until `data.status` is `SUCCESS` or `ERROR`. Omitting the Environment can select a different version's document set. On `ERROR`, inspect the document in Knowledge before retrying. Wait for a completed import before testing retrieval. Inspect the imported content and verify the actual agent answer in the target Environment; a diagnostic query alone does not prove runtime retrieval. Use the [Knowledge document reference](/docs/api-reference/kbpublicapidocument/create-document) for replacement, refresh and deletion operations.

### Maintain articles and private content

Separate article editing from the lifecycle of imported Knowledge.

Intercom MCP also exposes `list_articles`, `create_article` and `update_article`. Creation requires a title and author ID; updates require the article ID and a changed field. Use an authorized test article, keep new content in `draft` until reviewed, and verify the article in Intercom after each write. Editing it does not immediately update an already imported Knowledge document.

For content behind Intercom authentication, build an authorized export to an approved document and upload that document through the Knowledge API. Your exporter owns article selection, updates and removals. Do not make private material public to make the URL importer work.

<a id="live-agent"></a>

## Human agent hand-off

Keep the customer in Voiceflow while your team replies from Intercom.

This path requires a developer-built, HTTPS **Custom Handoff relay** between Voiceflow and Intercom. An MCP connection or a created Intercom conversation does not provide the two-way relay. Prepare the service and Intercom webhook subscription before configuring the Handoff step.

### Prepare the relay and Intercom workspace

Your relay must implement create, customer-message and close operations from the [Custom Handoff connection contract](/docs/developers/handoff/connection-api), plus a webhook receiver for Intercom replies and closure. The [shared starter](/docs/developers/handoff/connect#build-and-connect-the-service) provides mock mode and a Chatwoot pilot; implement the Intercom adapter yourself.

- Keep the verified customer's Intercom contact ID, provider conversation ID and Voiceflow connection ID in durable storage.
- In your Intercom app's **Webhooks** configuration, set your relay's HTTPS receiver URL and subscribe to `conversation.admin.replied` and `conversation.admin.closed`. Grant their required conversation permissions.
- Save the app's **Client secret** for verifying `X-Hub-Signature` on the raw request body. Intercom uses HMAC-SHA1 with a `sha1=` prefix. Authenticate and persist the event before acknowledging it. This receiver is your service, not Voiceflow's Custom Handoff callback.
- Your relay signs its separate [callbacks to Voiceflow](/docs/developers/handoff/webhook-events) with the configured Voiceflow webhook secret. Do not reuse the Intercom app secret for that boundary.

### Connect and route the handoff

#### Studio

### 1. Connect the deployed relay

Open your project in **Agent studio → More → Integrations**. Select **Connect** on **Custom Handoff**. Enter your relay's **Base URL**, its **Auth header name** and **Auth header value**, and the **Webhook secret** used to sign callbacks to Voiceflow. The webhook secret must contain at least 32 characters.

### 2. Configure the support Workflow

Open **Workflows**, create a support Workflow and add a **Handoff** step. Choose **Custom Handoff** as its provider. Map the verified customer identity and a queue ID your relay translates to an actual Intercom destination. Choose the conversation context to send and configure **Return** and **Fail** paths.

Native Handoff step configured with the Custom Handoff provider and customer context — Use Custom Handoff to route the conversation through your Intercom relay.

### 3. Make the Workflow reachable

Attach the Workflow to the agent and describe when to call it, such as when the customer asks for a person. Publish to a test Environment, connect a test widget to it and run the checks below with a teammate in Intercom.

#### Developer

Save your relay connection as `intercom-handoff.json`. These credentials authenticate Voiceflow to your service; your service holds the Intercom token separately.

```json
{
  "integration":"custom_handoff",
  "credentials":{
    "baseUrl":"https://support-bridge.example.com",
    "authHeaderName":"Authorization",
    "authHeaderValue":"Bearer YOUR_RELAY_TOKEN",
    "webhookSecret":"REPLACE_WITH_AT_LEAST_32_RANDOM_CHARACTERS"
  }
}
```

POST this file to `https://realtime-api.voiceflow.com/v1/stable/integration/custom_handoff?projectID=PROJECT_ID` with Voiceflow authorization and JSON content type. A 200 response confirms stored configuration, not relay delivery. This connects the default credential slot rather than an Environment-specific Draft slot.

Create an escalation Workflow with a Handoff step whose provider is `custom`, customer fields come from verified session variables, `queueId` maps to your Intercom destination, and `returnPath`/`failPath` are enabled. Follow the complete [headless Workflow creation, attachment and test publication sequence](/docs/developers/handoff/connect#configure-voiceflow-through-the-api); a Workflow is not reachable merely because it exists. Preserve existing agent registrations when adding it.

Your Chat client must handle Handoff traces and human replies using the [Chat handoff contract](/docs/api-reference/agent-runtime/chat/handoff). Test with the same published Environment as the client.

### Verify the complete conversation

With a test customer and an Intercom teammate:

1. Escalate once; confirm one conversation appears for the correct contact and inbox.
2. Send one customer message from Voiceflow and one public teammate reply from Intercom. Each must arrive once in the other interface.
3. Add a private note; it must stay in Intercom. Replay a provider event; it must not duplicate the reply.
4. Close the Intercom conversation; verify the configured Return path. Make the relay unavailable and verify the Fail path separately.

### Implement the Intercom relay mapping

Translate conversation operations and events without leaking notes or looping messages.

Use your workspace's regional Intercom API host with `Authorization: Bearer INTERCOM_TOKEN`, `Content-Type: application/json` and `Intercom-Version: 2.18`.

- **Create:** POST `/conversations` with `{"from":{"type":"user","id":"INTERCOM_CONTACT_ID"},"body":"Customer requested support."}`. Match `from.type` to the contact's actual role (`user` or `lead`). Save the returned **`conversation_id`**, not the initial message's `id`. Route it to the intended team using the provider's [assignment operation](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/conversations/manageconversation).
- **Customer message:** POST `/conversations/{conversation_id}/reply` with `message_type:"comment"`, `type:"user"`, the stored `intercom_user_id` and `body`. Deduplicate Voiceflow delivery IDs before posting.
- **Human reply:** verify the signed `conversation.admin.replied` notification, extract only the new public admin reply, and send one normalized `message.received` event with a stable ID, timestamp and agent name. Exclude customer echoes, private notes and already processed parts. Do not manufacture `agent.joined` from conversation creation.
- **Close:** POST `/conversations/{conversation_id}/parts` with `{"message_type":"close","type":"admin","admin_id":"INTERCOM_ADMIN_ID"}`. Process `conversation.admin.closed` as one `conversation.ended` callback. Record terminal state before sending the callback so your own close cannot trigger a loop.
- **Files:** start with `files:false`. Enable file delivery only after implementing both directions and checking each side's attachment constraints; text relay alone does not support attachments.

See Intercom's [create](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/conversations/createconversation), [reply](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/conversations/replyconversation), [conversation management](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/conversations/manageconversation) and [webhook contracts](https://developers.intercom.com/docs/references/webhooks/webhook-models). Use the shared service's [durability and recovery checks](/docs/developers/handoff/connect#build-and-connect-the-service) before deploying your adapter.

<a id="adding-notes"></a>

## Adding internal notes

Leave a support summary for teammates without messaging the customer.

Intercom's MCP `add_internal_note` tool adds a teammate-only note to an existing conversation. It cannot send a public reply. It requires **Write conversations** permission and a regular conversation ID, not a ticket ID. The note is attributed to the administrator who authorized the connection.

Use the [permitted conversation ID](#conversation-access), with the same binding as retrieval. The admin's workspace authorization does not establish which customer's conversation this request may change.

### Add and verify a note

#### Studio

Add `add_internal_note` from the Intercom MCP server. Bind `conversation_id` to `intercom_conversation_id` as a required input default and set `body` to the support summary. Write a trigger that limits it to recording agreed support context. Run one test, then open the conversation in Intercom and confirm the content appears as an internal note.

#### Developer

Use the discovered `add_internal_note` ID with the [MCP execution API or CLI](#finding-customers). Replace the illustrative conversation ID with the case authorized by your backend; for agent use, bind its ID as described in [conversation access](#conversation-access):

```json
{
  "inputs":{
    "conversation_id":"YOUR_INTERCOM_CONVERSATION_ID",
    "body":"Customer confirmed that the replacement arrived. Follow up on the return label."
  }
}
```

Inspect the execution result and created note part, then retrieve the thread with `get_conversation`. Do not retry a write blindly after an uncertain result; check whether the note already exists.

### Note visibility and conversation state

The note stays private to teammates, but adding it can reopen a snoozed conversation assigned to another administrator. The returned part can be `note_and_unsnooze`. Confirm the intended conversation state before adding notes to a background automation.

<a id="updating-customers"></a>

## Updating customer records

Use a custom API tool for changes outside the MCP tool catalog.

Intercom's MCP contact tools retrieve records. To create or update a contact, configure a Voiceflow API tool or call Intercom from your backend. Use [Intercom's contact API](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/contacts) to choose fields and permissions; this is a custom API request, not a prebuilt Voiceflow Intercom action.

Contact updates require Intercom's `read_write_users` or `write_users_companies` OAuth scope. A token that can only read contacts cannot perform the write. See [Update a contact](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/contacts/updatecontact).

### Update an existing contact

#### Studio

### 1. Configure the request

In **Agent → Global tools → + → API**, create **Update Intercom customer**. Set the method to **PUT** and URL to your workspace's Intercom API host plus `/contacts/{contact_id}`. Add `Authorization: Bearer` with a secret-backed token input, `Intercom-Version: 2.18` and `Content-Type: application/json`. Bind the token input's default to your Secret, not a model-supplied value.

### 2. Set the fields and test the result

Use a JSON body such as `{"name":"{customer_name}"}`. Bind `contact_id` to your authenticated session’s `intercom_contact_id` variable so the model cannot select another customer record. Describe `customer_name` as the name the customer confirmed. Capture the response's `id` and `name`, run the tool on a test contact, and verify the record in Intercom. Use the same configuration pattern for a contact search with **POST** `/contacts/search` and its documented query body.

#### Developer

Set `INTERCOM_API` to your workspace's regional API host and `INTERCOM_CONTACT_ID` to the existing contact. US uses `https://api.intercom.io`; select the matching regional host from [Intercom's API reference](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/contacts).

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "$INTERCOM_API/contacts/$INTERCOM_CONTACT_ID" \
  -H "Authorization: Bearer $INTERCOM_TOKEN" \
  -H 'Intercom-Version: 2.18' -H 'Content-Type: application/json' \
  -d '{"name":"Alex Morgan"}'
```

Check the returned contact `id` and `name`. This request updates Intercom directly; it does not create or attach a Voiceflow tool. To let the agent perform the operation, use the [API tool management contract](/docs/cli/commands/api-tool/create) and [tool attachment contract](/docs/cli/commands/tool/create) with the same method, URL and headers. Bind credentials as Secret-backed attachment input defaults and let the agent supply only the customer-approved fields. Test the saved tool with [API tool execution](/docs/cli/commands/api-tool/execute) before publishing.

### Write checks

Update the existing contact ID instead of creating a new contact for every conversation. Show the customer what will change before writing. On a validation error, inspect the provider response and correct the input; on a timeout, retrieve the record before retrying. Intercom search can lag a newly created contact, so preserve the ID returned by creation.

### Give the agent a customer-update tool

Create, test and attach the same Intercom request through Voiceflow.

#### Studio

Use **Global tools → + → API call** to save the PUT request above. Bind its token input to `intercom_token` and the contact input to the verified customer's ID. Require the agent to confirm the new name before calling it. Test the result, then publish the selected Environment.

#### Developer

Save this definition as `intercom-api-tool.json`. This example uses the US API host; replace it for your workspace. The placeholders declare API-tool inputs, not project Secrets:

```json
{
  "name":"Update Intercom customer",
  "description":"Update the authenticated customer's name after they confirm the new value.",
  "httpMethod":"put",
  "url":"https://api.intercom.io/contacts/{contact_id}",
  "headers":[
    {"key":"Authorization","value":"Bearer {token}"},
    {"key":"Intercom-Version","value":"2.18"},
    {"key":"Content-Type","value":"application/json"}
  ],
  "body":{"type":"raw-input","contentType":"json","content":"{\"name\":\"{customer_name}\"}"}
}
```

Save `intercom-update-inputs.json` with your test contact ID and confirmed name. At standalone execution, a top-level Secret reference supplies the token:

```json
{"inputs":{"token":"{intercom_token}","contact_id":"YOUR_INTERCOM_CONTACT_ID","customer_name":"Alex Morgan"}}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @intercom-api-tool.json
```

Save the returned `apiTool.id` as `API_TOOL_ID`, then inspect its schema and execute:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&apiToolID=$API_TOOL_ID" \
  -H "Authorization: Bearer $VF_TOKEN"

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @intercom-update-inputs.json
```

#### CLI

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < intercom-api-tool.json
```

Save `apiTool.id` as `API_TOOL_ID`:

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json

vf api-tool variable list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --api-tool-id "$API_TOOL_ID" --output-format json

vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < intercom-update-inputs.json
```

Check `success`, `output.status` and `output.body.id` / `output.body.name`. `error` explains a failed execution; HTTP success from Voiceflow does not itself prove an Intercom write succeeded. Retrieve the contact to verify an uncertain write before retrying.

Save this as `intercom-api-attachment.json`, replacing the API tool ID and each input ID with the corresponding `variables[].id` from the list response (match by `name`). [Create and populate the identity variable](#finding-customers) before attaching this tool, using the same verified session identity as the lookup:

```json
{
  "type":"api",
  "apiToolID":"YOUR_VOICEFLOW_API_TOOL_ID",
  "target":{"global":true},
  "description":"Update the authenticated customer's name only after they confirm the new value.",
  "inputVariables":{
    "token":{"apiToolInputVariableID":"TOKEN_INPUT_ID","required":false,"defaultValue":"{intercom_token}"},
    "contact_id":{"apiToolInputVariableID":"CONTACT_ID_INPUT_ID","required":false,"defaultValue":"{intercom_contact_id}"},
    "customer_name":{"apiToolInputVariableID":"CUSTOMER_NAME_INPUT_ID","required":true,"defaultValue":null}
  }
}
```

POST the artifact to `/v2/stable/tool` on `https://realtime-api.voiceflow.com` with the same bearer authorization and project/Environment query. With the CLI:

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < intercom-api-attachment.json
```

Inspect `unresolvedReferences`: an unrecognized Secret name is not a valid credential binding. Correct it before testing the agent. Attachment returns `tool`; creating the request alone does not attach it. Test routing and the confirmed write in your Draft, then prepare published credentials and publish the tested Environment.
