Conversational commerce developer's guide

This guide details how to integrate with the Conversational commerce 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.

Conversational product filtering API integration

Conversational product filtering lets your customer continue the conversation for basic product search queries, which use the simple_product_search query classification.

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

Setup

The Conversational commerce API supports the conversational commerce feature:

• gRPC: conversationalSearchService
• REST: conversationalSearch

The Conversational commerce 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 commerce API.

Send a query from the end user

This section describes how to initiate a conversational commerce 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

• Developers should create a conversational commerce request by setting the 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 commerce 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 UI:

• Option 1: Always show search results

  If your UX design dictates that search results should always be displayed regardless of the conversational output (such as in a dedicated search results area alongside the chat), then you should always send the your user's original query to the core Product Search API in parallel with your call to the Conversational Commerce API. This helps ensure that product listings are immediately available.

• Option 2: Show search results based on conversational output

  If your UX design is more dynamic and you only want to display search results when appropriate, based on the conversational API's response (such as only for SIMPLE_PRODUCT_SEARCH queries or when refined_search suggestions are provided), then you should wait for the Conversational Commerce API's response before sending any queries to the core Product Search API. You would then use the refined_search query provided in the response (if any) to fetch product results.

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 Step 2c. 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

Conversational commerce 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 uses search query categories to determine whether or not 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 search to show questions and product suggestions in conversational commerce.

When the Conversational commerce API returns refinedSearch queries, these 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 UI) 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 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 UI provides an explicit "Start New Chat" or "Reset Conversation" button, clicking this would trigger a new conversational session.
  • Conversational API integration: The API response will include 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 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 most recent refined_search.query from the previous response if the end user is acting on a refined query, or a completely new and unrelated query), and the conversationId. Remember to 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 would generally never reset the conversationId, even if the end user types a new, seemingly unrelated query. The system will use 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 commerce 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 commerce 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 will contain updated query(s) that incorporate the end user's latest input. The developer should update the client UI 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 will be 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 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 end user behavior and conversion paths.

Additional considerations and best practices

Additional considerations and best practices must be considered when implementing your conversational commerce 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 login or logout 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 Commerce API primarily focuses on the conversational experience and intent understanding, not directly returning product results itself.
• User interface design: Design your UI 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.