Human Handoff Integrations

Overview

Human handoff lets your Brainfish agent gracefully transfer a conversation to a live support agent when the AI cannot confidently answer a user's question — or when the user explicitly requests human help.

Rather than leaving users stuck, handoff preserves the full context of the conversation (the question asked and the AI's response) and passes it into your support platform so the human agent can pick up exactly where the AI left off.

---

How handoff works

1. The user asks a question the agent cannot confidently answer, or they click a handoff action button (e.g. "Talk to a human").
2. The Brainfish agent fires a JavaScript callback with the query (what the user asked) and answer (what the AI responded).
3. Your callback code uses those values to open your support chat platform, pre-populated with context.
4. The Brainfish widget closes and the support chat opens — the user sees a seamless transition.

---

Configuring a handoff action

Handoff is configured as a Callback action type inside Brainfish.

1. Navigate to Agents and select the agent you want to configure.
2. Open the Actions panel.
3. Add a new action and choose Callback as the type.
4. Paste in the integration-specific JavaScript snippet (see integration guides below).
5. Save the agent.

Alternatively, you can configure a global handoff directly in Agent Settings > Next Best Actions.

---

Available integrations

Platform	Status	Guide
Intercom	✅ Available	How to set up an Intercom Handoff
Salesforce	✅ Available	Salesforce Handoff Integration
Zendesk	✅ Available	Zendesk Handoff Integration
Custom / Other	✅ Available	Configure a Custom JS Callback

---

Best practices

• Always close the Brainfish widget before opening the support chat to avoid layout overlap.
• Pass the query and answer into the support platform so the human agent has full context and doesn't ask the user to repeat themselves.
• Truncate long strings before passing them to third-party APIs — most platforms have character limits on pre-filled messages.
• Test in a staging environment before going live to confirm the callback fires correctly and the support chat opens as expected.
• Add a fallback inside your callback in case the third-party chat SDK hasn't loaded yet (e.g. if (typeof window.zE !== 'function') return;).

---

Troubleshooting

The handoff button appears but nothing happens when clicked. Check that the target support chat SDK (Intercom, Zendesk, etc.) is fully loaded before the Brainfish callback fires. Add a typeof guard at the top of your callback function.

The Brainfish widget stays open after handoff. Make sure you are calling window?.Brainfish?.HelpWidget?.close('brainfish-trigger-button') at the start of your callback.

Context (query/answer) is not appearing in the support chat. Confirm you are using the query and answer parameters from the callback signature and that the target platform API call accepts a pre-filled message string.