@oyehello/chat

Framework-agnostic embeddable chat for oyehello agents — a <oyehello-chat> web component that renders a floating chat launcher (bottom-right; click to open a chat window), plus a headless createChatClient() for custom UIs. Zero framework dependencies.

The widget connects lazily (a session opens the first time the visitor opens the panel), renders assistant replies as markdown (sanitized), and has a full launcher → panel experience: an unread badge, expand/maximize, an emoji picker, file attach, a jump-to-latest control, smart auto-scroll, an optional teaser nudge, quick-reply suggestions, and a privacy footer. It follows the visitor's OS light/dark theme by default. Theme the accent with the --oc-accent CSS variable. Just drop the tag anywhere on the page; it positions itself as a floating launcher.

Attributes

The accent/logo/name (workspace brand), the teaser (a chat-agent setting), and the quick-reply chips (generated from the agent's flow after each reply) are served automatically by the API — the attributes below just override them.

| Attribute | Required | What it is | | --- | --- | --- | | api-key | yes | Publishable key (ohk_pub_…) | | agent-id | yes | The chat agent (agt_…) | | base-url | yes | API origin, e.g. https://api.oyehello.ai | | title | no | Header title (defaults to the agent's name) | | theme | no | auto (default, follows the OS), light, or dark | | teaser | no | Text for a one-time nudge bubble; omit to disable | | suggestions | no | Comma-separated quick-reply chips, e.g. "Book a demo, Pricing" | | privacy-url | no | Shows a Privacy-Policy footer linking here | | --oc-accent (CSS var) | no | Brand accent (default #096DD9) |

Install

npm install @oyehello/chat

Drop-in web component (any framework or plain HTML / Astro / Vue / Svelte)

<script type="module">import '@oyehello/chat';</script>
<oyehello-chat
  api-key="ohk_pub_…"
  agent-id="agt_…"
  base-url="https://api.oyehello.ai"
></oyehello-chat>

Or via a plain script tag (no bundler):

<script src="https://unpkg.com/@oyehello/[email protected]"></script>
<oyehello-chat api-key="ohk_pub_…" agent-id="agt_…" base-url="https://api.oyehello.ai"></oyehello-chat>

Pin a specific version (@0.5.0 above) rather than the bare package name, so a customer's site loads the exact widget it was tested against instead of silently auto-upgrading on every publish. Theme the accent with the --oc-accent CSS variable.

React

The custom element works in React too (React 19 natively; React 18 fine for these string attributes). The tag is <oyehello-chat> (hyphenated — a custom element must contain a dash; <oyehelloChat> is not valid) and attributes stay kebab-case:

import '@oyehello/chat';
export default function Chat() {
  return <oyehello-chat api-key="ohk_pub_…" agent-id="agt_…" base-url="https://api.oyehello.ai" />;
}

TypeScript/TSX users add this ambient declaration once (e.g. oyehello-chat.d.ts) so the tag typechecks:

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'oyehello-chat': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>
        & { 'api-key'?: string; 'agent-id'?: string; 'base-url'?: string; title?: string };
    }
  }
}
export {};

Headless (build your own UI)

import { createChatClient } from '@oyehello/chat';
const chat = createChatClient({ apiKey: 'ohk_pub_…', agentId: 'agt_…', baseUrl: 'https://api.oyehello.ai' });
chat.on((e) => { if (e.type === 'messages') render(e.messages); });
await chat.start();
await chat.sendMessage('Hello');

Client tools (browser actions)

The SDK supports two browser-side tools: navigate (go to a path on the current site) and openUrl (open a URL, by default in a new tab). Once a tool is enabled for the agent in the console and the target passes the agent's navigate allowlist (also set in the console), the SDK executes it itself — no host integration required:

<script type="module">import '@oyehello/chat';</script>
<oyehello-chat api-key="ohk_pub_…" agent-id="agt_…" base-url="https://api.oyehello.ai"></oyehello-chat>

That's it — a plain embed with no JS wiring can navigate the visitor or open a link when the agent calls the tool. navigate calls window.location.assign(path); openUrl calls window.open(url, '_blank') (pass newTab: false from the agent to open in the same tab instead).

A host page MAY still register its own navigate/openUrl handler to override the default behavior (e.g. push through a client-side router instead of a full navigation):

const chat = createChatClient({ apiKey, agentId, baseUrl });
chat.registerTools({
  navigate: ({ path }) => router.push(path),
});
// or on the web component: document.querySelector('oyehello-chat').registerTools({ … })

Register handlers BEFORE start(). A host-registered handler always takes priority over the SDK's built-in; any other tool name has no handler and fails cleanly.

Security. Navigation targets (both the SDK's built-in execution and a host-overridden handler) are validated against the agent's navigate allowlist server-side before the tool call ever reaches the browser — the SDK/host is not the trust boundary for where a visitor can be sent.

Requirements

• api-key is a publishable key (ohk_pub_…) created in the oyehello console.
• The agent must be a chat-channel agent (the channel is chosen when the agent is created; a call agent can't answer chat).
• The page's origin must be on the publishable key's allowlist.