# Connecting Foldspace to Intercom: Automated Support Handoff

Step-by-step walkthrough for implementing an automated handoff from your Foldspace Agent to a live Intercom support session.

## Overview

By implementing this action, your Foldspace Agent can intelligently recognize when it has reached its limits and seamlessly transition the conversation to your human support team. This ensures that frustrated users or complex technical issues are always handled with the highest level of care.

There are two ways to hand off to Intercom. Pick based on how your team works:

| Handoff type | What happens | Use when |
| :--- | :--- | :--- |
| **Live chat** | The Agent opens the Intercom Messenger on the page, seeded with the conversation summary, then steps aside. | You staff the Intercom Inbox for live chat. |
| **Email → conversation** | The Agent emails the summary and context to your Intercom-connected support address, which opens a conversation in the Inbox. | You handle support asynchronously. |

Both are triggered the same way; only the destination differs. The steps below cover the live-chat handoff — the email option is at the end of this guide.

:::caution[Leave the built-in handoff off]
This handoff is driven by your own `support_handoff` action, not by Foldspace's built-in escalation. Keep **Offer support handoff** OFF in **Style & Behavior → Data Access & Handoff** so the agent escalates through your handler rather than the built-in ticket channel. The toggle belongs to the email path only.
:::

## Prerequisites

- An active Intercom subscription with the Intercom Messenger installed on your site.
- Access to your Foldspace Dashboard.
- The Foldspace Web SDK integrated into your web application.

## Step 1: Create the "Support Handoff" Action

First, we need to define the action inside the Foldspace App so the Agent knows how to "call" for human help.

1. Log in to your Foldspace App.
2. Navigate to the **Actions** section and click **Create New Action**.
3. Fill in the fields below. Each one has a **Copy** button, so you can paste it straight into the form.

The Actions editor has a Foldspace assistant beside the form. Paste this prompt into it and it fills in every field below for you, then leaves the action as a draft for you to review before publishing.

```text
Create a new action for this agent with exactly these values.

Name: Support Handoff
Action key: support_handoff
Description: Triggers a live support hand-off via Intercom when the Agent cannot resolve an issue, detects a bug, or the user is frustrated.

Instructions:
Use this action ONLY when:

- The user explicitly asks for a human.
- You have failed to find an answer after multiple attempts.
- The user mentions a 'bug' or technical error.
- The user's sentiment is highly frustrated.

You must synthesize a clear, one-sentence summary of the user's problem for the 'user_prompt' property.

User input, one field:
- Name: user_prompt
- Type: string
- Required: yes
- Description: A concise summary of the user's issue and why the hand-off is being triggered (e.g. 'User is unable to save settings').

A front-end action handler in my own app runs this one: it opens the Intercom Messenger seeded with the summary. There is no API call and no server-side execution to configure.

Save it as a draft so I can review it before publishing.
```

### Fields

**Name**

Support Handoff

**Action key**

support_handoff

**Description**

Triggers a live support hand-off via Intercom when the Agent cannot resolve an issue, detects a bug, or the user is frustrated.

### Logic & Instructions

Paste this into the **Instructions** field. It stops the Agent from escalating on ordinary questions:

**Instructions**

Use this action ONLY when:

- The user explicitly asks for a human.
- You have failed to find an answer after multiple attempts.
- The user mentions a 'bug' or technical error.
- The user's sentiment is highly frustrated.

You must synthesize a clear, one-sentence summary of the user's problem for the 'user_prompt' property.

### User Input Configuration

Create a required input field so the Support Agent receives context immediately upon handoff. Set **Type** to `string` and **Required** to yes.

**Input name**

user_prompt

**Input description**

A concise summary of the user's issue and why the hand-off is being triggered (e.g. 'User is unable to save settings').

## Step 2: Code Implementation

Once the action is defined in the dashboard, you must handle the execution on your front-end. Add the following code to your application where you initialize the Foldspace Agent:

```javascript
window.foldspace("when", "ready", () => {
  const agent = window.foldspace.agent("planning-copilot");

  agent.addActionHandlers({
    support_handoff: {
      execute: async (params) => {
        try {
          const HANDOFF_DELAY_MS = 5000; // 5-second delay for smooth UX

          // Verify Intercom is loaded on the page
          if (!window.Intercom) {
            return {
              message:
                "Sorry, I'm unable to connect to the Support Agent right now. How else can I assist you?",
            };
          }

          const message = params?.user_prompt?.trim() || "User requested human assistance.";

          // Trigger the handoff sequence
          setTimeout(() => {
            window.Intercom("showNewMessage", message);
            agent.hide(); // Hide the Foldspace agent to let Intercom take over
          }, HANDOFF_DELAY_MS);

          return {
            message:
              "Transferring you to a Support Agent now. One moment please.",
          };
        } catch (error) {
          return {
            message:
              "Something went wrong while connecting to support. Please try again or reach out directly.",
          };
        }
      },
    },
  });

  agent.show();
});
```

## Email handoff (opens an Intercom conversation)

When you don't staff live chat, the Agent can hand off by **email** instead. This isn't a real-time transfer — Foldspace sends the conversation summary and context to your support address, and Intercom turns that email into a conversation in the Inbox.

No custom code required:

1. Enable handoff in **Style & Behavior → Data Access & Handoff** ([Style & Behavior](/user-guides/building-your-agent/)).
2. Set the destination to **Email** in [Integrations](/user-guides/integrations/).
3. Point it at an address that reaches your **Intercom Inbox**. Intercom only receives mail sent to your workspace's inbound address — `[app_id]@[workspace].intercom-mail.com` — so either send there directly, or send to a support address you've configured to auto-forward to it (**Settings → Channels → Email → Domains & addresses**).

**Don't send to a plain mailbox.** An address that doesn't forward to your workspace's inbound address never appears in the Intercom Inbox, so the escalation sits in someone's email — unassigned, unrouted, and untracked.

## Best Practices

- **User Expectations:** The 5-second delay defined in `HANDOFF_DELAY_MS` gives the user time to read the Agent's confirmation message before the UI switches.
- **Fallback:** If the Intercom script fails to load (e.g., due to an ad-blocker), the code includes a fallback message to ensure the user isn't left in a "dead end."
- **Context is King:** The `user_prompt` is automatically sent to Intercom, meaning your support team starts the conversation with a summary of the issue already in hand.

## Related

- [Connecting Foldspace to Zendesk](/guides/zendesk-handoff/) — the same live-handoff pattern for Zendesk, plus an email-to-ticket option.
- [Integrations](/user-guides/integrations/) — where handoff destinations (email, HubSpot, webhook) are configured.

## Intercom references

Official Intercom documentation for the APIs and setup this guide relies on:

- [JavaScript API: Methods](https://developers.intercom.com/installing-intercom/web/methods) — `Intercom("showNewMessage", prePopulatedContent)` and the other Messenger methods.
- [Installing the Intercom Messenger for web](https://developers.intercom.com/installing-intercom/web/installation) — get the Messenger snippet onto your page so `window.Intercom` is available.
- [Get started with Intercom Inbox](https://www.intercom.com/help/en/articles/6274899-get-started-with-intercom-inbox) — the Inbox that handles inbound support email.
- [Forward your email to your team inbox](https://www.intercom.com/help/en/articles/6522819-forward-your-email-to-your-team-inbox-using-the-next-gen-inbox) — the workspace inbound address and forwarding setup.