alby Context leverages event data from your website to tailor your agent’s interactions to each individual customer. For accurate context, you must implement required behavioral events directly in your codebase.
This guide details the events and expected payload structures to support a developer-friendly integration process to enable alby Context.
When implementing these events to enable alby Context, consider the following:
You need to implement the following JavaScript events to enable Context functionality. These events help alby understand customer behaviors and provide relevant responses.
These events do not fire automatically. You must call each event on your website when these actions occur. The alby snippet should be loaded on each page that one of the events will be fired.
alby Context is automatically enabled once the events are successfully sending to alby. If you need assistance, reach out to [email protected]
The alby Website Integration will log warnings in your browser console if required fields are missing or formatted incorrectly. Check the console for errors during integration or testing.
Avoid firing duplicate events for the same user action.
Never send sensitive or personal data in event payloads.
Event Type Description Required Fields Optional Fields 'AddedToCart'User adds a product to cart variantId,cost,quantityproductId,cartId'Purchase'User completes a purchase orderId,total,items- 'RemovedFromCart'User removes a product from cart variantId,cost,quantityproductId,cartId'Search'User submits a search query,results- 'ViewedCart'User views their cart cost,itemscartId'ViewedCollection'User views a product collection title,itemscollectionId'ViewedProduct'User views a product page productIdvariantId'ViewedVariant'User views a product variant variantId-
JavaScript
// Minimal required fields
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('AddedToCart', {
variantId: '678xyz', // required
cost: { amount: 29.99, currencyCode: 'USD' }, // required
quantity: 2 // required
});
// With optional fields
window.albyEvent.push('AddedToCart', {
variantId: '678xyz', // required
cost: { amount: 29.99, currencyCode: 'USD' }, // required
quantity: 2, // required
productId: 'abc123', // optional
cartId: 'cart_456' // optional
});Field Type Required Description variantId string Yes The unique identifier of the product variant/SKU added to the cart cost object Yes Price info; must contain amount quantity integer Yes Number of this variant added to cart. Must be greater than 0. productId string No ID of the parent/base product cartId string No ID for the current cart/session
Field Type Required Description amount number Yes The numerical price of the item. Must be greater than or equal to 0. currencyCode string No Defaults to ISO currency code USD
JavaScript
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('Purchase', {
orderId: 'order_789', // required
total: { amount: 59.98, currencyCode: 'USD' }, // required
items: [ // required
{
productId: 'abc123',
variantId: '678xyz',
quantity: 2,
cost: { amount: 29.99, currencyCode: 'USD' }
}
]
});Field Type Required Description orderId string Yes The unique identifier of the order made in the purchase event cost object Yes Price info; must contain amount items array of objects Yes List of purchased items, each with productId, variantId, quantity, and cost
Field Type Required Description productId string Yes ID of the parent/base product variantId string Yes Unique variant/SKU identifier quantity integer Yes Number of units of this variant purchased. Must be greater than 0. cost object Yes Price info; must contain amount
Field Type Required Description amount number Yes The numerical price of the item. Must be greater than or equal to 0. currencyCode string Yes Defaults to ISO currency code USD
JavaScript
// Minimal required fields
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('RemovedFromCart', {
variantId: '678xyz', // required
cost: { amount: 29.99, currencyCode: 'USD' }, // required
quantity: 1 // required
});
// With optional fields
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('RemovedFromCart', {
variantId: '678xyz', // required
cost: { amount: 29.99, currencyCode: 'USD' }, // required
quantity: 1, // required
productId: 'abc123', // optional
cartId: 'cart_456' // optional
});Field Type Required Description variantId string Yes Unique identifier of the product variant/SKU removed from the cart cost object Yes The price info; contains amount quantity integer Yes Number of units of this variant removed from cart. Must be greater than 0. productId string No ID of the parent/base product cartId string No Identifier for the current cart/session
Field Type Required Description amount number Yes The numerical price of the item. Must be greater than or equal to 0. currencyCode string Yes Defaults to ISO currency code USD
JavaScript
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('Search', {
query: 'running shoes', // required
results: [ // required
{ productId: 'shoe1', variantId: 'var1' },
{ productId: 'shoe2', variantId: 'var2' }
]
});Field Type Required Description query string Yes The text string the user searched for results array of objects Yes Array of search result items (see fields below)
Field Type Required Description productId string Yes Product identifier for the result item variantId string Yes Variant/SKU identifier for the result item
JavaScript
// Required fields only
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('ViewedCart', {
cost: { amount: 89.97, currencyCode: 'USD' }, // required
items: [ // required
{
productId: 'abc123',
variantId: '678xyz',
cost: { amount: 29.99, currencyCode: 'USD' },
quantity: 2
},
{
productId: 'def456',
variantId: '789abc',
cost: { amount: 29.99, currencyCode: 'USD' },
quantity: 1
}
]
});
// With optional cartId
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('ViewedCart', {
cost: { amount: 89.97, currencyCode: 'USD' }, // required
items: [ // required
{
productId: 'abc123',
variantId: '678xyz',
cost: { amount: 29.99, currencyCode: 'USD' },
quantity: 2
}
],
cartId: 'cart_456' // optional
});Field Type Required Description cost object Yes Total price of all items in the cart; object with amount items array of objects Yes Array of cart item objects, each representing an item in the cart cartId string No Identifier for the cart/session (optional)
Field Type Required Description productId string Yes ID of the parent/base product variantId string Yes Unique identifier for the product variant/SKU cost object Yes Price info of the item; object with amount quantity integer Yes Number of units of this item in the cart
Field Type Required Description amount number Yes The numerical price of the item. Must be greater than or equal to 0. currencyCode string Yes Defaults to ISO currency code USD
JavaScript
// Minimal required fields
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('ViewedCollection', {
title: 'Summer 2025 Collection', // required
items: [ // required
{ productId: 'summer1', variantId: 'var1' },
{ productId: 'summer2', variantId: 'var2' },
{ productId: 'summer3', variantId: 'var3' }
]
});
// With optional collectionId
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('ViewedCollection', {
title: 'Summer 2025 Collection', // required
items: [ // required
{ productId: 'summer1', variantId: 'var1' },
{ productId: 'summer2', variantId: 'var2' },
{ productId: 'summer3', variantId: 'var3' }
],
collectionId: 'summer-collection' // optional
});Field Type Required Description title string Yes Name of the collection viewed items array of objects Yes Array of item objects in the collection (see structure below) collectionId string No Identifier for this collection (optional)
Field Type Required Description productId string Yes Product identifier in the collection variantId string Yes Variant/SKU identifier for the item
JavaScript
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('ViewedProduct', {
productId: 'abc123', // required
variantId: '678xyz' // optional
});Field Type Required Description productId string Yes Unique identifier for the viewed product variantId string No Identifier for the viewed variant/SKU
JavaScript
window.albyEvent = window.albyEvent || [];
window.albyEvent.push('ViewedVariant', {
variantId: '678xyz' // required
});Field Type Required Description variantId string Yes Unique identifier for the viewed product variant/SKU
