cs-widget Integration Guide

<script async
  src="https://cs.sochatlive.com/widget.js"
  data-app-key="sk_xxxxxxxxxxxxxxxxx"
  data-api-base="https://api.starim.io"
  data-locale="zh-CN"
  data-theme="auto"
  data-position="br"></script>

<script async src="https://cs.sochatlive.com/widget.js?appKey=sk_xxxxxxxxxxxxxxxxx&apiBase=https%3A%2F%2Fapi.sochatlive.com&locale=en-US"></script>

<script async src="https://cs.sochatlive.com/widget.js" data-defer-init></script>
<script>
  // queue-style: commands are buffered while the script loads asynchronously
  window.StarIMCS = window.StarIMCS || function () {
    (window.StarIMCS.q = window.StarIMCS.q || []).push(arguments)
  }

  StarIMCS('init', {
    appKey: 'sk_xxxxxxxxxxxxxxxxx',
    apiBase: 'https://api.sochatlive.com',  // replace with your private API origin when self-hosting
    externalUserId: 'u_42',
    nickname: 'Alex Lee',
    extra: { orderNo: 'O-2026-001' },
    onReady: () => console.log('widget ready'),
    onMessage: (m) => console.log('msg', m),
  })
</script>

Commands are queued while the script loads asynchronously and replay automatically once the widget is ready. Use this when your host page already has its own initialization flow.

Ideal for SMS, email, QR codes, and other off-site channels: visitors open the link and land directly in a full-screen support window. No script embed is required on the destination page, and there is no domain allowlist requirement. You can enable it alongside CDN or npm embeds.

# Smallest possible link: appKey only
https://cs.sochatlive.com/?k=sk_xxxxxxxxxxxxxxxxx

# Include visitor identity (when your business user is already signed in)
https://cs.sochatlive.com/?k=sk_xxxxxxxxxxxxxxxxx&u=u_42&nick=Alex%20Lee

# pnpm
pnpm add @starim-io/cs-widget

# npm
npm install @starim-io/cs-widget

# yarn
yarn add @starim-io/cs-widget

const { init, identify, open, on, version } = require('@starim-io/cs-widget')

await init({
  appKey: 'sk_xxxxxxxxxxxxxxxxx',
  apiBase: 'https://api.sochatlive.com',  // Replace with your private API origin when self-hosting
  externalUserId: currentUser?.id,
  nickname: currentUser?.name,
})

console.log('StarIM CS SDK version:', version)

# Smallest possible link: appKey only
https://cs.sochatlive.com/?k=sk_xxxxxxxxxxxxxxxxx

# Include visitor identity (when your business user is already signed in)
https://cs.sochatlive.com/?k=sk_xxxxxxxxxxxxxxxxx&u=u_42&nick=Alex%20Lee

Use this for internal testing or tightly controlled channels. Production should enable signatures (admin → Site → Standalone link → Enforce signature validation).

https://cs.sochatlive.com/?k=sk_xxxxxxxxxxxxxxxxx&u=u_42&nick=Alex%20Lee&t=1716268800&s=8f0a...

t is the Unix timestamp in seconds and s is the HMAC-SHA256 signature in hex. Once the site TTL expires (300 seconds by default), the signature becomes invalid.

Signing algorithm

# Compute t / s with the same algorithm in your Node.js / Python / Go backend
t = floor(Date.now() / 1000)                       # Unix timestamp in seconds
payload = appKey + "\n" + t + "\n" + (externalUserId || "") + "\n" + (nickname || "")
s = HMAC_SHA256(signSecret, payload).digest("hex") # Put this value into ?s=...

# Node.js example
import crypto from 'node:crypto'
const t = Math.floor(Date.now() / 1000)
const payload = `${appKey}\n${t}\n${externalUserId || ''}\n${nickname || ''}`
const s = crypto.createHmac('sha256', signSecret).update(payload).digest('hex')

signSecret is returned by admin in plaintext only once, so store it securely. If you lose it, reset it and all previously issued signed links become invalid immediately.

Server-side signing (recommended)

Do not want to implement HMAC in your own backend? The admin console can generate signed links directly from "Site → Standalone Link → Generate signed link", or you can call:

# Admin Gateway · requires admin.cs.site.link.manage
POST /api/v1/admin/cs/sites/{siteId}/link-entry/sign
Authorization: Bearer <admin-jwt>
Content-Type: application/json

{ "externalUserId": "u_42", "nickname": "Alex Lee" }

# Response
{ "appKey": "sk_xxxx", "t": 1716268800, "s": "8f0a...",
  "ttlSec": 300, "expiresAt": "2026-05-21T07:53:20.000Z" }

The response already contains t / s / expiresAt, so you can append them back to the URL directly.