@unthread-io/portal-embed-sdk

SDK for embedding the Unthread customer portal in your application. Supports vanilla JavaScript, React, and any framework.

Installation

npm install @unthread-io/portal-embed-sdk

Quick Start

React

import { UnthreadPortal } from '@unthread-io/portal-embed-sdk/react';

function SupportPage() {
  const getToken = async () => {
    const res = await fetch('/api/portal-token');
    const { jwt } = await res.json();
    return jwt;
  };

  return (
    <UnthreadPortal
      baseUrl="https://help.acme.unthread.io"
      getToken={getToken}
      onAuthenticated={() => console.log('Portal ready')}
      style={{ height: 600 }}
    />
  );
}

Using the hook for programmatic control

import { UnthreadPortal, useUnthreadPortal } from '@unthread-io/portal-embed-sdk/react';

function SupportPage() {
  const portal = useUnthreadPortal();

  return (
    <div>
      <nav>
        <button onClick={() => portal.showAiChat()}>Ask AI</button>
        <button onClick={() => portal.showConversations()}>My Tickets</button>
        <button onClick={() => portal.showNewTicket()}>Submit Ticket</button>
        <button onClick={() => portal.showArticle('getting-started')}>Help</button>
      </nav>

      <UnthreadPortal baseUrl="https://help.acme.unthread.io" getToken={getToken} style={{ height: 600 }} />
    </div>
  );
}

Vanilla JavaScript

<div id="portal" style="width: 100%; height: 600px;"></div>

<script>
  window.UnthreadPortalSettings = {
    baseUrl: 'https://help.acme.unthread.io',
    getToken: function () {
      return fetch('/api/portal-token')
        .then(function (res) {
          return res.json();
        })
        .then(function (data) {
          return data.jwt;
        });
    },
    container: '#portal',
  };
</script>
<script src="https://help.acme.unthread.io/embed.js" async></script>

Use window.UnthreadPortalSettings before loading embed.js for the standard vanilla integration. The script boots automatically from these settings.

The queued UnthreadPortal('boot', options) snippet is also supported when used with the queue stub before the script loads. After loading, window.UnthreadPortal is an SDK object; use methods such as window.UnthreadPortal.boot(options) and window.UnthreadPortal.showConversations().

ES Module imports

import { boot, showConversations, onAuthenticated } from '@unthread-io/portal-embed-sdk';

await boot({
  baseUrl: 'https://help.acme.unthread.io',
  getToken: async () => {
    const res = await fetch('/api/portal-token');
    const { jwt } = await res.json();
    return jwt;
  },
  container: '#portal',
});

onAuthenticated(() => {
  console.log('User is authenticated in the portal');
});

showConversations();

Start with AI chat

Choose the starting page, theme, and sidebar visibility under Embedding → Embed Options in the portal dashboard and save. Existing embeds pick up these defaults on reload without changing their URL or snippet. Unconfigured portals start on the home page with the sidebar visible and use the portal's normal theme preference.

To override the saved starting page for an individual embed, set initialPage: 'aiChat' in boot(options) or window.UnthreadPortalSettings. In React, pass initialPage="aiChat" to <UnthreadPortal />. This opens the AI assistant after authentication. Explicit initialPage, theme, and showSidebar options take precedence over dashboard settings; omit them to follow the saved defaults.

Use showAiChat() to open the assistant later through the script SDK, module exports, or React hook. It preserves the current conversation. Other SDK navigation methods close the panel. During iframe startup, the latest navigation request wins.

initialPage applies at boot; changing the React prop after mounting does not navigate.

API Reference

Lifecycle

| Method | Description | | ------------------ | -------------------------------------------------------------------------- | | boot(options) | Initialize and render the portal | | shutdown() | Remove the portal and clean up all state | | authenticate() | Re-invoke getToken and send the result to the portal (for token refresh) | | update(userData) | Update user metadata (name, email, etc.) | | logout() | Clear the portal session |

Navigation

| Method | Description | | ------------------------------ | -------------------------------- | | navigate(path) | Navigate to any portal path | | showHome() | Navigate to the portal home page | | showAiChat() | Open the AI assistant panel | | showConversations() | Show the ticket list | | showConversation(id) | Open a specific conversation | | showArticle(slugOrId) | Open a knowledge base article | | showNewTicket(ticketTypeId?) | Open the ticket submission form |

Events

| Method | Description | | --------------------------- | ------------------------------------------------------- | | on(event, callback) | Subscribe to an event. Returns an unsubscribe function. | | onReady(callback) | Shorthand for on('ready', callback) | | onAuthenticated(callback) | Shorthand for on('authenticated', callback) | | onError(callback) | Shorthand for on('error', callback) |

React

| Export | Description | | --------------------- | ----------------------------------------------------------------- | | <UnthreadPortal /> | Component that renders the embedded portal | | useUnthreadPortal() | Hook returning stable references to all navigation/action methods |

Boot Options

| Option | Type | Required | Description | | ----------- | --------------------------------- | -------- | --------------------------------------------- | | baseUrl | string | Yes | Portal URL | | container | string \| HTMLElement | Yes | Where to render (CSS selector or DOM element) | | getToken | () => string \| Promise<string> | Yes | Callback that returns a signed JWT | | initialPage | 'home' \| 'aiChat' | No | Override the saved starting view | | showSidebar | boolean | No | Override the saved sidebar visibility | | theme | 'light' \| 'dark' | No | Override the saved embed theme |

JWT Format

Your backend signs a JWT using the embed secret key (generated in portal admin settings):

{
  "email": "[email protected]",
  "name": "Jane Doe",
  "external_id": "usr_123",
  "iat": 1709312400,
  "exp": 1709312700
}

| Field | Required | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------- | | email | Yes | User's email address. Used to identify the portal account. | | name | No | Display name shown in the portal. | | external_id | No | Your internal user ID. Reserved for future use — validated but not currently stored or processed. | | iat | Yes | Issued-at timestamp (Unix seconds). | | exp | Yes | Expiration timestamp. Max 5 minutes from iat. |

• Algorithm: HS256
• Max TTL: 5 minutes