@orkify/chat

v1.0.0-beta.12

Published

a month ago

Embeddable support chat widget for orkify — powered by Discord

Downloads

0High
0Medium
0Low

orkify-orkify

chat-widget discord support-chat live-chat customer-support embeddable react nextjs

Embeddable support chat widget that lets you talk to your website visitors in real time — directly from Discord. Add it to any website with a single script tag or a React component.

Visitor messages are routed through orkify and delivered to your Discord channel as threads. Your team replies in Discord, visitors see responses in the widget instantly. Requires an orkify account with a paid plan and a Discord bot connected via the dashboard. See the full setup guide for details.

Installation

npm install @orkify/chat

Or skip the install and use a CDN — no npm required:

<script
  src="https://cdn.jsdelivr.net/npm/@orkify/chat/orkify-chat.js"
  data-widget-key="YOUR_KEY"
></script>

Script Tag (any website)

Works on any website — no framework required. Add a single script tag before </body>:

CDN (recommended)

Served directly from npm via jsDelivr or unpkg — always up to date, no hosting needed:

<script
  src="https://cdn.jsdelivr.net/npm/@orkify/chat/orkify-chat.js"
  data-widget-key="YOUR_KEY"
></script>

Or pin to a specific version:

<script
  src="https://cdn.jsdelivr.net/npm/@orkify/[email protected]/orkify-chat.js"
  data-widget-key="YOUR_KEY"
></script>

Self-hosted

Copy the widget script to your site and reference it locally:

cp node_modules/@orkify/chat/orkify-chat.js public/

<script src="/orkify-chat.js" data-widget-key="YOUR_KEY"></script>

React / Next.js Component

For Next.js and React apps, use the <OrkifyChat> component. It handles script loading, visitor context, and SPA navigation automatically.

npm install @orkify/chat

Add it to your root layout:

// app/layout.tsx
import { OrkifyChat } from '@orkify/chat/react';

export default function Layout({ children }) {
  return (
    <html>
      <body>
        {children}
        <OrkifyChat widgetKey="wk_..." />
      </body>
    </html>
  );
}

With visitor info

Pass visitor props to skip the intro form and enable cross-browser chat restoration:

<OrkifyChat
  widgetKey="wk_..."
  visitorName={user.name}
  visitorEmail={user.email}
  visitorHash={hmac}
/>

Self-hosted script

By default the component loads the script from jsDelivr CDN. To self-host:

<OrkifyChat widgetKey="wk_..." src="/orkify-chat.js" />

Visitor Identity

There are three levels of integration:

| Level | What happens | | -------------------------- | ------------------------------------------------------------------------------ | | Anonymous | Visitors fill out a name + email form before chatting | | With user info | Pass visitorName + visitorEmail to skip the form | | With HMAC verification | Add visitorHash for identity verification and cross-browser chat restoration |

Identity Verification (HMAC)

HMAC-SHA256 verification proves the visitor's email was set by your server, preventing impersonation and enabling cross-browser chat restoration.

Compute HMAC-SHA256(email, signingSecret) on your server and pass the hex string as visitorHash (React) or data-visitor-hash (script tag).

// Server-side (Node.js)
const crypto = require('crypto');
const hash = crypto.createHmac('sha256', SIGNING_SECRET).update(user.email).digest('hex');

Your signing secret is on the Integrations settings page in the orkify dashboard. Never expose it in client-side code.

GIFs & Stickers

GIFs

Visitors can send GIFs using the built-in picker, powered by Klipy. Pass your Klipy API key:

<OrkifyChat widgetKey="wk_..." klipyKey="klipy_..." />

Or with the script tag:

<script
  src="https://orkify.com/orkify-chat.js"
  data-widget-key="YOUR_KEY"
  data-klipy-key="klipy_..."
></script>

GIFs sent from Discord are displayed in the widget automatically.

Stickers

Discord stickers sent by your team are rendered with full animation support. Animated stickers (Lottie format) play as smooth animations using lottie-web, loaded on demand. No configuration needed.

Widget Attributes

For the script tag integration:

| Attribute | Required | Description | | -------------------- | -------- | --------------------------------------------------------------------- | | data-widget-key | Yes | Widget key from the orkify Integrations settings page | | data-visitor-name | No | Visitor's display name. Skips the intro form when provided with email | | data-visitor-email | No | Visitor's email. Used for thread identification | | data-visitor-hash | No | HMAC-SHA256 hex digest for identity verification | | data-klipy-key | No | Klipy API key to enable the GIF picker |

Requirements

An orkify account with a paid plan
A Discord bot connected via the orkify dashboard (see the setup guide)
For the React component: React 18+ and Next.js 15+
Messages are routed through orkify.com — no self-hosted backend needed

License

Apache-2.0