Skip to content
Foldspace Docs
Talk to an engineer

Support handoff

Connecting Foldspace to Intercom: Automated Support Handoff

Overview

Section titled “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 typeWhat happensUse when
Live chatThe 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 → conversationThe 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.

Prerequisites

Section titled “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

Section titled “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.
Let the Foldspace assistant build it

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.

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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:

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)

Section titled “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).
  2. Set the destination to Email in 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

Section titled “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.
Section titled “Related”

Intercom references

Section titled “Intercom references”

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