watson_developer_cloud.conversation_v1 module¶

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

class ConversationV1(version, url='https://gateway.watsonplatform.net/conversation/api', username=None, password=None)[source]¶

Bases: watson_developer_cloud.watson_service.WatsonService

The Conversation V1 service.

default_url = 'https://gateway.watsonplatform.net/conversation/api'¶

message(workspace_id, input=None, alternate_intents=None, context=None, entities=None, intents=None, output=None, nodes_visited_details=None, **kwargs)[source]¶

Get response to user input.

Get a response to a user’s input. There is no rate limit for this operation.

Parameters:	workspace_id (str) – Unique identifier of the workspace. input (InputData) – An input object that includes the input text. alternate_intents (bool) – Whether to return more than one intent. Set to true to return all matching intents. context (Context) – State information for the conversation. Continue a conversation by including the context object from the previous response. entities (list[RuntimeEntity]) – 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. intents (list[RuntimeIntent]) – 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. output (OutputData) – System output. Include the output from the previous response to maintain intermediate information over multiple requests. nodes_visited_details (bool) – Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the message. headers (dict) – A dict containing the request headers
Returns:	A dict containing the MessageResponse response.
Return type:	dict

create_workspace(name=None, description=None, language=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None, metadata=None, learning_opt_out=None, **kwargs)[source]¶

Create workspace.

Create a workspace based on component objects. You must provide workspace components defining the content of the new workspace. This operation is limited to 30 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	name (str) – The name of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters. description (str) – The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. language (str) – The language of the workspace. intents (list[CreateIntent]) – An array of objects defining the intents for the workspace. entities (list[CreateEntity]) – An array of objects defining the entities for the workspace. dialog_nodes (list[CreateDialogNode]) – An array of objects defining the nodes in the workspace dialog. counterexamples (list[CreateCounterexample]) – An array of objects defining input examples that have been marked as irrelevant input. metadata (object) – Any metadata related to the workspace. learning_opt_out (bool) – Whether training data from the workspace can be used by IBM for general service improvements. true indicates that workspace training data is not to be used. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Workspace response.
Return type:	dict

delete_workspace(workspace_id, **kwargs)[source]¶

Delete workspace.

Delete a workspace from the service instance. This operation is limited to 30 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. headers (dict) – A dict containing the request headers
Return type:	None

get_workspace(workspace_id, export=None, include_audit=None, **kwargs)[source]¶

Get information about a workspace.

Get information about a workspace, optionally including all workspace content. With export**=`false`, this operation is limited to 6000 requests per 5 minutes. With **export**=`true`, the limit is 20 requests per 30 minutes. For more information, see **Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. export (bool) – Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the WorkspaceExport response.
Return type:	dict

list_workspaces(page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)[source]¶

List workspaces.

List the workspaces associated with a Conversation service instance. This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	page_limit (int) – The number of records to return in each page of results. include_count (bool) – Whether to include information about the number of records returned. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. cursor (str) – A token identifying the page of results to retrieve. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the WorkspaceCollection response.
Return type:	dict

update_workspace(workspace_id, name=None, description=None, language=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None, metadata=None, learning_opt_out=None, append=None, **kwargs)[source]¶

Update workspace.

Update an existing workspace with new or modified data. You must provide component objects defining the content of the updated workspace. This operation is limited to 30 request per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. name (str) – The name of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 64 characters. description (str) – The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. language (str) – The language of the workspace. intents (list[CreateIntent]) – An array of objects defining the intents for the workspace. entities (list[CreateEntity]) – An array of objects defining the entities for the workspace. dialog_nodes (list[CreateDialogNode]) – An array of objects defining the nodes in the workspace dialog. counterexamples (list[CreateCounterexample]) – An array of objects defining input examples that have been marked as irrelevant input. metadata (object) – Any metadata related to the workspace. learning_opt_out (bool) – Whether training data from the workspace can be used by IBM for general service improvements. true indicates that workspace training data is not to be used. append (bool) – Whether the new data is to be appended to the existing data in the workspace. If append=`false`, elements included in the new data completely replace the corresponding existing elements, including all subelements. For example, if the new data includes entities and append=`false`, all existing entities in the workspace are discarded and replaced with the new entities. If append=`true`, existing elements are preserved, and the new elements are added. If any elements in the new data collide with existing elements, the update request fails. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Workspace response.
Return type:	dict

