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 Concepts -> Authentication for examples
    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

See Authentication for more details.

1. From Ensemble - 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.

2. From Your Backend - Sign the JWT Token using the JWT Secret

Use the generated ID/Secret to sign the JWT token on your backend.

// 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. From Your Frontend - Fetch the token

Your front-end calls your backend to retrieve the JWT token, then uses it to communicate with Ensemble.

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

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

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

  useEffect(() => { fetchToken(); }, []);

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

  return (
    <ChatWidget
      api={{ baseUrl: 'https://service.ensembleapp.ai', token }}
      agentId="your-agent-id"
      threadId="unique-conversation-id"
      onAuthError={fetchToken}
    />
  );
}