System tools for Product Recommendations

  • Updated

System tools are built-in features that help Optimizely Opal take action. Each tool performs a specific task, such as creating a campaign, uploading files, or generating images. Think of tools like attachments on a Swiss Army knife. Each one has a distinct purpose that helps you get work done.

In addition to the system tools available in Opal, Optimizely Product Recommendations includes a set of system tools designed to help you improve your recommendations.

You can ask Opal what tools it has at any time. For example, enter "Please list the tools you have with a brief description of what they do and the parameters" into Opal Chat.

Click a tool's name to expand it and learn when to use it, its required and optional parameters, and example prompts to calling the tool. If you do not provide a required parameter, Opal prompts you for it.

System tools for Product Recommendations are in beta. Contact your Customer Success Manager for information.

Site and environment management

These tools help you set up and manage your high-level workspace, including selecting the active site, regional settings, and foundational configurations.

pr_get_sites – Retrieves the available sites for your organization.
  • When to use
    • To see a list of all sites you have access to.
    • To select a site to work with before performing other actions like creating pages or widgets.
    • At the beginning of a session to set the context to a specific site.
  • Parameters
    • None
  • Example prompts
    • List all my sites.
    • Show me the available sites.
    • Which sites can I access?
pr_switch_site – Switches the active site context.
  • When to use
    • To change the active site you are working on.
    • When you need to perform actions on a different site than the one currently selected.
    • To ensure subsequent commands are executed against the correct site.
  • Parameters
    • None
  • Example prompts
    • Switch to the 'My Test Site' site.
    • I want to work on the 'Staging Environment' site now.
    • Change the site to 'Production'.
pr_get_locations – Retrieves a list of locations or regions from a specified server and site.
  • When to use
    • Retrieve available geographic locations or regions configured for a specific site.
    • Fetch a list of store locations or delivery areas from the server.
    • Get location data to set up location-based personalization or targeting.
  • Parameters
    • serverUrl – The URL of the server to query for locations.
    • site – The specific site identifier or name to fetch locations for.
  • Example prompts
    • Get the locations for the site "main-store" from the server "https://api.optimizely.com".
    • Can you fetch the available regions for site "eu-region" using server URL "https://eu.api.optimizely.com"?
    • I need to see all the locations configured on "https://test.optimizely.com" for the "beta-site".
pr_get_currencies – Retrieves all available currencies for a site.
  • When to use
    • To find out the default currency for the site's reports.
    • To see a list of all supported currencies for reporting.
    • When you need to specify a currency for an order report.
  • Parameters
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • What currencies are available for my site?
    • Show me the list of supported currencies.
    • What is the default currency?
pr_get_channels – Retrieves all available widget channels for a site.
  • When to use
    • To see the list of channels that widgets can be assigned to.
    • When creating a widget and you want to specify a channel other than the default.
    • To understand how your site's channels are configured for recommendations.
  • Parameters
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • List all available widget channels for my site.
    • What channels can I use for a new widget?
    • Show me the channels.

Algorithms and catalog data

These tools help you set up and manage your high-level workspace, including selecting the active site, regional settings, and foundational configurations.

pr_get_algorithms – Retrieves a list of available algorithms for a specific project or environment.
  • When to use
    • View the available recommendation algorithms to configure a new Product Recommendations campaign.
    • Check which algorithms are currently supported or enabled for a specific project.
    • Retrieve algorithm IDs to use in subsequent API calls or tool actions for setting up recommendations.
  • Parameters
    • serverUrl – The URL of the server.
    • site – The name of the site. 
    • (Optional) pageType – Page type to filter algorithms. If you provide, only algorithms compatible with this page type are returned.
  • Example prompts
    • Get the product recommendation algorithms for the 'home' page type on the 'eu-store' site using server 'https://api.recs.optimizely.com'.
    • What algorithms are configured for the 'product' page on site 'us-main'? The server URL is 'https://recs.example.com'.
    • Can you fetch the algorithms for the 'category' pageType for the 'global' site?
pr_get_algorithm_hints – Retrieves available quick filters (hints) for a specific algorithm.
  • When to use
    • To see what filtering options are available for a particular recommendation algorithm.
    • To understand how you can refine the results of an algorithm. For example, by category or brand.
    • Before creating or updating a widget to know which hints can be applied to its algorithms.
  • Parameters
    • id – The ID of the algorithm.
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • What hints are available for algorithm ID 7?
    • Show me the quick filters for the 'Bestsellers' algorithm.
    • Can I filter the 'Recently Viewed' algorithm? What are the options?
