Quickstart

Embed this widget in your application in two steps:

1

Retrieve User Token (Backend)

async function getUserToken(widgetKey, userId, userData, limits, partnerHmacSecret) {
  const response = await fetch('https://api.elfa.ai/embed/v1/get-user-token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Widget-Key': widgetKey, // Your widget key from Elfa, e.g., "elfaw_..."
    },
    body: JSON.stringify({
      userIdentifier: userId, // Your user's unique identifier
      // Required. Real user context for personalization, e.g.
      // {name, walletAddress, preferredChains}. Do not send an empty object.
      userData: userData,
      // Optional per-user webhook signing secret (16-255 chars).
      partnerHmacSecret: partnerHmacSecret ?? undefined,
      // Optional per-user usage caps enforced server-side. Omit to inherit
      // partner defaults. Response includes a 'quota' block when active.
      limits: limits ?? {
        // user_daily_chats: 50,
        // user_monthly_chats: 1000,
        // user_session_messages: 30,
      }
    })
  });

  const data = await response.json();
  return data.userToken ?? data.data?.userToken ?? null;
}
2

Embed the Widget (Frontend)

<script
  src="https://widget.elfa.ai//embed-apollo.js"
  data-base-url="https://widget.elfa.ai//apollo/embed"
  data-user-token="RETRIEVED_USER_TOKEN"
  data-width="500"
  data-height="700"
  data-theme="dark"
></script>

Going further

Personalization, custom style overrides, keyboard shortcuts, per-user usage limits, order webhooks, and the full PostMessage contract are covered in the Partner Integration Guide.

Building a backend (headless) integration instead? See the Widget API docs at docs.elfa.ai.