Web SDK Integration Guide

Web SDK Integration Guide

Web SDK Integration

Integrate the Ask Clio chatbot into your website using our Web SDK. Follow the steps below to embed Clio's AI assistant and optionally pass secure runtime context into tool execution.

---

Step 1: Add the iFrame to Your Website

You can embed Ask Clio into your website using an iFrame.

Base URL:

https://app.askclio.ai

Supported Parameters

• client_id (required) — Your unique client identifier. The client_id can be found at the bottom of the Configuration tab in the Ask Clio dashboard.

• st (optional) — A short-lived session token generated by your backend. The session token securely passes Dynamic Inputs (firm-defined secure fields) and clearing identifiers into Ask Clio tool execution. Values passed via st are not exposed to the LLM prompt -- they are only accessible to tools that explicitly reference them. The token is scoped to a single session and must be regenerated per session.

• is_wide (optional) — When set to true, the interface will use a wider layout.

Note on user identity The session token includes a user.id value (set during token creation). user.id should be your internal end-user identifier (e.g., your app user UUID). Do not use clearing account identifiers (e.g., alpaca_account_id) as user.id. Clearing identifiers should be passed only via tools_input (Dynamic Inputs).

How Chat History Is Determined

Chat history in Ask Clio is always scoped to user.id.

• user.id represents your application’s internal user identifier (for example, a UUID from your auth system).

• Ask Clio uses user.id as the source of truth for restoring and continuing conversations.

Clearing account identifiers (such as Alpaca account IDs) and other Dynamic Inputs:

• Are used only for tool execution

• Do not determine chat history

• Do not affect which conversation is loaded

Important: If multiple sessions are created using the same user.id, Ask Clio will correctly restore the same chat history — even if the clearing account or Dynamic Inputs differ.

To ensure each end user sees only their own conversation:

• Always pass a unique, stable user.id per end user

• Do not reuse user.id values across different users or environments

Example iFrame

<iframe
  id="clio-iframe"
  src="https://app.askclio.ai/?client_id=YOUR_CLIENT_ID&st=SESSION_TOKEN"
  width="100%"
  height="800"
  style="border: none; border-radius: 8px;"
  allowfullscreen
></iframe>

• The st parameter is optional. Omit it if you do not need to pass Dynamic Inputs or clearing identifiers.

• Replace YOUR_CLIENT_ID with your actual client ID. This value can be found at the bottom of the Configuration tab in the Ask Clio dashboard.

---

Alternative Install: Floating Widget (Script)

If you want Clio to appear as a floating chat button in the bottom-right corner (instead of embedding it directly in the page), use the script loader option.

<script src="https://app.askclio.ai/inject.js"></script>
<script>
  var clio = attachClioSDK(
    "https://app.askclio.ai?client_id=YOUR_CLIENT_ID",
    "YOUR_CLIENT_ID",
    "SESSION_TOKEN"   // optional — session token (st)
  );
</script>

attachClioSDK(iframeLocation, clientId, sessionToken)

• iframeLocation (string, required) — The full URL to the Clio app, including the client_id query parameter. Example: "https://app.askclio.ai?client_id=abc-123"

• clientId (string, optional) — Your client identity ID. When provided, the widget fetches your custom branding (logo, theme) automatically.

• sessionToken (string, optional) — Session token (st). Automatically appended to the iframe URL. Can also be embedded directly in iframeLocation instead.

Returns an SDK object with methods to control the widget programmatically (see SDK Methods below).

If provided, the session token (st) is consumed automatically by Ask Clio during session initialization and made available to tools during execution.

You can also embed st directly in the URL if you prefer:

var clio = attachClioSDK(
  "https://app.askclio.ai?client_id=YOUR_CLIENT_ID&st=SESSION_TOKEN",
  "YOUR_CLIENT_ID"
);

---

Important: User Identity vs Clearing Account IDs

When generating a session token (st), the user.id field must be a stable identifier from your own application (for example, your internal user UUID or database ID).

Do not use clearing or brokerage account identifiers (such as Alpaca account IDs) as user.id.

Clearing account identifiers should be passed only via Dynamic Inputs in tools_input (for example, alpaca_account_id).

Ask Clio intentionally separates who the user is (user.id) from which account is being queried (alpaca_account_id).

Ask Clio scopes chat history by (client_id, user.id).

If two sessions share the same user.id, the same conversation history will be restored by design. Each end user must have a unique user.id to maintain isolated chat history.

---

Anonymous to Authenticated Sessions

The Web SDK reads the session token (st) at initialization time. If your user context changes (e.g., anonymous → authenticated, or user switches accounts), you must re-initialize the widget with a new token. If you are using React 18 StrictMode or remounting components, ensure your integration is idempotent (do not attach twice with the same token) and supports teardown/re-init.

Using the Floating Widget

clio.refreshSession("newly-generated-session-token");

Using a Direct iFrame Embed

Send a postMessage to the iframe:

document.getElementById("clio-iframe").contentWindow.postMessage(
  JSON.stringify({
    type: "CLIO_REFRESH_SESSION",
    sessionToken: "newly-generated-session-token"
  }),
  "*"
);

See Refreshing Sessions below for full details and examples.

---

SDK Methods

These methods are available on the object returned by attachClioSDK().

