SDK Methods

Complete reference for all public methods available on the SDK.

Initialization

init(options)

Initialize the SDK and (unless headless) render the chat widget.

import { init } from "@deliverychat/sdk";
 
init({
  appId: "your-app-uuid",
  position: "bottom-right",
  headless: false,
});

destroy()

Remove the widget, close the WebSocket, and release all resources.

import { destroy } from "@deliverychat/sdk";
 
destroy();

After calling destroy(), you can call init() again to re-initialize.

Widget Control

All widget control methods require init() to have been called. In headless mode, these are no-ops.

open()

Open the chat window.

const chat = getSdkApi();
chat.open();

close()

Close the chat window.

chat.close();

toggle()

Toggle the chat window open or closed.

chat.toggle();

hideWidget()

Hide the launcher button. The chat window (if open) is not affected.

chat.hideWidget();

showWidget()

Show the launcher button.

chat.showWidget();

Messaging

sendMessage(text)

Send a message and wait for server acknowledgment. Creates a conversation automatically if none exists.

const message = await chat.sendMessage("Hello!");
console.log(message.id, message.status); // "msg_abc123", "sent"

Parameters:

Returns: Promise<ChatMessage>

type ChatMessage = {
  id: string;
  content: string;
  type: "text" | "system";
  senderRole: "visitor" | "operator" | "admin";
  senderId: string;
  status: "pending" | "sent" | "failed";
  createdAt: string;
  editedAt?: string | null;
  isDeleted?: boolean;
};

Throws if the WebSocket is disconnected, the server rejects the message, or the 15-second ACK timeout expires.

getConversation()

Get the current conversation state, or null if no conversation exists.

const conv = chat.getConversation();
if (conv) {
  console.log(conv.id, conv.status, conv.messages.length);
}

Returns: ConversationSnapshot | null

type ConversationSnapshot = {
  id: string;
  status: string;
  messages: ChatMessage[];
};

Identity

identify(params)

Associate the current anonymous visitor with known user data. See Visitor Identity for the full guide.

await chat.identify({
  name: "Jane Doe",
  email: "jane@example.com",
  externalId: "user_123",
  metadata: { plan: "premium" },
});

Parameters:

Returns: Promise<IdentityResult>

Events

on(event, callback)

Subscribe to an event. See Events for all available events.

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

off(event, callback)

Unsubscribe a previously registered callback.

const handler = (msg: ChatMessage) => console.log(msg);
chat.on("message:received", handler);
chat.off("message:received", handler);