Skip to content
Foldspace Docs

Connecting Foldspace to Zendesk: Support Handoff

Open in ChatGPT Open in Claude

Overview

Section titled “Overview”

When the Foldspace Agent reaches its limits — the user asks for a human, an issue can’t be resolved, or sentiment turns frustrated — it can escalate to your Zendesk support team. The Agent synthesizes a one-sentence summary of the problem and passes it along so the handoff arrives with context, not a cold start.

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

Handoff typeWhat happensUse when
Live chatThe Agent opens the Zendesk messaging widget on the page and seeds it with the conversation summary, then steps aside.You run Zendesk Messaging or the Web Widget and staff live chat.
Email → ticketThe Agent sends the summary and context to your Zendesk support address, which opens a ticket.You handle support asynchronously through the Zendesk Agent Workspace.

Both are triggered the same way: the user asks to escalate to a human (and the handoff is enabled). The difference is only the destination.

Live chat handoff

Section titled “Live chat handoff”

This mirrors the Intercom handoff: you author a Support Handoff action so the Agent knows when to escalate, then implement a front-end handler that drives the Zendesk widget.

Prerequisites

Section titled “Prerequisites”
  • A Zendesk account with Messaging or the Web Widget installed on your site (so window.zE is available).
  • 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”

In your Foldspace App, navigate to Actions and click Create New Action:

FieldValue
NameSupport Handoff
Keysupport_handoff
DescriptionTriggers a live support hand-off via Zendesk when the Agent cannot resolve an issue, detects a bug, or the user is frustrated.

In the Instructions field, constrain when the Agent escalates:

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.

Add one required input so the summary travels with the 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

Section titled “Step 2: Code implementation”

Add the handler where you initialize the Foldspace Agent. It passes the Agent’s summary to Zendesk as conversation context, opens the widget, then hides the Foldspace panel so Zendesk takes over.

window.foldspace("when", "ready", () => {
  const agent = window.foldspace.agent("YOUR_AGENT_API_NAME");


  agent.addActionHandlers({
    support_handoff: {
      execute: async (params) => {
        try {
          const HANDOFF_DELAY_MS = 5000; // let the user read the confirmation first


          // Zendesk must be present on the page (Messaging or Web Widget).
          if (!window.zE) {
            return {
              message:
                "Sorry, I'm unable to connect to the Support team right now. How else can I assist you?",
            };
          }


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


          setTimeout(() => {
            // Zendesk Messaging: attach the summary as context, then open the widget.
            // Create the field first in Zendesk Admin Center → Objects and rules →
            // Conversation fields, and put its ID below.
            try {
              window.zE("messenger:set", "conversationFields", [
                { id: "YOUR_SUMMARY_FIELD_ID", value: summary },
              ]);
            } catch (e) {}
            window.zE("messenger", "open");


            // Zendesk Web Widget (Classic) — use this instead if you run the
            // classic widget rather than Messaging:
            // window.zE("webWidget", "open");


            agent.hide(); // let Zendesk take over
          }, HANDOFF_DELAY_MS);


          return {
            message: "Transferring you to our Support team 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 a Zendesk ticket)

Section titled “Email handoff (opens a Zendesk ticket)”

When you don’t staff live chat, the Agent can hand off by email instead. This is not a real-time transfer — the Agent sends the conversation summary and context to your Zendesk support address, and Zendesk turns that email into a ticket for an agent to pick up.

Configure it with the built-in handoff destination, no custom code required:

  1. Enable handoff in Style & Behavior → Data Access & Handoff (Style & Behavior).
  2. Set the destination to Email in Integrations.
  3. On escalation, Foldspace emails the conversation summary and captured context to that address.

The address must be your Zendesk support address

Section titled “The address must be your Zendesk support address”

This is the rule that makes the difference between a tracked ticket and a lost email:

  • Send to the mailbox Zendesk turns into tickets — the Zendesk-generated support address, which looks like support@[your-subdomain].zendesk.com. (A custom or external support address works too, as long as it’s added under Admin Center → Channels → Talk and email → Email → Manage support addresses.)
  • Do not send to a plain human inbox (e.g. a personal or shared mailbox that isn’t wired into Zendesk). If you do, the handoff email lands in someone’s inbox but Zendesk never creates a ticket — so it isn’t triaged, routed, assigned, or SLA-tracked, and it never appears in the Zendesk Agent Workspace.

In short: point the handoff email at Zendesk’s support address so every escalation becomes a ticket.

Best practices

Section titled “Best practices”
  • User expectations: the delay before the widget opens (HANDOFF_DELAY_MS) gives the user time to read the Agent’s confirmation before the UI switches.
  • Fallback: if the Zendesk script fails to load (e.g. an ad-blocker), the handler returns a graceful message so the user isn’t left in a dead end.
  • Context is king: the user_prompt summary — or the summary in the ticket email — means your support team starts with the problem already in hand.
  • Pick one path per surface: use live chat where you staff it and email everywhere else, so users are never routed to a channel no one is watching.
Section titled “Related”

Zendesk references

Section titled “Zendesk references”

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