Botonom Window

import { ChatWidget } from "@botonom/chat-widget";

function App() {
  return (
    <div>
      <YourContent />
      <ChatWidget agentId="d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90" />
    </div>
  );
}

__botonom_chat.emit("open")
__botonom_chat.emit("botMessage", { text: "Hello there!" })

import { ChatTrigger } from "@botonom/chat-widget";

<ChatTrigger
  variant="link"
  label="Have questions? Ask Judith"
  systemPrompt="User is on the pricing page"
  botMessage="I can help you pick the right plan!"
/>

npm install @botonom/chat-widget
# peer deps
npm install react lucide-react

import { ChatWidget } from "@botonom/chat-widget";

function App() {
  return (
    <div>
      <YourContent />
      <ChatWidget agentId="your-agent-uuid" />
    </div>
  );
}

┌──────────────────┐       GET /v1/agents/{uuid}/widget-config
│  ChatWidget      │ ────────────────────────────────────────▶ Botonom API
│  agentId="abc.." │ ◀──────────────────────────────────────── 
└──────────────────┘       { name, role, colors, avatarUrl,
                             locale, responses, ... }

curl -H "Authorization: Bearer $API_KEY" \
  https://api.botonom.com/v1/agents | jq '.[0].id'

<ChatWidget agentId="d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90" />

GET https://api.botonom.com/v1/agents/{agentId}/widget-config

{
  "agent": {
    "name": "Judith",
    "role": "Brand Representative",
    "avatarUrl": "https://cdn.botonom.com/avatars/judith-animated.svg",
    "avatarExpressions": ["idle", "thinking", "talking"]
  },
  "branding": {
    "companyName": "Botonom",
    "primaryColor": "#3B82F6",
    "gradientFrom": "#2563EB",
    "gradientTo": "#3B82F6"
  },
  "widget": {
    "showDelay": 2000,
    "teaserDelay": 5000,
    "idleNudgeDelay": 30000,
    "teaserHighlightWord": "Judith",
    "locale": "en"
  }
}

<ChatWidget
  agentId="d4e5f6a7-..."
  config={{
    showDelay: 0,        // show FAB immediately
    teaserDelay: 3000,   // show teaser faster
    idleNudgeDelay: 0,   // disable idle nudge
  }}
/>

<ChatWidget
  agentId="d4e5f6a7-..."
  config={{
    detectLocale: () => navigator.language.slice(0, 2),
  }}
/>

{/* Icon — next to a heading */}
<h2>
  Token Usage <ChatTrigger variant="icon" size="sm"
    botMessage="Tokens are consumed per action..." />
</h2>

{/* Link — below a search bar */}
<ChatTrigger
  variant="link"
  label="Can't find what you need? Ask Judith"
  color="blue"
  systemPrompt="User is on the Knowledge Base."
  botMessage="I can help you navigate our docs!"
/>

{/* Button — in a pricing CTA area */}
<ChatTrigger
  variant="button"
  label="Not sure which plan?"
  color="blue"
  botMessage="Let me help you pick the right plan!"
/>

{/* Custom — wrap anything */}
<ChatTrigger variant="custom" botMessage="Need help?">
  <span className="underline cursor-pointer">Ask Judith</span>
</ChatTrigger>

Check out our [Agent:Executive Secretary|secretary] — it handles
email, calendar, and CRM. You can also browse the
[Skill:Reservation|reservation] skill or visit
[Page:Pricing|/pricing] for plans.

<section data-chat-target="pricing">
  <h2>Pricing</h2>
  ...
</section>

<button data-chat-target="hire-btn">Hire Now</button>

Here's our pricing section — [Action:Show Me|pointer|#pricing-table]

// Via event bus
__botonom_chat.emit("uiAction", {
  action: "pointer",
  target: "#pricing-table"
})

// Highlight an element
__botonom_chat.emit("uiAction", {
  action: "highlight",
  target: "[data-chat-target=hire-btn]"
})

// Just scroll
__botonom_chat.emit("uiAction", {
  action: "scroll",
  target: "#faq-section"
})

┌──────────────┐                  ┌──────────────┐
│  Your Site   │  ── inbound ──▶  │   Widget     │
│  (React /    │                  │  (ChatWidget) │
│   vanilla)   │  ◀── outbound ── │              │
└──────────────┘                  └──────────────┘

import { useChatWidget } from "@botonom/chat-widget";

function MyComponent() {
  const chat = useChatWidget();

  return (
    <div>
      <button onClick={() => chat.open()}>Open Chat</button>
      <button onClick={() => chat.send("What is CORTEX?")}>
        Ask about CORTEX
      </button>
      <button onClick={() => chat.botMessage("Let me explain...")}>
        Bot Speaks
      </button>
      <button onClick={() => chat.nudge("Need help?", 5000)}>
        Show Nudge
      </button>
    </div>
  );
}

import { useOnChatEvent } from "@botonom/chat-widget";

function Analytics() {
  useOnChatEvent("userMessage", ({ text }) => {
    trackEvent("chat_message", { text });
  });

  useOnChatEvent("navigate", ({ href }) => {
    console.log("Bot navigated to:", href);
  });

  useOnChatEvent("botResponse", ({ raw, markers }) => {
    console.log("Bot said:", raw);
    console.log("Markers:", markers);
  });

  return null;
}

// ── Basic Controls ──
__botonom_chat.emit("open")
__botonom_chat.emit("close")
__botonom_chat.emit("toggle")

// ── Make the Bot Speak ──
__botonom_chat.emit("botMessage", {
  text: "Hello! How can I help you today?"
})

// ── Send as User ──
__botonom_chat.emit("send", { text: "What agents do you have?" })

// ── Inject Hidden Context ──
__botonom_chat.emit("system", {
  prompt: "User is a developer integrating the API"
})

// ── Rich Markers in Bot Message ──
__botonom_chat.emit("botMessage", {
  text: "Try our [Agent:Executive Secretary|secretary] or browse [Page:All Agents|/agents]"
})

// ── Attention Effects ──
__botonom_chat.emit("highlight", { duration: 3000 })
__botonom_chat.emit("badge", { count: 3 })
__botonom_chat.emit("nudge", {
  text: "We have a special offer!", duration: 5000
})

// ── Pointer Animation ──
__botonom_chat.emit("uiAction", {
  action: "pointer", target: "#some-element"
})

// ── Highlight Ring ──
__botonom_chat.emit("uiAction", {
  action: "highlight", target: ".cta-button"
})

// ── Scroll to Element ──
__botonom_chat.emit("uiAction", {
  action: "scroll", target: "#faq"
})

// ── Debug Mode (logs all events) ──
__botonom_chat.debug(true)

// ── Check Listener Count ──
console.log(__botonom_chat.listenerCount)