SDK Quickstart

The @deliverychat/sdk package gives you programmatic control over Delivery Chat — open/close the widget, listen to events, send messages from code, and more.

⚠️

Prerequisite: Application ID

You need an appId to use the SDK. Create an application in your dashboard first.

AI Quickstart

Copy this prompt into your AI coding assistant (Cursor, Copilot, Claude, etc.) to get a working integration in one shot:

SDK Integration PromptAI

Installation


npm install @deliverychat/sdk@^1.0.0


bun add @deliverychat/sdk@^1.0.0

Then import and initialize:


import { init, getSdkApi } from "@deliverychat/sdk";
 
init({
  appId: process.env.NEXT_PUBLIC_DELIVERYCHAT_APP_ID,
  apiBaseUrl: process.env.NEXT_PUBLIC_DELIVERYCHAT_API_URL,
});
 
const chat = getSdkApi();
chat.on("ready", () => {
  console.log("Widget is ready");
});

ℹ️

apiBaseUrl is origin-only

The apiBaseUrl option must be the origin only (protocol + host + optional port). Never append /api/v1 — the SDK handles path construction internally.

Examples: “https://api.deliverychat.online ”, “http://localhost:8000 ”

Environment variable naming by framework

Framework	Prefix	Example
Next.js	`NEXT_PUBLIC_`	`NEXT_PUBLIC_DELIVERYCHAT_APP_ID`
Vite / React Router	`VITE_`	`VITE_DELIVERYCHAT_APP_ID`
Create React App	`REACT_APP_`	`REACT_APP_DELIVERYCHAT_APP_ID`
Nuxt	`NUXT_PUBLIC_`	`NUXT_PUBLIC_DELIVERYCHAT_APP_ID`
Astro (client)	`PUBLIC_`	`PUBLIC_DELIVERYCHAT_APP_ID`

Client-Only Lifecycle

The SDK must only be initialized in the browser. Never call init() during SSR or server-side rendering.

React (useEffect)


import { init, destroy } from "@deliverychat/sdk";
import { useEffect } from "react";
 
function App() {
  useEffect(() => {
    init({
      appId: process.env.NEXT_PUBLIC_DELIVERYCHAT_APP_ID,
      apiBaseUrl: process.env.NEXT_PUBLIC_DELIVERYCHAT_API_URL,
    });
    return () => { destroy(); };
  }, []);
 
  return <div>...</div>;
}

Vue (onMounted / onUnmounted)


import { init, destroy } from "@deliverychat/sdk";
import { onMounted, onUnmounted } from "vue";
 
onMounted(() => {
  init({
    appId: import.meta.env.VITE_DELIVERYCHAT_APP_ID,
    apiBaseUrl: import.meta.env.VITE_DELIVERYCHAT_API_URL,
  });
});
onUnmounted(() => { destroy(); });

Vanilla JS (DOMContentLoaded)


import { init } from "@deliverychat/sdk";
 
document.addEventListener("DOMContentLoaded", () => {
  init({
    appId: "YOUR_APP_ID",
    apiBaseUrl: "https://api.deliverychat.online",
  });
});

Basic Usage


const chat = getSdkApi();
 
chat.open();       // Open the chat window
chat.close();      // Close it
chat.toggle();     // Toggle open/close
chat.hideWidget(); // Hide the launcher button
chat.showWidget(); // Show it again

Listen to events


chat.on("message:received", (message) => {
  console.log("New message:", message.content);
});
 
chat.on("unread:changed", ({ count }) => {
  document.title = count > 0 ? `(${count}) My App` : "My App";
});

Send messages programmatically


const message = await chat.sendMessage("Hello from code!");
console.log("Sent:", message.id);

Cleanup

Remove the widget and release all resources:


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

Always call destroy() on component unmount (React useEffect cleanup, Vue onUnmounted, etc.) to prevent memory leaks in single-page applications.