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’, **kwargs)

Bases: watson_developer_cloud.watson_developer_cloud_service.WatsonDeveloperCloudService

Client for the Conversation service.

default_url = ‘https://gateway.watsonplatform.net/conversation/api’

latest_version = ‘2017-04-21’

create_counterexample(workspace_id, text)

Create counterexample.

Add a new counterexample to a workspace. Counterexamples are examples that have been marked as irrelevant input.

Parameters:

• workspace_id – The workspace ID.
• text – The text of a user input example.

delete_counterexample(workspace_id, text)

Delete counterexample.

Delete a counterexample from a workspace. Counterexamples are examples that have been marked as irrelevant input.

Parameters:

• workspace_id – The workspace ID.
• text – The text of a user input counterexample (for example, What are you wearing?).

get_counterexample(workspace_id, text)

Get counterexample.

Get information about a counterexample. Counterexamples are examples that have been marked as irrelevant input.

Parameters:

• workspace_id – The workspace ID.
• text – The text of a user input counterexample (for example, What are you wearing?).

list_counterexamples(workspace_id, page_limit=None, include_count=None, sort=None, cursor=None)

List counterexamples.

List the counterexamples for a workspace. Counterexamples are examples that have been marked as irrelevant input.

Parameters:

• workspace_id – The workspace ID.
• page_limit – The number of records to return in each page of results. The default page limit is 100.
• include_count – Whether to include information about the number of records returned.
• sort – Sorts the response according to the value of the specified property, in ascending or descending order.
• cursor – A token identifying the last value from the previous page of results.

update_counterexample(workspace_id, text, new_text=None)

Update counterexample.

Update the text of a counterexample. Counterexamples are examples that have been marked as irrelevant input.

Parameters:

• workspace_id – The workspace ID.
• text – The text of a user input counterexample (for example, What are you wearing?).
• new_text – The new text of a user input counterexample.

create_entity(workspace_id, entity, description=None, metadata=None, values=None, fuzzy_match=None)

Create entity.

Create a new entity.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• description – The description of the entity.
• metadata – Any metadata related to the value.
• values – An array of entity values.
• fuzzy_match – Whether to use fuzzy matching for the entity.

delete_entity(workspace_id, entity)

Delete entity.

Delete an entity from a workspace.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.

get_entity(workspace_id, entity, export=None)

Get entity.

Get information about an entity, optionally including all entity content.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• export – 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. The default value is false.

list_entities(workspace_id, export=None, page_limit=None, include_count=None, sort=None, cursor=None)

List entities.

List the entities for a workspace.

Parameters:

• workspace_id – The workspace ID.
• export – 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. The default value is false.
• page_limit – The number of records to return in each page of results. The default page limit is 100.
• include_count – Whether to include information about the number of records returned.
• sort – Sorts the response according to the value of the specified property, in ascending or descending order.
• cursor – A token identifying the last value from the previous page of results.

update_entity(workspace_id, entity, new_entity=None, new_description=None, new_metadata=None, new_fuzzy_match=None, new_values=None)

Update entity.

Update an existing entity with new or modified data.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• new_entity – The new name of the entity.
• new_description – The new description of the entity.
• new_metadata – Any new metadata related to the entity.
• new_fuzzy_match – Whether to use fuzzy matching for the entity.
• new_values – A new array of entity values.

create_example(workspace_id, intent, text)

Create user input example.

Add a new user input example to an intent.

Parameters:

• workspace_id – The workspace ID.
• intent – The intent name (for example, pizza_order).
• text – The text of a user input example.

delete_example(workspace_id, intent, text)

Delete user input example.

Delete a user input example from an intent.

Parameters:

• workspace_id – The workspace ID.
• intent – The intent name (for example, pizza_order).
• text – The text of the user input example.

get_example(workspace_id, intent, text)

Get user input example.

Get information about a user input example.

Parameters:

• workspace_id – The workspace ID.
• intent – The intent name (for example, pizza_order).
• text – The text of the user input example.