clio.open()

Programmatically opens the chat widget.

clio.open();

clio.close()

Programmatically closes the chat widget.

clio.close();

clio.refreshSession(newSessionToken?)

Refreshes the authentication session inside the Clio iframe without a full page reload.

• newSessionToken (string, optional) — A new session token to use. If omitted, the session is re-created with the existing stored parameters.

When to use:

• The user's session token has changed on your side (e.g. after login or re-authentication).

• You need to switch from an anonymous session to an authenticated one.

• You need to switch to a different session/user context.

• The session has expired and you want to silently renew it.

// Refresh with a new token:
clio.refreshSession("new-session-token-abc123");

// Or re-create the current session:
clio.refreshSession();

clio.on(eventName, callback)

Registers a callback for SDK events.

Supported events:

• "sessionRefreshed" — Fired when the session was successfully refreshed. Callback receives { success: true }.

• "sessionRefreshError" — Fired when the session refresh failed. Callback receives { error: "..." } with the error message.

clio.on("sessionRefreshed", function (data) {
  // Session was refreshed successfully
});

clio.on("sessionRefreshError", function (data) {
  // Handle refresh failure — data.error contains the message
});

---

Refreshing Sessions

Both install options use the same underlying postMessage mechanism. The floating widget SDK wraps it for convenience; with a direct iFrame embed you send the messages yourself.

Floating Widget

var clio = attachClioSDK(
  "https://app.askclio.ai?client_id=YOUR_CLIENT_ID",
  "YOUR_CLIENT_ID"
);

clio.on("sessionRefreshed", function () {
  // success
});

clio.on("sessionRefreshError", function (err) {
  // err.error contains the message
});

// Later, when the user logs in:
clio.refreshSession("new-session-token");

Direct iFrame Embed

var clioIframe = document.getElementById("clio-iframe");

// Listen for results
window.addEventListener("message", function (event) {
  try {
    var data = typeof event.data === "string" ? JSON.parse(event.data) : event.data;

    if (data.type === "CLIO_SESSION_REFRESHED") {
      // success
    } else if (data.type === "CLIO_SESSION_REFRESH_ERROR") {
      // data.error contains the message
    }
  } catch (e) {
    // Ignore non-Clio messages
  }
});

// Later, when the user logs in:
clioIframe.contentWindow.postMessage(
  JSON.stringify({
    type: "CLIO_REFRESH_SESSION",
    sessionToken: "new-session-token"   // or null to re-use current params
  }),
  "*"
);

postMessage Reference

All messages are JSON-stringified.

Parent -> iFrame:

• CLIO_REFRESH_SESSION — Requests a session refresh. Payload: { type: "CLIO_REFRESH_SESSION", sessionToken: "..." }. The sessionToken field is optional (string or null).

iFrame -> Parent:

• CLIO_SESSION_REFRESHED — Session was refreshed successfully. Payload: { type: "CLIO_SESSION_REFRESHED" }.

• CLIO_SESSION_REFRESH_ERROR — Session refresh failed. Payload: { type: "CLIO_SESSION_REFRESH_ERROR", error: "..." }.

---

Step 2: Customization Options

The Web SDK provides several customization options to align the chatbot with your branding:

• Custom Logo — Replace the default Clio logo with your own branding in the Ask Clio middle office.

• Custom Sizing — The is_wide=true parameter is optional; remove it if you prefer the default layout.

• Custom Colors & Fonts — Background colors, fonts, and other styling options can be configured in the Ask Clio middle office.

For help configuring these options, contact our support team at [e-mail].

---

Step 3: Final Verification

To verify your integration:

1. Open the iFrame or load the floating widget.

2. Interact with the chatbot.

3. Confirm that tools execute correctly (including any Dynamic Inputs or clearing integrations, if applicable).

4. If using session refresh: start anonymous, call refreshSession() with a token, and confirm the session upgrades without a page reload.

Hint: If multiple users are seeing the same chat history, it is usually due to browser session state or reused user.id:

1. Test in Incognito / Private Mode (or a separate browser profile) to rule out cached widget state.

2. Ensure you are not logged into the Ask Clio workspace/admin UI (app.askclio.ai) in the same browser profile as the embedded SDK.

3. Confirm each end user gets a unique user.id in the token request. If two users share the same user.id, Ask Clio will correctly restore the same conversation.

Testing in the Ask Clio Dashboard (Important)

Note when testing inside the Ask Clio dashboard (middle office):

When you are logged into the Ask Clio workspace and testing chats directly in the dashboard UI, Ask Clio will use the currently logged-in workspace user as the effective user.id.

As a result:

• All chats started from the dashboard will share the same chat history for that workspace user

• This applies even if you pass a session token (st) with a different user.id

• Clearing account IDs and Dynamic Inputs are still respected for tool execution, but chat history will appear consolidated

This behavior is expected and intended for admin and testing workflows.

For accurate end-user testing, we recommend:

• Testing via your embedded SDK (web or mobile)

• Or using an incognito/private browser window

• Or ensuring you are logged out of the Ask Clio dashboard when testing

---

Next Steps

Once verified, your Clio chatbot is live and ready to assist your users.

If you encounter any issues or have questions about session tokens, Dynamic Inputs, or clearing integrations, contact [e-mail] for additional help.