Help Center> Conversational Bot Service> API Reference> QABot APIs> Other APIs> Single-Round Q&A (Offline Soon)

Updated on 2023-06-06 GMT+08:00

View PDF

Single-Round Q&A (Offline Soon)

Function Description

For QABot, questions entered by users serve as the input, and top N (N is 5 by default) knowledge points matching the input serve as the output. The knowledge points are sorted by score in descending order.

If the returned knowledge point contains the answer, the matched answer is returned. If the returned knowledge point does not contain the answer, the recommended question is returned.

URI

POST https://{endpoint}/v1/{project_id}/qabots/{qabot_id}/requests

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
endpoint	Yes	String	Endpoint, which is the request address for calling an API. The endpoint varies depending on services in different regions. For more details, see Endpoints.
project_id	Yes	String	Project ID, which is used for resource isolation. For details, see Obtaining a Project ID.
qabot_id	Yes	String	Q&A bot ID, which is in the UUID format. For example, 303a0a00-c88a-43e3-aa2f-d5b8b9832b02. This parameter is displayed in the Q&A Bot Name/ID column of the QABot console.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It is used to obtain the permission to call APIs. The token is the value of X-Subject-Token in the response header in Authentication.
Content-Type	Yes	String	Message body type (format). The value is application/json.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
session_id	Yes	String	Session ID, which is a custom character string used to differentiate sessions.
user_id	No	String	User ID, which uniquely identifies a user.
question	Yes	String	User question.
extends	No	Extends object	Extended parameter.
threshold_enable	No	Boolean	Value true indicates that the internal threshold is enabled. If this parameter is set to true, the answer with threshold processing performed is returned. Value false indicates that the internal threshold is disabled. If this parameter is set to false, the original answer is returned.
chat_enable	No	Boolean	The default value is true. true indicates that the chit-chat is used when the bot does not know how to reply. false indicates that the chit-chat is not used when the bot does not know how to reply.
operate_type	No	Integer	Transferred when the API is called to label the Q&A behavior. The default value is 0. It is displayed in the Q&A log. Value 0 indicates that a user inputs a question. Value 1 indicates that a user clicks a question from the hot questions. Value 3 indicates that a user clicks a question in the Recommend Questions area. Value 4 indicates that a user clicks a question in the prompted questions.

**Table 4** Extends
Parameter	Mandatory	Type	Description
domains	No	Array of strings	Domain list. Multiple domains are separated by semicolons (;). If certain domains are specified, the API matches answers from the domains. If no domains are specified, the API matches answers from the entire knowledge base of the user. Currently, a maximum of 10 domains are supported.
top	No	Integer	Number of answers. The default value is 5. The value ranges from 1 to 10.

Response

Status code: 200

**Table 5** Response body parameters
Parameter	Type	Description
request_id	String	Request ID. This parameter is not included when the API fails to be called.
question	String	Question. This parameter is not included when the API fails to be called.
answers	Array of Answers objects	Set of questions similar to the user question. This parameter is not included when the API fails to be called.
extends	Extends object	Extended parameter. This parameter is not included when the API fails to be called.

**Table 6** Answers
Parameter	Type	Description
qa_pair_id	String	Q&A pair ID.
st_question	String	Standard question.
ex_questions	Array of ExQuestions objects	Extended question.
answer	String	Answer.
score	Float	Similarity score, which is accurate to three decimal places.
domain	String	Problem category

**Table 7** ExQuestions
Parameter	Type	Description
content	String	Extended question.

**Table 8** Extends
Parameter	Mandatory	Type	Description
domains	No	Array of strings	Domain list. Multiple domains are separated by semicolons (;). If certain domains are specified, the API matches answers from the domains. If no domains are specified, the API matches answers from the entire knowledge base of the user. Currently, a maximum of 10 domains are supported.
top	No	Integer	Number of answers. The default value is 5. The value ranges from 1 to 10.

Status code: 400

**Table 9** Response body parameters
Parameter	Type	Description
error_code	String	Error code returned when the API fails to be called. This parameter is not included when the API is successfully called.
error_msg	String	Error message returned when the API fails to be called. This parameter is not included when the API is successfully called.

Example Requests

Example request

POST https://{endpoint}/v1/1604d8170cd84440a81281e5a3a04f8b/qabots/303a0a00-c88a-43e3-aa2f-d5b8b9832b02/requests

Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...

Request Body:
{
    "user_id": "z00123456",
    "session_id": "xxxxxxxxxxxxxxxxxx",
    "operate_type":3,      
    "question": "What should I do if I fail to log in to my cloud desktop?"
    "extends":{
    "domains":" [Cloud desktop]",
	"top":5
    },
    "threshold_enable":false,
    "chat_enable":true
}

