Install the Engage SDK

Using Copilot, Cursor, Claude Code or Windsurf? Copy the prompt below into the agent, replace bk_live_YOUR_KEY and the origins, and let it do the install — script tag, form conversion and ticket wiring. Then run through Verify.

Install the Buckhy Engage SDK (AI chat + managed forms + support desk) on this website.

FACTS
- Loader URL: https://api.buckhy.com/v1/engage/sdk.js
- My site key (publishable, safe in client code): bk_live_YOUR_KEY
- My production origin(s): https://www.example.com (and http://localhost:<dev-port>
  for local dev — both are added to allowed origins in the Buckhy console)

WHAT THE SDK DOES (do not reimplement)
- GET {api}/v1/engage/config with header X-Api-Key decides show/hide. On failure,
  wrong key, unlisted origin, or disabled site, the widget renders NOTHING by
  design. Never add fallback UI for a missing widget.
- The launcher runs in a Shadow DOM with its own styles. Branding (assistant
  name, label, accent, greeting) is set in the console, not in CSS.
- Chat answers are grounded in the knowledge pack managed in the console. There
  is no client-side knowledge file.

TASKS
1. Load the SDK once per page. Plain HTML: paste before </body>:
     <script src="https://api.buckhy.com/v1/engage/sdk.js" defer
       data-site-key="bk_live_YOUR_KEY"></script>
   React/Next.js App Router: a "use client" component that appends the script in
   useEffect (guard against double-insert), key from NEXT_PUBLIC_BUCKHY_ENGAGE_KEY,
   mounted in the root layout. Other frameworks: the idiomatic equivalent.
2. Convert my contact/lead form(s): add data-buckhy-form="contact" to the <form>,
   keep existing fields, add a hidden honeypot input named "website" (off-screen),
   and an empty <p data-buckhy-status role="status"></p>. Remove any old submit
   handler that would double-post. Custom success copy -> data-buckhy-success.
3. Programmatic tickets: POST https://api.buckhy.com/v1/engage/support with
   X-Api-Key + Idempotency-Key (randomUUID created ONCE per intent, REUSED on
   retry), body { name, email, phone?, category, subject, message, page }.
   4xx = show the user; network/5xx = retry with the SAME idempotency key.

RULES
- The key lives only in client-side code/env. It is publishable.
- Never fetch /v1/engage/chat yourself unless building a fully custom UI.
- Always defer the script; never block rendering on it.
- After editing, start the dev server and verify: launcher appears, form submit
  shows the success line with no console errors, and a chat question gets an
  answer or a polite "I don't know" with an offer to create a ticket.
- Report the files you changed and anything you could not verify.

A good run adds one script or component (never a hand-rolled chat widget), converts forms by adding attributes rather than rewriting markup, uses one idempotency key per intent, and verifies in a real browser. Prefer to do it yourself? Continue below.

The Engage SDK is a single script that runs on your pages with a publishable site key. It delivers three apps, each switchable per site:

The key is safe in HTML because the API answers only for the origins you register (origin lock) and rate-limits per key. If the key, origin or site is wrong, the SDK renders nothing — no broken launcher, no console noise.

1. Open Businesses > your website > Apps and select AI Chat, Managed Forms or Support Desk.
2. Complete Configure for the selected environment. In Integrate, create or reuse the publishable credential.
3. Install the generated code once. For AI Chat or Managed Forms, paste the loader before </body>:

<script src="https://api.buckhy.com/v1/engage/sdk.js" defer
  data-site-key="bk_live_…"></script>

Branding lives in the console, so you can change it without a deploy. Config is cached for 5 minutes.

Mount one client component in the root layout; it appends the script once.

// components/buckhy-engage.tsx
"use client";
import { useEffect } from "react";

const SITE_KEY = process.env.NEXT_PUBLIC_BUCKHY_ENGAGE_KEY ?? "";

export function BuckhyEngage() {
  useEffect(() => {
    if (!SITE_KEY || document.querySelector("script[data-buckhy-engage-loader]")) return;
    const script = document.createElement("script");
    script.src = "https://api.buckhy.com/v1/engage/sdk.js";
    script.defer = true;
    script.setAttribute("data-site-key", SITE_KEY);
    script.setAttribute("data-buckhy-engage-loader", "");
    document.body.appendChild(script);
  }, []);
  return null;
}

# .env.local
NEXT_PUBLIC_BUCKHY_ENGAGE_KEY=bk_live_…

Open Businesses > your website > Apps for app configuration and status. Shared assistant and delivery settings are in the website's Settings. Check Test versus Live before changing a shared Engage connection.

1. Open your site and verify the selected app's interface appears without a console error.
2. For AI Chat, ask a question covered by the configured knowledge and review the answer.
3. For Managed Forms or Support Desk, submit one request and inspect the website's Inbox. Check email processing separately.
4. If a webhook is configured, verify the signed event at your receiver and its successful acknowledgement.
5. Return to the selected app's Test step, run the checks, then review and Activate.

If the widget doesn't appear

The SDK never shows an error to visitors. Check GET /v1/engage/config in the network panel: