# Connecting Foldspace to Zendesk: Support Handoff

Hand off from your Foldspace Agent to Zendesk — either a live chat handoff into the Zendesk widget, or an email handoff that opens a Zendesk ticket.

## 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 type | What happens | Use when |
| :--- | :--- | :--- |
| **Live chat** | The 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 → ticket** | The 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

This mirrors the [Intercom handoff](/guides/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.

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

- 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

In your Foldspace App, navigate to **Actions** and click **Create New Action**, then 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 Zendesk 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 Zendesk messaging widget 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.
```

**Name**

Support Handoff

**Action key**

support_handoff

**Description**

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

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

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

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.

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

:::note[Messaging vs Web Widget Classic]
The escalation action and trigger are identical across Zendesk products — only the widget call changes. **Zendesk Messaging** carries structured context through pre-configured **conversation fields** (created in Admin Center); the **Web Widget (Classic)** uses `window.zE("webWidget", "open")` and prefill. Confirm which product you run and keep the matching call.
:::

## 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](/user-guides/building-your-agent/)).
2. Set the destination to **Email** in [Integrations](/user-guides/integrations/).
3. On escalation, Foldspace emails the conversation summary and captured context to that address.

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

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

## Related

- [Connecting Foldspace to Intercom](/guides/intercom-handoff/) — the same live-handoff pattern for Intercom.
- [Integrations](/user-guides/integrations/) — where handoff destinations (email, HubSpot, webhook) are configured.
- [Style & Behavior](/user-guides/building-your-agent/) — enable handoff and set its escalation conditions.

## Zendesk references

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

- [Core messaging Web Widget API](https://developer.zendesk.com/api-reference/widget-messaging/web/core/) — `zE("messenger", "open")` and setting `conversationFields` / `conversationTags`.
- [Web Widget (Classic) API](https://developer.zendesk.com/api-reference/widget/introduction/) — `zE("webWidget", ...)` commands, if you run the classic widget.
- [Adding support email addresses for users to submit tickets](https://support.zendesk.com/hc/en-us/articles/4408842868506-Adding-support-email-addresses-for-users-to-submit-tickets) — create the `…@[subdomain].zendesk.com` address that turns email into tickets.
- [Managing your support addresses](https://support.zendesk.com/hc/en-us/articles/5279521301914-Managing-your-support-addresses) — add, verify, and route custom or external support addresses.