You can integrate a Conversational Search Assistant using the **Conversational Search API**. # Core concepts **Session:** A **Session** represents the entire continuous interaction between a user and the assistant within a single interface. It encapsulates the **multi\-turn conversation history**, allowing the assistant to maintain context and continuity throughout the dialogue. **User information:** This refers to the metadata passed during a session, currently supporting **User ID** and **Nickname**. Providing this information enables the Dialogue Engine to accumulate interaction data, which is crucial for building accurate **user interest profiles** and delivering personalized experiences. **Step:** The conversation assistant uses an Agent architecture. Before producing the final answer, it goes through steps such as reasoning, tool invocation, and receiving search results. Each of these is reported as step events during the process to indicate the current execution phase of the agent. **Payload:** Represents intermediate results output by the conversation interface that are not final replies. Each step may return different payload information, which you can either ignore or use to enhance the display of the agent's intermediate execution process to users. # Start a new session Session startup supports two modes: * **No opening:** No welcome message or initial item recommendations; It waits for the first user input and begins the Q&A process immediately. See [Start the Q&A session](/docs/85296/1873499#4c96fc7a) * **Use Conversation Opening:** The assistant first presents the **Smart Welcome Message** or **Personalized Item Recommendations** as defined in your settings. Once the user has engaged with the opening content or entered a query, the conversation proceeds. The opening setting is set in your console. See: [Configure Conversation Opening](/docs/85296/1873498) ## Use Conversation Opening ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/c721a11b8f5a4447945a115b8d34c80c =2744x) **Example invocation:** ```Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/{application_id}/chat_search' \ -H 'Content-Type: application/json' \ -H 'Authorization:Bearer {API_KEY}' \ -d '{ "session_id": "25ee998a-5462-9385-9f18-035f1da7a6e5", "user": { "_user_id":"ldy_199432", "nickname":"[User Nickname for Greetings]" }, "context":{ "location":{ "longitude":"-12.299", "latitude":"-10.019" } } "opening_remarks":true }' ``` **Parameter parsing:** `{application_id}`: the application ID of the app that this Conversational Search Experience belongs to, available in the console. `{API_KEY}`: the API key created in the console, see [API Authentication](/docs/393/92216). `opening_remarks`: whether to activate Conversation Opening, pass `true`. `session_id`: the unique identifier of the session, used to track and manage user conversation status. You need to maintain the session ID on your server. For each new user conversation, pass a unique new session_id. The session_id must remain consistent within one conversation. `_user_id`: recommended to pass, represents a unique user ID in your platform You need to ensure that the user ID matches the user ID in the incoming behavior data If you have enabled recommendation at conversation start in the configuration, this parameter must be passed. `nickname`: recommended to pass, used to address the user with their custom nickname during opening greetings. Please refer to [Personalized welcome message](/docs/85296/1873498#4918a786) for more details. `location`: user’s current geographic location can be passed in. ### Return conversation opening #### Return only Welcome Message and Starter Questions If no Initial Item Recommendation is configured in the console, only return the welcome message, then return suggested Starter Questions. **Output parameters:** **request_id ** `String` The unique request identifier for this request **result ** `Object` The top\-level structure returned in the stream * **content ** `String` Welcome message in the streaming output **Return example:** ```JSON { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "#"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": " 🎬"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": " Hi"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "，"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "下午"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "好"} } ... ... { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": { "stop_reason": "stop" } } ``` After streaming the welcome message, immediately return the recommended starter questions: **Output parameters** **request_id ** `String` The unique identifier for this request **result ** `Object` The top\-level structure returned in streaming * **payload ** `Object` The content output in batch mode at once * **suggestions ** `List[String]` The list of “guess what you want to search” questions for the welcome phase, limited by the maximum number configured in the console ```JSON { "request_id": "fc627693-cc53-4903-8de6-9a49a51f4e05", "result": { "payload": { "suggestions": [ "What are the trending color options for monitoring headphones?", "What colors are available for gaming headsets?", "Are Apple monitoring headphones reliable?", "How long is the typical warranty period for headphones?", "What scenarios are best suited for headphones with a 5-hour battery life?", "Can you recommend a mirrorless camera with image stabilization?", "What is the standard warranty policy for mirrorless cameras?", "视"Which mirrorless camera is best for a beginner videographer?" ] } } } ``` #### Return Welcome Message with Initial Item Recommendations at conversation opening When Initial Item Recommendations are configured, the agent first calls the recommendation API using the user ID to obtain a personalized recommendation list, then summarizes, processes, and streams the curated recommended items, welcome message, and starter questions. **Step 1: call Recommendation API on startup** At the start, use the user ID to call the recommendation API and get the personalized recommendation results list. **Output parameters:** **request_id ** `String` The unique request identifier for this request. **result ** `Object` The top\-level structure of the streaming response. * **step_info ** `Object` Output step description structure * **step ** `Object` Step name, returned when calling a tool: `tool call`: call the recommended tool `get_results`: fetch the recommendation list * **tool_name ** `String` Return the tool name when step is a `tool call`; outputs `"rec"` when starting to recommend items. * **step_payload ** `Object` Additional information output with the step, such as tool call details * **param** Object Parameters for the recommendation scenario; defaults to the homepage recommendation configuration's scene_id configured in the console {"scene_id":""} * **payload** `Object` Content returned from the recommendation tool call * **rec ** `Object` Recommendation tool return structure * **rec_results ** `List[Object]` List of recommended content returned; the list contains multiple recommended items. Content includes: _id: item ID of the recommended content display_fields: all fields of the item **Output example:** * Call the recommendation tool ```JSON { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "step_info": { "step": "tool call", "step_payload": { "param": {"scene_id": "scene-C4fI0e8b"}, "tool_name": "rec" } } } } ``` * Return results from calling the recommendation tool ```JSON { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "step_info": { "step": "get results" } } } { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "payload": { "rec": { "rec_results": [ { "_id": "019992810", "display_fields": { "_hash_item_id": 4635372581706750000, "formatted_description_info": {} "articleId": "GK9607", "contents": [] }] } } ``` **Step 2: stream Welcome Message and recommendation reasons** After returning to the recommendation list, the model generates personalized welcome messages and recommendation reasons based on the recommended items, user profile, uploaded user nickname, and time. **Output parameters:** **request_id ** `String` The unique request identifier for this request **result ** `Object` The top\-level structure of the streaming return * **content ** `String` The welcome message content for streaming output ```JSON { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "#"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": " 🎬"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": " Hi"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "，"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "Good afternoon!"} } } ... ... { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": { "stop_reason": "stop" } } ``` **Step 3: Output recommended items related to the recommendation reasons and welcome messages** After output, return the list of selected recommended items actually referenced in the welcome messages and recommendation reasons, along with starter questions **Output parameters:** **request_id ** `String` The unique request identifier for this request **result ** `Object` Top\-level structure returned as stream * **payload ** `Object` Batch output content structure * **related_rec_items ** `List[Object]` If the console configures Initial Item Recommendations and links to an active recommendation configuration, the interface returns a curated content list after the welcome message, including multiple recommended items. * **_id ** `String` Item ID * **display_fields ** `Object` Returns all field information of the item * **suggestions ** `List [String]` Return recommended questions based on the suggestion list as a list of strings **Output the curated recommendation list** ```JSON { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "payload": { "related_rec_items": [ { "_id": "019992810", "display_fields": { "_hash_item_id": 4635372581706750000, "formatted_description_info": {} "articleId": "GK9607", "contents": [] } ] } } ``` **Output suggested questions** ```JSON { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "payload": { "suggestions": [ "What are the key design highlights of the GAZELLE classic sneakers?", "Do you have any other recommendations for retro-style footwear?", "What other comfortable and breathable sports-leisure shoes are available?" ] } } } ``` # Start the Q&A session :::tip \*Explanation This request allows skipping Welcome Message and Initial Item Recommendations to directly answer questions. It also applies to each user input after the conversation opening and requires passing the session_id provided at the start. ::: **Receive the user's conversation information and begin the conversation immediately:** ```Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/${application_id}/chat_search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "session_id": "25ee998a-5462-9385-9f18-035f1da7a6e5", "input_message": { "content":[{"type":"text", "text":"What are some good Chinese sci-fi movies worth watching?"}] }, "user": { "_user_id": "ldy_199432", "nickname":"Apple" }, enable_suggestions:true "search_param": { "page_size": 20, "dataset_ids": ["111111104"], "filters": { "106265704": { "op": "must", "field": "parent_conent_id", "conds": [""] } } "output_fields":{ "10299201": ["product_code", "product_name", "description"], "10299202": ["content_id", "title", "keywords", "summary"] } } "context":{ "location":{ "longitude":"-12.299", "latitude":"-10.019" } } }' ``` **Parameter description:** `input_message`: The content provided by the user. This can include **multimodal data**, such as both image and text information. `search_params`: Parameters to follow when triggering Search tools during the conversation, including the number of homepage results to return, restrictions within a specific dataset, and search filters limiting the dataset `enable_suggestion`: Determines whether to generate **Follow\-up Questions** at the end of the response. The default is false. For detailed parameter explanation, see [ChatSearch](/docs/393/92249) :::tip \*Explanation For video conversations, if you want to display or recommend a series of content (such as a full season of a TV show instead of individual episodes) , you need to pass the following filter: `"{App-linked video dataset ID}": {"op": "must","field": "parent_content_id","conds": [""]}` ::: # Receive Conversation Response Message

