bytedesk-web

• Online Demo

• 

• 

• npmjs

Online customer service SDK, supporting multiple frameworks:

• React Guide
• Next.js Guide
• Vue Guide
• Svelte Guide
• Angular Guide
• JavaScript Guide

basic settings

user info

goods info

order info

unread count

doc feedback

中文文档

• 
• 
• npmjs

Installation Steps

Development Environment

# Required Node.js version for Angular 21 / Vite 8
nvm use 22.12.0

# This repo uses pnpm instead of yarn
pnpm install

Install Dependencies

npm install bytedesk-web
# or
yarn add bytedesk-web

Import Component

import { BytedeskReact } from 'bytedesk-web/react';
import type { BytedeskConfig } from 'bytedesk-web/react';
# or
# import type { BytedeskConfig } from 'bytedesk-web';

Configure Parameters

const config: BytedeskConfig = {
  chatPath: '/chat', // default: /chat, thread history: /chat/thread
  placement: 'bottom-right',
  marginBottom: 20,
  marginSide: 20,
  bubbleConfig: {
    show: true,
    icon: '👋',
    title: 'Need help?',
    subtitle: 'Click to chat'
  },
  buttonConfig: {
    show: true,
    width: 60,
    height: 60,
    // icon: '👋',
    // text: '需要帮助吗？',
  },
  chatConfig: {
    org: 'df_org_uid',  // Replace with your organization ID
    t: "2",
    sid: 'df_rt_uid'      // Replace with your SID
  }
};

Thread History Page (/chat/thread)

Set chatPath to /chat/thread to make icon click and showChat() open the visitor thread history page.

const config: BytedeskConfig = {
  htmlUrl: 'https://cdn.weiyuai.cn/chat',
  chatPath: '/chat/thread',
  chatConfig: {
    org: 'df_org_uid',
    t: '1',
    sid: 'df_wg_uid',
    visitorUid: 'visitor_001',
    nickname: 'Visitor',
    avatar: 'https://weiyuai.cn/assets/images/avatar/02.jpg'
  }
};

Direct URL integration (same query params as /chat):

https://cdn.weiyuai.cn/chat/thread?org=df_org_uid&t=1&sid=df_wg_uid&visitorUid=visitor_001&nickname=Visitor&avatar=https%3A%2F%2Fweiyuai.cn%2Fassets%2Fimages%2Favatar%2F02.jpg&lang=en&mode=light

Use Component

const App = () => {
  const handleInit = () => {
    console.log('BytedeskReact initialized');
  };

  return (
    <div>
      <BytedeskReact {...config} onInit={handleInit} />
      <button onClick={() => (window as any).bytedesk?.showChat()}>
        Open Chat
      </button>
    </div>
  );
};

Inline Embed Mode

Embed the chat panel directly into any page — no floating bubble required.

Two modes are supported:

Mode	Description	Requires host container?
container	Chat fills a host-provided container	Yes
fixed-right	SDK auto-creates a right-sidebar panel on document.body, stays pinned when scrolling	No

container — Host-managed container

<div style={{ display: 'flex', height: '100vh' }}>
  <main style={{ flex: 1 }}>Main content</main>
  <aside style={{ width: 380 }}>
    <BytedeskReact
      mode="inline"
      chatConfig={{ org: 'df_org_uid', t: '2', sid: 'df_rt_uid' }}
    />
  </aside>
</div>

fixed-right — Zero host dependency (auto-panel)

The SDK injects a 420px panel pinned to position: fixed; right: 0 and automatically reserves body padding-right so page content reflows around it.

<BytedeskReact
  mode="inline"
  inlineConfig={{ mode: 'fixed-right', autoShow: true, width: 420 }}
  chatConfig={{ org: 'df_org_uid', t: '2', sid: 'df_rt_uid' }}
/>

Vanilla JS:

<script src="https://cdn.weiyuai.cn/embed/bytedesk-web.js"></script>
<script>
  new BytedeskWeb({
    mode: 'inline',
    inlineConfig: { mode: 'fixed-right', autoShow: true, width: 420 },
    chatConfig: { org: 'df_org_uid', t: '2', sid: 'df_rt_uid' },
    locale: 'zh-cn',
  }).init();
</script>

inlineConfig options:

Field	Type	Default	Description
mode	'container' | 'fixed-right'	'container'	Host container vs. SDK auto-panel
autoShow	boolean	true	Show the panel immediately after init
showBubble	boolean	false	Keep a floating bubble entry in inline mode
width	number	420	Panel width in px (fixed-right only)
zIndex	number	1000	Panel z-index (fixed-right only)
offsetTop	number	0	Top offset in px (fixed-right only, e.g. 64 for a 64px header)
offsetBottom	number	0	Bottom offset in px (fixed-right only, e.g. 40 for a footer)

Available Methods

# show/hide button
(window as any).bytedesk?.showButton();
(window as any).bytedesk?.hideButton();

# show/hide bubble
(window as any).bytedesk?.showBubble();
(window as any).bytedesk?.hideBubble();

# show/hide chat window
(window as any).bytedesk?.showChat();
(window as any).bytedesk?.hideChat();

# show/hide invite dialog
(window as any).bytedesk?.showInviteDialog();
(window as any).bytedesk?.hideInviteDialog();

# get unread message count
(window as any).bytedesk?.getUnreadMessageCount()
# clear unread messages
(window as any).bytedesk?.clearUnreadMessages()

Run Examples

pnpm install
pnpm demo:react    # Run React demo
pnpm demo:vue      # Run Vue demo
pnpm demo:svelte   # Run Svelte demo
pnpm demo:vanilla  # Run Vanilla JS demo
pnpm demo:angular  # Run Angular demo
pnpm demo:nextjs   # Run Next.js demo

# JavaScript demo requires build first
pnpm build
pnpm demo:javascript

CDN

# https://cdn.jsdelivr.net/npm/bytedesk-web@1.4.9/dist/
https://cdn.jsdelivr.net/npm/bytedesk-web@1.4.9/dist/bytedesk-web.js
https://cdn.jsdelivr.net/npm/bytedesk-web@1.4.9/dist/bytedesk-web.umd.js

Server

• Bytedesk

Open Source Demo + SDK

Project	Description	Forks	Stars
iOS	iOS
Android	Android
Flutter	Flutter
UniApp	Uniapp
Web	Vue/React/Angular/Next.js/JQuery/...
Wordpress	Wordpress
Woocommerce	woocommerce
Magento	Magento
Prestashop	Prestashop
Shopify	Shopify
Opencart	Opencart
Laravel	Laravel
Django	Django