JavaScript API & events

const chat = HiveChat.init({ key: 'hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY' });

chat.open();                       // show the panel
await chat.send('Where is my order?');   // send as the visitor, resolves when the run settles
chat.update({ locale: 'ar' });     // re-render in Arabic, same session
chat.reset();                      // new thread
chat.destroy();                    // remove the element

<!-- Drive the element directly (no loader) -->
<hive-chat id="support" key="hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY" api-url="https://HIVE" mode="inline"
           style="display:block;height:600px"></hive-chat>
<script type="module">
  import 'https://HIVE/embed/v1/hive-embed.mjs';
  const el = document.getElementById('support');
  el.addEventListener('hive:ready', () => el.send('Hello!'));
  console.log(el.threadId);   // null until the first message is accepted
</script>

const chat = HiveChat.init({ key: 'hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY' });
const el = chat.element;

el.addEventListener('hive:ready', (e) => {
  console.log('config loaded for key', e.detail.key_id);   // no session yet
});
el.addEventListener('hive:session', (e) => {
  const { visitor_id, identified } = e.detail;   // minted on first open / first send
  analytics.identify(visitor_id);
});
el.addEventListener('hive:message', (e) => {
  const { role, text } = e.detail;      // 'user' | 'agent'
  analytics.track('chat_message', { role, length: text.length });
});
el.addEventListener('hive:error', (e) => {
  console.warn('hive-chat error', e.detail.code);   // e.g. 'RATE_LIMITED'
});
el.addEventListener('hive:open', () => document.body.classList.add('chat-open'));
el.addEventListener('hive:close', () => document.body.classList.remove('chat-open'));

// TypeScript: the events are plain CustomEvents — type the detail yourself
import type { HiveChatElement } from '@hive/embed';

type HiveEvents = {
  'hive:ready': { key_id: string };
  'hive:session': { visitor_id: string; identified: boolean };
  'hive:message': { role: 'user' | 'agent'; text: string };
  'hive:error': { code: string };
};

function on<K extends keyof HiveEvents>(
  el: HiveChatElement, name: K, fn: (detail: HiveEvents[K]) => void,
) {
  el.addEventListener(name, (e) => fn((e as CustomEvent<HiveEvents[K]>).detail));
}

<button id="help">Need help?</button>
<script async src="https://HIVE/embed/v1/hive-embed.js" data-key="hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY"></script>
<script>
  // The script is async: a click can land before it has loaded, when
  // window.HiveChat is still the stub below and has no init(). The loader
  // drains the queue (q: [[options, container?]]) as soon as it runs.
  window.HiveChat = window.HiveChat || { q: [] };
  document.getElementById('help').addEventListener('click', () => {
    if (typeof window.HiveChat.init === 'function') {
      // Loaded: init() is idempotent per key and returns the auto-initialized handle.
      window.HiveChat.init({ key: 'hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY' }).open();
    } else {
      // Not yet: queue an init that opens the panel once the bundle arrives.
      window.HiveChat.q.push([{ key: 'hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY', open: true }]);
    }
  });
</script>

// Open with a context-aware first message (sent as the visitor).
const chat = HiveChat.init({ key: 'hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY' });

document.querySelector('#ask-about-product').addEventListener('click', async () => {
  chat.open();
  await chat.send(`I have a question about ${document.title} (${location.pathname})`);
});

// Pass page URL and user metadata — the safe way.
//
// The widget sends no free-form metadata from the browser (it is untrusted).
// Page context therefore travels either as part of the message text (visible
// to the visitor, above) or — for attributes you vouch for — inside the
// identity JWT your backend signs:
//
//   { sub: user.id, name: user.name, meta: { plan: 'pro', region: 'ae', page: '/pricing' } }
//
// meta lands on the contact record (end_users.attributes.embed) and is visible
// to operators in the console; it is not injected into the prompt.
const { token } = await fetch('/api/hive-identity?page=' + encodeURIComponent(location.pathname))
  .then((r) => r.json());
HiveChat.init({ key: 'hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY', user: { token } });

// Single-page apps: create once, update on route change, destroy on logout.
let chat;

export function mountChat(user) {
  chat = HiveChat.init({
    key: 'hive_pk_REPLACE_WITH_YOUR_PUBLISHABLE_KEY',
    locale: document.documentElement.lang.startsWith('ar') ? 'ar' : 'en',
    user: user ? { token: user.hiveToken } : undefined,
  });
}

router.afterEach((to) => {
  // e.g. hide the launcher on checkout
  chat?.element.toggleAttribute('hidden', to.path.startsWith('/checkout'));
});

export function onLogout() {
  chat?.reset();                       // drop the identified thread
  chat?.update({ user: undefined });   // continue as anonymous …
  // … or chat?.destroy() to remove it entirely
}