list_examples(workspace_id, intent, page_limit=None, include_count=None, sort=None, cursor=None)

List user input examples.

List the user input examples for an intent.

Parameters:

• workspace_id – The workspace ID.
• intent – The intent name (for example, pizza_order).
• page_limit – The number of records to return in each page of results. The default page limit is 100.
• include_count – Whether to include information about the number of records returned.
• sort – Sorts the response according to the value of the specified property, in ascending or descending order.
• cursor – A token identifying the last value from the previous page of results.

update_example(workspace_id, intent, text, new_text=None)

Update user input example.

Update the text of a user input example.

Parameters:

• workspace_id – The workspace ID.
• intent – The intent name (for example, pizza_order).
• text – The text of the user input example.
• new_text – The text of the user input example.

create_intent(workspace_id, intent, description=None, examples=None)

Create intent.

Create a new intent.

Parameters:

• workspace_id – The workspace ID.
• intent – The name of the intent.
• description – The description of the intent.
• examples – An array of user input examples.

delete_intent(workspace_id, intent)

Delete intent.

Delete an intent from a workspace.

Parameters:

• workspace_id – The workspace ID.
• intent – The intent name (for example, pizza_order).

get_intent(workspace_id, intent, export=None)

Get intent.

Get information about an intent, optionally including all intent content.

Parameters:

• workspace_id – The workspace ID.
• intent – The intent name (for example, pizza_order).
• export – 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. The default value is false.

list_intents(workspace_id, export=None, page_limit=None, include_count=None, sort=None, cursor=None)

List intents.

List the intents for a workspace.

Parameters:

• workspace_id – The workspace ID.
• export – 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. The default value is false.
• page_limit – The number of records to return in each page of results. The default page limit is 100.
• include_count – Whether to include information about the number of records returned.
• sort – Sorts the response according to the value of the specified property, in ascending or descending order.
• cursor – A token identifying the last value from the previous page of results.

update_intent(workspace_id, intent, new_intent=None, new_description=None, new_examples=None)

Update intent.

Update an existing intent with new or modified data. You must provide data defining the content of the updated intent.

Parameters:

• workspace_id – The workspace ID.
• intent – The intent name (for example, pizza_order).
• new_intent – The new intent name.
• new_description – The description of the intent.
• new_examples – An array of new user input examples.

list_logs(workspace_id, sort=None, filter=None, page_limit=None, cursor=None)

List log events.

List log events associated with the given workspace.

Parameters:

• workspace_id – The workspace ID.
• sort – Sorts the response according to the value of the specified property, in ascending or descending order.
• filter – A cacheable parameter that limits the results to those matching the specified filter.
• page_limit – The number of records to return in each page of results. The default page limit is 100.
• cursor – A token identifying the last value from the previous page of results.

message(workspace_id, message_input, alternate_intents=None, context=None, entities=None, intents=None, output=None)

Get a response to a user’s input.

Send a user’s message and receive a response.

Parameters:

• workspace_id – Unique identifier of the workspace.
• message_input – An input object that includes the input text.
• alternate_intents – Whether to return more than one intent. Set to true to return all matching intents.
• context – State information for the conversation. Continue a conversation by including the context object from the previous response.
• entities – Include the entities from the previous response when they do not need to change and to prevent Watson from trying to identify them.
• intents – An array of name-confidence pairs for the user input. Include the intents from the previous response when they do not need to change and to prevent Watson from trying to identify them.
• output – System output. Include the output from the request when you have several requests within the same Dialog turn to pass back in the intermediate information.

create_synonym(workspace_id, entity, value, synonym)

Add entity value synonym.

Add a new synonym to an entity value.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.
• synonym – The text of the synonym.

delete_synonym(workspace_id, entity, value, synonym)

Delete entity value synonym.

Delete a synonym for an entity value.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.
• synonym – The text of the synonym.

get_synonym(workspace_id, entity, value, synonym)

Get entity value synonym.

Get information about a synonym for an entity value.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.
• synonym – The text of the synonym.

