Quick Start

Install

Ensemble's client-sdk is published on npm.

npm install @ensembleapp/client-sdk

Usage

React Component (React 18+)

Embed the ChatWidget or PopupChatWidget directly into your React 18+ app.

import { ChatWidget } from '@ensembleapp/client-sdk';
import { useState, useEffect } from 'react';

function App() {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    // calling your server to return Ensemble's JWT token.
    // See example implementation below
    fetchToken().then(setToken);
  }, []);

  if (!token) return <div>Loading...</div>;

  return (
    <ChatWidget
      api={{
        baseUrl: 'https://service.ensembleapp.ai',
        token,
      }}
      // Ensemble agent id
      agentId="your-agent-id"
      // Unique thread id for history
      threadId="unique-conversation-id"
      // fetch new token when expired
      onAuthError={fetchToken}
    />
  );
}

For flexibility and maximum compatibility, you can load our chat widget via <script> tag at run time. This enables you to select specific versions of the widget. The widget will have its own React root separate from your Javascript/React.

<div id="chat-container"></div>

<!-- Use 'latest' or a specific sdk version like '0.0.24' -->
<script src="https://cdn.jsdelivr.net/npm/@ensembleapp/client-sdk@latest/dist/widget/widget.global.js"></script>
<script>
  window.ChatWidget.init({
    containerId: 'chat-container',
    api: {
      baseUrl: 'https://service.ensembleapp.ai',
      // the Ensemble JWT token from your server
      token: 'ensemble-jwt-token',
    },
    agentId: 'your-agent-id',
    threadId: 'unique-conversation-id',
  });
</script>

Authentication

Ensemble uses JWT (JSON Web Token) authentication to secure the chat widget.

1. Create a JWT Secret

In the Ensemble console, navigate to Settings → JWT Secrets and click Create Secret. Copy the generated secret—it will only be shown once.

Also note down the Secret ID. You will need both for the next step.

Create JWT secret via Ensemble settings

2. Generate JWT Tokens

Use the secret to sign JWT tokens on your backend. The token must include:

sub - A unique user identifier for tracking purposes
exp - Expiration in seconds from now
aud - Must be ensembleapp.ai

// Example Backend using jsonwebtoken (Node.js)
const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    // a unique user id for tracking purposes (e.g. user id on your system)
    sub: 'user-123',
    // expire in 3600 seconds (1 hour)
    exp: nowInSeconds + 3600,
    iat: nowInSeconds,
    aud: 'ensembleapp.ai',
  },
  process.env.ENSEMBLE_JWT_SECRET,
  {
    algorithm: 'HS256',
    // The Ensemble ID associated with the secret
    keyid: 'ensemble-secret-id',
  }
);

3. Fetch Token from Frontend

Update your JS code above to implement the fetchToken() - calling your backend to retrieve the JWT token.

const fetchToken = async () => {
  const res = await fetch('https://<your-server>/api/ensemble-token');
  const { token } = await res.json();
  return token;
};