Zendesk Handoff Integration

Overview

This guide explains how to configure a Zendesk Chat (Zendesk Web Widget) handoff from a Brainfish agent. When a user cannot be helped by the AI, or clicks a handoff action button, the Brainfish callback fires and opens Zendesk Chat pre-populated with the conversation context.

Prerequisites

• Zendesk Web Widget (Classic or Messaging) must already be installed and loaded on the same page as the Brainfish widget.
• You need access to the Brainfish Agents configuration page.
• The Zendesk zE global function must be available on the page before the handoff is triggered.

Setting up the handoff in Brainfish

1. Navigate to Agents and select the agent you want to configure.
2. Open the Actions panel.
3. Add a new action, set the label to something like "Talk to a human", and choose Callback as the type.
4. Paste the JavaScript code from the section below.
5. Save the agent.

Code implementation

Paste this callback into the Brainfish action:

function (query, answer) {
  // Close Brainfish widget
  try {
    window?.Brainfish?.HelpWidget?.close('brainfish-trigger-button');
  } catch (e) {
    console.warn('[Brainfish] Could not close HelpWidget', e);
  }

  // Guard: Zendesk must be loaded
  if (typeof window.zE !== 'function') {
    console.warn('[Brainfish -> Zendesk] Zendesk Web Widget not loaded');
    return;
  }

  var maxLen = 1000;
  var safeQuery = (query || '').slice(0, maxLen);
  var safeAnswer = (answer || '').slice(0, maxLen);

  var prefill = 'I asked: ' + safeQuery + '\n\nAI answered: ' + safeAnswer;

  // Zendesk Messaging (newer)
  try {
    window.zE('messenger', 'open');
    window.zE('messenger:set', 'conversationFields', [
      { id: 'bf_query', value: safeQuery }
    ]);
    return;
  } catch (e) {}

  // Zendesk Web Widget Classic (fallback)
  try {
    window.zE('webWidget', 'open');
    window.zE('webWidget', 'prefill', {
      name: { value: '', readOnly: false },
      email: { value: '', readOnly: false },
      phone: { value: '', readOnly: false }
    });
    window.zE('webWidget:on', 'open', function () {
      window.zE('webWidget', 'updateSettings', {
        webWidget: {
          contactForm: {
            subject: true
          }
        }
      });
    });
  } catch (e) {
    console.warn('[Brainfish -> Zendesk Classic] Failed to open widget', e);
  }
}

Zendesk Messaging vs Classic Web Widget

Brainfish supports both Zendesk flavours. The snippet above tries Zendesk Messaging first, then falls back to the Classic Web Widget. If you know which version you have, you can remove the unused block.

Frequently asked questions

Q: Nothing happens when the handoff button is clicked. Confirm that window.zE exists in your browser console before the button is clicked. If it is undefined, Zendesk has not finished loading.

Q: The Brainfish widget stays open. Ensure window?.Brainfish?.HelpWidget?.close('brainfish-trigger-button') is called at the start of the callback, before opening Zendesk.

Q: Can I pass the full conversation transcript to Zendesk? Yes. You can concatenate query and answer into a string and submit it as a pre-filled message or a ticket description depending on your Zendesk setup.

Q: Does this work with Zendesk Talk or email tickets? The callback snippet above targets the Zendesk live chat surface. For email ticket creation, use the Zendesk REST API inside the callback instead.