Last updated: 16/06/2025

​
Best practices

​
1. Ensure responsiveness for mobile devices

To guarantee optimal responsiveness and prevent the agent UI text from appearing too small on mobile devices, include the following HTML tag within the <head> section of your webpage:

<head>
     <meta name="viewport" content="width=device-width, initial-scale=1">
</head>

This meta tag ensures proper scaling and a good user experience across various devices.

​
2. Control embedded agent UI dimensions

You can manage the size and position of the agent UI by passing parameters to its style attribute. If necessary, you can also wrap the <mindset-agent> tag within a parent <div> container.

For example:

<mindset-agent
    agentUid="1rLosTJfVV0Ew9FPDfB7"
    style="width: 80%; height: 100%; display: block;">
</mindset-agent>

​
3. Customize embedded agent UI appearance

The <mindset-agent> tag allows for customization of the following:

  • Agent UI Width
  • Agent UI Height
  • Agent UI Background Color: This is only visible for a few milliseconds while the UI loads completely.

Example with background color:

<mindset-agent
    agentUid="1rLosTJfVV0Ew9FPDfB7"
    style="width: 100%; height: 100%; display: block; background-color: tomato;">
</mindset-agent>

You can also apply additional standard CSS parameters as needed:

<mindset-agent
    agentUid="v8srU0hv88BeWBDcirSm"
    style="transition: 0.3s; position: fixed; bottom: 0px; right: 0px; width: 100%; height: calc(100%); margin: 0px; border-radius: 0px; box-shadow: rgba(0, 0, 0, 0.2) 0px 4px 12px; background-color: rgb(255, 255, 255); overflow: hidden; transform-origin: right bottom; transform: scale(1); z-index: 9999; opacity: 1; pointer-events: auto; display: block;">
</mindset-agent>

​
4. Agent UI responsiveness for Videos and Segments

The agent UI is designed to be responsive and will adjust content based on the viewer’s screen size. When video content is played, a “Segment” area allows users to navigate between video segments.

The display of the segment area depends on the screen width:

  • Right of the video: If the screen width is greater than 1056px.
  • Below the video: If the screen width is less than 1056px.

​
5. Agent access granted by Agent Sessions

If you embed your agents and provision the knowledge context through the agent Sessions mechanism and APIs, you have the full control over agents’ access.

For example, as seen in the tutorial, when you create an AgentSession:

POST https://${MINDSET-API-HOST}/api/v1/appuid/${YOUR-APP-UID}/agentsessions
body : {
    agentUid: "v8srU0hv88BeWBDcirSm",
    externalUserId: "user-x123456",
    contextUids: ["qZJGsjytbM5fL15sfBui", "3am8rolEPXx3j0n132Bf"]
}
headers: {
    'Content-Type': 'application/json',
    'x-api-key': YOUR-MINDSET-API-KEY
}

You then give access to the agentUid v8srU0hv88BeWBDcirSm for the user user-x123456 (remember that the externalUserId is also passed to the embed agent SDK via the SDK Users auth API, so the Mindset system recognizes the user accordingly)

In the Agent settings (Mindset app admin), there is an Access tab where two types of access can be set:

  • Open access - all app users
  • Restricted Access - only users with specified account membership

We recommend selecting the restricted access (without assigning any accounts) type because if the agent is restricted, then only users who have been granted access through an agent session will be able to communicate with it.

​
6. Agent access granted by Account membership

Without the agent sessions mechanism, agents access is managed via the SDK users API.

When creating the user session (see authentication), you can specify the accountUids to which the user should be added. This is done by passing the accountUids array in the request body:

POST https://MINDSET-API-HOST/api/v1/appuid/YOUR-APP-UID/sdkusers/auth
body: {
  name: "My User Name", // optional 
  userEmail: "myuser@email.com", // Pass the userEmail if you want to authenticate a user by email as you did previously
  // OR
  externalId: "user-x123456", // Pass the externalId if you want to authenticate a user by externalId
  accountUids: ["accountUid1", "accountUid2"]
},
headers: {
    'Content-Type': 'application/json',
    'x-api-key': YOUR-MINDSET-API-KEY
}

if accountUids are provided, the user will be granted to use the agent only if the agent settings are :

  • Open access - all app users

OR

  • Restricted Access with one of the account selected (accountUid1, accountUid2).

In most cases we recommend using agent sessions so you control the users permissions without managing accounts in your Mindset app admin area.

​
7. Sample code for embedding an agent in a Single Page Application

Below, a sample React component that embeds a Mindset agent:

import React, { useEffect } from "react";

export default function Mindset({ config }) {
    
    async function getAuthToken() {
        const currentUserId = 'session123'
        const userAuthTokenServerUrl = `YOUR-BACKEND-API-RETURNING-AUTHTOKEN`
        // e.g. https://mycompany-backend/api/getusertoken/${currentUserId}

        try {
            const headers = {
                "accept": "application/json",
                "Content-Type": "application/json"
            };
            const response = await fetch(userAuthTokenServerUrl, {
                method: 'POST',
                headers: headers,
                body: JSON.stringify({"currentUserId": `${currentUserId}`})
            });
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            const responseData = await response.json();
            return responseData.authToken;
        } catch (error) {
            console.log('Error fetching auth token:', error);
            throw error;
        }
    }

    function mindsetAgentInit() {
        if (window.mindset && typeof window.mindset.init === 'function' && !window.__mindsetInitCalled) {
            window.mindset.init({
                fetchAuthentication: getAuthToken,
                appUid: config.YOUR-APP-UID
            });
            window.__mindsetInitCalled = true;
        }
    }

    function mindsetSDKscriptLoad(scriptId) {
        const script = document.createElement('script');
        script.src = config.mindsetSdkUrl;
        script.id = scriptId;
        script.async = true;
        script.onload = () => {
            mindsetAgentInit()
        };
        document.body.appendChild(script);
    }

    useEffect(() => {
        const scriptId = 'mindset-sdk2-script';
        if (!document.getElementById(scriptId)) {
            mindsetSDKscriptLoad(scriptId)
        } else {
            mindsetAgentInit()
        }
    }, [config]);

    return (
        <mindset-agent 
            agentUid={config.YOUR-AGENT-UID}
            style={{
                width: '100%',
                height: '600px', 
                display: 'block',
                backgroundColor: rgb(255, 255, 255)
            }}
        ></mindset-agent>
    );
}

​
Limitations

​
1. Single agent per page

Our current implementation still limits the number of agents per page to one. We are working to remove this limitation and will let you know as soon as it is lifted.

​
2. Supported Google fonts

When using a google font for customizing the agent UI, we do not support 100% of the Google fonts available in that offical list: Google Fonts.

We support most of them, but to ensure the font you want to use is supported, please check that Font list: Supported Google Fonts.

The font name to use in the fontFamily parameter must be the font name displayed in that Google fonts list.

For example:

const myCustomFontTheme = {
    fontFamily: 'Google Sans 3'
}