SDK Reference

import { waitForBubblaVAPI } from '@bubblav/ai-chatbot-sdk';

const controller = new AbortController();
const api = await waitForBubblaVAPI({ signal: controller.signal });
api?.open();
// On teardown: controller.abort();

'use client';

import { BubblaVWidget } from '@bubblav/ai-chatbot-react';

export function DashboardChat({ websiteId, initialToken, refreshSettings }: {
  websiteId: string;
  initialToken: string | null;
  refreshSettings: () => void;
}) {
  return (
    <BubblaVWidget
      websiteId={websiteId}
      identity={{ token: initialToken, tokenEndpoint: '/api/chat-identity' }}
      onToolExecuted={({ toolNames }) => {
        console.info('Tools finished', toolNames);
      }}
      toolRefresh={{
        refresh: refreshSettings,
        shouldRefresh: ({ toolNames }) => toolNames.includes('update_settings'),
        debounceMs: 500,
      }}
      onError={(error) => console.error('Widget error', error.code)}
    />
  );
}

<script setup lang="ts">
import { BubblaVWidget } from '@bubblav/ai-chatbot-vue';
import type { BubblaVWidgetError, ToolExecutedEvent } from '@bubblav/ai-chatbot-sdk';

defineProps<{
  websiteId: string;
  initialToken: string | null;
  refreshSettings: () => void;
}>();
const selectSettings = ({ toolNames }: ToolExecutedEvent) => toolNames.includes('update_settings');
const onTools = ({ toolNames }: ToolExecutedEvent) => console.info('Tools finished', toolNames);
const onError = (error: BubblaVWidgetError) => console.error('Widget error', error.code);
</script>

<template>
  <BubblaVWidget
    :website-id="websiteId"
    :identity="{ token: initialToken, tokenEndpoint: '/api/chat-identity' }"
    :tool-refresh="{ refresh: refreshSettings, shouldRefresh: selectSettings, debounceMs: 500 }"
    @tool-executed="onTools"
    @error="onError"
  />
</template>

import { Component, Input } from '@angular/core';
import { BubblaVWidgetComponent } from '@bubblav/ai-chatbot-angular';
import type { BubblaVWidgetError, ToolExecutedEvent, ToolRefreshOptions } from '@bubblav/ai-chatbot-sdk';

@Component({
  selector: 'app-dashboard-chat',
  standalone: true,
  imports: [BubblaVWidgetComponent],
  template: `
    <bubblav-widget
      [websiteId]="websiteId"
      [identity]="{ token: initialToken, tokenEndpoint: '/api/chat-identity' }"
      [toolRefresh]="toolRefresh"
      (toolExecuted)="onTools($event)"
      (error)="onError($event)"
    />
  `,
})
export class DashboardChatComponent {
  @Input({ required: true }) websiteId!: string;
  @Input({ required: true }) initialToken!: string | null;
  @Input({ required: true }) toolRefresh!: ToolRefreshOptions;
  onTools({ toolNames }: ToolExecutedEvent) { console.info('Tools finished', toolNames); }
  onError(error: BubblaVWidgetError) { console.error('Widget error', error.code); }
}

npm install @bubblav/ai-chatbot-sdk

import { mountBubblaVWidget } from '@bubblav/ai-chatbot-sdk';

export function mountDashboardChat(websiteId: string, initialToken: string) {
  const options = {
    websiteId,
    identity: { token: initialToken, tokenEndpoint: '/api/chat-identity' },
  };
  const connection = mountBubblaVWidget(options); // Browser lifecycle only
  void connection.ready.then(api => api.open()).catch(error => {
    console.error('Widget failed to become ready', error.code);
  });

  return {
    logout() {
      connection.update({ ...options, identity: { token: null } });
    },
    dispose() { connection.dispose(); },
  };
}

import type { IdentityTokenProvider, WidgetIdentity } from '@bubblav/ai-chatbot-sdk';

const getToken: IdentityTokenProvider = async ({ signal }) => {
  const response = await fetch('/api/chat-identity', {
    method: 'POST',
    credentials: 'same-origin',
    cache: 'no-store',
    signal,
  });
  if (!response.ok) throw new Error('Identity refresh failed');
  const data = await response.json();
  if (typeof data?.token !== 'string' || !data.token.trim()) {
    throw new Error('Identity refresh returned no token');
  }
  return data.token;
};

export const identityFor = (initialToken: string): WidgetIdentity => ({ token: initialToken, getToken });

// Server-only configuration
export const identityOptions = {
  websiteId: process.env.BUBBLAV_WEBSITE_ID ?? '',
  signingSecret: process.env.BUBBLAV_END_USER_SIGNING_SECRET ?? '',
};

// app/api/chat-identity/route.ts — adapt the auth helper to your app
import { createEndUserToken } from '@bubblav/ai-chatbot-sdk/server';
import { getAuthenticatedUser } from '@/lib/auth';
import { identityOptions } from '@/lib/chat-identity-options';

export async function GET() {
  const headers = { 'Cache-Control': 'no-store' };
  const user = await getAuthenticatedUser();
  if (!user) return Response.json({ error: 'Unauthorized' }, { status: 401, headers });
  const token = await createEndUserToken(
    { userId: user.id, email: user.email, name: user.name },
    { ...identityOptions, ttlSeconds: 600 },
  );
  return Response.json({ token }, { headers });
}

