Conversational Commerce agent developer's guide

This guide details how to integrate with the Conversational API to provide dynamic, AI-powered chat experiences for your customers. By understanding different query types and leveraging the API's responses, you can deliver relevant product searches, answer your customer inquiries, and guide your end-users through their shopping journey.

The conversationalFilteringMode in the Conversational API makes the differences clear between Conversational Commerce agent and conversational product filtering.

Setup

The Conversational API supports the Conversational Commerce agent feature:

• gRPC: conversationalSearchService
• REST: conversationalSearch

The Conversational API enables a chat experience where your users send queries and the system returns a text response, classified query types, and potential refined search options.

This API operates as a streaming service, allowing for early detection of query intent. Subsequent interactions in the conversation require attaching a conversation_id.

For returning search results, the legacy Retail API must be called in parallel to the Conversational API.

Send a query from the end-user

This section describes how to initiate a Conversational Commerce agent experience. For example, your user might enter Help me plan a party in the search field.

Send a request to Vertex AI Search for commerce

There are two different API endpoints:

1. The Conversational API must be used to fetch the conversational experience.
2. The core Search API must be used to fetch search results.

Endpoint 1: Conversational API request

• You should create a Conversational Commerce agent request by setting your user's input as the query.
• The request should be sent as an HTTP POST request to the projects/*/locations/*/catalogs/*/placements/*:conversationalSearch endpoint.

  POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
  

Conversational API request:

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}

Endpoint 2: Core Search API request

There are two primary approaches for displaying search results in your web interface.

Regardless of the user interface option you choose, when you need to fetch actual product results, you can make a call to the Retail API. For more information, see Understand query types and retailer actions.

    POST https://retail.googleapis.com/v2beta/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search
    

Core product Search API request:

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
    

Understand the response

This code sample demonstrates a response from the Conversational commerce API.

The API response (ConversationalSearchResponse) includes query_types, conversational_text_response (if applicable), refined_search options, and potentially a followup_question or conversational_filtering_result. The conversation_id is essential for continuing the session.

Response from Vertex AI Search for commerce

This code sample demonstrates a Conversational API response:

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }
    

Understand query types and retailer actions

The query_types field in the response is a list indicating the classification(s) of your user's intent. Your system should handle these as follows. Note that conversational_text_response refers to the AI-generated natural language response from the API.

Conversational Commerce agent uses search query categories to determine whether an LLM-based answer is generated and how end-user queries are handled by the Conversational and Search APIs for these scenarios:

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "show me some monster energy drinks",
  "visitorId": "test"
}
    

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9",
  "refinedSearch": [
    {
      "query": "monster energy drinks"
    }
  ]
}
    

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  

  {
    "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
    "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
    "query": "Compare 1% milk with 2% milk",
    "visitorId": "test"
  }
    

{
  "userQueryTypes": ["PRODUCT_COMPARISON"],
  "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.",
  "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba",
  "refinedSearch": [
    {
      "query": "1% milk"
    },
    {
      "query": "2% milk"
    }
  ]
}
  

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "1% milk",
  "visitorId": "test"
}
  

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "Help me plan a party",
  "visitorId": "test"
}
  

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}
  

Show suggested queries for products

This is how to configure Google Search to show questions and product suggestions in Conversational Commerce agent.

When the Conversational API returns refinedSearch queries, these queries represent excellent opportunities to guide the end user towards relevant products. This is particularly valuable for Category 4 (LLM answer-seeking queries) and Category 5 (INTENT_REFINEMENT).

Recommendation

• Display: Present the top N (1-3, pending testing on the ideal number for your web interface) refinedSearch queries to your user.
• Mechanism: These suggested queries should be run through the core Search API (SearchService.Search) in the background or upon user interaction.
• Presentation: Show the results as interactive carousels or clickable cards, letting your user browse related product categories or specific items. This provides immediate value and helps bridge the gap between conversational interaction and product discovery.

Search API request:

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}
  

Events to send to Vertex AI Search for commerce

It's important to accurately attribute search queries to conversational interactions and use full analytics capabilities within Vertex AI Search for commerce using proper event tagging:

1. Retrieve conversation_id. When you make a conversationalSearch API call, the ConversationalSearchResponse.conversation_id is returned.
2. Tag user events. In cases where the conversational response leads to a search query, such as by displaying a refined_search suggestion that the end user then clicks, or if your system automatically executes a search based on the refined query, you must tag that subsequent search user event (UserEvent) with the same conversation_id received in the ConversationalSearchResponse.

By correctly tagging UserEvent.conversation_id, your analytics can accurately attribute search queries to the preceding conversational interactions, providing valuable insights into user behavior and conversion paths.

Continue the conversation

This section describes how Conversational Commerce agent sessions are maintained by the Conversational API and continue in this final step.

The Conversational API uses a conversation_id to manage ongoing conversations. To ensure consistency between LLM answers and search results, subsequent Conversational API requests must include SearchParams that mirror the configuration of the core Search API calls.

placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
query: "Help me plan a party"
conversational_filtering_spec {
  conversational_filtering_mode: ENABLED
}
visitor_id: "test"

user_query_types: "INTENT_REFINEMENT"
conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake."
followup_question {
  followup_question: "What kind of party are you planning?"
}
conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb"
refined_search {
  query: "Decorations"
}

placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb"
query: "Help me plan a party"
conversational_filtering_spec {
  conversational_filtering_mode: ENABLED
}
visitor_id: "test"

user_query_types: "INTENT_REFINEMENT"
conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake."
followup_question {
  followup_question: "What kind of party are you planning?"
}
conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb"
refined_search {
  query: "Decorations"
}

placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb"
query: "Help me plan a party"
conversational_filtering_spec {
  conversational_filtering_mode: ENABLED
}
visitor_id: "test"
search_params {
  filter: "filter"
  canonical_filter: "canonical_filter"
  sort_by: "sort_by"
  boost_spec {
    condition_boost_specs {
      condition: "condition"
    }
  }
}
  

Session handling

• Start a new conversation:
  • Description: To begin a new conversation, the client omits the conversationId from the API request.
  • When to start a new conversation: A client would want to initiate a new conversation — thereby getting a fresh conversationId from the API response — in several common user experience scenarios:
    • New tab or session: When a customer opens your site in a new browser tab or starts a completely new session.
    • New original query: In some UX designs, if a customer enters a new, unrelated query, you might choose to restart the conversational flow to ensure the most relevant context.
    • Restart conversation button: If your web interface provides an explicit Start new chat or Reset conversation button, clicking this would trigger a new conversational session.
  • Conversational API integration: The API response includes a new conversationId that is used for subsequent requests.
• Continue the Conversation:
  • Description: The Conversational API returns a conversation_id as part of the API response. This ID must be sent in follow-up requests to continue the same conversation. This helps to ensure that Conversational Commerce agent responds to your user's queries based on the conversation history within that session, covering the end-user query, the conversational_text_response, and the followup_question.
  • Conversational API integration: The client passes the conversation_id from the previous response in the ConversationalSearchRequest.
• Ensure search result consistency:
  • Description: To help ensure the LLM answers are consistent with the search results shown to your user, the client must use searchParams in the Conversational API request. These search parameters should have the same configuration, such as filters, sort order) as the Search API calls made to retrieve product results.
  • Conversational API integration: The searchParams object within the ConversationalSearchRequest should be populated identically to the SearchRequest used for core product search.

Send a request to Vertex AI Search for commerce

You can retrieve the conversation_id from session storage. The request should include the new customer query, which might be a reply to the question from the previous response. The request should also include the most recent refined_search.query from the previous response if the end user is acting on a refined query. Otherwise, it should include a completely new and unrelated query, and the conversationId. Remember to always include consistent searchParams.

• Scenario 1: Single search bar and persistent conversation: If your search interface has only one main search bar or a persistent conversational window, you won't reset the conversationId, even if the end user types a new, seemingly unrelated query. The system uses the existing conversation history (tied to the conversationId) to provide contextually relevant responses.
• Scenario 2: Separate conversation window and query window: If your search interface features a distinct conversational chat window and a separate, standard search query bar (such as a site-wide search box), entering a new query into the standard search bar might implicitly signal an intent to start a new, unrelated search, thus potentially leading to the conversationId being reset for that specific search action. However, within the dedicated conversational window, the conversationId should always be maintained for continuity.

Ultimately, the decision on when to reuse versus reset the conversationId is a design choice to optimize the conversational experience for your customers.

POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
    

Conversational API request:

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}
  

Conversational API response:

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}
  

Examples of an end user continuing to receive questions:

• User question: Help me plan a party.
• System answer: What kind of party are you planning?
• User reply: A birthday party.

What retailers should do with the response

The way to render fields is similar to the initial response, but note the changes reflecting the continued conversation:

• refined_search: This field contains updated query(s) that incorporate the end user's latest input. You should update the client console for the current query correspondingly (such as showing the user-facing query having changed from "decorations" to "birthday party decorations" or "birthday party supplies"). The refined_search queries can be used for calls to the core Search API (SearchService.Search) or can also be displayed to the end-user as suggestions.
• conversational_text_response: Display the new AI-generated text response relevant to the latest turn.
• followup_question: If the conversation needs to continue for further refinement, a new followup_question is provided.

Events to send to Vertex AI Search for commerce

Event tagging is important to accurately attribute search queries to conversational interactions and to use the analytics capabilities in Vertex AI Search for commerce.

There are two steps in the process of event tagging:

1. Retrieve conversation_id. When you make a conversationalSearch API call, the ConversationalSearchResponse.conversation_id is returned.
2. Tag user events. In cases where the conversational response leads to a search query, such as by displaying a refined_search suggestion, or if your system automatically executes a search based on the refined query, you must tag that subsequent search user event (UserEvent) with the same conversation_id received in the ConversationalSearchResponse.

By correctly tagging UserEvent.conversation_id, your analytics can accurately attribute search queries to the preceding conversational interactions, providing valuable insights into end-user behavior and conversion paths.

Integrate the agent with conversational product filtering

This guide outlines how to integrate with both the Conversational API and conversational product filtering to provide an AI-powered shopping experience. When conversationalFilteringSpec.mode is set to ENABLED, your system can directly transition between open-ended conversational interactions and guided product filtering, offering a highly refined user journey.

Understand the interplay

When both conversational commerce agent and conversational product filtering are enabled, the system leverages the strengths of each. Conversational Commerce agent handles broad inquiries, provides AI-generated responses, and refines initial intents, while conversational product filtering guides users through specific product attribute selections using a simplified chip- or tile-based interaction model.

The point of interaction and potential transition between these two modes occurs when the Conversational Commerce API's classification leads to a product-oriented search, specifically SIMPLE_PRODUCT_SEARCH. At this point, the API can either provide a direct search query or, if the user's intent can be further refined, it triggers a guided filtering flow through conversational product filtering.

A key principle of this integration is that all free-text input is handled by the Conversational Commerce API, while clicks on suggested answers that appear as chips are handled by conversational product filtering.

Send user query

Example user input: Help me plan a party

To enable both conversational commerce agent and conversational product filtering, ensure that your ConversationalSearchRequest includes this configuration:

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

Initial response: Intent refinement

The userQueryTypes field remains central to understanding the user's intent. For an initial broad query like Help me plan a party, the API will likely classify it as INTENT_REFINEMENT if a more specific product search isn't immediately clear.

Response from Google

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}

Action

1. Display the conversationalTextResponse.
2. Present the refinedSearch suggestions like clickable chips for Decorations, Snacks. Alternatively, call the Commerce Search API in parallel using the refined_search queries to display relevant product results, such as for Decorations, Snacks as a carousel, alongside the conversational exchange.
3. Display the followupQuestion: What kind of party are you planning?
4. Allow free-form user input to progress the conversation.

Event tagging and analytics

To ensure accurate analytics and attribution for the initial conversational interaction:

• Retrieve conversation_id. Capture the conversation_id from the ConversationalSearchResponse. This ID is crucial for linking all subsequent actions to this specific conversational session.
• Tag user events. If the conversational response leads to a search query, such as your system automatically executes a search based on a refined_search query, or if the user clicks a refined_search suggestion, you must tag that subsequent search user event (UserEvent) with the same conversation_id.

Follow-up query

When the user responds to the followupQuestion, the conversation refines.

Example user input: A birthday party

Intent refinement | Code snippets

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Action

1. Similar to the initial response, update the web interface with the new conversationalTextResponse, refinedSearch suggestions, and followupQuestion.
2. Continue the conversation flow, prompting for more detail.

Event tagging and analytics

When the user continues the conversation:

• Retrieve conversation_id. Ensure the conversation_id from the previous ConversationalSearchResponse is passed in the current ConversationalSearchRequest.
• Tag user events. If the conversational response leads to a new search query, such as due to a user clicking a refined_search suggestion or your system making a parallel search call, tag that subsequent search user event (UserEvent) with the same conversation_id. This helps track the multi-turn conversational journey.

Transition to conversational product filtering

As the conversation gets more specific, the system might classify the intent as SIMPLE_PRODUCT_SEARCH, and if suitable, trigger conversational product filtering.

Example user input: Princess theme

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Possible outcomes for core product search

When a query is classified as SIMPLE_PRODUCT_SEARCH, there are two possible API responses, depending on whether Conversational Product Filtering is triggered. The key difference lies in the presence and content of the conversationalFilteringResult field.

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      { "answer": "Balloons", "query": "princess birthday balloons" },
      { "answer": "Streamers", "query": "princess birthday streamers" },
      { "answer": "Tablecloths", "query": "princess birthday tablecloths" }
    ]
  },
  "state": "SUCCEEDED"
}

Continue in conversational product filtering

When the user selects a suggestedAnswer, send a new ConversationalSearchRequest.

Example user input (Clicking a suggested answer): Balloons

Simple product search | Code snippets

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

Action

The API responds with a SIMPLE_PRODUCT_SEARCH query but without the conversationalFilteringResult field, indicating that the guided filtering flow has concluded.

• Use the final refinedSearch query (princess birthday balloons) to make a direct call to the Retail Search API.
• Display the final product results to the user. At this point, the conversation can either end, or the user can enter a new query to start a new turn.

Event tagging and analytics

For each step within the product filtering process:

• Retrieve conversation_id. Always use the same conversation_id for all requests within the filtering session.
• Tag user events. Each user interaction with a suggestedAnswer such as a click, should trigger a relevant UserEvent such as a filter event or a new search event if a new query is formed. This UserEvent must be tagged with the conversation_id to accurately track the filtering journey and its impact on conversion.

User interface recommendations and design choices

The interaction between Conversational Commerce agent and conversational product filtering offers significant flexibility. Here are some key UX considerations for creating a smooth and intuitive experience:

• Single input bar: There should only be one free-text input bar for the entire experience. There is no separate, dedicated input bar for Conversational Product Filtering. This simplifies the user interface and keeps the interaction consistent.
• Seamless transitions: Design your web interface to make transitions between conversational responses, suggested queries, and filtering options feel natural and intuitive.
• Clear guidance: Use visual cues like distinct button styles for suggested answers instead of general input, and clear instructions to guide the user on how to interact at each stage.
• Balancing control: The user should always feel in control of the conversation's direction.
• Filtering vs. free-form: The single free-text input bar remains active at all times. This gives the user a constant choice: they can either click a suggested answer to continue refining their search or type a new query into the text bar to start a new conversational turn. This design ensures that even during a filtering flow, the user can pivot to a different topic if their needs change.
• Reset option: Provide a clear Start new conversation or Reset filters option to allow users to restart their search or filtering process.
• Visual persistence: Even when transitioning to product filtering, maintaining the conversation history within the chat window, such as showing previous questions and answers, can enhance context and user experience.

Additional considerations and best practices

Additional considerations and best practices must be considered when implementing your Conversational Commerce agent interface:

• Visitor ID consistency: Help to ensure that a unique visitor_id is consistently sent with each request for a given end user. This is vital for accurate personalization and model training. This identifier should ideally remain consistent for an end user across sessions and sign in or sign out states.
• Branch management: While default_branch is common, ensure you are using the correct branch ID if your product catalog is structured with multiple branches.
• Search API interaction: For SIMPLE_PRODUCT_SEARCH and any cases where refined_search is provided, remember to make a separate call to the core Search API (SearchService.Search) using the query from the refined_search field or the original query to get the actual product listings. The Conversational API primarily focuses on the conversational experience and user intent understanding rather than directly returning product results.
• User interface design: Design your web interface to clearly present conversational_text_response, followup_question, and refined_search options in an intuitive manner to guide your user.

What's next

For additional support resources, see conversational feature FAQs.