Example Responses

Status code: 200

Example of a successful response

If the internal threshold is disabled (threshold_enable is set to false), the number of results is returned based on the value of top.

{ 
    "request_id": "303a0a00-c88a",
    "question": "What should I do if I cannot open my cloud desktop?",
    "answers": [
        {
            "qa_pair_id":"123",
            "st_question":"Why does my cloud desktop fail to be opened?",
            "answer":"Incorrect user account",
            "score":0.952,
            "domain":"Cloud desktop"
     },
     {
            "qa_pair_id":"123",
            "st_question":"Why would my cloud desktop fail to be opened?",
            "answer":"Incorrect user account",        
            "score":0.901,
            "domain":"Cloud desktop"
        },
        {
            "qa_pair_id":"123",
            "st_question":"What is cloud desktop?",
            "answer": "Cloud desktop is a system that supports remote office.",
            "score":0.352,
            "domain":"Cloud desktop"
        },
     {
            "qa_pair_id":"123",
            "st_question": "Why does my computer desktop fail to be opened?",
            "answer": "Check whether the monitor is started.",
            "score":0.352,
            "domain":"Cloud desktop"
        },
    ]
}

Enable the internal threshold.

**Table 10** Internal threshold description
Condition	Result	Remarks
Score > 0.85	Q&A pairs whose scores have a difference within 0.05 from the highest score are returned.	If answers of Q&A pairs are specified, the Q&A pairs are returned. If answers are not specified, recommended Q&A pairs are returned.
0.70 < Score < 0.85	If there are Q&A pairs whose scores are in this range, Q&A pairs whose highest scores are in this range are returned. If there are no Q&A pairs whose scores are in this range, recommended Q&A pairs are returned.
0.55 < Score < 0.70	Recommended Q&A pairs are returned.
Score < 0.55	No Q&A pairs are returned.

Example 1

{ 
    "request_id": "303a0a00-c88a",
    "question": "What should I do if I cannot open my cloud desktop?",
    "answers": [
        {
            "qa_pair_id":"123",
            "st_question":"Why does my cloud desktop fail to be opened?",
            "ex_questions": [
                {
                    "content":"Cloud desktop"
                }
            ],
            "answer":"Incorrect user account",
            "top_score_question":"Why does my cloud desktop fail to be opened?",
            "score":0.952,
            "domain":"Cloud desktop"
        },
      {
            "qa_pair_id":"123",
            "st_question":"How to open the cloud desktop?",
            "ex_questions": [
                {
                    "content":"Desktop"
                }
            ],
            "answer":"Open the cloud desktop.",
            "top_score_question":"How to open the cloud desktop?",
            "score":0.912,
            "domain":"Cloud desktop"
        }
    ]
}

Example 2

{ 
    "request_id": "303a0a00-c88a",
    "question": "What should I do if I cannot open my cloud desktop?",
    "answers": [
        {
            "qa_pair_id":"123",
            "st_question":"Why does my cloud desktop fail to be opened?",
            "top_score_question":"Why does my cloud desktop fail to be opened?",
            "answer":"Incorrect user account",
            "score":0.752,
            "domain":"Cloud desktop"
        }
    {
            "qa_pair_id":"123",
            "st_question":"Why would my cloud desktop fail to be opened?",
            "score":0.70,
            "domain":"Cloud desktop"
        },
        {
            "qa_pair_id":"123",
            "st_question":"What is cloud desktop?",
            "score":0.54,
            "domain":"Cloud desktop"
        }
    ]
}

Example 3

{ 
    "request_id": "303a0a00-c88a",
    "question": "What should I do if I cannot open my cloud desktop?",
    "answers": [
    {
            "qa_pair_id":"123",
            "st_question":"Why would my cloud desktop fail to be opened?",
            "score":0.291,
            "domain":"Cloud desktop"
        },
        {
            "qa_pair_id":"123",
            "st_question":"What is cloud desktop?",
            "score":0.252,
            "domain":"Cloud desktop"
        }
    ]
}

Have a chit-chat or ask a question with no matched answer.

{ 
    "request_id": "303a0a00-c88a",
    "question": "Hello",
    "answers": [
    {
            "answer": "Hello. May I help you?"

        }
    ]
}

Status code: 400

Example of a failed response

{
  "error_code": "CBS.0022",
  "error_msg": "session_id can not be null"
}

Status Code

For details about status codes, see Status Code.

Error Code

For details about error codes, see Error Code.

Parent topic: Other APIs

Previous topic: Labeling and Transferring a Conversation to a Human Agent

Next topic: Data Structure

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot