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.