How to set up an Intercom Handoff in a Brainfish Agent or Handoff Action
Summary
This article shows how to set up an Intercom handoff in a Brainfish Agent or Handoff Action. It includes the JavaScript callback you can paste into either an agent action (under the Agents tab) or a standalone Handoff Action (under the Actions tab). Nothing needs to be configured inside Intercom — the snippet just requires Intercom to already be loaded on the page.
Code implementation
Paste the following into your Brainfish action's Callback field:
/**
* Brainfish callback button handler
*
* @param {string} query
* @param {string} answer
*/
function (query, answer) {
// 🔍 Debug: confirm callback fires
console.group("[Brainfish → Intercom handoff]");
console.log("Query:", query);
console.log("Answer:", answer);
console.groupEnd();
// Close Brainfish HelpWidget (non-fatal if unavailable)
try {
window?.Brainfish?.HelpWidget?.close("brainfish-trigger-button");
console.log("[Brainfish] HelpWidget closed");
} catch (e) {
console.warn("[Brainfish] Failed to close HelpWidget", e);
}
// Safety: Intercom must exist
if (typeof window.Intercom !== "function") {
console.warn("[Brainfish → Intercom] Intercom not loaded yet");
return;
}
// Helper to keep payloads safe
const safeString = (v, max = 1200) => {
if (v == null) return "";
const s =
typeof v === "string"
? v
: (() => {
try { return JSON.stringify(v, null, 2); }
catch { return String(v); }
})();
return s.length > max ? s.slice(0, max) + "…(truncated)" : s;
};
const transcript =
`I asked
this question:
${safeString(query, 1500)}
And I received this AI answer:
${safeString(answer, 2500)}
`;
// 🔍 Debug: payload going to Intercom
console.group("[Brainfish → Intercom payload]");
console.log("Prefilled message:", transcript);
console.groupEnd();
// Optional: lightweight metadata on the user (keep these short)
window.Intercom("update", {
bf_handoff_source: "brainfish",
bf_last_query: safeString(query, 255),
});
// Open Intercom with a prefilled message
window.Intercom("showNewMessage", transcript);
}
FAQ
Q: What is an Intercom handoff? A handoff routes the conversation to a human in Intercom when the user wants more personalised help, ensuring continuity from the AI to live support.
Q: How is context transferred during the handoff?
The callback receives query (the user's original question) and answer (the AI's reply) directly from Brainfish. The snippet above formats both into a single prefilled message that Intercom opens via showNewMessage. It also writes two lightweight tags onto the Intercom user record (bf_handoff_source and bf_last_query) so your support team can identify Brainfish-originated conversations and filter on them.
Q: Do I need to configure anything inside Intercom?
No. The snippet calls Intercom's standard showNewMessage and update APIs, which are already available on any page that loads the Intercom Messenger.
Q: What if Intercom hasn't finished loading when the user clicks the handoff button?
The snippet returns early with a console warning. To prevent the issue entirely, ensure Intercom's bootstrap script is in your page <head> so it loads before the user interacts with the Brainfish agent.
Related articles
- How to Configure a Custom JavaScript Callback for a Handoff Action — the parent article with the full callback setup flow.
- Zendesk Handoff Integration
- Salesforce Handoff Integration