Connecting Foldspace to Intercom: Automated Support Handoff

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.

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.

Log in to your Foldspace App.
Navigate to the Actions section and click Create New Action.
Fill in the following details:

Field	Value
Name	`Support Handoff`
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

In the Instructions field, copy and paste the following guidelines. This ensures the Agent only triggers the handoff when appropriate:

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.

Name: user_prompt
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').
Type: string
Required: Yes

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();
});

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