Bot Ask and Answer
The bots asks a question and retrieves an answer from a knowledge base.
Starting from IBM RPA 23.0.3, support for Interactive Voice Response (IVR) is removed from this command due to the removal of IVR. For more information, see Removed.
Command availability: IBM RPA SaaS and IBM RPA on premises
Description
The bot asks the user a question in a chat and recognizes the answer by using a knowledge base that is prepared for the chat subject.
To learn more about knowledge bases, see Knowledge Base.
Script syntax
IBM RPA's proprietary script language has a syntax similar to other programming languages. The script syntax defines the command's syntax in the script file. You can work with this syntax in IBM RPA Studio's Script mode.
botAnswerQuestion --kb(String) --evaluate(Boolean) [--version(Numeric)] [--minimumscore(Numeric)] [--topn(Numeric)] [--options(Nullable<AnswerQuestionOptions>)] [--retry(Boolean)] [--attempts(Numeric)] [--retrytext(String)] [--timeoutsub(String)] [--recognitionTimeout(TimeSpan)] [--speechCompleteTimeout(TimeSpan)] [--noInputTimeout(TimeSpan)] [--speechIncompleteTimeout(TimeSpan)] [--confidenceThreshold(Numeric)] [--beep(Boolean)] [--language(Language)] --text(String) [--textformat(String)] [--timeout(TimeSpan)] (String)=utterance (Boolean)=timedout (String)=answer (String)=tags (String)=context (Numeric)=score (List<String>)=options (DataTable)=data (Boolean)=success (String)=botHistoryMessageId
Dependencies
- Use the Connect to Chatbot (
botConnect) command to start a chatbot or IVR scope. The Bot Ask and Answer command must be inside this scope. - You must have a knowledge base model published in your tenant. For more information about how to create knowledge base models, see Knowledge Base.
Input parameters
The following table displays the list of input parameters available in this command. In the table, you can see the parameter name when working in IBM RPA Studio's Script mode and its Designer mode equivalent label.
| Designer mode label | Script mode name | Required | Accepted variable types | Description |
|---|---|---|---|---|
| Knowledge base | kb |
Required |
Text |
Knowledge Base for questions and answers. |
| Version | version |
Optional |
Number |
Knowledge base version. If empty, it uses the production version of the knowledge base on the tenant. |
| Evaluate | evaluate |
Optional |
Boolean |
Enable to replace a reference variable with the value that is assigned to it. See the evaluate parameter options. |
| Context (Obsolete) | context |
Optional |
Text |
The context of the answer to look for on the question. 🛈 Note: This parameter is obsolete. Use the Context output parameter instead. |
| Minimum score | minimumscore |
Optional |
Number |
Minimum score of the answer to the question. |
| Number of answers | topn |
Optional |
Number |
Number of answers that are expected to a question. Questions can have more than one answer defined on a knowledge base. |
| Options | options |
Optional |
AnswerQuestionOptions |
Option to use when querying answers from a knowledge base. See the options parameter options. |
| Retry | retry |
Optional |
Boolean |
Enable to allow the bot to ask a new question if there is no answer on the first attempt. |
| Attempts | attempts |
Optional |
Number |
Number of times that the bot attempts to ask the question. |
| Retry text | retrytext |
Optional |
Text |
Alternative question that is asked to the user if there is no answer on the first attempt. |
| Sub-routine | timeoutsub |
Optional |
Text |
Subroutine that runs if user response time runs out. |
| Recognition timeout | recognitionTimeout |
Optional |
Time Span |
Time out to acknowledge the user's response. If the time ends, the interaction is forwarded to the subroutine specified in the Sub-routine parameter. 🛈 Remember: This parameter is specific for interactive voice response (IVR) communications. |
| Speech complete timeout | speechCompleteTimeout |
Optional |
Time Span |
Maximum amount of time allowed without interaction with the bot. If the time ends, the interaction is forwarded to the subroutine specified in the Sub-routine parameter. 🛈 Remember: This parameter is specific for interactive voice response (IVR) communications. Starting from IBM RPA 23.0.3, this parameter is removed. |
| Start timeout | noInputTimeout |
Optional |
Time Span |
Maximum amount of time to wait for the user to start the conversation. If the time ends, the interaction is forwarded to the subroutine specified in the Sub-routine parameter. 🛈 Remember: This parameter is specific for interactive voice response (IVR) communications. Starting from IBM RPA 23.0.3, this parameter is removed. |
| Speech incomplete timeout | speechIncompleteTimeout |
Optional |
Time Span |
Maximum amount of time to wait for the user to complete the speech. 🛈 Remember: This parameter is specific for interactive voice response (IVR) communications. Starting from IBM RPA 23.0.3, this parameter is removed. |
| Confidence | confidenceThreshold |
Optional |
Number |
Numeric expression that indicates the confidence level for recognizing user response. Confidence rate is in the range 1 - 100. If the obtained value is lower than the specified range, it returns null. Starting from IBM RPA 23.0.3, this parameter is removed. |
| Beep | beep |
Optional |
Boolean |
Enable to play a beep each time that the bot speaks. 🛈 Remember: This parameter is specific for interactive voice response (IVR) communications. Starting from IBM RPA 23.0.3, this parameter is removed. |
| Language | language |
Optional |
Language |
Language used for bot communication. Use the Create a Language (createLanguage) command to get the language variable. |
| Text | text |
Required |
Text |
Question to answer. |
| Text Format | textformat |
Optional |
Text, BotTextFormat |
The text format. See the textformat parameter options. |
| Timeout | timeout |
Optional |
Time Span, Number, Text |
Timeout for waiting the user's response. The default timeout is 5 seconds. Use the Set Timeout (setTimeout) command to change the default timeout at run time.If the time ends, the interaction is forwarded to the subroutine specified in the Sub-routine parameter. |
evaluate parameter options
This parameter evaluates references to variables in answers. A reference to a variable is any text that follows the ${variableName} pattern, where the variable is replaced by a value that is defined by you on the script.
For example, if the knowledge base contains a sentence such as "To contact us send an email to ${email}, or access our site at ${website}.", both ${email} and ${website} are references
to variables in the current script.
If this parameter is enabled, the user sees these variables with the values that the email and website variables contain in the current script, like contact@example.com and www.example.com.
If this parameter is disabled, you must use the Evaluate (evaluate) command to evaluate the variables, so they can receive the values from their respective variables.
Notice that when you use the Evaluate command, it replaces all references to variables to their values. Variables without values also are evaluated. For a sample usage, see the example 2.
options parameter options
The following table displays the options available for the options input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.
| Designer mode label | Script mode name | Description |
|---|---|---|
| Use Synonyms | UseSynonyms |
Check the synonyms of the words in the question sent to the KB. Option available for Machine Learning algorithm version 2. |
textformat parameter options
The following table displays the options available for the textformat input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.
| Designer mode label | Script mode name | Description |
|---|---|---|
| Markdown | Markdown |
Markdown format. |
| Plain Text | Plain |
Plain Text format. |
Output parameters
| Designer mode label | Script mode name | Accepted variable types | Description |
|---|---|---|---|
| Utterance | utterance |
Text |
Returns the text that is provided by the user. |
| Timed out | timedout |
Boolean |
Returns True if the time ends, or False otherwise. |
| Answer | answer |
Text |
Returns the answer with the highest score. |
| Tags | tags |
Text |
Returns the tags that are assigned to the answer, which are defined in the knowledge base. |
| Context | context |
Text |
Returns the context that is assigned to the answer, which is defined in the knowledge base. |
| Score | score |
Number |
Returns the score for the answer. |
| Additional answers | options |
List<Text> |
Returns a list of additional answers to the question. |
| Data | data |
Data Table |
Returns a data table with information on the questions, answers, contexts, scores, and tags. |
| Success | success |
Boolean |
Returns True if the script runs successfully, or False otherwise. |
| History message | botHistoryMessageId |
Text |
Returns the identifier of the chat history. This identifier uniquely identifies a piece of communication for each Bot Ask command. It establishes and enforces a link between the data that is generated in the Bot Ask command in context and the data returned from the knowledge base to register what data relates to each piece of communication in a chatbot scope. |
Example
Example 1: The following example demonstrates how to ask and get an answer to a question in a chatbot by using a knowledge base.
Consider a sample knowledge base called "Chatbot_Sales", which supports sales agents who want to look for information on it to deal with customer questions. This knowledge base contains a set of answers and questions about a sample product.
The Bot Ask and Answer command ask a question, and based on the user's response, analyzes, and retrieve the best answer from the specified knowledge base.
🛈 Remember: The knowledge base that is used in the following examples is a sample one, which represents a fictitious scenario. You need to create and publish a knowledge base to your tenant before you use it. For more information about how to create knowledge base models, see Knowledge Base.
defVar --name answer --type String
defVar --name answerScore --type Numeric
defVar --name culture --type Language
createLanguage --culture "en-US" culture=value
// Connects the chatbot.
botConnect --type "Chat" --language ${culture} --timeout "00:05:00"
// Ask and answer a question, considering the "Chatbot_Sales" knowledge base, and a minimum score of 500.
botAnswerQuestion --kb "Chatbot_Sales" --minimumscore 500 --timeoutsub miscommunication --text "Hi! How can I help you?" --textformat "Plain" --timeout "00:01:00" answer=answer answerScore=score
// Shows the answer on the chat.
botSay --text "${answer}" --textformat "Plain"
// Disconnects the chatbot.
botDisconnect
beginSub --name miscommunication
// Shows a message on the chat, if the user don't interact with the chatbot in the time out defined.
botSay --text "Thank you for contacting us!" --textformat "0"
endSub
Example 2: The following example demonstrates how to evaluate reference to variables in answers by using the Evaluate command.
Consider that the ${email}, ${telephone}, and ${website} variables might return as part of an answer. In the example, values are assigned to them, so they can be used when needed.
The Bot Ask and Answer command sends a question on the chat, and based on a sample user's response like "What are the company's contact details?", the knowledge base can return an answer like "To contact us send an email to ${email}, access our site at ${website}, or call us by ${telephone}. Can I assist you with something else?".
Notice that it returns the raw reference to variables and not their values because the Evaluate input parameter is turned off. Then, after the Evaluate command,
you get the answer with the variables' values assigned like "To contact us send an email to contact@gmail.com, access our site at www.example.com, or call us by (11) 99999-9999. Can I assist you with something else?".
defVar --name answer --type String
defVar --name answerScore --type Numeric
defVar --name culture --type Language
defVar --name email --type String
defVar --name website --type String
defVar --name telephone --type String --value "(11) 99999-9999"
// Creates a Language variable.
createLanguage --culture "en-US" culture=value
// Connects the chatbot.
botConnect --type "Chat" --language ${culture} --timeout "00:05:00"
// Ask and answer a question.
// It doesn't evaluate the expected variables' values in the answer because the Evaluate input parameter is turned off.
botAnswerQuestion --kb Chatbot_Sales --minimumscore 500 --text "Hi! How can I help you?" --textformat "Plain" --timeout "00:01:00" answer=answer answerScore=score
// Consider that the KB returns the answer "To contact us send an email to ${email}, access our site at ${website}, or call us by ${telephone}."
// The following command shows the previous answer on the chat before the Evaluate command.
botSay --text "Answer before the Evaluate command:\r\n${answer}" --textformat "Plain"
// Sets a value to the "${email}" variable.
setVar --name "${email}" --value "contact@gmail.com"
// Sets a value to the "${telephone}" variable.
setVar --name "${telephone}" --value "(11) 99999-9999"
// Sets a value to the "${website}" variable.
setVar --name "${website}" --value "www.example.com"
// Evaluate the answer to replace the reference variables to its values.
evaluate --expression "${answer}" answer=value
// The following command shows the previous answer on the chat after the Evaluate command. Now the variables' values are assigned to them.
// For example, "To contact us send an email to contact@gmail.com, access our site at www.example.com, or call us by (11) 99999-9999."
botSay --text "Answer after the Evaluate command:\r\n${answer}" --textformat "Plain"
// Disconnects the chatbot.
botDisconnect