# OGAMI — Full Integration Reference

OGAMI is a hosted conversation layer for websites. You add it with one script
tag; its assistant (OgaChat) answers visitor enquiries, captures leads, books
appointments, and follows up — on the website, on WhatsApp, and in social DMs.
This file is the complete, flat-text integration reference for AI coding agents
and developers. It is a release artifact: it changes only when the widget
contract changes.

--------------------------------------------------------------------------------
WIDGET CONTRACT
--------------------------------------------------------------------------------

Embed (canonical, 3 steps):

    <!-- Step 1: one script tag with your public key -->
    <script src="https://ogamy.co/widget.js" data-key="pk_live_yourkey"></script>
    <!-- Step 2: nothing. The widget is live. -->
    <!-- Step 3: tell the business owner to watch for the claim email. -->

- The script renders a launcher bubble and a chat panel. No other markup needed.
- It is self-contained: no build step, no dependencies, no framework required.
- Note: widget.js is in early access. Request a key at
  https://ogamy.co/partner-with-us/developers. The embed format above is the stable contract.

--------------------------------------------------------------------------------
DATA-KEY FORMAT
--------------------------------------------------------------------------------

- Attribute: `data-key` on the script tag.
- Format: `pk_live_` followed by a client identifier, e.g. `pk_live_acmeclinic`.
- The public key is an IDENTIFIER, not a secret. It is safe to commit and to
  ship in client-side HTML. It never exposes prompts, internal ids, or
  credentials — the server resolves it to a client configuration.

--------------------------------------------------------------------------------
CONFIG OPTIONS
--------------------------------------------------------------------------------

Widget appearance and greeting are configured server-side per key (set during
early access / in the claimed dashboard) and fetched by the widget at runtime:

- theme      — accent color of the launcher and panel.
- greeting   — the opening message the assistant shows.
- position   — launcher corner: bottom-right (default) or bottom-left.
- persona    — display name of the assistant for that business.

No secrets or prompt text are ever returned to the browser.

--------------------------------------------------------------------------------
HOW TO OBTAIN A pk_ KEY
--------------------------------------------------------------------------------

1. Go to https://ogamy.co/partner-with-us/developers and request early access (email capture).
2. You receive a `pk_live_...` key for your client's site.
3. Paste it into the script tag's `data-key`. Ship the site.
(Self-serve, instant key issuance is rolling out and will live at the same URL.)

--------------------------------------------------------------------------------
FRAMEWORK SNIPPETS
--------------------------------------------------------------------------------

Plain HTML — before </body>:

    <script src="https://ogamy.co/widget.js" data-key="pk_live_yourkey"></script>

Next.js (App Router) — use the Script component:

    import Script from "next/script";

    export default function Layout({ children }) {
      return (
        <>
          {children}
          <Script
            src="https://ogamy.co/widget.js"
            data-key="pk_live_yourkey"
            strategy="afterInteractive"
          />
        </>
      );
    }

React (Vite / CRA) — inject once on mount:

    import { useEffect } from "react";

    export function OgamiWidget() {
      useEffect(() => {
        const s = document.createElement("script");
        s.src = "https://ogamy.co/widget.js";
        s.setAttribute("data-key", "pk_live_yourkey");
        s.async = true;
        document.body.appendChild(s);
        return () => { s.remove(); };
      }, []);
      return null;
    }

WordPress (manual embed, until the plugin ships) — add to the active theme's
footer.php before </body>, or use a "custom HTML / scripts in footer" plugin:

    <script src="https://ogamy.co/widget.js" data-key="pk_live_yourkey"></script>

--------------------------------------------------------------------------------
WHAT HAPPENS AFTER YOU EMBED (CLAIM FLOW)
--------------------------------------------------------------------------------

1. The site ships. The widget is live in an UNCLAIMED state and works
   immediately: it answers visitors and logs conversations + leads against the
   site. A small "Powered by OGAMI" badge shows.
2. OGAMI emails the business owner a weekly digest ("34 conversations, 12
   leads — claim your dashboard") with a magic link.
3. The owner clicks the link, verifies their email, and CLAIMS the dashboard
   (state becomes CLAIMED_FREE). They see conversation history and a lead list.
4. Paid upgrades (PAID state, via existing plans) unlock: lead contact details
   + export, the WhatsApp bridge, human takeover / auto-followup, and a lifted
   free conversation cap.

Free tier: a lighter model class, a monthly conversation cap, no WhatsApp
bridge, badge shown. Existing per-IP and per-key rate limits apply.

--------------------------------------------------------------------------------
COMMON ERRORS
--------------------------------------------------------------------------------

- Widget doesn't appear: confirm the script tag is present in the served HTML
  and `data-key` is a valid `pk_live_...` key. Check the browser console.
- "Invalid key" / nothing loads: the key is unknown or the site was disabled
  (per-key kill switch). Re-check the key or contact OGAMI.
- Widget shows a cap message: the site hit its free monthly conversation cap —
  the owner can claim and upgrade to lift it.
- Styling looks off on the host site: the widget isolates its own styles; if a
  host CSS reset interferes, ensure the script loads at the end of <body>.

--------------------------------------------------------------------------------
LINKS
--------------------------------------------------------------------------------

- Developer channel + rev-share: https://ogamy.co/partner-with-us/developers
- Short index for agents: https://ogamy.co/llms.txt