API Reference

Complete API documentation for the Chatoshi SDK including all methods, events, and type definitions.

API Reference

Complete reference documentation for the Chatoshi SDK.

Classes

Chatoshi

The main SDK class for initializing and managing crypto assistant chat instances.

Constructor

new Chatoshi(options: ChatoshiInitOptions)

Parameters:

  • options - Configuration options for the chat instance

Example:

const chat = new Chatoshi({
  partnerKey: "your-partner-key",
  container: "#chat-container",
});

Methods

on(eventName: string, callback: Function)

Adds an event listener for the specified event.

Parameters:

  • eventName - Name of the event to listen for
  • callback - Function to call when the event is triggered

Returns: Chatoshi - Returns the instance for method chaining

Example:

chat.on("app:ready", () => {
  console.log("Crypto assistant is ready!");
});

chat.on("popup:open", () => {
  console.log("Popup opened");
});
off(eventName: string, callback?: Function)

Removes an event listener.

Parameters:

  • eventName - Name of the event
  • callback - (Optional) Specific callback to remove. If not provided, all listeners for the event are removed

Returns: Chatoshi - Returns the instance for method chaining

Example:

const handler = () => console.log("Event fired");
chat.on("app:ready", handler);
chat.off("app:ready", handler); // Remove specific listener
chat.off("app:ready"); // Remove all listeners for this event
open()

Opens the chat interface (only applicable for popup and drawer modes).

Example:

chat.open(); // Opens popup or drawer
close()

Closes the chat interface (only applicable for popup and drawer modes).

Example:

chat.close(); // Closes popup or drawer
toggle()

Toggles the chat interface open/closed state (only applicable for popup and drawer modes).

Example:

chat.toggle(); // Opens if closed, closes if open
getPopup()

Returns the popup instance if in popup mode.

Returns: Popup | null

Example:

const popup = chat.getPopup();
if (popup) {
  console.log("Popup is open:", popup.isOpen());
}
getDrawer()

Returns the drawer instance if in drawer mode.

Returns: Drawer | null

Example:

const drawer = chat.getDrawer();
if (drawer) {
  console.log("Drawer is open:", drawer.isOpen());
}
isReady()

Checks if the SDK is ready and initialized.

Returns: boolean

Example:

if (chat.isReady()) {
  console.log("SDK is ready to use");
}
destroy()

Destroys the chat instance and cleans up all resources.

Example:

chat.destroy(); // Clean up when no longer needed

Manages popup mode functionality. Access via chat.getPopup().

Methods

open()

Opens the popup if it's currently closed.

close()

Closes the popup if it's currently open.

toggle()

Toggles the popup open/closed state.

isOpen()

Returns whether the popup is currently open.

Returns: boolean

destroy()

Destroys the popup and removes all DOM elements.

getElements()

Returns the DOM elements created by the popup.

Returns: { popupWrapper: HTMLElement, toggleWrapper: HTMLElement }

Drawer

Manages drawer mode functionality. Access via chat.getDrawer().

Methods

open()

Opens the drawer if it's currently closed.

close()

Closes the drawer if it's currently open.

toggle()

Toggles the drawer open/closed state.

isOpen()

Returns whether the drawer is currently open.

Returns: boolean

destroy()

Destroys the drawer and removes all DOM elements.

getElements()

Returns the DOM elements created by the drawer.

Returns: { drawerWrapper: HTMLElement, drawerOverlay: HTMLElement }

Events

The SDK emits various events that you can listen to using the on() method.

Application Events

app:ready

Fired when the crypto assistant application is fully loaded and ready to use.

chat.on("app:ready", () => {
  console.log("Crypto assistant is ready!");
});

app:error

Fired when there's an application error.

chat.on("app:error", (error) => {
  console.error("Application error:", error);
});

Communication Events

message:sent

Fired when a user sends a message to the crypto assistant.

chat.on("message:sent", (data) => {
  console.log("User message sent:", data);
});

message:received

Fired when the crypto assistant responds to the user.

chat.on("message:received", (data) => {
  console.log("AI response received:", data);
});

UI Events

popup:open

Fired when the popup is opened.

chat.on("popup:open", () => {
  console.log("Popup opened");
});
popup:close

Fired when the popup is closed.

chat.on("popup:close", () => {
  console.log("Popup closed");
});

Drawer Events

drawer:open

Fired when the drawer is opened.

chat.on("drawer:open", () => {
  console.log("Drawer opened");
});
drawer:close

Fired when the drawer is closed.

chat.on("drawer:close", () => {
  console.log("Drawer closed");
});

Type Definitions

ChatoshiInitOptions

interface ChatoshiInitOptions {
  partnerKey: string;
  container?: HTMLElement | string;
  containerStyle?: Record<string, string | number>;
  containerClass?: string | string[];
  mode?: "default" | "full" | "popup" | "drawer";
  theme?: "light" | "dark" | "system";
  popupOptions?: PopupOptions;
  drawerOptions?: DrawerOptions;
  splashScreen?: boolean | { customHTML?: string | HTMLElement };
  colors?: IColorOptions | { default?: IColorOptions; dark?: IColorOptions };
  customLogo?: string | { dark: string; light: string };
}

PopupOptions

interface PopupOptions {
  width?: string;
  height?: string;
  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
  customToggleButton?: string | HTMLElement;
  containerClass?: string | string[];
}

DrawerOptions

interface DrawerOptions {
  width?: string;
  position?: "left" | "right";
  closeButtonDisabled?: boolean; // NEW: disables the close button if true
  containerClass?: string | string[];
}

New Feature:

  • closeButtonDisabled?: boolean — Set to true to hide/disable the close button in the drawer UI. Default is false (close button is shown).

Example:

drawerOptions: {
  width: '350px',
  position: 'right',
  closeButtonDisabled: true // disables the close button
}

IColorOptions

interface IColorOptions {
  primary?: string;
  secondary?: string;
  background?: string;
  border?: string;
  text?: string;
  ring?: string;
}

Error Handling

The SDK throws descriptive errors for common configuration issues:

Common Errors

// Missing required parameters
new Chatoshi({});
// Error: Partner Key is required for Chatoshi initialization

// Missing container for default mode
new Chatoshi({
  partnerKey: "partner-key",
  mode: "default",
});
// Error: Container is required for Chatoshi initialization

// Invalid container selector
new Chatoshi({
  partnerKey: "partner-key",
  container: "#non-existent",
});
// Error: Container element not found

Best Practices

Memory Management

Always clean up when the chat is no longer needed:

// Store reference
const chat = new Chatoshi(options);

// Clean up when component unmounts or page unloads
window.addEventListener("beforeunload", () => {
  chat.destroy();
});

Event Handling

Remove event listeners to prevent memory leaks:

const handler = (data) => console.log(data);

chat.on("app:ready", handler);

// Later, remove the listener
chat.off("app:ready", handler);

Theme and Color Configuration

Use consistent color schemes across themes:

const chat = new Chatoshi({
  partnerKey: "your-partner-key",
  colors: {
    default: {
      primary: "#0066cc",
      background: "#ffffff",
      text: "#333333",
    },
    dark: {
      primary: "#3399ff",
      background: "#1a1a1a",
      text: "#ffffff",
    },
  },
});

Error Handling

Wrap initialization in try-catch for better error handling:

try {
  const chat = new Chatoshi({
    partnerId: "your-partner-id",
    appId: "your-app-id",
    container: "#chat-container",
  });
} catch (error) {
  console.error("Failed to initialize chat:", error.message);
}