create_intent(workspace_id, intent, description=None, examples=None, **kwargs)[source]¶

Create intent.

Create a new intent. This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The name of the intent. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 128 characters. description (str) – The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. examples (list[CreateExample]) – An array of user input examples for the intent. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Intent response.
Return type:	dict

delete_intent(workspace_id, intent, **kwargs)[source]¶

Delete intent.

Delete an intent from a workspace. This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The intent name. headers (dict) – A dict containing the request headers
Return type:	None

get_intent(workspace_id, intent, export=None, include_audit=None, **kwargs)[source]¶

Get intent.

Get information about an intent, optionally including all intent content. With export**=`false`, this operation is limited to 6000 requests per 5 minutes. With **export**=`true`, the limit is 400 requests per 30 minutes. For more information, see **Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The intent name. export (bool) – Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the IntentExport response.
Return type:	dict

list_intents(workspace_id, export=None, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)[source]¶

List intents.

List the intents for a workspace. With export**=`false`, this operation is limited to 2000 requests per 30 minutes. With **export**=`true`, the limit is 400 requests per 30 minutes. For more information, see **Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. export (bool) – Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included. page_limit (int) – The number of records to return in each page of results. include_count (bool) – Whether to include information about the number of records returned. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. cursor (str) – A token identifying the page of results to retrieve. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the IntentCollection response.
Return type:	dict

update_intent(workspace_id, intent, new_intent=None, new_description=None, new_examples=None, **kwargs)[source]¶

Update intent.

Update an existing intent with new or modified data. You must provide component objects defining the content of the updated intent. This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The intent name. new_intent (str) – The name of the intent. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 128 characters. new_description (str) – The description of the intent. new_examples (list[CreateExample]) – An array of user input examples for the intent. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Intent response.
Return type:	dict

create_example(workspace_id, intent, text, **kwargs)[source]¶

Create user input example.

Add a new user input example to an intent. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The intent name. text (str) – The text of a user input example. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 1024 characters. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Example response.
Return type:	dict

delete_example(workspace_id, intent, text, **kwargs)[source]¶

Delete user input example.

Delete a user input example from an intent. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The intent name. text (str) – The text of the user input example. headers (dict) – A dict containing the request headers
Return type:	None

get_example(workspace_id, intent, text, include_audit=None, **kwargs)[source]¶

Get user input example.

Get information about a user input example. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The intent name. text (str) – The text of the user input example. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Example response.
Return type:	dict

list_examples(workspace_id, intent, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)[source]¶

List user input examples.

List the user input examples for an intent. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The intent name. page_limit (int) – The number of records to return in each page of results. include_count (bool) – Whether to include information about the number of records returned. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. cursor (str) – A token identifying the page of results to retrieve. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the ExampleCollection response.
Return type:	dict

update_example(workspace_id, intent, text, new_text=None, **kwargs)[source]¶

Update user input example.

Update the text of a user input example. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. intent (str) – The intent name. text (str) – The text of the user input example. new_text (str) – The text of the user input example. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 1024 characters. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Example response.
Return type:	dict

create_counterexample(workspace_id, text, **kwargs)[source]¶

Create counterexample.

Add a new counterexample to a workspace. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. text (str) – The text of a user input marked as irrelevant input. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters - It cannot consist of only whitespace characters - It must be no longer than 1024 characters. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Counterexample response.
Return type:	dict

delete_counterexample(workspace_id, text, **kwargs)[source]¶

Delete counterexample.

