JSPM – @paramms/chat-widget@1.0.1

Package Exports

@paramms/chat-widget
@paramms/chat-widget/react

Readme

Real-time embeddable chat widget for the Relay platform. Drop into any website with a single script tag — no build step required.

Install

npm install @paramms/chat-widget

Quick start — CDN (no npm, no build)

<div id="chat"></div>
<script type="module">
  import { mount } from 'https://relay.paramms.com/index.js'
  mount({
    el:        document.getElementById('chat'),
    url:       'wss://api.paramms.com/ws',
    profileId: 'YOUR_PROFILE_ID',
  })
</script>

React / Next.js

'use client'
import { ChatWidget } from '@paramms/chat-widget/react'

export default function SupportChat() {
  return (
    <ChatWidget
      url="wss://api.paramms.com/ws"
      profileId="YOUR_PROFILE_ID"
    />
  )
}

Pass your own user's ID as the token and their details via user. Anonymous users work without any configuration.

<ChatWidget
  url="wss://api.paramms.com/ws"
  profileId="YOUR_PROFILE_ID"
  token={currentUser.id}          // your own stable user ID — ties history across devices
  user={{
    name:   currentUser.name,     // shown to agents instead of opaque ID
    email:  currentUser.email,    // agents can follow up even after disconnect
    avatar: currentUser.avatarUrl,
    meta: {
      plan:      currentUser.plan,
      accountId: currentUser.id,
    },
  }}
/>

Cryptographically verified identity (Tier 4)

For marketplaces and financial services — the guest's identity is verified against your ECDSA key so it cannot be spoofed.

// 1. Generate a key pair (once, server-side)
//    openssl ecparam -genkey -name prime256v1 -noout | openssl pkcs8 -topk8 -nocrypt -out private.pem
//    openssl ec -in private.pem -pubout | base64 -w0  → paste in Dashboard → Domain → Guest identity linking

// 2. Sign a token per user (your backend)
import { createSign } from 'node:crypto'
const hdr = Buffer.from(JSON.stringify({ alg: 'ES256', typ: 'JWT' })).toString('base64url')
const pay = Buffer.from(JSON.stringify({ sub: userId, iat: Math.floor(Date.now() / 1000), exp: Math.floor(Date.now() / 1000) + 3600 })).toString('base64url')
const sig = createSign('SHA256').update(`${hdr}.${pay}`).sign(privateKey, 'base64url')
const signedToken = `${hdr}.${pay}.${sig}`

// 3. Pass to widget — server verifies the signature automatically
<ChatWidget url="..." profileId="..." token={signedToken} />

Marketplace / multi-item (one thread per listing)

<ChatWidget
  url="wss://api.paramms.com/ws"
  profileId="YOUR_PROFILE_ID"
  subjectId={`car_${listing.id}`}   // one conversation per item
  showChatList={true}                // guest can switch between their threads
/>

Launcher (floating button)

<ChatWidget
  url="wss://api.paramms.com/ws"
  profileId="YOUR_PROFILE_ID"
  launcher={true}
  position="bottom-right"
  accent="#4F63F5"
/>

Internationalisation

<ChatWidget
  url="wss://api.paramms.com/ws"
  profileId="YOUR_PROFILE_ID"
  i18n={{
    placeholder: 'Écrivez un message…',
    send:        'Envoyer',
    offline:     'Nous sommes hors ligne pour l\'instant',
    poweredBy:   '',   // empty string hides the footer
  }}
/>

RTL is detected automatically for Arabic, Hebrew, Persian and Urdu browsers.

All options

Option	Type	Default	Description
`el`	`HTMLElement`	required	Mount target
`url`	`string`	required	WebSocket URL (`wss://...`)
`profileId`	`string`	required	Domain profile ID
`token`	`string`	auto-generated	Guest identity token — pass your user's stable ID to tie history across devices
`user`	`UserInfo`	—	Name, email, avatar, custom metadata — shown to agents
`subjectId`	`string`	—	Item ID for marketplace mode
`showChatList`	`boolean`	`false`	Show conversation switcher in header
`accent`	`string`	`#f5713c`	Brand colour (hex)
`launcher`	`boolean`	`false`	Render as floating button
`position`	`'bottom-right' \| 'bottom-left'`	`'bottom-right'`	Launcher position
`translateLang`	`string`	—	Auto-translate incoming messages (ISO language code)
`quickReplies`	`string[]`	—	Pre-set reply chips shown above input
`i18n`	`I18nStrings`	English	UI string overrides

Development

npm install
npm run dev          # Vite preview at http://localhost:5174/
npm run build        # tsc → dist/
npm run build:bundle # Vite → standalone CDN bundle
npm test             # 75 tests via vitest
npm run typecheck

@paramms/chat-widget