Skip to main content

Conversation hand-off

When a user submits a ticket after seeing a Kapa answer, the deflector hands the Kapa conversation back to your support form by appending it to a form field you specify, either as a short link to the conversation on the Kapa dashboard or as the full conversation rendered as markdown. That way, the agent who picks up the ticket sees what the user already tried.

Best practice​

The most reliable way to carry the Kapa context onto the ticket is to add a dedicated hidden ticket field on your support platform and have the deflector write into it. The field is invisible to the end user filling the form but lands on the ticket payload for you to see. This approach avoids any interaction with your main description field.

Platform specific guides​

Zendesk​

  1. Create a custom ticket field. In Zendesk Admin Center -> Objects and rules -> Tickets -> Fields -> Add field. Choose the Text type, name it something like "Kapa conversation link", and mark it Editable for end users (the field must render in the end-user form so the deflector can write to it; you'll hide it visually in the next step). Save and note the numeric field ID that appears after creation; it looks like 31234567890.

  2. Attach the field to the ticket form. In Admin Center -> Objects and rules -> Tickets -> Forms, open the form used by your Help Center (the one flagged Default), add the field you just created, and save.

  3. Hide the field from the end user. In your Help Center theme (Guide -> Customize design -> edit code), add a style rule that hides the rendered field. Match the wrapping element via the input's name using :has():

    <style>
      div:has(> input[name="request[custom_fields][31234567890]"]) {
        display: none;
      }
    </style>

    (Replace the numeric id with your own.) For themes that don't support :has() yet, a small script that locates the input and hides its closest wrapper also works.

  4. Point the deflector at the hidden field. On the support form deflector script tag, set data-handoff-enabled="true" and data-handoff-target-query-selector to the hidden input's name:

    <script
      async
      src="https://widget.kapa.ai/kapa-support-form-deflector.bundle.js"
      data-integration-id="YOUR_INTEGRATION_ID"
      data-handoff-enabled="true"
      data-handoff-target-query-selector="input[name='request[custom_fields][31234567890]']"
    ></script>

    (Note the outer double quotes and inner single quotes. The input name contains square brackets, which can't be escaped inside the same quote style.)

When the user submits, the deflector writes the Kapa conversation link into the hidden field. Zendesk stores it on the ticket as the custom field value.

Configuration​

See Conversation hand-off configuration for the full attribute reference.

Rich-text editors​

Results with rich-text editors (WYSIWYG) are not guaranteed. The editor's own submit-time sync can overwrite a write to the plain textarea behind it. Prefer the hidden-field approach above on any form that renders a rich-text editor.

Markdown payload format​

When data-handoff-payload-format="markdown", the field receives the full conversation. Example output:

### Kapa AI conversation

Thread: https://link.kapa.ai/sfd/<threadId>

**Question:**

How do I get started?

**Answer:**

You can get started by...

**Sources:**
- [Getting started](https://docs.example.com/getting-started)

JavaScript event​

When the hand-off is enabled (data-handoff-enabled="true"), the deflector dispatches a kapa-deflector:submit CustomEvent on document every time the user submits after interacting with the deflector. Subscribe via standard addEventListener.

<script>
  document.addEventListener("kapa-deflector:submit", (event) => {
    // event.detail = { version, link, markdown }
    console.log("Kapa conversation:", event.detail);
  });
</script>

Use the event for XHR-based forms that build FormData by hand, for platforms where the hidden-field approach isn't available, or to enrich the payload before sending.

Multiple listeners are supported natively; remove one with removeEventListener.