Once the user’s input is received, the interface streams the Agent’s execution process followed by the final response content. For detailed execution flow and parameter explanation, see: [ChatSearch](/docs/393/92249). The streaming of the actual answer begins when the `step` is identified as **"reply"** . This output includes the response text in Markdown format, as well as specific item fields referenced within the response paragraphs. The return fields are as follows: **Output parameters** **request_id ** `String` The unique request identifier for this request **result ** `Object` top\-level structure of the streaming return * **step_info ** `Object` information related to the step * **step ** `String` step name, \"reply\" is returned at this stage * **content ** `String` streaming returned string * **citation ** `Array [Citation structure]` when outputting references for items or document content, output a list of item data sources for the referenced paragraph; each element in the list is an Object containing the item content type, dataset ID, and data ID. If the output contains no citations, this field will not appear. At the end of a paragraph, if the paragraph introduces or cites certain media asset information, a list will be returned. The citation object's return structure is as follows: * **type ** `String` The data type enumeration of the citation will return the following values: `"item"` item data in the item dataset; `"document"` document data in the document dataset * **dataset_id ** `String` The dataset ID to which the cited content belongs * **_id ** `String` The unique ID of the cited item or document, corresponding to the item ID in the image & text item dataset or the `content_id` in the video dataset * **display_fields ** `Object` Detailed information of the cited data. Currently, the following content is returned when referencing document data: * **doc_id ** `String`: document ID * **doc_name ** `String`: document name used to identify the specific referenced document * **doc_type ** `String`: document extension * **text ** `String`: original text of the referenced document slice **Output example** ```JSON {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"Can"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"you"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"recommend"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"some"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"lipsticks"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"perfect"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"for"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"clubbing"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"："}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"\\"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"n"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"-"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":" Glam"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"orous"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":" Ch"}} {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"icks"}} ... ... {"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"citation":{"type":"item","dataset_id":"289112891","_id":"P19029XJSKK_0928812"}}} ``` ## (Video application) Output the video segment information cited in the reply In video applications, user questions trigger deep video search. After returning the streaming output, a list of video clips related to the user's question will be provided. Each clip includes video ID, start timestamp, and end timestamp to help users quickly locate relevant content. **Output parameters** **request_id ** `String` Unique request identifier for this request **result ** `Object` top\-level structure for streamed return * **payload ** `Object` use payload to output structured fragment data * **video_deep_answer ** `List[Object]` return all fields of all items referenced in this answer, along with the datasets these items belong to * **highlights ** `List[Object]` return highlights and summaries related to user questions across multiple videos * **content_id ** `String` return highlights and summaries related to user questions across multiple videos * **video_title ** `String` The title of the video to which the highlight belongs, returning the field value of the "title" attribute marked in the uploaded video asset * **generated_title ** String The video title generated during the video understanding phase * **snippets ** `List[Object]` Highlight segments in the video containing the following information: * **start_timestamp ** `Int` Start timestamp of the segment (seconds) * **end_timestamp ** `Int` End timestamp of the segment (seconds) * **summary ** `String` Short summary of the clip * **cover ** `String` URL of the clip's non\-black first frame, used for cover display **Output example** ```JSON { "payload":{ "video_deep_answer":{ "106706135":{ "highlights":[ {"content_id":"video_episode_002", "generated_title":"The Countdown Enigma: Collapsing Physics and the Battle for Scientific Frontiers", "video_title":"", "snippets":[{ "start_timestamp":262, "end_timestamp":322, "summary":"Physics no longer exists", "cover":"XXX"}]}, {"content_id":"video_episode_020", "generated_title":"Mathematical Deadlocks in a Chaotic Universe and the Rebirth of Civilization", "video_title":"", "snippets":[{ "start_timestamp":1412, "end_timestamp":1465, "summary":"A Monument and a Tombstone for Civilization", "cover":"XXXX"}, {"start_timestamp":1948, "end_timestamp":2001, "summary":"Physics has never existed.", "cover":"XXXXX"}]}] } ] } } } } ``` ## Return follow\-up questions suggestion If the parameter 'enable_suggestion' is enabled, a list of suggested questions related to the current search will be returned to help users explore further or refine their queries. **Output parameters** **request_id ** `String` Unique request identifier for this request **result ** `Object` Top\-level structure for streaming return * **payload ** `Object` Use payload to output suggested questions * **suggestions ** `List[String]` Return 3 recommended follow\-up questions for users **Output example** ```JSON { "request_id":"ba88a50a58928940c56f2399fd176045", "result":{ "payload":{ "suggestions":["Who said 'Physics no longer exists'?","What else was in Yang Dong's suicide note?","Which episode is 'The bugs have never been defeated' from?"] } } } ``` :::tip \*Explanation For more integrated practices, see: best practices \-[Configure and Integrate Conversational Search](/docs/393/92266) :::

Viking AI Search