list_synonyms(workspace_id, entity, value, page_limit=None, include_count=None, sort=None, cursor=None)

List entity value synonyms.

List the synonyms for an entity value.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.
• page_limit – The number of records to return in each page of results. The default page limit is 100.
• include_count – Whether to include information about the number of records returned.
• sort – Sorts the response according to the value of the specified property, in ascending or descending order.
• cursor – A token identifying the last value from the previous page of results.

update_synonym(workspace_id, entity, value, synonym, new_synonym=None)

Update entity value synonym.

Update the information about a synonym for an entity value.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.
• synonym – The text of the synonym.
• new_synonym – The text of the synonym.

create_value(workspace_id, entity, value, metadata=None, synonyms=None)

Add entity value.

Create a new value for an entity.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.
• metadata – Any metadata related to the entity value.
• synonyms – Any array of synonyms for the entity value.

delete_value(workspace_id, entity, value)

Delete entity value.

Delete a value for an entity.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.

get_value(workspace_id, entity, value, export=None)

Get entity value.

Get information about an entity value.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.
• export – 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. The default value is false.

list_values(workspace_id, entity, export=None, page_limit=None, include_count=None, sort=None, cursor=None)

List entity values.

List the values for an entity.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• export – 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. The default value is false.
• page_limit – The number of records to return in each page of results. The default page limit is 100.
• include_count – Whether to include information about the number of records returned.
• sort – Sorts the response according to the value of the specified property, in ascending or descending order.
• cursor – A token identifying the last value from the previous page of results.

update_value(workspace_id, entity, value, new_value=None, new_metadata=None, new_synonyms=None)

Update entity value.

Update the content of a value for an entity.

Parameters:

• workspace_id – The workspace ID.
• entity – The name of the entity.
• value – The text of the entity value.
• new_value – The text of the entity value.
• new_metadata – Any metadata related to the entity value.
• new_synonyms – An array of synonyms for the entity value.

create_workspace(name=None, description=None, language=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None, metadata=None)

Create workspace.

Create a workspace based on component objects. You must provide workspace components defining the content of the new workspace.

Parameters:

• name – The name of the workspace.
• description – The description of the workspace.
• language – The language of the workspace.
• intents – An array of CreateIntent objects defining the intents for the workspace.
• entities – An array of CreateEntity objects defining the entities for the workspace.
• dialog_nodes – An array of CreateDialogNode objects defining the nodes in the workspace dialog.
• counterexamples – An array of CreateExample objects defining input examples that have been marked as irrelevant input.
• metadata – Any metadata related to the workspace.

delete_workspace(workspace_id)

Delete workspace.

Delete a workspace from the service instance.

Parameters:workspace_id – The workspace ID.

get_workspace(workspace_id, export=None)

Get information about a workspace.

Get information about a workspace, optionally including all workspace content.

Parameters:

• workspace_id – The workspace ID.
• export – 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. The default value is false.

list_workspaces(page_limit=None, include_count=None, sort=None, cursor=None)

List workspaces.

List the workspaces associated with a Conversation service instance.

Parameters:

• page_limit – The number of records to return in each page of results. The default page limit is 100.
• include_count – Whether to include information about the number of records returned.
• sort – Sorts the response according to the value of the specified property, in ascending or descending order.
• cursor – A token identifying the last value from the previous page of results.

update_workspace(workspace_id, name=None, description=None, language=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None, metadata=None)

Update workspace.

Update an existing workspace with new or modified data. You must provide component objects defining the content of the updated workspace.

Parameters:

• workspace_id – The workspace ID.
• name – The name of the workspace.
• description – The description of the workspace.
• language – The language of the workspace.
• intents – An array of CreateIntent objects defining the intents for the workspace.
• entities – An array of CreateEntity objects defining the entities for the workspace.
• dialog_nodes – An array of CreateDialogNode objects defining the nodes in the workspace dialog.
• counterexamples – An array of CreateExample objects defining input examples that have been marked as irrelevant input.
• metadata – Any metadata related to the workspace.