watson_developer_cloud.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: watson_developer_cloud.watson_service.WatsonService

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://console.bluemix.net/docs/services/assistant/create-assistant.html#creating-assistants). 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://console.bluemix.net/docs/services/assistant/create-assistant.html#creating-assistants). 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://console.bluemix.net/docs/services/assistant/create-assistant.html#creating-assistants). Note: Currently, the v2 API does not support creating assistants. :param str session_id: Unique identifier of the session. :param MessageInput input: The user input. :param MessageContext context: State information for the conversation. :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 object 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) The user input.

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 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 object 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) The user input.

class MessageContext(global_=None, skills=None)

Bases: object

State information for the conversation.

Attr MessageContextGlobal globalglobal_:  (optional) Contains information that can be shared

by all skills within the Assistant. :attr MessageContextSkills skills: (optional) Contains information specific to particular skills within the Assistant.

class MessageContextGlobal(system=None)

Bases: object

Contains information that can be shared by all skills within the Assistant.

Attr MessageContextGlobalSystem system:  (optional) Properties that are shared by all

skills used by the assistant.

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

Bases: object

Properties that are shared by 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.

class MessageContextSkill(user_defined=None)

Bases: object

Contains information specific to a particular skill within the Assistant.

Attr str user_defined:  (optional) Arbitrary variables that can be read and written to

by a particular skill within the Assistant.

class MessageContextSkills(**kwargs)

Bases: object

Contains information specific to particular skills within the Assistant.

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

Bases: object

The user input.

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 start a new conversation with this user input. Specify true to clear the state information stored by the session. :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 object user_defined: (optional) Arbitrary variables that can be read and written to by a particular skill within the Assistant.

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.

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 object 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.