pr_get_attributes – Retrieves specific attributes for product recommendations based on a search term.
  • When to use
    • Fetch specific product attributes (like category, brand, or price) from the Product Recommendations server.
    • Search for available attribute values matching a specific term within a given site.
    • Retrieve configuration or catalog data needed to configure product recommendation campaigns.
  • Parameters
    • serverUrl – The URL of the Product Recommendations server.
    • site – The specific site identifier or name to query the attributes from.
    • (Optional) attr – The specific attribute to retrieve or search against (for instance, brand or category).
    • (Optional) term – The search term or keyword used to filter the attributes.
  • Example prompts
    • Get the "brand" attributes matching the term "Nike" from the server at https://pr.example.com for the "US-Main" site.
    • Can you use pr_get_attributes to find the "category" attribute for "shoes" on site "EU-Store" (serverUrl: https://pr-eu.example.com)?
    • I need to retrieve the "color" attributes using the term "blue" from the product recommendations server (https://api.pr.optimizely.com) for site "Global".
pr_get_categories – Retrieves a list of categories based on a search term for a specific site and server.
  • When to use
    • Fetch available product or content categories matching a specific keyword.
    • Retrieve category data from a specific server URL and site configuration.
    • Look up category identifiers or names to use in subsequent product recommendation API calls.
  • Parameters
    • serverUrl – The base URL of the server to query for categories.
    • site – The specific site identifier or name to retrieve categories from.
    • (Optional) term – The search term or keyword used to filter the categories.
  • Example prompts
    • Get the categories matching the term "shoes" from the site "retail-us" on server "https://api.example.com".
    • Can you find the "electronics" categories for the "global" site using the server URL "https://recommendations.api.com"?
    • I need to retrieve all categories related to "accessories" from the "eu-store" site at "https://api.optimizely.com".
pr_get_product_sets – Retrieves all available product sets for a site.
  • When to use
    • To see the list of product sets that can be used as fallbacks for widgets.
    • When creating a widget and you want to specify a fallback product set.
    • To manage and review the product sets configured for your site.
  • Parameters
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • List all product sets for my site.
    • What product sets can I use as a fallback?
    • Show me the available product sets.

Page and position management

These tools are used to define the layout and scaffolding of your website to prepare it for recommendation widgets.

pr_get_pages – Retrieves all pages for a site.
  • When to use
    • To get a list of all pages where you can place recommendation widgets.
    • To find the ID of a specific page before creating a position or a widget.
    • To see all standard and custom pages available on your site.
  • Parameters
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • List all pages on my site.
    • What pages are available for widgets?
    • Show me the pages.
pr_create_page – Creates a new page within a site.
  • When to use
    • When you need to add a new page to your site for placing recommendation widgets.
    • To create a custom page that is not one of the standard types (like Homepage, Product page, and so on).
    • Before creating a widget if the desired page for it does not exist yet.
  • Parameters
    • name – The name for the new page.
    • serverUrl – The server URL for the site.
    • site – The name of the site where the page is created.
  • Example prompts
    • Create a new page named 'Special Promotions'.
    • I need a new page for our 'Summer Collection' campaign.
    • Add a page called 'Brand Collaborations' to my site.
pr_get_positions – Retrieves the available widget positions for a specific page.
  • When to use
    • To see where you can place a widget on a particular page.
    • To find the ID of a position before creating a widget.
    • To check the available widget slots on a page like the 'Homepage' or a 'Product Detail Page'.
  • Parameters
    • page – The ID of the page.
    • isCustomPage – A boolean indicating if the page is a custom page.
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • What positions are available on the 'Homepage'?
    • Show me the positions for page ID 123.
    • List the widget positions on my custom page 'Special Promotions'.
pr_create_position – Creates a new position on a specific page for placing widgets.
  • When to use
    • To define a new area on a page where a recommendation widget can be displayed.
    • When the existing positions on a page are already in use or not suitable for a new widget.
    • To organize and name different widget locations on a page for clarity.
  • Parameters
    • page – The ID of the page where the position will be created.
    • isCustomPage – A boolean indicating if the page is a custom page.
    • name – The name for the new position.
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • Create a new position named 'Header Banner' on page ID 123.
    • On the 'Homepage', which is not a custom page, add a position called 'Footer Recommendations'.
    • I need a new position for a widget on my custom page with ID 456. Call it 'Sidebar Ad'.

Widget configuration and management

These tools are focused directly on creating, reviewing, and managing the actual recommendation blocks (widgets) shown to the end user.

pr_get_widgets – Retrieves all available widgets for a site.
  • When to use
    • To get a list of all widgets currently configured on your site.
    • To find the ID of a specific widget you want to examine or modify.
    • To get an overview of all recommendation widgets running on the site.
  • Parameters
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • List all widgets on my site.
    • Show me all the recommendation widgets.
    • What widgets are currently active?
pr_get_widget_config – Retrieves the configuration details for a specific widget.
  • When to use
    • To see the detailed configuration of an existing widget, including its name, status, and associated page and position.
    • To check which algorithms are currently being used by a widget.
    • To review a widget's configuration before making changes.
  • Parameters
    • id – The ID of the widget.
    • serverUrl – The server URL for the site.
    • site – The name of the site.
  • Example prompts
    • Show me the configuration for widget ID 3059898.
    • What are the details of the 'Homepage Bestsellers' widget?
    • Get the config for widget 12345.
pr_create_widget – Creates a new recommendation widget. Optimizely currently supports quick filters only. Advanced filters support will be added in a future release.
  • When to use
    • To add a new set of product recommendations to a page.
    • To configure a widget with specific algorithms, a certain number of recommendations, and a fallback product set.
    • To place a recommendation block in a predefined position on a page.
  • Parameters
    • name – The name of the widget.
    • page – The ID of the page where the widget displays.
    • position – The ID of the position on the page for the widget.
    • isCustomPage – A boolean indicating if the page is a custom page.
    • serverUrl – The server URL for the site.
    • site – The name of the site.
    • (Optional) numOfRecs  – The number of recommendations to display.
    • (Optional) alias – An alternate name for the widget.
    • (Optional) channel – The channel ID for the widget.
    • (Optional) fallbackProdSet – The ID of a fallback product set.
    • (Optional) recsExpected – A boolean indicating if recommendations are expected.
    • (Optional) widgetAlgorithms – A JSON string of algorithms to apply.
  • Example prompts
    • Create a new widget named 'Homepage Bestsellers' on the 'Homepage' in the 'Main Content' position.
    • I want to create a widget on the 'Product Detail Page' in the 'Cross-sell' position. It should show five recommendations.
    • Add a new widget called 'Recently Viewed' to the 'Sidebar' on page ID 789. Use the 'Recently viewed' algorithm.

Reports and performance analytics

These tools help you analyze the success, engagement, and revenue impact of your product recommendation.

pr_get_order_report – Retrieves order reports for a specified date range.
  • When to use
    • To analyze the performance of product recommendations over a period.
    • To see how much revenue is being generated by Optimizely Product Recommendations.
    • To compare total orders, revenue, and products sold with those influenced by recommendations.
  • Parameters
    • serverUrl – The server URL for the site.
    • site – The name of the site.
    • startDate – The start date for the report (DD-MM-YYYY).
    • stopDate – The end date for the report (DD-MM-YYYY).
    • currency – The currency for the report.
    • (Optional) page – The page number for pagination.
    • (Optional) size – The number of items per page.
    • (Optional) sortBy – The field to sort the results by.
  • Example prompts
    • Show me the order report for last month.
    • Generate an order report from January 1st to today, sorted by revenue.
    • I need the order report for the past seven days in USD.
pr_get_products_report – Retrieves a products report based on specified criteria such as date range, location, and sorting preferences.
  • When to use
    • Generate a report of product performance over a specific date range.
    • Retrieve a paginated list of products for a specific site or location.
    • Analyze product data sorted by specific metrics (e.g., revenue, views) in a given currency.
  • Parameters
    • site – The name of the site.
    • startDate – The beginning date for the report's time period in DD-MM-YYYY format. For example: 20-11-2025
    • stopDate – The ending date for the report's time period in DD-MM-YYYY format. For example: 20-12-2025
    • serverUrl – The server URL or environment endpoint.
    • (Optional) currency – The currency code for revenue metrics. You can get the list of supported currencies using the pr_get_currencies tool. 
    • (Optional) locationId – The identifier for a specific location or region.
    • (Optional) page – The page number for paginated results.
    • (Optional)size – The number of results to return per page.
    • (Optional)sortBy – The metric or field to sort the report by (for example, revenue or clicks).
  • Example prompts
    • Get a products report for site mysite from 2023-01-01 to 2023-01-31 sorted by revenue.
    • Retrieve page 2 of the products report for location loc-123 with a page size of 50.
    • Can you pull the products report in USD currency for the last week?
pr_get_conversion_report – Retrieves a conversion report for a specific site or location within a given date range, letting you filter by traffic, conversion type, and currency, with pagination and sorting options.
  • When to use
    • Generate a report to analyze conversion rates and traffic for a specific website over a defined date range.
    • Retrieve paginated conversion data for a particular physical location or store to evaluate performance.
    • Pull a sorted list of conversions filtered by a specific currency to analyze revenue metrics.
    • Export traffic and conversion metrics for a specific server environment to monitor campaign success.
  • Parameters
    • startDate – The start date for the report's date range in DD-MM-YYYY format. Example: 20-11-2025.
    • stopDate – The end date for the report's date range in DD-MM-YYYY format. For example: 20-12-2026.
    • site – The specific site or website identifier to pull the report for.
    • traffic – Filter by traffic value: high or low.
    • conversion – Filter by specific conversion value: high or low.
    • serverUrl – The server URL to query for the report data.
    • (Optional) locationId – The identifier for a specific physical or logical location.
    • (Optional) currency – The currency code to filter or display revenue data. You can get the list of supported currencies using the pr_get_currencies tool. 
    • (Optional) page – The page number for pagination. Default is 1.
    • (Optional) size – The number of items per page. Default is 10.
    • (Optional) sortBy – The field and direction to sort the report results by.
  • Example prompts
    • Get the conversion report for site optimizely-main from 2025-01-01 to 2025-01-31, sorted by conversions.
    • Pull the conversion data for location loc-123 in USD currency, showing page 1 with a size of 50 records.
    • I need a conversion report showing organic traffic conversions for the last week on server https://api.example.com.
    • Can you fetch the conversion report for the UK site, starting from March 1st to March 8th, and sort it by traffic volume?
pr_get_engagement_report – Retrieves an engagement report for a specific site within a given date range.
  • When to use
    • Retrieve user engagement metrics for a specific site over a defined time period.
    • Analyze engagement data filtered by specific locations or currencies.
    • Fetch paginated engagement reports for dashboard displays, data exports, or performance reviews.
  • Parameters
    • site – The name of the site to retrieve the engagement report for.
    • startDate – The beginning date for the report data in DD-MM-YYYY format. For example: 20-11-2025.
    • stopDate – The end date for the report data in DD-MM-YYYY format. For example: 20-12-2025.
    • serverUrl – The server URL. 
    • (Optional) currency – The currency code for financial engagement metrics. You can get the list of supported currencies using the pr_get_currencies tool.
    • (Optional) locationId – The specific location identifier to filter the report. You can get the list of supported locations using the pr_get_locations tool.
    • (Optional) page – The page number for paginated results.
    • (Optional) size – The number of records to return per page.
    • (Optional) sortBy – The field to sort the report results by.
  • Example prompts
    • Get the engagement report for site 'US-Main' from 2025-01-01 to 2025-01-31.
    • Fetch the first page of the engagement report for location 'NYC', showing 50 results per page sorted by date.
    • Can you pull the engagement metrics for the EU site in EUR currency for last week?
pr_get_pagetype_report – Retrieves a performance report broken down by page type for Product Recommendations.
  • When to use
    • Analyze the performance of Product Recommendations across different page types (for example, home, product, and cart).
    • Retrieve revenue and engagement metrics for specific page types within a given date range.
    • Compare recommendation performance across different sites or locations.
  • Parameters
    • site – The name of the site.
    • startDate – The beginning date for the report's time period in DD-MM-YYYY format. For example: 20-11-2025
    • stopDate – The ending date for the report's time period in DD-MM-YYYY format. For example: 20-12-2025
    • serverUrl – The server URL or environment endpoint.
    • (Optional) currency – The currency code for revenue metrics. You can get the list of supported currencies using the pr_get_currencies tool. 
    • (Optional) locationId – The identifier for a specific location or region.
    • (Optional) page – The page number for paginated results.
    • (Optional)size – The number of results to return per page.
    • (Optional)sortBy – The metric or field to sort the report by (for example, revenue or clicks).
  • Example prompts
    • Get the page type report for site "my-store" from January 1st to January 31st, sorted by revenue.
    • Show me the product recommendations performance by page type for location 123 in USD.
    • Retrieve the first page of the page type report for the EU site, with a size of 50 results per page.

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applications.