Delete a counterexample from a workspace. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. text (str) – The text of a user input counterexample (for example, What are you wearing?). headers (dict) – A dict containing the request headers
Return type:	None

get_counterexample(workspace_id, text, include_audit=None, **kwargs)[source]¶

Get counterexample.

Get information about a counterexample. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. text (str) – The text of a user input counterexample (for example, What are you wearing?). include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Counterexample response.
Return type:	dict

list_counterexamples(workspace_id, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)[source]¶

List counterexamples.

List the counterexamples for a workspace. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. page_limit (int) – The number of records to return in each page of results. include_count (bool) – Whether to include information about the number of records returned. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. cursor (str) – A token identifying the page of results to retrieve. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the CounterexampleCollection response.
Return type:	dict

update_counterexample(workspace_id, text, new_text=None, **kwargs)[source]¶

Update counterexample.

Update the text of a counterexample. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. text (str) – The text of a user input counterexample (for example, What are you wearing?). new_text (str) – The text of a user input counterexample. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Counterexample response.
Return type:	dict

create_entity(workspace_id, entity, description=None, metadata=None, values=None, fuzzy_match=None, **kwargs)[source]¶

Create entity.

Create a new entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, underscore, and hyphen characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 64 characters. description (str) – The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. metadata (object) – Any metadata related to the value. values (list[CreateValue]) – An array of objects describing the entity values. fuzzy_match (bool) – Whether to use fuzzy matching for the entity. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Entity response.
Return type:	dict

delete_entity(workspace_id, entity, **kwargs)[source]¶

Delete entity.

Delete an entity from a workspace. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. headers (dict) – A dict containing the request headers
Return type:	None

get_entity(workspace_id, entity, export=None, include_audit=None, **kwargs)[source]¶

Get entity.

Get information about an entity, optionally including all entity content. With export**=`false`, this operation is limited to 6000 requests per 5 minutes. With **export**=`true`, the limit is 200 requests per 30 minutes. For more information, see **Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. export (bool) – Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the EntityExport response.
Return type:	dict

list_entities(workspace_id, export=None, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)[source]¶

List entities.

List the entities for a workspace. With export**=`false`, this operation is limited to 1000 requests per 30 minutes. With **export**=`true`, the limit is 200 requests per 30 minutes. For more information, see **Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. export (bool) – Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included. page_limit (int) – The number of records to return in each page of results. include_count (bool) – Whether to include information about the number of records returned. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. cursor (str) – A token identifying the page of results to retrieve. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the EntityCollection response.
Return type:	dict

update_entity(workspace_id, entity, new_entity=None, new_description=None, new_metadata=None, new_fuzzy_match=None, new_values=None, **kwargs)[source]¶

Update entity.

Update an existing entity with new or modified data. You must provide component objects defining the content of the updated entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. new_entity (str) – The name of the entity. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, underscore, and hyphen characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 64 characters. new_description (str) – The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. new_metadata (object) – Any metadata related to the entity. new_fuzzy_match (bool) – Whether to use fuzzy matching for the entity. new_values (list[CreateValue]) – An array of entity values. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Entity response.
Return type:	dict

create_value(workspace_id, entity, value, metadata=None, synonyms=None, patterns=None, value_type=None, **kwargs)[source]¶

Add entity value.

