IMPORTANT: This feature is available in private preview mode and accessible only on selected workspaces. To get access, contact your account manager or Synerise Support.
The quality of the assistant's answers depends on what it knows about the situation: who the customer is, which product they are looking at, and what was said earlier in the conversation. This article explains where each piece of context comes from, what you can add from your website, and how to let customers continue a conversation later.
The examples use the options of the init() function. In the React package, the same options are props of the AIAssistant component. See AI Assistant SDK.
Who the assistant is talking to
The chat takes the visitor's identity from the Synerise tracking code - the same UUID that identifies the visitor in every other Synerise feature - and sends it with each message. This is what makes the assistant's answers personal and what saves every conversation as events on the profile. You do not have to pass any customer data yourself. See Customer identification.
A conversation belongs to the identity that started it. When the identity changes - the customer logs in and the anonymous profile is merged with a recognized one, logs out, or clears cookies - earlier conversations cannot be continued under the new identity. If your website tries to resume one, the chat reports that the conversation is no longer available and offers to start a new one.
TIP: If your website remembers a conversation to resume it later, store the conversation ID together with the customer's UUID and discard it when the UUID changes. See Returning to earlier conversations.
The product the customer is looking at
When a customer opens the chat on a product page, questions like "Is this waterproof?", "Do you have it in blue?", or "Show me something cheaper" only make sense if the assistant knows which product "this" is. The chat can pass this information with every message, in two ways.
Automatic detection from Open Graph tags
If your product pages carry the Open Graph tags used by Synerise, the chat can read the product on its own. It needs two tags:
<meta property="og:type" content="product" />
<meta property="product:retailer_part_no" content="SKU-12345" />
- The
og:typetag must containproductorproduct.itemas its value. Pages markedproduct.group(a parent of several variants) are ignored on purpose, because their ID does not point to a single item in your feed. product:retailer_part_nomust contain the item ID that you mapped to theitemIdattribute in the Products section of the assistant configuration. If the IDs differ, the assistant cannot find the product.
Enable the detection with one option:
init({
rootElementId: "synerise-assistant",
autoDetectPageContext: true,
});
The chat reads the tags when it is initialized and keeps watching them, so single-page applications that update the tags on navigation (with libraries such as react-helmet, next/head, or vue-meta) are handled without extra code. If your application does not update the tags between pages, set the product manually instead.
Setting the product manually
Your code can tell the chat which product is on the page and clear it when the customer leaves:
const chat = init({ rootElementId: "synerise-assistant" });
// When a product page is shown:
chat.setPageContext({ pageType: "product", itemId: "SKU-12345" });
// When the customer navigates to a page that is not a product page:
chat.setPageContext(null);
You can also pass the initial product in the pageContext option when you initialize the chat. Only pageType: "product" is supported today.
IMPORTANT: Choose one method - automatic detection or manual setting - and stick with it. As soon as you use either of them, it takes precedence over any page_context value you might place in additionalContextValues yourself.
Additional business context
Beyond the product, you can send any information that helps the assistant or your analytics: the store language or country, the current currency, a segment or loyalty tier, an A/B test variant, or whether the customer is logged in. Two options carry it:
context- information that scopes the conversation, for example the store and language.additionalContextValues- extra metadata, for example segment IDs or experiment flags.
const chat = init({
rootElementId: "synerise-assistant",
context: { store: "pl", language: "pl-PL", currency: "PLN" },
additionalContextValues: { loyaltyTier: "gold", abVariant: "B" },
});
// Later, when something changes:
chat.setAdditionalContextValues({ loyaltyTier: "gold", abVariant: "B", loggedIn: true });
Both objects are sent with every message. Synerise records contextual key/value pairs of each turn in the context parameter of the assistant.responseGenerated event, so you can compare conversations by them in analytics. See Measuring the Customer AI Assistant.
NOTE: Do not send personal data such as names or e-mail addresses in the context. The assistant already knows the profile through the UUID, and the context is stored with the conversation events.
Sending a message on the customer's behalf
Your website can open the chat with a question already asked. A typical use is a button on the product page such as "Ask the assistant about this product":
document.getElementById("ask-about-product").addEventListener("click", () => {
chat.open();
chat.message("Tell me more about this product and what goes with it.");
});
The message is sent exactly as if the customer had typed it and appears in the conversation.
Returning to earlier conversations
The assistant keeps the full context within a conversation. Your website can also let customers come back to a conversation later - after a page reload, on another page, or on the next visit. Past conversations are available for up to two weeks.
The chat does not display a history list. It gives your website the building blocks and you decide where a "Your conversations" list or a "Continue" button appears:
| Building block | What it does |
|---|---|
onMessage callback |
Runs after every answer with response.meta.threadId, the ID of the current conversation. Save it to resume later. |
threadId option |
Initializes the chat with an existing conversation loaded instead of starting a new one. |
chat.loadThread(threadId) |
Replaces the conversation shown in the chat with an earlier one. |
chat.getConversations() |
Lists the customer's conversations with their date and an automatically generated title, so you can render a picker. |
onConversationTitle callback |
Runs when Synerise generates the title of the current conversation (streaming only). Use it to refresh your list. |
Example: continue after a page reload
const key = `synerise-assistant-thread:${SyneriseTC.uuid}`;
const chat = init({
rootElementId: "synerise-assistant",
stream: true,
threadId: sessionStorage.getItem(key) ?? undefined,
onMessage: ({ meta }) => sessionStorage.setItem(key, meta.threadId),
});
The key includes the customer's UUID, so a conversation is never resumed under another identity.
Example: a list of past conversations
const list = document.getElementById("assistant-history");
const conversations = await chat.getConversations();
conversations
.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt))
.forEach((conversation) => {
const item = document.createElement("li");
item.textContent = conversation.title || conversation.summary || new Date(conversation.createdAt).toLocaleDateString();
item.onclick = () => chat.loadThread(conversation.threadId);
list.appendChild(item);
});
When a conversation is no longer available
If the conversation has expired, was started under another identity, or does not exist, the chat shows a message and a Start new conversation button. Clicking it starts a fresh conversation without any action on your side. Remove the stored ID at this point, so the customer is not sent to the same missing conversation again.
Starting a new conversation
Every initialization without a threadId starts a new conversation. To offer a "New conversation" action on your website, remove the chat and initialize it again in the same container:
chat.unmount();
chat = init({ rootElementId: "synerise-assistant", stream: true });
chat.open();