​
Intro

You can pass 2 types of data to your AI on your website:

  1. User data (e.g. your customer’s email, name, ID) in a simple JSON format

  2. Custom instructions for the AI to follow (in addition to the instructions configured via our dashboard on the Personality page)

Both of these will appear in the dashboard (on the Inbox page) for your agents to see. Both of these will be passed to your AI to help it generate relevant responses to your user.

​
Demo

We prepared a demo environment that shows you an example implementation: Demo: Personalization API | StackBlitz.

​
How to pass data

You will pass data through the Molin AI widget. The widget is either installed automatically (if your platform uses our plugin, e.g. Shopify, UNAS, Shoprenter) or it is embedded manually (if you use a custom platform).

The snippet for manually embedding the widget looks like this:

<script type="module" src="https://widget.molin.ai/shop-ai.js?w=YOUR_WIDGET_ID"></script>

You can always find yours on the Publish page in our dashboard.

Simply include your data in a <script> tag, placed anywhere inside the <head></head> section of your website:

<script>
window.molinSettings = {
  userData: {
    user_id: 'u123',
    name: 'John Doe',
    email: 'john@doe.com',
    created_at: '2021-01-01T00:00:00Z',
  },
  customInstructions: `
The user's most recent order ID is 12345. The total amount was 25.90 USD.
They are not eligible for new customer discounts, so do not recommend any.
`,
};
</script>

When the widget loads, it will automatically read the data from window.molinSettings.

Using this method, you must ensure that the <script> snippet above exists inside the <head></head> section of your website before the browser emits the load event. Ideally, it should be rendered on the server.

​
Option 2. Inject directly into the component (advanced)

If you manually render the custom components <molin-shop-ai> or <molin-shop-ai-chat>, you can assign data programmatically:

// using properties (preferred)
const el = document.querySelector('molin-shop-ai');
el.userData = { name: 'John Doe' };
el.customInstructions = `Never give this user a coupon code.`;

// using attributes
const el = document.querySelector('molin-shop-ai');
el.setAttribute('user-data', JSON.stringify({ name: 'John Doe' }));
el.setAttribute('custom-instructions', `Never give this user a coupon code.`);

Pay attention to the type of each property: userData is an object, customInstructions is a string. Please see below the data format section.

​
Data formats

​
User data

You must pass user data as a stringified JSON object. Only primitve types are allowed, no nested objects or arrays.

The user data must satisfy this TypeScript type:

type XUserData = {
  [x: string]: string | number | boolean | null;
};

And this valibot schema:

const xUserDataSchema = v.record(
  v.string(),
  v.union([ v.string(), v.number(), v.boolean(), v.null() ])
);

This is an example of valid user data:

{
  "user_id": "u123",
  "name": "John Doe",
  "email": "john@doe.com",
  "created_at": "2021-01-01T00:00:00Z"
}

This is an example of bad user data (it contains nested objects/arrays):

{
  "user": {"id": "u123"},
  "names": ["John", "Doe"]
}

​
Custom instructions

You must pass custom instructions as a string, in plain text or markdown.

The minimum length is 1 character and the maximum is 5000 characters. If you pass an empty string, the attribute will be ignored.

​
Data persistence

Molin’s client side widget remembers the most recently active conversation. If you inject user data or custom instructions, they will be remembered for the duration of the conversation. Therefore, it is mandatory to reset the widget when the user logs out:

if (window.Molin) {
  window.Molin.reset();
}

​
Security

​
Data handling

You must understand how user data and custom instructions are handled by Molin:

  1. Both are stored in our database, encrypted at rest and in transit.

  2. Both are visible to your agents in the dashboard. Verify the Settings > Members page in our dashboard to check who has access to view this data.

  3. Both are shown to the LLM we use to generate AI responses. Assume that this data can be shown to the user in its entirety, even if the AI is usually smart enough to only disclose the specific information the user is asking for.

​
Protection against session reuse

You must ensure that you reset the widget when the user logs out. This is to prevent the next user from seeing the previous user’s data when continuing the conversation. See Data persistence.

Custom Actions APIShow/Hide Widget