Create a new value for an entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. metadata (object) – Any metadata related to the entity value. synonyms (list[str]) – An array containing any synonyms for the entity value. You can provide either synonyms or patterns (as indicated by type), but not both. A synonym must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. patterns (list[str]) – An array of patterns for the entity value. You can provide either synonyms or patterns (as indicated by type), but not both. A pattern is a regular expression no longer than 128 characters. For more information about how to specify a pattern, see the [documentation](https://console.bluemix.net/docs/services/conversation/entities.html#creating-entities). value_type (str) – Specifies the type of value. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Value response.
Return type:	dict

delete_value(workspace_id, entity, value, **kwargs)[source]¶

Delete entity value.

Delete a value from an entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. headers (dict) – A dict containing the request headers
Return type:	None

get_value(workspace_id, entity, value, export=None, include_audit=None, **kwargs)[source]¶

Get entity value.

Get information about an entity value. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. export (bool) – Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the ValueExport response.
Return type:	dict

list_values(workspace_id, entity, export=None, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)[source]¶

List entity values.

List the values for an entity. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. export (bool) – Whether to include all element content in the returned data. If export=`false`, the returned data includes only information about the element itself. If export=`true`, all content, including subelements, is included. page_limit (int) – The number of records to return in each page of results. include_count (bool) – Whether to include information about the number of records returned. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. cursor (str) – A token identifying the page of results to retrieve. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the ValueCollection response.
Return type:	dict

update_value(workspace_id, entity, value, new_value=None, new_metadata=None, new_type=None, new_synonyms=None, new_patterns=None, **kwargs)[source]¶

Update entity value.

Update an existing entity value with new or modified data. You must provide component objects defining the content of the updated entity value. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. new_value (str) – The text of the entity value. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. new_metadata (object) – Any metadata related to the entity value. new_type (str) – Specifies the type of value. new_synonyms (list[str]) – An array of synonyms for the entity value. You can provide either synonyms or patterns (as indicated by type), but not both. A synonym must conform to the following resrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. new_patterns (list[str]) – An array of patterns for the entity value. You can provide either synonyms or patterns (as indicated by type), but not both. A pattern is a regular expression no longer than 128 characters. For more information about how to specify a pattern, see the [documentation](https://console.bluemix.net/docs/services/conversation/entities.html#creating-entities). headers (dict) – A dict containing the request headers
Returns:	A dict containing the Value response.
Return type:	dict

create_synonym(workspace_id, entity, value, synonym, **kwargs)[source]¶

Add entity value synonym.

Add a new synonym to an entity value. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. synonym (str) – The text of the synonym. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Synonym response.
Return type:	dict

delete_synonym(workspace_id, entity, value, synonym, **kwargs)[source]¶

Delete entity value synonym.

Delete a synonym from an entity value. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. synonym (str) – The text of the synonym. headers (dict) – A dict containing the request headers
Return type:	None

get_synonym(workspace_id, entity, value, synonym, include_audit=None, **kwargs)[source]¶

Get entity value synonym.

Get information about a synonym of an entity value. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. synonym (str) – The text of the synonym. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Synonym response.
Return type:	dict

list_synonyms(workspace_id, entity, value, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)[source]¶

List entity value synonyms.

List the synonyms for an entity value. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. page_limit (int) – The number of records to return in each page of results. include_count (bool) – Whether to include information about the number of records returned. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. cursor (str) – A token identifying the page of results to retrieve. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the SynonymCollection response.
Return type:	dict

update_synonym(workspace_id, entity, value, synonym, new_synonym=None, **kwargs)[source]¶

Update entity value synonym.

Update an existing entity value synonym with new text. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. entity (str) – The name of the entity. value (str) – The text of the entity value. synonym (str) – The text of the synonym. new_synonym (str) – The text of the synonym. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. headers (dict) – A dict containing the request headers
Returns:	A dict containing the Synonym response.
Return type:	dict

create_dialog_node(workspace_id, dialog_node, description=None, conditions=None, parent=None, previous_sibling=None, output=None, context=None, metadata=None, next_step=None, actions=None, title=None, node_type=None, event_name=None, variable=None, digress_in=None, digress_out=None, digress_out_slots=None, **kwargs)[source]¶

Create dialog node.

Create a new dialog node. This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. dialog_node (str) – The dialog node ID. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 1024 characters. description (str) – The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. conditions (str) – The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters. parent (str) – The ID of the parent dialog node. previous_sibling (str) – The ID of the previous dialog node. output (object) – The output of the dialog node. For more information about how to specify dialog node output, see the [documentation](https://console.bluemix.net/docs/services/conversation/dialog-overview.html#complex). context (object) – The context for the dialog node. metadata (object) – The metadata for the dialog node. next_step (DialogNodeNextStep) – The next step to be executed in dialog processing. actions (list[DialogNodeAction]) – An array of objects describing any actions to be invoked by the dialog node. title (str) – The alias used to identify the dialog node. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 64 characters. node_type (str) – How the dialog node is processed. event_name (str) – How an event_handler node is processed. variable (str) – The location in the dialog context where output is stored. digress_in (str) – Whether this top-level dialog node can be digressed into. digress_out (str) – Whether this dialog node can be returned to after a digression. digress_out_slots (str) – Whether the user can digress to top-level nodes while filling out slots. headers (dict) – A dict containing the request headers
Returns:	A dict containing the DialogNode response.
Return type:	dict

delete_dialog_node(workspace_id, dialog_node, **kwargs)[source]¶

Delete dialog node.

Delete a dialog node from a workspace. This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. dialog_node (str) – The dialog node ID (for example, get_order). headers (dict) – A dict containing the request headers
Return type:	None

get_dialog_node(workspace_id, dialog_node, include_audit=None, **kwargs)[source]¶

Get dialog node.

Get information about a dialog node. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. dialog_node (str) – The dialog node ID (for example, get_order). include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the DialogNode response.
Return type:	dict

list_dialog_nodes(workspace_id, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)[source]¶

List dialog nodes.

List the dialog nodes for a workspace. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. page_limit (int) – The number of records to return in each page of results. include_count (bool) – Whether to include information about the number of records returned. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. cursor (str) – A token identifying the page of results to retrieve. include_audit (bool) – Whether to include the audit properties (created and updated timestamps) in the response. headers (dict) – A dict containing the request headers
Returns:	A dict containing the DialogNodeCollection response.
Return type:	dict

update_dialog_node(workspace_id, dialog_node, new_dialog_node=None, new_description=None, new_conditions=None, new_parent=None, new_previous_sibling=None, new_output=None, new_context=None, new_metadata=None, new_next_step=None, new_title=None, new_type=None, new_event_name=None, new_variable=None, new_actions=None, new_digress_in=None, new_digress_out=None, new_digress_out_slots=None, **kwargs)[source]¶

Update dialog node.

Update an existing dialog node with new or modified data. This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. dialog_node (str) – The dialog node ID (for example, get_order). new_dialog_node (str) – The dialog node ID. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 1024 characters. new_description (str) – The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. new_conditions (str) – The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters. new_parent (str) – The ID of the parent dialog node. new_previous_sibling (str) – The ID of the previous sibling dialog node. new_output (object) – The output of the dialog node. For more information about how to specify dialog node output, see the [documentation](https://console.bluemix.net/docs/services/conversation/dialog-overview.html#complex). new_context (object) – The context for the dialog node. new_metadata (object) – The metadata for the dialog node. new_next_step (DialogNodeNextStep) – The next step to be executed in dialog processing. new_title (str) – The alias used to identify the dialog node. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 64 characters. new_type (str) – How the dialog node is processed. new_event_name (str) – How an event_handler node is processed. new_variable (str) – The location in the dialog context where output is stored. new_actions (list[DialogNodeAction]) – An array of objects describing any actions to be invoked by the dialog node. new_digress_in (str) – Whether this top-level dialog node can be digressed into. new_digress_out (str) – Whether this dialog node can be returned to after a digression. new_digress_out_slots (str) – Whether the user can digress to top-level nodes while filling out slots. headers (dict) – A dict containing the request headers
Returns:	A dict containing the DialogNode response.
Return type:	dict

list_all_logs(filter, sort=None, page_limit=None, cursor=None, **kwargs)[source]¶

List log events in all workspaces.

List the events from the logs of all workspaces in the service instance. If cursor is not specified, this operation is limited to 40 requests per 30 minutes. If cursor is specified, the limit is 120 requests per minute. For more information, see Rate limiting.

Parameters:	filter (str) – A cacheable parameter that limits the results to those matching the specified filter. You must specify a filter query that includes a value for language, as well as a value for workspace_id or request.context.metadata.deployment. For more information, see the [documentation](https://console.bluemix.net/docs/services/conversation/filter-reference.html#filter-query-syntax). sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. page_limit (int) – The number of records to return in each page of results. cursor (str) – A token identifying the page of results to retrieve. headers (dict) – A dict containing the request headers
Returns:	A dict containing the LogCollection response.
Return type:	dict

list_logs(workspace_id, sort=None, filter=None, page_limit=None, cursor=None, **kwargs)[source]¶

List log events in a workspace.

List the events from the log of a specific workspace. If cursor is not specified, this operation is limited to 40 requests per 30 minutes. If cursor is specified, the limit is 120 requests per minute. For more information, see Rate limiting.

Parameters:	workspace_id (str) – Unique identifier of the workspace. sort (str) – The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-). Supported values are name, updated, and workspace_id. filter (str) – A cacheable parameter that limits the results to those matching the specified filter. For more information, see the [documentation](https://console.bluemix.net/docs/services/conversation/filter-reference.html#filter-query-syntax). page_limit (int) – The number of records to return in each page of results. cursor (str) – A token identifying the page of results to retrieve. headers (dict) – A dict containing the request headers
Returns:	A dict containing the LogCollection response.
Return type:	dict

class CaptureGroup(group, location=None)[source]¶

Attr list[int] location:
Attr str group:	A recognized capture group for the entity.
	(optional) Zero-based character offsets that indicate where the entity value begins and ends in the input text.

Attr str conversation_id:
	(optional) The unique identifier of the conversation.
Attr SystemResponse system:
	(optional) For internal use only.

Attr datetime created:
Attr str text:	The text of the counterexample.
	(optional) The timestamp for creation of the counterexample.
Attr datetime updated:
	(optional) The timestamp for the last update to the counterexample.

Attr list[Counterexample] counterexamples:
	An array of objects describing the examples marked as irrelevant input.
Attr Pagination pagination:
	The pagination data for the returned objects.

Attr str dialog_node:
	The dialog node ID. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 1024 characters.
Attr str description:
	(optional) The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
Attr str conditions:
	(optional) The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters.
Attr str parent:
	(optional) The ID of the parent dialog node.
Attr str previous_sibling:
	(optional) The ID of the previous dialog node.
Attr object output:
	(optional) The output of the dialog node. For more information about how to specify dialog node output, see the [documentation](https://console.bluemix.net/docs/services/conversation/dialog-overview.html#complex).
Attr object context:
	(optional) The context for the dialog node.
Attr object metadata:
	(optional) The metadata for the dialog node.
Attr DialogNodeNextStep next_step:
	(optional) The next step to be executed in dialog processing.
Attr list[DialogNodeAction] actions:
	(optional) An array of objects describing any actions to be invoked by the dialog node.
Attr str title:	(optional) The alias used to identify the dialog node. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 64 characters.
Attr str node_type:
	(optional) How the dialog node is processed.
Attr str event_name:
	(optional) How an event_handler node is processed.
Attr str variable:
	(optional) The location in the dialog context where output is stored.
Attr str digress_in:
	(optional) Whether this top-level dialog node can be digressed into.
Attr str digress_out:
	(optional) Whether this dialog node can be returned to after a digression.
Attr str digress_out_slots:
	(optional) Whether the user can digress to top-level nodes while filling out slots.

Attr str entity:
	The name of the entity. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, underscore, and hyphen characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 64 characters.
Attr str description:
	(optional) The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
Attr object metadata:
	(optional) Any metadata related to the value.
Attr list[CreateValue] values:
	(optional) An array of objects describing the entity values.
Attr bool fuzzy_match:
	(optional) Whether to use fuzzy matching for the entity.

Attr str intent:
	The name of the intent. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 128 characters.
Attr str description:
	(optional) The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters.
Attr list[CreateExample] examples:
	(optional) An array of user input examples for the intent.

Attr object metadata:
Attr str value:	The text of the entity value. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters.
	(optional) Any metadata related to the entity value.
Attr list[str] synonyms:
	(optional) An array containing any synonyms for the entity value. You can provide either synonyms or patterns (as indicated by type), but not both. A synonym must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters.
Attr list[str] patterns:
	(optional) An array of patterns for the entity value. You can provide either synonyms or patterns (as indicated by type), but not both. A pattern is a regular expression no longer than 128 characters. For more information about how to specify a pattern, see the [documentation](https://console.bluemix.net/docs/services/conversation/entities.html#creating-entities).
Attr str value_type:
	(optional) Specifies the type of value.

Attr str dialog_node_id:
	The dialog node ID.
Attr str description:
	(optional) The description of the dialog node.
Attr str conditions:
	(optional) The condition that triggers the dialog node.
Attr str parent:
	(optional) The ID of the parent dialog node. This property is not returned if the dialog node has no parent.
Attr str previous_sibling:
	(optional) The ID of the previous sibling dialog node. This property is not returned if the dialog node has no previous sibling.
Attr object output:
	(optional) The output of the dialog node.
Attr object context:
	(optional) The context (if defined) for the dialog node.
Attr object metadata:
	(optional) Any metadata for the dialog node.
Attr DialogNodeNextStep next_step:
	(optional) The next step to execute following this dialog node.
Attr datetime created:
	(optional) The timestamp for creation of the dialog node.
Attr datetime updated:
	(optional) The timestamp for the most recent update to the dialog node.
Attr list[DialogNodeAction] actions:
	(optional) The actions for the dialog node.
Attr str title:	(optional) The alias used to identify the dialog node.
Attr str node_type:
	(optional) How the dialog node is processed.
Attr str event_name:
	(optional) How an event_handler node is processed.
Attr str variable:
	(optional) The location in the dialog context where output is stored.
Attr str digress_in:
	(optional) Whether this top-level dialog node can be digressed into.
Attr str digress_out:
	(optional) Whether this dialog node can be returned to after a digression.
Attr str digress_out_slots:
	(optional) Whether the user can digress to top-level nodes while filling out slots.

Attr str action_type:
Attr str name:	The name of the action.
	(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.

Attr list[DialogNode] dialog_nodes:
	An array of objects describing the dialog nodes defined for the workspace.
Attr Pagination pagination:
	The pagination data for the returned objects.

Attr str behavior:
	What happens after the dialog node completes. The valid values depend on the node type: - The following values are valid for any node: - get_user_input - skip_user_input - jump_to - If the node is of type event_handler and its parent node is of type slot or frame, additional values are also valid: - if event_name=`filled` and the type of the parent node is slot: - reprompt - skip_all_slots - if event_name=`nomatch` and the type of the parent node is slot: - reprompt - skip_slot - skip_all_slots - if event_name=`generic` and the type of the parent node is frame: - reprompt - skip_slot - skip_all_slots If you specify jump_to, then you must also specify a value for the dialog_node property.
Attr str dialog_node:
	(optional) The ID of the dialog node to process next. This parameter is required if behavior=`jump_to`.
Attr str selector:
	(optional) Which part of the dialog node to process next.

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.

Attr str entity_name:
	The name of the entity.
Attr datetime created:
	(optional) The timestamp for creation of the entity.
Attr datetime updated:
	(optional) The timestamp for the last update to the entity.
Attr str description:
	(optional) The description of the entity.
Attr object metadata:
	(optional) Any metadata related to the entity.
Attr bool fuzzy_match:
	(optional) Whether fuzzy matching is used for the entity.

Attr list[EntityExport] entities:
	An array of objects describing the entities defined for the workspace.
Attr Pagination pagination:
	The pagination data for the returned objects.

Attr str example_text:
	The text of the user input example.
Attr datetime created:
	(optional) The timestamp for creation of the example.
Attr datetime updated:
	(optional) The timestamp for the last update to the example.

Attr str intent_name:
	The name of the intent.
Attr datetime created:
	(optional) The timestamp for creation of the intent.
Attr datetime updated:
	(optional) The timestamp for the last update to the intent.
Attr str description:
	(optional) The description of the intent.

Attr list[IntentExport] intents:
	An array of objects describing the intents defined for the workspace.
Attr Pagination pagination:
	The pagination data for the returned objects.

Attr list[LogExport] logs:
	An array of objects describing log events.
Attr LogPagination pagination:
	The pagination data for the returned objects.

Attr MessageRequest request:
	A request received by the workspace, including the user input and context.
Attr MessageResponse response:
	The response sent by the workspace, including the output text, detected intents and entities, and context.
Attr str log_id:
	A unique identifier for the logged event.
Attr str request_timestamp:
	The timestamp for receipt of the message.
Attr str response_timestamp:
	The timestamp for the system response to the message.
Attr str workspace_id:
	The unique identifier of the workspace where the request was made.
Attr str language:
	The language of the workspace where the message request was made.

Attr str level:	The severity of the log message.
Attr str msg:	The text of the log message.

Attr str next_url:
	(optional) The URL that will return the next page of results, if any.
Attr int matched:
	(optional) Reserved for future use.
Attr str next_cursor:
	(optional) A token identifying the next page of results.

Attr InputData input:
	(optional) An input object that includes the input text.
Attr bool alternate_intents:
	(optional) Whether to return more than one intent. Set to true to return all matching intents.
Attr Context context:
	(optional) State information for the conversation. Continue a conversation by including the context object from the previous response.
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 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 OutputData output:
	(optional) System output. Include the output from the previous response to maintain intermediate information over multiple requests.

Attr MessageInput input:
	(optional) The user input from the request.
Attr list[RuntimeIntent] intents:
	An array of intents recognized in the user input, sorted in descending order of confidence.
Attr list[RuntimeEntity] entities:
	An array of entities identified in the user input.
Attr bool alternate_intents:
	(optional) Whether to return more than one intent. A value of true indicates that all matching intents are returned.
Attr Context context:
	State information for the conversation.
Attr OutputData output:
	Output from the dialog, including the response to the user, the nodes that were triggered, and log messages.

Attr list[LogMessage] log_messages:
	An array of up to 50 messages logged with the request.
Attr list[str] text:
	An array of responses to the user.
Attr list[str] nodes_visited:
	(optional) An array of the nodes that were triggered to create the response, in the order in which they were visited. This information is useful for debugging and for tracing the path taken through the node tree.
Attr list[DialogNodeVisitedDetails] nodes_visited_details:
	(optional) An array of objects containing detailed diagnostic information about the nodes that were triggered during processing of the input message. Included only if nodes_visited_details is set to true in the message request.

Attr str refresh_url:
	The URL that will return the same page of results.
Attr str next_url:
	(optional) The URL that will return the next page of results.
Attr int total:	(optional) Reserved for future use.
Attr int matched:
	(optional) Reserved for future use.
Attr str refresh_cursor:
	(optional) A token identifying the current page of results.
Attr str next_cursor:
	(optional) A token identifying the next page of results.

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.

Attr str intent:
	The name of the recognized intent.
Attr float confidence:
	A decimal percentage that represents Watson’s confidence in the intent.

Attr str synonym_text:
	The text of the synonym.
Attr datetime created:
	(optional) The timestamp for creation of the synonym.
Attr datetime updated:
	(optional) The timestamp for the most recent update to the synonym.

Attr list[Synonym] synonyms:
	An array of synonyms.
Attr Pagination pagination:
	The pagination data for the returned objects.