Build with

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 for Intercom’s tool catalog, an API tool for a request you configure, Knowledge import for public support articles, or a handoff relay for live teammate replies. These paths have separate setup; adding an MCP server does not configure the others.

Examples of when to use 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.

Code

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.

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.

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; for articles or live support, follow the setup in their own sections.

Connect through MCP

Studio

1

Prepare the Intercom secret

Open your project in Agent studio. 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.

Enter Intercom’s regional MCP endpoint and configure its authorization header. Photo:
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.

Code

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 with mcp-server create, mcp-tool execute and tool create support. CLI examples read the Voiceflow token from VF_TOKEN and preserve JSON output.

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:

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

2

Register the server and list its tools

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.

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

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 with versionVariant: "published", then publish the tested agent.

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

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.

Code

Create intercom_contact_id and, for email search, intercom_customer_email in the selected Environment with the Variables API or CLI, 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, 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

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

Code

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:

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 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:

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.

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.

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

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.

Code

Create intercom_conversation_id using the same variable setup. 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. 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.

Code

Use the MCP execution procedure 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.

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.

Import help articles

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

Choose the path that matches how your agent should answer:

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.

Code

Use the MCP execution flow 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.

Import a public Help Center article using its public URL. Photo:
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.

Code

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.

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

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

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, plus a webhook receiver for Intercom replies and closure. The shared starter 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 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.

Use Custom Handoff to route the conversation through your Intercom relay. Photo:
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.

Code

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

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; 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. 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.
  • 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, reply, conversation management and webhook contracts. Use the shared service’s durability and recovery checks before deploying your adapter.

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

Code

Use the discovered add_internal_note ID with the MCP execution API or CLI. Replace the illustrative conversation ID with the case authorized by your backend; for agent use, bind its ID as described in conversation access:

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.

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

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.

Code

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.

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 and tool attachment contract 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 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.

Code

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:

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

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

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 before attaching this tool, using the same verified session identity as the lookup:

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:

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.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.