Assistant

Overview

The assistant lets your users ask questions about the dashboard in front of them, about one card, or about any data they can reach, and get answers in plain words. Every answer runs under the user's own access: the same row and column policies, semantic domain access and permissions as the dashboard itself.

Your users can:

• Ask about a dashboard or one card. From a card's ··· menu, Ask starts from exactly what that card shows, with its filters, inputs and comparisons.
• Pick up where they left off. In full page, the conversations of the last 24 hours are listed and can be reopened and continued.
• Choose where it sits. Docked right, docked left, centered over the dashboard, or full page. The choice is remembered in their browser.
• Add a source. Bring a semantic dataset, or a connection, into the conversation with Add source. Only the datasets and connections the user may use are offered.

Turning it on

The assistant shows when all of these are true:

1. The project allows it. In Project settings, the AI features and Assistant switches are on (they are on by default).
2. The token enables it. Your backend mints the token with config.assistant.enabled: true.
3. The token names a user. An end user (endUserId) or an organization user. A token for a whole tenant, without a user, gets no assistant, because conversations belong to a person.

When any of these is false, the assistant does not appear at all: no button, no Ask item, and no panel.

Token options

Pass the assistant's options under config.assistant in the token request.

const requestBody = {
  type: 'project',
  projectId: PROJECT_ID,
  projectSecret: PROJECT_SECRET,
  endUserId: 'user_123',
  rcls: [{ name: 'account_rows', params: { account: 'acme' } }],
  config: { 
    assistant: { 
      enabled: true, 
      name: 'Acme Insights', 
      layout: 'docked-right', 
    }, 
  }, 
};

const response = await fetch(TOKEN_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(requestBody),
});

Where it appears

• The dashboard toolbar. The assistant's button sits in the toolbar. In an iframe embed, show the toolbar with showControls=true; in React, with the showControls prop.
• A card's ··· menu. Ask opens the assistant about that card, with or without the toolbar.
• Your own interface (React). Mount AssistantProvider above your toolbar and the dashboard, with the same token, and place AssistantToolbarButton wherever you like, or call toggle() from useAssistant() on your own button.

import { AssistantProvider, AssistantToolbarButton, Surfboard } from 'react-semaphor';

function AnalyticsPage({ authToken }) {
  return (
    <AssistantProvider authToken={authToken}>
      <header>
        <AssistantToolbarButton />
      </header>
      <Surfboard authToken={authToken} />
    </AssistantProvider>
  );
}

In full page, the assistant fills the dashboard's area inside your page or iframe, so your own navigation stays in place.

What it can reach

The assistant uses the same governed tools as the MCP server, under the user's access:

• Semantic datasets in the domains the user may open. A token limited with semanticDomainAccess keeps the assistant, and Add source, to those domains.
• SQL on your connections' tables for organization users with the Author role or above, and for end users. Their row and column policies apply to every query. A token limited to some semantic domains does not browse direct tables.

Conversations belong to one user with one set of access. If a user's policies or security parameters change, their earlier conversations are no longer shown or continued, and a new history starts.