ibm_watson.assistant_v2 module

The IBM Watson™ Assistant service combines machine learning, natural language understanding, and integrated dialog tools to create conversation flows between your apps and your users.

class AssistantV2(version, url='https://gateway.watsonplatform.net/assistant/api', username=None, password=None, iam_apikey=None, iam_access_token=None, iam_url=None)

Bases: ibm_cloud_sdk_core.base_service.BaseService

The Assistant V2 service.

default_url = 'https://gateway.watsonplatform.net/assistant/api'

create_session(assistant_id, **kwargs)

Create a session.

Create a new session. A session is used to send user input to a skill and receive responses. It also maintains the state of the conversation.

Parameters

assistant_id (str) – Unique identifier of the assistant. You can find the

assistant ID of an assistant on the Assistants tab of the Watson Assistant tool. For information about creating assistants, see the [documentation](https://cloud.ibm.com/docs/services/assistant?topic=assistant-assistant-add#assistant-add-task). Note: Currently, the v2 API does not support creating assistants. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_session(assistant_id, session_id, **kwargs)

Delete session.

Deletes a session explicitly before it times out.

Parameters

assistant_id (str) – Unique identifier of the assistant. You can find the

assistant ID of an assistant on the Assistants tab of the Watson Assistant tool. For information about creating assistants, see the [documentation](https://cloud.ibm.com/docs/services/assistant?topic=assistant-assistant-add#assistant-add-task). Note: Currently, the v2 API does not support creating assistants. :param str session_id: Unique identifier of the session. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

message(assistant_id, session_id, input=None, context=None, **kwargs)

Send user input to assistant.

Send user input to an assistant and receive a response. There is no rate limit for this operation.

Parameters

assistant_id (str) – Unique identifier of the assistant. You can find the

assistant ID of an assistant on the Assistants tab of the Watson Assistant tool. For information about creating assistants, see the [documentation](https://cloud.ibm.com/docs/services/assistant?topic=assistant-assistant-add#assistant-add-task). Note: Currently, the v2 API does not support creating assistants. :param str session_id: Unique identifier of the session. :param MessageInput input: An input object that includes the input text. :param MessageContext context: State information for the conversation. The context is stored by the assistant on a per-session basis. You can use this property to set or modify context variables, which can also be accessed by dialog nodes. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

class CaptureGroup(group, location=None)

Bases: object

CaptureGroup.

Attr str group

A recognized capture group for the entity.

Attr list[int] location

(optional) Zero-based character offsets that indicate where

the entity value begins and ends in the input text.

class DialogLogMessage(level, message)

Bases: object

Dialog log message details.

Attr str level

The severity of the log message.

Attr str message

The text of the log message.

class DialogNodeAction(name, result_variable, action_type=None, parameters=None, credentials=None)

Bases: object

DialogNodeAction.

Attr str name

The name of the action.

Attr str action_type

(optional) The type of action to invoke.

Attr dict parameters

(optional) A map of key/value pairs to be provided to the

action. :attr str result_variable: The location in the dialog context where the result of the action is stored. :attr str credentials: (optional) The name of the context variable that the client application will use to pass in credentials for the action.

class DialogNodeOutputOptionsElement(label, value)

Bases: object

DialogNodeOutputOptionsElement.

Attr str label

The user-facing label for the option.

Attr DialogNodeOutputOptionsElementValue value

An object defining the message input

to be sent to the assistant if the user selects the corresponding option.

class DialogNodeOutputOptionsElementValue(input=None)

Bases: object

An object defining the message input to be sent to the assistant if the user selects the corresponding option.

Attr MessageInput input

(optional) An input object that includes the input text.

class DialogNodesVisited(dialog_node=None, title=None, conditions=None)

Bases: object

DialogNodesVisited.

Attr str dialog_node

(optional) A dialog node that was triggered during processing

of the input message. :attr str title: (optional) The title of the dialog node. :attr str conditions: (optional) The conditions that trigger the dialog node.

class DialogRuntimeResponseGeneric(response_type, text=None, time=None, typing=None, source=None, title=None, description=None, preference=None, options=None, message_to_human_agent=None, topic=None, suggestions=None)

Bases: object

DialogRuntimeResponseGeneric.

Attr str response_type

The type of response returned by the dialog node. The

specified response type must be supported by the client application or channel. Note: The suggestion response type is part of the disambiguation feature, which is only available for Premium users. :attr str text: (optional) The text of the response. :attr int time: (optional) How long to pause, in milliseconds. :attr bool typing: (optional) Whether to send a “user is typing” event during the pause. :attr str source: (optional) The URL of the image. :attr str title: (optional) The title or introductory text to show before the response. :attr str description: (optional) The description to show with the the response. :attr str preference: (optional) The preferred type of control to display. :attr list[DialogNodeOutputOptionsElement] options: (optional) An array of objects describing the options from which the user can choose. :attr str message_to_human_agent: (optional) A message to be sent to the human agent who will be taking over the conversation. :attr str topic: (optional) A label identifying the topic of the conversation, derived from the user_label property of the relevant node. :attr list[DialogSuggestion] suggestions: (optional) An array of objects describing the possible matching dialog nodes from which the user can choose. Note: The suggestions property is part of the disambiguation feature, which is only available for Premium users.

class DialogSuggestion(label, value, output=None)

Bases: object

DialogSuggestion.

Attr str label

The user-facing label for the disambiguation option. This label is

taken from the user_label property of the corresponding dialog node. :attr DialogSuggestionValue value: An object defining the message input to be sent to the assistant if the user selects the corresponding disambiguation option. :attr dict output: (optional) The dialog output that will be returned from the Watson Assistant service if the user selects the corresponding option.

class DialogSuggestionValue(input=None)

Bases: object

An object defining the message input to be sent to the assistant if the user selects the corresponding disambiguation option.

Attr MessageInput input

(optional) An input object that includes the input text.

class MessageContext(global_=None, skills=None)

Bases: object

MessageContext.

Attr MessageContextGlobal globalglobal_

(optional) Information that is shared by all

skills used by the Assistant. :attr MessageContextSkills skills: (optional) Information specific to particular skills used by the Assistant. Note: Currently, only a single property named main skill is supported. This object contains variables that apply to the dialog skill used by the assistant.

class MessageContextGlobal(system=None)

Bases: object

Information that is shared by all skills used by the Assistant.

Attr MessageContextGlobalSystem system

(optional) Built-in system properties that

apply to all skills used by the assistant.

class MessageContextGlobalSystem(timezone=None, user_id=None, turn_count=None)

Bases: object

Built-in system properties that apply to all skills used by the assistant.

Attr str timezone

(optional) The user time zone. The assistant uses the time zone to

correctly resolve relative time references. :attr str user_id: (optional) A string value that identifies the user who is interacting with the assistant. The client must provide a unique identifier for each individual end user who accesses the application. For Plus and Premium plans, this user ID is used to identify unique users for billing purposes. This string cannot contain carriage return, newline, or tab characters. :attr int turn_count: (optional) A counter that is automatically incremented with each turn of the conversation. A value of 1 indicates that this is the the first turn of a new conversation, which can affect the behavior of some skills (for example, triggering the start node of a dialog).

class MessageContextSkills(**kwargs)

Bases: object

Information specific to particular skills used by the Assistant. Note: Currently, only a single property named main skill is supported. This object contains variables that apply to the dialog skill used by the assistant.

class MessageInput(message_type=None, text=None, options=None, intents=None, entities=None, suggestion_id=None)

Bases: object

An input object that includes the input text.

Attr str message_type

(optional) The type of user input. Currently, only text input

is supported. :attr str text: (optional) The text of the user input. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters. :attr MessageInputOptions options: (optional) Optional properties that control how the assistant responds. :attr list[RuntimeIntent] intents: (optional) Intents to use when evaluating the user input. Include intents from the previous response to continue using those intents rather than trying to recognize intents in the new input. :attr list[RuntimeEntity] entities: (optional) Entities to use when evaluating the message. Include entities from the previous response to continue using those entities rather than detecting entities in the new input. :attr str suggestion_id: (optional) For internal use only.

class MessageInputOptions(debug=None, restart=None, alternate_intents=None, return_context=None)

Bases: object

Optional properties that control how the assistant responds.

Attr bool debug

(optional) Whether to return additional diagnostic information. Set

to true to return additional information under the output.debug key. :attr bool restart: (optional) Whether to restart dialog processing at the root of the dialog, regardless of any previously visited nodes. Note: This does not affect turn_count or any other context variables. :attr bool alternate_intents: (optional) Whether to return more than one intent. Set to true to return all matching intents. :attr bool return_context: (optional) Whether to return session context with the response. If you specify true, the response will include the context property.

class MessageOutput(generic=None, intents=None, entities=None, actions=None, debug=None, user_defined=None)

Bases: object

Assistant output to be rendered or processed by the client.

Attr list[DialogRuntimeResponseGeneric] generic

(optional) Output intended for any

channel. It is the responsibility of the client application to implement the supported response types. :attr list[RuntimeIntent] intents: (optional) An array of intents recognized in the user input, sorted in descending order of confidence. :attr list[RuntimeEntity] entities: (optional) An array of entities identified in the user input. :attr list[DialogNodeAction] actions: (optional) An array of objects describing any actions requested by the dialog node. :attr MessageOutputDebug debug: (optional) Additional detailed information about a message response and how it was generated. :attr dict user_defined: (optional) An object containing any custom properties included in the response. This object includes any arbitrary properties defined in the dialog JSON editor as part of the dialog node output.

class MessageOutputDebug(nodes_visited=None, log_messages=None, branch_exited=None, branch_exited_reason=None)

Bases: object

Additional detailed information about a message response and how it was generated.

Attr list[DialogNodesVisited] nodes_visited

(optional) An array of objects

containing detailed diagnostic information about the nodes that were triggered during processing of the input message. :attr list[DialogLogMessage] log_messages: (optional) An array of up to 50 messages logged with the request. :attr bool branch_exited: (optional) Assistant sets this to true when this message response concludes or interrupts a dialog. :attr str branch_exited_reason: (optional) When branch_exited is set to true by the Assistant, the branch_exited_reason specifies whether the dialog completed by itself or got interrupted.

class MessageResponse(output, context=None)

Bases: object

A response from the Watson Assistant service.

Attr MessageOutput output

Assistant output to be rendered or processed by the

client. :attr MessageContext context: (optional) State information for the conversation. The context is stored by the assistant on a per-session basis. You can use this property to access context variables. Note: The context is included in message responses only if **return_context**=`true` in the message request.

class RuntimeEntity(entity, location, value, confidence=None, metadata=None, groups=None)

Bases: object

A term from the request that was identified as an entity.

Attr str entity

An entity detected in the input.

Attr list[int] location

An array of zero-based character offsets that indicate where

the detected entity values begin and end in the input text. :attr str value: The term in the input text that was recognized as an entity value. :attr float confidence: (optional) A decimal percentage that represents Watson’s confidence in the entity. :attr dict metadata: (optional) Any metadata for the entity. :attr list[CaptureGroup] groups: (optional) The recognized capture groups for the entity, as defined by the entity pattern.

class RuntimeIntent(intent, confidence)

Bases: object

An intent identified in the user input.

Attr str intent

The name of the recognized intent.

Attr float confidence

A decimal percentage that represents Watson’s confidence in

the intent.

class SessionResponse(session_id)

Bases: object

SessionResponse.

Attr str session_id

The session ID.