ibm_watson.assistant_v2 module

The IBM Watson™ Assistant service combines machine learning, natural language understanding, and an integrated dialog editor to create conversation flows between your apps and your users. The Assistant v2 API provides runtime methods your client application can use to send user input to an assistant and receive a response.

class AssistantV2(version, authenticator=None)

Bases: ibm_cloud_sdk_core.base_service.BaseService

The Assistant V2 service.

default_service_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. A session persists until it is deleted, or until it times out because of inactivity. (For more information, see the [documentation](https://cloud.ibm.com/docs/services/assistant?topic=assistant-assistant-settings).

Parameters

• assistant_id (str) – Unique identifier of the assistant. To find the assistant ID in the Watson Assistant user interface, open the assistant settings and click API Details. 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.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

delete_session(assistant_id, session_id, **kwargs)

Delete session.

Deletes a session explicitly before it times out. (For more information about the session inactivity timeout, see the [documentation](https://cloud.ibm.com/docs/services/assistant?topic=assistant-assistant-settings)).

Parameters

• assistant_id (str) – Unique identifier of the assistant. To find the assistant ID in the Watson Assistant user interface, open the assistant settings and click API Details. 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.

• session_id (str) – Unique identifier of the session.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

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. To find the assistant ID in the Watson Assistant user interface, open the assistant settings and click API Details. 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.

• session_id (str) – Unique identifier of the session.

• input (MessageInput) – (optional) An input object that includes the input text.

• context (MessageContext) – (optional) 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.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

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 LevelEnum

Bases: enum.Enum

The severity of the log message.

INFO = 'info'

ERROR = 'error'

WARN = 'warn'

class DialogNodeAction(name, result_variable, *, type=None, parameters=None, credentials=None)

Bases: object

DialogNodeAction.

Attr str name

The name of the action.

Attr str 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 TypeEnum

Bases: enum.Enum

The type of action to invoke.

CLIENT = 'client'

SERVER = 'server'

WEB_ACTION = 'web-action'

CLOUD_FUNCTION = 'cloud-function'

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 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 title or user_label property of the corresponding dialog node, depending on the disambiguation options.

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 MessageContextSkill(*, user_defined=None)

Bases: object

Contains information specific to a particular skill used by the Assistant.

Attr dict user_defined

(optional) Arbitrary variables that can be read and written by a particular skill.

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.

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 MessageTypeEnum

Bases: enum.Enum

The type of user input. Currently, only text input is supported.

TEXT = 'text'

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[RuntimeResponseGeneric] 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 BranchExitedReasonEnum

Bases: enum.Enum

When branch_exited is set to true by the Assistant, the branch_exited_reason specifies whether the dialog completed by itself or got interrupted.

COMPLETED = 'completed'

FALLBACK = 'fallback'

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

The entity value that was recognized in the user input.

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 recognized 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 RuntimeResponseGeneric(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, header=None, results=None)

Bases: object

RuntimeResponseGeneric.

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.

Attr str header

(optional) The title or introductory text to show before the response. This text is defined in the search skill configuration.

Attr list[SearchResult] results

(optional) An array of objects containing search results.

class ResponseTypeEnum

Bases: enum.Enum

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.

TEXT = 'text'

PAUSE = 'pause'

IMAGE = 'image'

OPTION = 'option'

CONNECT_TO_AGENT = 'connect_to_agent'

SUGGESTION = 'suggestion'

SEARCH = 'search'

class PreferenceEnum

Bases: enum.Enum

The preferred type of control to display.

DROPDOWN = 'dropdown'

BUTTON = 'button'

class SearchResult(id, result_metadata, *, body=None, title=None, url=None, highlight=None)

Bases: object

SearchResult.

Attr str id

The unique identifier of the document in the Discovery service collection. This property is included in responses from search skills, which are a beta feature available only to Plus or Premium plan users.

Attr SearchResultMetadata result_metadata

An object containing search result metadata from the Discovery service.

Attr str body

(optional) A description of the search result. This is taken from an abstract, summary, or highlight field in the Discovery service response, as specified in the search skill configuration.

Attr str title

(optional) The title of the search result. This is taken from a title or name field in the Discovery service response, as specified in the search skill configuration.

Attr str url

(optional) The URL of the original data object in its native data source.

Attr SearchResultHighlight highlight

(optional) An object containing segments of text from search results with query-matching text highlighted using HTML <em> tags.

class SearchResultHighlight(*, body=None, title=None, url=None, **kwargs)

Bases: object

An object containing segments of text from search results with query-matching text highlighted using HTML <em> tags.

Attr list[str] body

(optional) An array of strings containing segments taken from body text in the search results, with query-matching substrings highlighted.

Attr list[str] title

(optional) An array of strings containing segments taken from title text in the search results, with query-matching substrings highlighted.

Attr list[str] url

(optional) An array of strings containing segments taken from URLs in the search results, with query-matching substrings highlighted.

class SearchResultMetadata(*, confidence=None, score=None)

Bases: object

An object containing search result metadata from the Discovery service.

Attr float confidence

(optional) The confidence score for the given result. For more information about how the confidence is calculated, see the Discovery service [documentation](../discovery#query-your-collection).

Attr float score

(optional) An unbounded measure of the relevance of a particular result, dependent on the query and matching document. A higher score indicates a greater match to the query parameters.

class SessionResponse(session_id)

Bases: object

SessionResponse.

Attr str session_id

The session ID.