---
title: "POST /v2/{+placement}:conversationalSearch"
method: POST
path: "/v2/{+placement}:conversationalSearch"
tags: ["projects"]
---

# POST /v2/{+placement}:conversationalSearch

`POST /v2/{+placement}:conversationalSearch`

Performs a conversational search. This feature is only available for users who have Conversational Search enabled.

## Path parameters

- `placement` string, required

## Request body

- GoogleCloudRetailV2ConversationalSearchRequest — Request message for ConversationalSearchService.ConversationalSearch method.
  - `query` string — Optional. Raw search query to be searched for. If this field is empty, the request is considered a category browsing request.
  - `visitorId` string — Required. A unique identifier for tracking visitors. For example, this could be implemented with an HTTP cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor logs in or out of the website. This should be the same identifier as UserEvent.visitor_id. The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an INVALID_ARGUMENT error is returned.
  - `pageCategories` string[] — Optional. The categories associated with a category page. Must be set for category navigation queries to achieve good search quality. The format should be the same as UserEvent.page_categories; To represent the full path of category, use the '>' sign, with one space on each side, to separate different hierarchies. If '>' is part of the category name, replace it with other character(s). Category pages include special pages such as sales or promotions. For instance, a special sale page may have the category hierarchy: "pageCategories" : ["Sales > 2017 Black Friday Deals"].
  - `branch` string — Required. The branch resource name, such as `projects/*/locations/global/catalogs/default_catalog/branches/0`. Use "default_branch" as the branch ID or leave this field empty, to search products under the default branch.
  - `searchParams` GoogleCloudRetailV2ConversationalSearchRequestSearchParams — Search parameters.
    - `sortBy` string — Optional. The sort string to specify the sorting of search results. The syntax of the sort string is the same as SearchRequest.order_by.
    - `boostSpec` GoogleCloudRetailV2SearchRequestBoostSpec — Boost specification to boost certain items.
      - `conditionBoostSpecs` GoogleCloudRetailV2SearchRequestBoostSpecConditionBoostSpec[] — Condition boost specifications. If a product matches multiple conditions in the specifications, boost scores from these specifications are all applied and combined in a non-linear way. Maximum number of specifications is 20.
        - `condition` string — An expression which specifies a boost condition. The syntax and supported fields are the same as a filter expression. See SearchRequest.filter for detail syntax and limitations. Examples: * To boost products with product ID "product_1" or "product_2", and color "Red" or "Blue": * (id: ANY("product_1", "product_2")) AND (colorFamilies: ANY("Red","Blue"))
        - `boost` number, float — Strength of the condition boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0. Setting to 1.0 gives the item a big promotion. However, it does not necessarily mean that the boosted item will be the top result at all times, nor that other items will be excluded. Results could still be shown even when none of them matches the condition. And results that are significantly more relevant to the search query can still trump your heavily favored but irrelevant items. Setting to -1.0 gives the item a big demotion. However, results that are deeply relevant might still be shown. The item will have an upstream battle to get a fairly high ranking, but it is not blocked out completely. Setting to 0.0 means no boost applied. The boosting condition is ignored.
      - `skipBoostSpecValidation` boolean — Whether to skip boostspec validation. If this field is set to true, invalid BoostSpec.condition_boost_specs will be ignored and valid BoostSpec.condition_boost_specs will still be applied.
    - `filter` string — Optional. The filter string to restrict search results. The syntax of the filter string is the same as SearchRequest.filter.
    - `canonicalFilter` string — Optional. The canonical filter string to restrict search results. The syntax of the canonical filter string is the same as SearchRequest.canonical_filter.
  - `userInfo` GoogleCloudRetailV2UserInfo — Information of an end user.
    - `userId` string — Highly recommended for logged-in users. Unique identifier for logged-in user, such as a user name. Don't set for anonymous users. Always use a hashed value for this ID. Don't set the field to the same fixed ID for different users. This mixes the event history of those users together, which results in degraded model quality. The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an INVALID_ARGUMENT error is returned.
    - `ipAddress` string — The end user's IP address. This field is used to extract location information for personalization. This field must be either an IPv4 address (e.g. "104.133.9.80") or an IPv6 address (e.g. "2001:0db8:85a3:0000:0000:8a2e:0370:7334"). Otherwise, an INVALID_ARGUMENT error is returned. This should not be set when: * setting SearchRequest.user_info. * using the JavaScript tag in UserEventService.CollectUserEvent or if direct_user_request is set.
    - `userAgent` string — User agent as included in the HTTP header. The field must be a UTF-8 encoded string with a length limit of 1,000 characters. Otherwise, an INVALID_ARGUMENT error is returned. This should not be set when using the client side event reporting with GTM or JavaScript tag in UserEventService.CollectUserEvent or if direct_user_request is set.
    - `directUserRequest` boolean — True if the request is made directly from the end user, in which case the ip_address and user_agent can be populated from the HTTP request. This flag should be set only if the API request is made directly from the end user such as a mobile app (and not if a gateway or a server is processing and pushing the user events). This should not be set when using the JavaScript tag in UserEventService.CollectUserEvent.
  - `safetySettings` GoogleCloudRetailV2SafetySetting[] — Optional. The safety settings to be applied to the generated content.
    - `threshold` 'HARM_BLOCK_THRESHOLD_UNSPECIFIED' | 'BLOCK_LOW_AND_ABOVE' | 'BLOCK_MEDIUM_AND_ABOVE' | 'BLOCK_ONLY_HIGH' | 'BLOCK_NONE' | 'OFF' — The harm block threshold.
    - `method` 'HARM_BLOCK_METHOD_UNSPECIFIED' | 'SEVERITY' | 'PROBABILITY' — Optional. Specify if the threshold is used for probability or severity score. If not specified, the threshold is used for probability score.
    - `category` 'HARM_CATEGORY_UNSPECIFIED' | 'HARM_CATEGORY_HATE_SPEECH' | 'HARM_CATEGORY_DANGEROUS_CONTENT' | 'HARM_CATEGORY_HARASSMENT' | 'HARM_CATEGORY_SEXUALLY_EXPLICIT' | 'HARM_CATEGORY_CIVIC_INTEGRITY' — Harm category.
  - `conversationId` string — Optional. This field specifies the conversation id, which maintains the state of the conversation between client side and server side. Use the value from the previous ConversationalSearchResponse.conversation_id. For the initial request, this should be empty.
  - `userLabels` object — Optional. The user labels applied to a resource must meet the following requirements: * Each resource can have multiple labels, up to a maximum of 64. * Each label must be a key-value pair. * Keys have a minimum length of 1 character and a maximum length of 63 characters and cannot be empty. Values can be empty and have a maximum length of 63 characters. * Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed. * The key portion of a label must be unique. However, you can use the same key with multiple resources. * Keys must start with a lowercase letter or international character. See [Google Cloud Document](https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements) for more details.
  - `conversationalFilteringSpec` GoogleCloudRetailV2ConversationalSearchRequestConversationalFilteringSpec — This field specifies all conversational filtering related parameters addition to conversational retail search.
    - `enableConversationalFiltering` boolean — Optional. This field is deprecated. Please use ConversationalFilteringSpec.conversational_filtering_mode instead.
    - `conversationalFilteringMode` 'MODE_UNSPECIFIED' | 'DISABLED' | 'ENABLED' | 'CONVERSATIONAL_FILTER_ONLY' — Optional. Mode to control Conversational Filtering. Defaults to Mode.DISABLED if it's unset.
    - `userAnswer` GoogleCloudRetailV2ConversationalSearchRequestUserAnswer — This field specifies the current user answer during the conversational filtering search. This can be either user selected from suggested answers or user input plain text.
      - `textAnswer` string — This field specifies the incremental input text from the user during the conversational search.
      - `selectedAnswer` GoogleCloudRetailV2ConversationalSearchRequestUserAnswerSelectedAnswer — This field specifies the selected answers during the conversational search.
        - `productAttributeValue` GoogleCloudRetailV2ProductAttributeValue — Product attribute which structured by an attribute name and value. This structure is used in conversational search filters and answers. For example, if we have `name=color` and `value=red`, this means that the color is `red`.
          - `name` string — The attribute name.
          - `value` string — The attribute value.

## Response `200`

Successful response

---

[API](https://skmtc.net/google/apis/retail.md) · [All operations](https://skmtc.net/google/apis/retail/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/retail/versions/146c67e59640/schema)