import { BubblaVTokenError, verifyMcpRequest } from '@bubblav/ai-chatbot-sdk/server';
import { identityOptions } from '@/lib/chat-identity-options';
import { settingsForUser } from '@/lib/settings';

const verificationOptions = {
  ...identityOptions,
  previousSigningSecret: process.env.BUBBLAV_PREVIOUS_SIGNING_SECRET || undefined,
};

// Called by your protected tool handler, not by anonymous schema discovery.
export async function readSettings(headers: Headers) {
  const identity = await verifyMcpRequest(headers, verificationOptions);
  if (!identity) throw new BubblaVTokenError('Authentication required');
  return settingsForUser(identity.sub); // Resolve current permissions and scope every query here.
}

BubblaV.open();

BubblaV.close();

BubblaV.toggle();

BubblaV.openSearch();

if (BubblaV.isOpen()) {
  console.log('Widget is open');
}

// Send a simple message
BubblaV.sendMessage('Hello, I need help!');

// Send to a specific conversation
BubblaV.sendMessage('Where is my order?', 'conv_123');

// Show default greeting
BubblaV.showGreeting();

// Show custom message
BubblaV.showGreeting('Hi! How can I help you today?');

// Show greeting with sender info
BubblaV.showGreeting({
  message: 'Hi! How can I help you today?',
  senderName: 'Support Team',
  senderAvatarUrl: 'https://example.com/avatar.png',
  timestamp: new Date().toISOString()
});

BubblaV.hideGreeting();

const config = BubblaV.getConfig();
console.log('Widget config:', config);

// Enable debug mode
BubblaV.setDebug(true);

// Disable debug mode
BubblaV.setDebug(false);

BubblaV.on('chat:opened', () => {
  console.log('Chat widget opened');
});

BubblaV.on('message:received', (message) => {
  console.log('New message:', message);
});

const handler = () => console.log('Chat opened');

BubblaV.on('chat:opened', handler);
// Later...
BubblaV.off('chat:opened', handler);

'use client';

import { useRef } from 'react';
import { BubblaVWidget, useBubblaVWidget } from '@bubblav/ai-chatbot-react';
import type { BubblaVAPI } from '@bubblav/ai-chatbot-sdk';

function SupportButton() {
  const widgetRef = useRef<BubblaVAPI | null>(null);
  const widget = useBubblaVWidget();


  const openSupport = () => {
    widget?.open();
  };

  return (
    <>
      <button onClick={openSupport}>Get Support</button>
      <BubblaVWidget ref={widgetRef} websiteId="your-website-id" />
    </>
  );
}

import { BubblaVWidget } from '@bubblav/ai-chatbot-react';

function App() {
  return (
    <BubblaVWidget
      websiteId="your-website-id"
      onToolExecuted={({ toolNames }) => console.info('Tools finished', toolNames)}
    />
  );
}

<script setup>
import { BubblaVWidget, useBubblaVWidget } from '@bubblav/ai-chatbot-vue';

const widget = useBubblaVWidget();
const openSupport = () => widget.value?.open();
</script>

<template>
  <button @click="openSupport">Get Support</button>
  <BubblaVWidget website-id="your-website-id" />
</template>

import { Component, inject } from '@angular/core';
import { BubblaVWidgetComponent, BubblaVWidgetService } from '@bubblav/ai-chatbot-angular';

@Component({
  selector: 'app-support',
  standalone: true,
  imports: [BubblaVWidgetComponent],
  template: `
    <button (click)="openSupport()">Get Support</button>
    <bubblav-widget websiteId="your-website-id" />
  `
})
export class SupportComponent {
  private bubblav = inject(BubblaVWidgetService);


  openSupport() {
    this.bubblav.open();
  }
}

import type { BubblaVAPI, ToolExecutedEvent, WidgetIdentity, ToolRefreshOptions } from '@bubblav/ai-chatbot-sdk';
import type { BubblaVWidgetProps } from '@bubblav/ai-chatbot-react';

const config: BubblaVWidgetProps = {
  websiteId: 'your-website-id',
  onToolExecuted: (event: ToolExecutedEvent) => console.info(event.toolNames),
};

import type { ToolExecutedEvent } from '@bubblav/ai-chatbot-sdk';

interface BubblaVAPI {
  open(): void;
  close(): void;
  toggle(): void;
  isOpen(): boolean;
  show(): void;
  hide(): void;
  openSearch(): void;
  closeSearch(): void;
  toggleSearch(): void;
  sendMessage(message: string, conversationId?: string): void;
  showGreeting(data?: string | {
    message?: string;
    senderName?: string;
    senderAvatarUrl?: string;
    timestamp?: string | number;
  }): void;
  hideGreeting(): void;
  identify(token: string | null): boolean | void;
  onIdentityNeeded(callback: () => void): (() => void) | void;
  offIdentityNeeded(callback: () => void): void;
  on(event: 'toolExecuted', callback: (event: ToolExecutedEvent) => void): void;
  on<T = unknown>(event: string, callback: (data: T, ...args: unknown[]) => void): void;
  off(event: 'toolExecuted', callback: (event: ToolExecutedEvent) => void): void;
  off<T = unknown>(event: string, callback: (data: T, ...args: unknown[]) => void): void;
  getConfig(): Record<string, unknown>;
  setDebug(enabled: boolean): void;
  ready(callback: () => void): void;
  track(eventName: string, properties?: Record<string, unknown>): void;
}