Curl Node Java Python

Watson Assistant

API reference

Introduction

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.

For details about using Watson Assistant, see the IBM® Cloud docs.

Authentication

IBM Cloud is migrating to token-based Identity and Access Management (IAM) authentication.

  • With some service instances, you authenticate to the API by using IAM. You can pass either a bearer token in an Authorization header or an API key. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. Learn more about IAM.

  • In other instances, you authenticate by providing the username and password for the service instance. For more information, see Service credentials for Watson services.

To find out which authentication to use, view the service credentials by clicking the service instance on the Dashboard. You can also access the service credentials from the Watson Assistant tool. From a workspace, select Deploy from the menu, and then go to the Credentials tab.

IAM authentication. Replace {apikey} and {url} with your service credentials.


curl -u "apikey:{apikey}" "{url}/{method}"
        

Basic authentication. Replace {username}, {password}, and {url} with your service credentials.


curl -u "{username}:{password}" "{url}/{method}"
        

Service endpoint

The service endpoint is based on the location of the service instance. If your API endpoint URL differs from the default, you must set your endpoint. For example, when Watson Assistant is hosted in Sydney, the base URL is https://gateway-syd.watsonplatform.net. The URL might also be different when you use IBM Cloud Dedicated.

To find out which URL to use, view the service credentials by clicking the service instance on the Dashboard. Use that URL in your requests to Watson Assistant. Set the correct service URL by calling the setEndPoint() method of the service instance. Set the correct service URL by using the url parameter when you create the service instance. Set the correct service URL by using the url parameter when you create the service instance or by calling the set_url() method of the service instance. Set the correct service URL by using the url parameter when you create the service instance or by calling the url= method of the service instance. Set the correct service URL by using the serviceURL property of the service instance.

Service endpoints by location:

  • US South: https://gateway.watsonplatform.net/assistant/api (Default)
  • US East: https://gateway-wdc.watsonplatform.net/assistant/api
  • Germany: https://gateway-fra.watsonplatform.net/assistant/api
  • Sydney: https://gateway-syd.watsonplatform.net/assistant/api
  • United Kingdom: https://gateway.watsonplatform.net/assistant/api

All locations might not support Watson Assistant. For details, see Services by region.

US South API endpoint

https://gateway.watsonplatform.net/assistant/api

Your service instance might not use this URL

Default URL

https://gateway.watsonplatform.net/assistant/api

Examples for the US East location in the constructor and after instantiation


Assistant assistant = new Assistant("{version}");
assistant.setEndPoint("https://gateway-wdc.watsonplatform.net/assistant/api");
                

var  = require('watson-developer-cloud/');

var watsonAssistant = new ({
    version: '{version}',
    iam_apikey: '{iam_api_key}',
    url: 'https://gateway-wdc.watsonplatform.net/assistant/api'
});
    
                    

assistant = (
    version='{version}',
    iam_apikey='{iam_api_key}',
    url='https://gateway-wdc.watsonplatform.net/assistant/api'
)

                    

or


assistant.set_url('https://gateway-wdc.watsonplatform.net/assistant/api')
                    

assistant = IBMWatson::.new(
  version: "{version}",
    iam_apikey: "{iam_api_key}",
  url: "https://gateway-wdc.watsonplatform.net/assistant/api"
)

                    

or


assistant.url = "https://gateway-wdc.watsonplatform.net/assistant/api"
                

let assistant = Assistant(username: "{username}", password: "{password}", version: "{version}")
assistant.serviceURL = "{url}"
                    

Versioning

API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. When we change the API in a backwards-incompatible way, we release a new version date.

Send the version parameter with every API request. The service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

Specify the version to use on API requests with the version parameter when you create the service instance. The service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

Error handling

The Watson Assistant service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error. Response codes are listed with the method.

ErrorResponse
Name Description
error string

General description of an error.

errors ErrorDetail[]

Collection of specific constraint violations associated with the error.

code integer

HTTP status code for the error response.

ErrorDetail
Name Description
message string

Description of a specific constraint violation.

path string

The location of the constraint violation.

Data handling

Data labels

You can remove customer data if you associate the customer and the data when you send the information to a service. First you label the data with a customer ID, and then you can delete the data by the ID.

  • Use the X-Watson-Metadata header to associate a customer ID with the data. By adding a customer ID to a request, you indicate that it contains data that belongs to that customer.

    Specify a random or generic string for the customer ID. Do not include personal data, such as an email address. Pass the string customer_id={id} as the argument of the header. For more information about how to pass headers, see Additional headers.

  • Use the Delete labeled data method to remove data that is associated with a customer ID.

Labeling data is used only by methods that accept customer data. For more information about Watson Assistant and labeling data, see Information security.

Data collection

By default, all Watson services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public. If you prefer that your data not be used for service improvements, use one of the following options:

  • To prevent IBM from accessing user input and Watson responses, set the X-Watson-Learning-Opt-Out header parameter to true when sending a message. You must set the header on each message request that you do not want IBM to access for general service improvements. You can set the header using the setDefaultHeaders method of the service object you use to send message requests that you do not want to be accessed. You can set the header using the headers parameter when you create the service object you use to create or update the workspace. You can set the header using the set_default_headers method of the service object you use to send message requests that you do not want to be accessed. You can set the header by using the add_default_headers method of the service object you use to send message requests that you do not want to be accessed.

  • To prevent IBM from accessing workspace training data such as intents and entities, set the X-Watson-Learning-Opt-Out header parameter to true when creating or updating a workspace. This option marks the workspace as opted out, and no training data for that workspace will be used. (This option does not apply to messages, which must be opted out individually.) You can set the header using the setDefaultHeaders method of the service object you use to create or update the workspace. You can set the header using the headers parameter when you create the service object you use to create or update the workspace. You can set the header using the set_default_headers method of the service object you use to create or update the workspace. You can set the header by using the add_default_headers method of the service object you use to create or update the workspace.

  • You can also mark a workspace as opted out by specifying a value of true for the learning_opt_out property in the JSON data used to create or update a workspace. This option applies only to training data, not to messages. (The HTTP header always overrides the JSON property, if both are specified.)

Example request


curl -u "apikey:{apikey}" -H "X-Watson-Learning-Opt-Out: true" "{url}/{method}"
            

Map<String, String> headers = new HashMap<String, String>();
headers.put("X-Watson-Learning-Opt-Out", "true");

assistant.setDefaultHeaders(headers);
            

var  = require('watson-developer-cloud/');

var watsonAssistant = new ({
  version: '{version}',
  iam_apikey: '{iam_api_key}',
  url: '{url}',
  headers: {
    'X-Watson-Learning-Opt-Out': 'true'
  }
});
            

assistant.set_default_headers({'x-watson-learning-opt-out': "true"})
            

assistant.add_default_headers(headers: {"x-watson-learning-opt-out" => "true"})
            

let assistant = Assistant(apiKey: "{iam_api_key}")
assistant.defaultHeaders = ["X-Watson-Learning-Opt-Out": "true"]
            

Rate limiting

Rate limits for API requests are enforced on a per-service-instance basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

The response to each HTTP request includes headers you can use to determine whether you are close to the rate limit:

  • X-RateLimit-Reset: the time the current timer expires (in UNIX epoch time)
  • X-RateLimit-Remaining: the number of requests remaining in the current time window
  • X-RateLimit-Limit: the total number of requests allowed within the time window

An HTTP status code of 429 indicates that the rate limit has been exceeded.

The number of allowed requests, and the length of the time window, vary by method and endpoint. The reference information for each endpoint specifies the rate limit that applies.

Pagination

Some API requests might return a large number of results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

  • /v1/workspaces
  • /v1/workspaces/{workspace_id}/counterexamples
  • /v1/workspaces/{workspace_id}/intents
  • /v1/workspaces/{workspace_id}/intents/{intent}/examples

The default page size is 100 objects. To use a different page size, use the page_limit query parameter.

To change the attribute by which results are sorted, use the sort query parameter. If you include multiple sort parameters on the same query, the results are sorted first by the first sorting attribute, then the second, and so on.

The supported sorting attributes vary by endpoint; for more information, see the API Reference information for each request.

For any request that uses pagination, the response includes a pagination object that specifies pagination information. This object includes two URLs you can use to make subsequent requests:

  • refresh_url: the URL for requesting the same page of results again.
  • next_url: the URL for requesting the next page of results. The next_url property is omitted if there no more results.

These URLs retain the same page_limit and sort parameters that were used for the initial request.

Pagination
Name Description
refresh_url string The URL that will return the same page of results.
next_url string The URL that will return the next page of results, if any.
total integer Reserved for future use.
matched integer Reserved for future use.

Message

Send user input to the service and receive a response.

Get response to user input

Get a response to a user's input.

There is no rate limit for this operation.

Request

POST /v1/workspaces/{workspace_id}/message
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body MessageRequest

The message to be sent. This includes the user's input, along with optional intents, entities, and context from the last response.

nodes_visited_details query boolean

Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the message.

false

MessageRequest

A message request formatted for the Watson Assistant service.

Name Description
input InputData

An input object that includes the input text.

alternate_intents boolean

Whether to return more than one intent. Set to true to return all matching intents.

false

context Context

State information for the conversation. Continue a conversation by including the context object from the previous response.

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

InputData

The user input.

Name Description
text string

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.

Context

State information for the conversation. To maintain state, include the context from the previous response.

Name Description
conversation_id string

The unique identifier of the conversation.

system SystemResponse

For internal use only.

RuntimeEntity

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

Name Description
entity string

An entity detected in the input.

location integer[]

An array of zero-based character offsets that indicate where the detected entity values begin and end in the input text.

value string

The term in the input text that was recognized as an entity value.

confidence number

A decimal percentage that represents Watson's confidence in the entity.

metadata object

Any metadata for the entity.

groups CaptureGroup[]

The recognized capture groups for the entity, as defined by the entity pattern.

CaptureGroup
Name Description
group string

A recognized capture group for the entity.

location integer[]

Zero-based character offsets that indicate where the entity value begins and ends in the input text.

RuntimeIntent

An intent identified in the user input.

Name Description
intent string

The name of the recognized intent.

confidence double

A decimal percentage that represents Watson's confidence in the intent.

OutputData

An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.

Name Description
log_messages LogMessage[]

An array of up to 50 messages logged with the request.

text string[]

An array of responses to the user.

generic DialogRuntimeResponseGeneric[]

Output intended for any channel. It is the responsibility of the client application to implement the supported response types.

nodes_visited string[]

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.

nodes_visited_details DialogNodeVisitedDetails[]

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.

LogMessage

Log message details.

Name Description
level string

The severity of the log message.

Allowable values:
  • info
  • error
  • warn
msg string

The text of the log message.

DialogRuntimeResponseGeneric
Name Description
response_type string

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.

Allowable values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
  • suggestion
text string

The text of the response.

time integer

How long to pause, in milliseconds.

typing boolean

Whether to send a "user is typing" event during the pause.

source string

The URL of the image.

title string

The title or introductory text to show before the response.

description string

The description to show with the the response.

preference string

The preferred type of control to display.

Allowable values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose.

message_to_human_agent string

A message to be sent to the human agent who will be taking over the conversation.

topic string

A label identifying the topic of the conversation, derived from the user_label property of the relevant node.

suggestions DialogSuggestion[]

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.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

DialogSuggestion
Name Description
label string

The user-facing label for the disambiguation option. This label is taken from the user_label property of the corresponding dialog node.

value DialogSuggestionValue

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

output object

The dialog output that will be returned from the Watson Assistant service if the user selects the corresponding option.

DialogSuggestionValue

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

Name Description
input InputData

The user input.

intents RuntimeIntent[]

An array of intents to be sent along with the user input.

entities RuntimeEntity[]

An array of entities to be sent along with the user input.

DialogNodeVisitedDetails
Name Description
dialog_node string

A dialog node that was triggered during processing of the input message.

title string

The title of the dialog node.

conditions string

The conditions that trigger the dialog node.

Example request

curl -X POST -u "{username}":"{password}" --header "Content-Type:application/json" --data "{\"input\": {\"text\": \"Hello\"}}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/message?version=2018-09-20"
        

Response

MessageResponse

A response from the Watson Assistant service.

Name Description
input MessageInput

The user input from the request.

intents RuntimeIntent[]

An array of intents recognized in the user input, sorted in descending order of confidence.

entities RuntimeEntity[]

An array of entities identified in the user input.

alternate_intents boolean

Whether to return more than one intent. A value of true indicates that all matching intents are returned.

context Context

State information for the conversation.

output OutputData

Output from the dialog, including the response to the user, the nodes that were triggered, and log messages.

actions DialogNodeAction[]

An array of objects describing any actions requested by the dialog node.

MessageInput

The text of the user input.

Name Description
text string

The user's input.

RuntimeIntent

An intent identified in the user input.

Name Description
intent string

The name of the recognized intent.

confidence double

A decimal percentage that represents Watson's confidence in the intent.

RuntimeEntity

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

Name Description
entity string

An entity detected in the input.

location integer[]

An array of zero-based character offsets that indicate where the detected entity values begin and end in the input text.

value string

The term in the input text that was recognized as an entity value.

confidence number

A decimal percentage that represents Watson's confidence in the entity.

metadata object

Any metadata for the entity.

groups CaptureGroup[]

The recognized capture groups for the entity, as defined by the entity pattern.

CaptureGroup
Name Description
group string

A recognized capture group for the entity.

location integer[]

Zero-based character offsets that indicate where the entity value begins and ends in the input text.

Context

State information for the conversation. To maintain state, include the context from the previous response.

Name Description
conversation_id string

The unique identifier of the conversation.

system SystemResponse

For internal use only.

OutputData

An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.

Name Description
log_messages LogMessage[]

An array of up to 50 messages logged with the request.

text string[]

An array of responses to the user.

generic DialogRuntimeResponseGeneric[]

Output intended for any channel. It is the responsibility of the client application to implement the supported response types.

nodes_visited string[]

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.

nodes_visited_details DialogNodeVisitedDetails[]

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.

LogMessage

Log message details.

Name Description
level string

The severity of the log message.

Possible values:
  • info
  • error
  • warn
msg string

The text of the log message.

DialogRuntimeResponseGeneric
Name Description
response_type string

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.

Possible values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
  • suggestion
text string

The text of the response.

time integer

How long to pause, in milliseconds.

typing boolean

Whether to send a "user is typing" event during the pause.

source string

The URL of the image.

title string

The title or introductory text to show before the response.

description string

The description to show with the the response.

preference string

The preferred type of control to display.

Possible values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose.

message_to_human_agent string

A message to be sent to the human agent who will be taking over the conversation.

topic string

A label identifying the topic of the conversation, derived from the user_label property of the relevant node.

suggestions DialogSuggestion[]

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.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogSuggestion
Name Description
label string

The user-facing label for the disambiguation option. This label is taken from the user_label property of the corresponding dialog node.

value DialogSuggestionValue

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

output object

The dialog output that will be returned from the Watson Assistant service if the user selects the corresponding option.

DialogSuggestionValue

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

Name Description
input InputData

The user input.

intents RuntimeIntent[]

An array of intents to be sent along with the user input.

entities RuntimeEntity[]

An array of entities to be sent along with the user input.

DialogNodeVisitedDetails
Name Description
dialog_node string

A dialog node that was triggered during processing of the input message.

title string

The title of the dialog node.

conditions string

The conditions that trigger the dialog node.

DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Possible values:
  • client
  • server
parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

Example response


{
  "intents" : [ {
    "intent" : "hello",
    "confidence" : 0.9755029201507568
  } ],
  "entities" : [ ],
  "input" : {
    "text" : "Hello"
  },
  "output" : {
    "generic" : [ {
      "response_type" : "text",
      "text" : "Hello! What can I do for you?"
    } ],
    "text" : [ "Hello! What can I do for you?" ],
    "nodes_visited" : [ "greeting" ],
    "log_messages" : [ ]
  },
  "context" : {
    "conversation_id" : "a96ec62f-773c-4e84-8be9-f9dbca9f83d0",
    "system" : {
      "dialog_stack" : [ {
        "dialog_node" : "root"
      } ],
      "dialog_turn_counter" : 1,
      "dialog_request_counter" : 1,
      "_node_output_map" : {
        "greeting" : {
          "0" : [ 0, 0 ]
        }
      },
      "branch_exited" : true,
      "branch_exited_reason" : "completed"
    }
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Workspaces

Create, update, and manage workspaces.

List workspaces

List the workspaces associated with a Watson Assistant service instance.

This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Request

GET /v1/workspaces
Parameter Description
version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

page_limit query integer

The number of records to return in each page of results.

100

include_count query boolean

Whether to include information about the number of records returned.

false

sort query string

The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

cursor query string

A token identifying the page of results to retrieve.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces?version=2018-09-20"
        

Response

WorkspaceCollection
Name Description
workspaces Workspace[]

An array of objects describing the workspaces associated with the service instance.

pagination Pagination

An object defining the pagination data for the returned objects.

Workspace
Name Description
name string

The name of the workspace.

language string

The language of the workspace.

created DateTime

The timestamp for creation of the workspace.

updated DateTime

The timestamp for the last update to the workspace.

workspace_id string

The workspace ID.

description string

The description of the workspace.

metadata object

Any metadata related to the workspace.

learning_opt_out boolean

Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

system_settings WorkspaceSystemSettings

Global settings for the workspace.

WorkspaceSystemSettings
Name Description
tooling WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant tool.

disambiguation WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

Note: This feature is available only to Premium users.

human_agent_assist object

For internal use only.

WorkspaceSystemSettingsTooling
Name Description
store_generic_responses boolean

Whether the dialog JSON editor displays text responses within the output.generic object.

WorkspaceSystemSettingsDisambiguation
Name Description
prompt string

The text of the introductory prompt that accompanies disambiguation options presented to the user.

none_of_the_above_prompt string

The user-facing label for the option users can select if none of the suggested options is correct. If no value is specified for this property, this option does not appear.

enabled boolean

Whether the disambiguation feature is enabled for the workspace.

sensitivity string

The sensitivity of the disambiguation feature to intent detection conflicts. Set to high if you want the disambiguation feature to be triggered more often. This can be useful for testing or demonstration purposes.

Possible values:
  • auto
  • high
Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "workspaces" : [ {
    "name" : "Car_Dashboard",
    "language" : "en",
    "metadata" : {
      "runtime_version" : "2018-09-20"
    },
    "description" : "Cognitive Car workspace which allows multi-turn conversations to perform tasks in the car.",
    "workspace_id" : "0a0c06c1-8e31-4655-9067-58fcac5134fc",
    "learning_opt_out" : false
  }, {
    "name" : "testing",
    "language" : "en",
    "metadata" : {
      "runtime_version" : "2018-09-20"
    },
    "workspace_id" : "e42c8e5c-eb34-4b65-99f0-59f9329b66ec",
    "learning_opt_out" : false
  }, {
    "name" : "workspace-example",
    "language" : "en",
    "metadata" : {
      "runtime_version" : "2018-09-20"
    },
    "description" : "Example workspace to try out the service",
    "workspace_id" : "293b58fc-3c5b-4ac5-a8f4-8d52c393d875",
    "learning_opt_out" : false
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces?version=2018-09-20"
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces
Parameter Description
version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body CreateWorkspace

The content of the new workspace.

The maximum size for this data is 50MB. If you need to import a larger workspace, consider importing the workspace without intents and entities and then adding them separately.

CreateWorkspace
Name Description
name string

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 string

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 string

The language of the workspace.

intents CreateIntent[]

An array of objects defining the intents for the workspace.

entities CreateEntity[]

An array of objects defining the entities for the workspace.

dialog_nodes CreateDialogNode[]

An array of objects defining the nodes in the workspace dialog.

counterexamples 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 boolean

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.

false

system_settings WorkspaceSystemSettings

Global settings for the workspace.

CreateIntent
Name Description
intent string

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 string

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 CreateExample[]

An array of user input examples for the intent.

CreateExample
Name Description
text string

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.
mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

CreateEntity
Name Description
entity string

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 string

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 CreateValue[]

An array of objects describing the entity values.

fuzzy_match boolean

Whether to use fuzzy matching for the entity.

CreateValue
Name Description
value string

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 string[]

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 string[]

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 512 characters. For more information about how to specify a pattern, see the documentation.

type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

CreateDialogNode
Name Description
dialog_node string

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 string

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 string

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 string

The ID of the parent dialog node.

previous_sibling string

The ID of the previous dialog node.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

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 DialogNodeAction[]

An array of objects describing any actions to be invoked by the dialog node.

title string

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.
type string

How the dialog node is processed.

Allowable values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Allowable values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

digress_in string

Whether this top-level dialog node can be digressed into.

Allowable values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Allowable values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Allowable values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Allowable values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Allowable values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

\n

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Allowable values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

true

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Allowable values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Allowable values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Allowable values:
  • client
  • server

client

parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

CreateCounterexample
Name Description
text string

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.
WorkspaceSystemSettings
Name Description
tooling WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant tool.

disambiguation WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

Note: This feature is available only to Premium users.

human_agent_assist object

For internal use only.

WorkspaceSystemSettingsTooling
Name Description
store_generic_responses boolean

Whether the dialog JSON editor displays text responses within the output.generic object.

WorkspaceSystemSettingsDisambiguation
Name Description
prompt string

The text of the introductory prompt that accompanies disambiguation options presented to the user.

none_of_the_above_prompt string

The user-facing label for the option users can select if none of the suggested options is correct. If no value is specified for this property, this option does not appear.

enabled boolean

Whether the disambiguation feature is enabled for the workspace.

false

sensitivity string

The sensitivity of the disambiguation feature to intent detection conflicts. Set to high if you want the disambiguation feature to be triggered more often. This can be useful for testing or demonstration purposes.

Allowable values:
  • auto
  • high

auto

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"name\":\"API test\",\"intents\":[],\"entities\":[],\"language\":\"en\",\"description\":\"Example workspace created via API.\",\"dialog_nodes\":[]}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces?version=2018-09-20"
        

Response

Workspace
Name Description
name string

The name of the workspace.

language string

The language of the workspace.

created DateTime

The timestamp for creation of the workspace.

updated DateTime

The timestamp for the last update to the workspace.

workspace_id string

The workspace ID.

description string

The description of the workspace.

metadata object

Any metadata related to the workspace.

learning_opt_out boolean

Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

system_settings WorkspaceSystemSettings

Global settings for the workspace.

WorkspaceSystemSettings
Name Description
tooling WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant tool.

disambiguation WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

Note: This feature is available only to Premium users.

human_agent_assist object

For internal use only.

WorkspaceSystemSettingsTooling
Name Description
store_generic_responses boolean

Whether the dialog JSON editor displays text responses within the output.generic object.

WorkspaceSystemSettingsDisambiguation
Name Description
prompt string

The text of the introductory prompt that accompanies disambiguation options presented to the user.

none_of_the_above_prompt string

The user-facing label for the option users can select if none of the suggested options is correct. If no value is specified for this property, this option does not appear.

enabled boolean

Whether the disambiguation feature is enabled for the workspace.

sensitivity string

The sensitivity of the disambiguation feature to intent detection conflicts. Set to high if you want the disambiguation feature to be triggered more often. This can be useful for testing or demonstration purposes.

Possible values:
  • auto
  • high

Example response


{
  "name" : "API test",
  "language" : "en",
  "description" : "Example workspace created via API.",
  "workspace_id" : "245edf96-b89f-46ac-b647-c6618b2eb5f0",
  "learning_opt_out" : false
}
        

Response Codes

Status Description
201

Successful request.

400

Invalid request.

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.

Request

GET /v1/workspaces/{workspace_id}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

export query boolean

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.

false

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/394927d3-bf81-40d8-8cb5-368a13f60fee?version=2018-09-20"
        

Response

WorkspaceExport
Name Description
name string

The name of the workspace.

description string

The description of the workspace.

language string

The language of the workspace.

metadata object

Any metadata that is required by the workspace.

created DateTime

The timestamp for creation of the workspace.

updated DateTime

The timestamp for the last update to the workspace.

workspace_id string

The workspace ID.

status string

The current status of the workspace.

Possible values:
  • Non Existent
  • Training
  • Failed
  • Available
  • Unavailable
learning_opt_out boolean

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.

system_settings WorkspaceSystemSettings

Global settings for the workspace.

intents IntentExport[]

An array of intents.

entities EntityExport[]

An array of entities.

counterexamples Counterexample[]

An array of counterexamples.

dialog_nodes DialogNode[]

An array of objects describing the dialog nodes in the workspace.

WorkspaceSystemSettings
Name Description
tooling WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant tool.

disambiguation WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

Note: This feature is available only to Premium users.

human_agent_assist object

For internal use only.

WorkspaceSystemSettingsTooling
Name Description
store_generic_responses boolean

Whether the dialog JSON editor displays text responses within the output.generic object.

WorkspaceSystemSettingsDisambiguation
Name Description
prompt string

The text of the introductory prompt that accompanies disambiguation options presented to the user.

none_of_the_above_prompt string

The user-facing label for the option users can select if none of the suggested options is correct. If no value is specified for this property, this option does not appear.

enabled boolean

Whether the disambiguation feature is enabled for the workspace.

sensitivity string

The sensitivity of the disambiguation feature to intent detection conflicts. Set to high if you want the disambiguation feature to be triggered more often. This can be useful for testing or demonstration purposes.

Possible values:
  • auto
  • high
IntentExport
Name Description
intent string

The name of the intent.

created DateTime

The timestamp for creation of the intent.

updated DateTime

The timestamp for the last update to the intent.

description string

The description of the intent.

examples Example[]

An array of objects describing the user input examples for the intent.

Example
Name Description
text string

The text of the user input example.

created DateTime

The timestamp for creation of the example.

updated DateTime

The timestamp for the last update to the example.

mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

EntityExport
Name Description
entity string

The name of the entity.

created DateTime

The timestamp for creation of the entity.

updated DateTime

The timestamp for the last update to the entity.

description string

The description of the entity.

metadata object

Any metadata related to the entity.

fuzzy_match boolean

Whether fuzzy matching is used for the entity.

values ValueExport[]

An array objects describing the entity values.

ValueExport
Name Description
value string

The text of the entity value.

metadata object

Any metadata related to the entity value.

created DateTime

The timestamp for creation of the entity value.

updated DateTime

The timestamp for the last update to the entity value.

synonyms string[]

An array containing any synonyms for the entity value.

patterns string[]

An array containing any patterns for the entity value.

type string

Specifies the type of value.

Possible values:
  • synonyms
  • patterns
Counterexample
Name Description
text string

The text of the counterexample.

created DateTime

The timestamp for creation of the counterexample.

updated DateTime

The timestamp for the last update to the counterexample.

DialogNode
Name Description
dialog_node string

The dialog node ID.

description string

The description of the dialog node.

conditions string

The condition that triggers the dialog node.

parent string

The ID of the parent dialog node. This property is not returned if the dialog node has no parent.

previous_sibling string

The ID of the previous sibling dialog node. This property is not returned if the dialog node has no previous sibling.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

context object

The context (if defined) for the dialog node.

metadata object

Any metadata for the dialog node.

next_step DialogNodeNextStep

The next step to execute following this dialog node.

created DateTime

The timestamp for creation of the dialog node.

updated DateTime

The timestamp for the most recent update to the dialog node.

actions DialogNodeAction[]

The actions for the dialog node.

title string

The alias used to identify the dialog node.

type string

How the dialog node is processed.

Possible values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Possible values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

digress_in string

Whether this top-level dialog node can be digressed into.

Possible values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Possible values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Possible values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Possible values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Possible values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Possible values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Possible values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Possible values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Possible values:
  • client
  • server
parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

Example response


{
  "name" : "Pizza app",
  "language" : "en",
  "metadata" : { },
  "description" : "Pizza app",
  "status" : "Available",
  "workspace_id" : "pizza_app-e0f3",
  "learning_opt_out" : false
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body UpdateWorkspace

Valid data defining the new and updated workspace content.

The maximum size for this data is 50MB. If you need to import a larger amount of workspace data, consider importing components such as intents and entities using separate operations.

append query boolean

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.

false

UpdateWorkspace
Name Description
name string

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 string

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 string

The language of the workspace.

intents CreateIntent[]

An array of objects defining the intents for the workspace.

entities CreateEntity[]

An array of objects defining the entities for the workspace.

dialog_nodes CreateDialogNode[]

An array of objects defining the nodes in the workspace dialog.

counterexamples 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 boolean

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.

false

system_settings WorkspaceSystemSettings

Global settings for the workspace.

CreateIntent
Name Description
intent string

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 string

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 CreateExample[]

An array of user input examples for the intent.

CreateExample
Name Description
text string

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.
mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

CreateEntity
Name Description
entity string

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 string

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 CreateValue[]

An array of objects describing the entity values.

fuzzy_match boolean

Whether to use fuzzy matching for the entity.

CreateValue
Name Description
value string

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 string[]

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 string[]

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 512 characters. For more information about how to specify a pattern, see the documentation.

type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

CreateDialogNode
Name Description
dialog_node string

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 string

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 string

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 string

The ID of the parent dialog node.

previous_sibling string

The ID of the previous dialog node.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

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 DialogNodeAction[]

An array of objects describing any actions to be invoked by the dialog node.

title string

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.
type string

How the dialog node is processed.

Allowable values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Allowable values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

digress_in string

Whether this top-level dialog node can be digressed into.

Allowable values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Allowable values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Allowable values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Allowable values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Allowable values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

\n

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Allowable values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

true

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Allowable values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Allowable values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Allowable values:
  • client
  • server

client

parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

CreateCounterexample
Name Description
text string

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.
WorkspaceSystemSettings
Name Description
tooling WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant tool.

disambiguation WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

Note: This feature is available only to Premium users.

human_agent_assist object

For internal use only.

WorkspaceSystemSettingsTooling
Name Description
store_generic_responses boolean

Whether the dialog JSON editor displays text responses within the output.generic object.

WorkspaceSystemSettingsDisambiguation
Name Description
prompt string

The text of the introductory prompt that accompanies disambiguation options presented to the user.

none_of_the_above_prompt string

The user-facing label for the option users can select if none of the suggested options is correct. If no value is specified for this property, this option does not appear.

enabled boolean

Whether the disambiguation feature is enabled for the workspace.

false

sensitivity string

The sensitivity of the disambiguation feature to intent detection conflicts. Set to high if you want the disambiguation feature to be triggered more often. This can be useful for testing or demonstration purposes.

Allowable values:
  • auto
  • high

auto

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"name\":\"Updated workspace\",\"intents\":[],\"entities\":[],\"language\":\"en\",\"description\":\"Example workspace updated via API.\",\"dialog_nodes\":[]}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/394927d3-bf81-40d8-8cb5-368a13f60fee?version=2018-09-20"
        

Response

Workspace
Name Description
name string

The name of the workspace.

language string

The language of the workspace.

created DateTime

The timestamp for creation of the workspace.

updated DateTime

The timestamp for the last update to the workspace.

workspace_id string

The workspace ID.

description string

The description of the workspace.

metadata object

Any metadata related to the workspace.

learning_opt_out boolean

Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used.

system_settings WorkspaceSystemSettings

Global settings for the workspace.

WorkspaceSystemSettings
Name Description
tooling WorkspaceSystemSettingsTooling

Workspace settings related to the Watson Assistant tool.

disambiguation WorkspaceSystemSettingsDisambiguation

Workspace settings related to the disambiguation feature.

Note: This feature is available only to Premium users.

human_agent_assist object

For internal use only.

WorkspaceSystemSettingsTooling
Name Description
store_generic_responses boolean

Whether the dialog JSON editor displays text responses within the output.generic object.

WorkspaceSystemSettingsDisambiguation
Name Description
prompt string

The text of the introductory prompt that accompanies disambiguation options presented to the user.

none_of_the_above_prompt string

The user-facing label for the option users can select if none of the suggested options is correct. If no value is specified for this property, this option does not appear.

enabled boolean

Whether the disambiguation feature is enabled for the workspace.

sensitivity string

The sensitivity of the disambiguation feature to intent detection conflicts. Set to high if you want the disambiguation feature to be triggered more often. This can be useful for testing or demonstration purposes.

Possible values:
  • auto
  • high

Example response


{
  "name" : "Updated workspace",
  "language" : "en",
  "description" : "Example workspace modified via API",
  "workspace_id" : "164cca2d-8af7-4034-a121-89049a665183",
  "learning_opt_out" : false
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

DELETE /v1/workspaces/{workspace_id}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/394927d3-bf81-40d8-8cb5-368a13f60fee?version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Intents

Create, update, and manage intents.

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.

Request

GET /v1/workspaces/{workspace_id}/intents
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

export query boolean

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.

false

page_limit query integer

The number of records to return in each page of results.

100

include_count query boolean

Whether to include information about the number of records returned.

false

sort query string

The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

cursor query string

A token identifying the page of results to retrieve.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2018-09-20"
        

Response

IntentCollection
Name Description
intents IntentExport[]

An array of objects describing the intents defined for the workspace.

pagination Pagination

The pagination data for the returned objects.

IntentExport
Name Description
intent string

The name of the intent.

created DateTime

The timestamp for creation of the intent.

updated DateTime

The timestamp for the last update to the intent.

description string

The description of the intent.

examples Example[]

An array of objects describing the user input examples for the intent.

Example
Name Description
text string

The text of the user input example.

created DateTime

The timestamp for creation of the example.

updated DateTime

The timestamp for the last update to the example.

mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "intents" : [ {
    "intent" : "goodbye"
  }, {
    "intent" : "hello"
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2017-08-21"
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Create intent

Create a new intent.

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

Request

POST /v1/workspaces/{workspace_id}/intents
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body CreateIntent

The content of the new intent.

CreateIntent
Name Description
intent string

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 string

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 CreateExample[]

An array of user input examples for the intent.

CreateExample
Name Description
text string

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.
mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"intent\":\"hello\",\"examples\":[{\"text\":\"Good morning\"},{\"text\":\"Hi there\"}]}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents?version=2018-09-20"
        

Response

Intent
Name Description
intent string

The name of the intent.

created DateTime

The timestamp for creation of the intent.

updated DateTime

The timestamp for the last update to the intent.

description string

The description of the intent.

Example response


{
  "intent" : "hello"
}
        

Response Codes

Status Description
201

Successful request.

400

Invalid request.

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.

Request

GET /v1/workspaces/{workspace_id}/intents/{intent}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

intent path string

The intent name.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

export query boolean

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.

false

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello?version=2018-09-20"
        

Response

IntentExport
Name Description
intent string

The name of the intent.

created DateTime

The timestamp for creation of the intent.

updated DateTime

The timestamp for the last update to the intent.

description string

The description of the intent.

examples Example[]

An array of objects describing the user input examples for the intent.

Example
Name Description
text string

The text of the user input example.

created DateTime

The timestamp for creation of the example.

updated DateTime

The timestamp for the last update to the example.

mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Example response


{
  "intent" : "hello"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/intents/{intent}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

intent path string

The intent name.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body UpdateIntent

The updated content of the intent.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the user input examples for an intent, the previously existing examples are discarded and replaced with the new examples specified in the update.

UpdateIntent
Name Description
intent string

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 string

The description of the intent.

examples CreateExample[]

An array of user input examples for the intent.

CreateExample
Name Description
text string

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.
mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"intent\":\"hello\",\"examples\":[{\"text\":\"Good afternoon\"}],\"description\":\"Updated intent\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello?version=2018-09-20"
        

Response

Intent
Name Description
intent string

The name of the intent.

created DateTime

The timestamp for creation of the intent.

updated DateTime

The timestamp for the last update to the intent.

description string

The description of the intent.

Example response


{
  "intent" : "hello",
  "description" : "Updated intent"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Delete intent

Delete an intent from a workspace.

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

Request

DELETE /v1/workspaces/{workspace_id}/intents/{intent}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

intent path string

The intent name.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello?version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Examples

Create, update, and manage intent user input examples.

List user input examples

List the user input examples for an intent, optionally including contextual entity mentions.

This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Request

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples
Parameter Description
workspace_id path string

Unique identifier of the workspace.

intent path string

The intent name.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

page_limit query integer

The number of records to return in each page of results.

100

include_count query boolean

Whether to include information about the number of records returned.

false

sort query string

The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

cursor query string

A token identifying the page of results to retrieve.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2018-09-20&export=true"
        

Response

ExampleCollection
Name Description
examples Example[]

An array of objects describing the examples defined for the intent.

pagination Pagination

The pagination data for the returned objects.

Example
Name Description
text string

The text of the user input example.

created DateTime

The timestamp for creation of the example.

updated DateTime

The timestamp for the last update to the example.

mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "examples" : [ {
    "text" : "Good afternoon"
  }, {
    "text" : "hi there"
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2018-09-20&export=true"
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples
Parameter Description
workspace_id path string

Unique identifier of the workspace.

intent path string

The intent name.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body CreateExample

The content of the new user input example.

CreateExample
Name Description
text string

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.
mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"text\":\"Howdy!\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples?version=2018-09-20"
        

Response

Example
Name Description
text string

The text of the user input example.

created DateTime

The timestamp for creation of the example.

updated DateTime

The timestamp for the last update to the example.

mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Example response


{
  "text" : "Howdy!"
}
        

Response Codes

Status Description
201

Successful request.

400

Invalid request.

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.

Request

GET /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

intent path string

The intent name.

text path string

The text of the user input example.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples/Good%20afternoon?version=2018-09-20"
        

Response

Example
Name Description
text string

The text of the user input example.

created DateTime

The timestamp for creation of the example.

updated DateTime

The timestamp for the last update to the example.

mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Example response


{
  "text" : "Good afternoon"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

intent path string

The intent name.

text path string

The text of the user input example.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body UpdateExample

The new text of the user input example.

UpdateExample
Name Description
text string

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.
mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"text\":\"Hello there!\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples/hi%20there?version=2018-09-20"
        

Response

Example
Name Description
text string

The text of the user input example.

created DateTime

The timestamp for creation of the example.

updated DateTime

The timestamp for the last update to the example.

mentions Mentions[]

An array of contextual entity mentions.

Mentions

A mention of a contextual entity.

Name Description
entity string

The name of the entity.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Example response


{
  "text" : "Hello there!"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

DELETE /v1/workspaces/{workspace_id}/intents/{intent}/examples/{text}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

intent path string

The intent name.

text path string

The text of the user input example.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/intents/hello/examples/Good%20afternoon?version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
200

Successful request.

400

Invalid request

Counterexamples

Create, update, and manage user input examples that are marked as irrelevant input.

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.

Request

GET /v1/workspaces/{workspace_id}/counterexamples
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

page_limit query integer

The number of records to return in each page of results.

100

include_count query boolean

Whether to include information about the number of records returned.

false

sort query string

The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

cursor query string

A token identifying the page of results to retrieve.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2018-09-20"
        

Response

CounterexampleCollection
Name Description
counterexamples Counterexample[]

An array of objects describing the examples marked as irrelevant input.

pagination Pagination

The pagination data for the returned objects.

Counterexample
Name Description
text string

The text of the counterexample.

created DateTime

The timestamp for creation of the counterexample.

updated DateTime

The timestamp for the last update to the counterexample.

Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "counterexamples" : [ {
    "text" : "What are you wearing?"
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2018-09-20"
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/counterexamples
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body CreateCounterexample

The content of the new counterexample.

CreateCounterexample
Name Description
text string

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.
Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"text\":\"Make me a sandwich\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples?version=2018-09-20"
        

Response

Counterexample
Name Description
text string

The text of the counterexample.

created DateTime

The timestamp for creation of the counterexample.

updated DateTime

The timestamp for the last update to the counterexample.

Example response


{
  "text" : "Make me a sandwich"
}
        

Response Codes

Status Description
201

Successful request.

400

Invalid request.

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.

Request

GET /v1/workspaces/{workspace_id}/counterexamples/{text}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

text path string

The text of a user input counterexample (for example, What are you wearing?).

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples/What%20are%20you%20wearing%3F?version=2018-09-20"
        

Response

Counterexample
Name Description
text string

The text of the counterexample.

created DateTime

The timestamp for creation of the counterexample.

updated DateTime

The timestamp for the last update to the counterexample.

Example response


{
  "text" : "What are you wearing?"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/counterexamples/{text}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

text path string

The text of a user input counterexample (for example, What are you wearing?).

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body UpdateCounterexample

The text of the counterexample.

UpdateCounterexample
Name Description
text string

The text of a user input counterexample.

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"text\":\"Make me a cheeseburger!\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples/Make%20me%20a%20sandwich?version=2018-09-20"
        

Response

Counterexample
Name Description
text string

The text of the counterexample.

created DateTime

The timestamp for creation of the counterexample.

updated DateTime

The timestamp for the last update to the counterexample.

Example response


{
  "text" : "Make me a cheeseburger!"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

DELETE /v1/workspaces/{workspace_id}/counterexamples/{text}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

text path string

The text of a user input counterexample (for example, What are you wearing?).

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/counterexamples/Make%20me%20a%20sandwich?version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Entities

Create, update, and manage entities.

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.

Request

GET /v1/workspaces/{workspace_id}/entities
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

export query boolean

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.

false

page_limit query integer

The number of records to return in each page of results.

100

include_count query boolean

Whether to include information about the number of records returned.

false

sort query string

The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

cursor query string

A token identifying the page of results to retrieve.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities?version=2018-09-20"
        

Response

EntityCollection

An array of entities.

Name Description
entities EntityExport[]

An array of objects describing the entities defined for the workspace.

pagination Pagination

The pagination data for the returned objects.

EntityExport
Name Description
entity string

The name of the entity.

created DateTime

The timestamp for creation of the entity.

updated DateTime

The timestamp for the last update to the entity.

description string

The description of the entity.

metadata object

Any metadata related to the entity.

fuzzy_match boolean

Whether fuzzy matching is used for the entity.

values ValueExport[]

An array objects describing the entity values.

ValueExport
Name Description
value string

The text of the entity value.

metadata object

Any metadata related to the entity value.

created DateTime

The timestamp for creation of the entity value.

updated DateTime

The timestamp for the last update to the entity value.

synonyms string[]

An array containing any synonyms for the entity value.

patterns string[]

An array containing any patterns for the entity value.

type string

Specifies the type of value.

Possible values:
  • synonyms
  • patterns
Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "entities" : [ {
    "entity" : "animal"
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities?version=2018-09-20"
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Create entity

Create a new entity.

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

Request

POST /v1/workspaces/{workspace_id}/entities
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body CreateEntity

The content of the new entity.

CreateEntity
Name Description
entity string

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 string

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 CreateValue[]

An array of objects describing the entity values.

fuzzy_match boolean

Whether to use fuzzy matching for the entity.

CreateValue
Name Description
value string

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 string[]

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 string[]

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 512 characters. For more information about how to specify a pattern, see the documentation.

type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"entity\": \"beverage\",\"values\":[{\"value\":\"water\"},{\"value\":\"orange juice\"},{\"value\":\"soda\"}]}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities?version=2018-09-20"
        

Response

Entity
Name Description
entity string

The name of the entity.

created DateTime

The timestamp for creation of the entity.

updated DateTime

The timestamp for the last update to the entity.

description string

The description of the entity.

metadata object

Any metadata related to the entity.

fuzzy_match boolean

Whether fuzzy matching is used for the entity.

Example response


{
  "entity" : "beverage"
}
        

Response Codes

Status Description
201

Successful request.

400

Invalid request.

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.

Request

GET /v1/workspaces/{workspace_id}/entities/{entity}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

export query boolean

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.

false

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage?version=2018-09-20"
        

Response

EntityExport
Name Description
entity string

The name of the entity.

created DateTime

The timestamp for creation of the entity.

updated DateTime

The timestamp for the last update to the entity.

description string

The description of the entity.

metadata object

Any metadata related to the entity.

fuzzy_match boolean

Whether fuzzy matching is used for the entity.

values ValueExport[]

An array objects describing the entity values.

ValueExport
Name Description
value string

The text of the entity value.

metadata object

Any metadata related to the entity value.

created DateTime

The timestamp for creation of the entity value.

updated DateTime

The timestamp for the last update to the entity value.

synonyms string[]

An array containing any synonyms for the entity value.

patterns string[]

An array containing any patterns for the entity value.

type string

Specifies the type of value.

Possible values:
  • synonyms
  • patterns

Example response


{
  "entity" : "beverage"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/entities/{entity}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body UpdateEntity

The updated content of the entity. Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the values for an entity, the previously existing values are discarded and replaced with the new values specified in the update.

UpdateEntity
Name Description
entity string

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 string

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

fuzzy_match boolean

Whether to use fuzzy matching for the entity.

values CreateValue[]

An array of entity values.

CreateValue
Name Description
value string

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 string[]

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 string[]

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 512 characters. For more information about how to specify a pattern, see the documentation.

type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"description\":\"Liquid refreshment\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage?version=2018-09-20"
        

Response

Entity
Name Description
entity string

The name of the entity.

created DateTime

The timestamp for creation of the entity.

updated DateTime

The timestamp for the last update to the entity.

description string

The description of the entity.

metadata object

Any metadata related to the entity.

fuzzy_match boolean

Whether fuzzy matching is used for the entity.

Example response


{
  "entity" : "beverage",
  "description" : "Liquid refreshment"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Delete entity

Delete an entity from a workspace.

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

Request

DELETE /v1/workspaces/{workspace_id}/entities/{entity}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage?version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Mentions

Create, update, and manage entity mentions in the context of user input examples.

List entity mentions

List mentions for a contextual entity. An entity mention is an occurrence of a contextual entity in the context of an intent user input example.

This operation is limited to 200 requests per 30 minutes. For more information, see Rate limiting.

Request

GET /v1/workspaces/{workspace_id}/entities/{entity}/mentions
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

export query boolean

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.

false

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}:{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/mentions?version=2018-09-20"
        

Response

EntityMentionCollection
Name Description
examples EntityMention[]

An array of objects describing the entity mentions defined for an entity.

pagination Pagination

The pagination data for the returned objects.

EntityMention

An object describing a contextual entity mention.

Name Description
text string

The text of the user input example.

intent string

The name of the intent.

location integer[]

An array of zero-based character offsets that indicate where the entity mentions begin and end in the input text.

Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "examples" : [ {
    "text" : "Can I get a soda?",
    "intent" : "place_order",
    "location" : [ 12, 16 ]
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/mentions?version=2018-09-20"
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Values

Create, update, and manage entity values.

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.

Request

GET /v1/workspaces/{workspace_id}/entities/{entity}/values
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

export query boolean

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.

false

page_limit query integer

The number of records to return in each page of results.

100

include_count query boolean

Whether to include information about the number of records returned.

false

sort query string

The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

cursor query string

A token identifying the page of results to retrieve.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2018-09-20"
        

Response

ValueCollection
Name Description
values ValueExport[]

An array of entity values.

pagination Pagination

An object defining the pagination data for the returned objects.

ValueExport
Name Description
value string

The text of the entity value.

metadata object

Any metadata related to the entity value.

created DateTime

The timestamp for creation of the entity value.

updated DateTime

The timestamp for the last update to the entity value.

synonyms string[]

An array containing any synonyms for the entity value.

patterns string[]

An array containing any patterns for the entity value.

type string

Specifies the type of value.

Possible values:
  • synonyms
  • patterns
Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "values" : [ {
    "type" : "synonyms",
    "value" : "orange juice"
  }, {
    "type" : "synonyms",
    "value" : "soda"
  }, {
    "type" : "synonyms",
    "value" : "water"
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2018-09-20"
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/entities/{entity}/values
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body CreateValue

The new entity value.

CreateValue
Name Description
value string

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 string[]

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 string[]

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 512 characters. For more information about how to specify a pattern, see the documentation.

type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"value\":\"beer\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values?version=2018-09-20"
        

Response

Value
Name Description
value string

The text of the entity value.

metadata object

Any metadata related to the entity value.

created DateTime

The timestamp for creation of the entity value.

updated DateTime

The timestamp for the last update to the entity value.

synonyms string[]

An array containing any synonyms for the entity value.

patterns string[]

An array containing any patterns for the entity value.

type string

Specifies the type of value.

Possible values:
  • synonyms
  • patterns

Example response


{
  "type" : "synonyms",
  "value" : "beer"
}
        

Response Codes

Status Description
201

Successful request.

400

Invalid request.

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.

Request

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

value path string

The text of the entity value.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

export query boolean

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.

false

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice?version=2018-09-20"
        

Response

ValueExport
Name Description
value string

The text of the entity value.

metadata object

Any metadata related to the entity value.

created DateTime

The timestamp for creation of the entity value.

updated DateTime

The timestamp for the last update to the entity value.

synonyms string[]

An array containing any synonyms for the entity value.

patterns string[]

An array containing any patterns for the entity value.

type string

Specifies the type of value.

Possible values:
  • synonyms
  • patterns

Example response


{
  "type" : "synonyms",
  "value" : "orange juice"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

value path string

The text of the entity value.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body UpdateValue

The updated content of the entity value.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the synonyms for an entity value, the previously existing synonyms are discarded and replaced with the new synonyms specified in the update.

UpdateValue
Name Description
value string

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.

type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

synonyms string[]

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.
patterns string[]

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 512 characters. For more information about how to specify a pattern, see the documentation.

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"synonyms\":[\"pop\",\"soft drink\"]}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/soda?version=2018-09-20"
        

Response

Value
Name Description
value string

The text of the entity value.

metadata object

Any metadata related to the entity value.

created DateTime

The timestamp for creation of the entity value.

updated DateTime

The timestamp for the last update to the entity value.

synonyms string[]

An array containing any synonyms for the entity value.

patterns string[]

An array containing any patterns for the entity value.

type string

Specifies the type of value.

Possible values:
  • synonyms
  • patterns

Example response


{
  "type" : "synonyms",
  "value" : "soda"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

value path string

The text of the entity value.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/beer?version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Synonyms

Create, update, and manage entity value synonyms.

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.

Request

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

value path string

The text of the entity value.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

page_limit query integer

The number of records to return in each page of results.

100

include_count query boolean

Whether to include information about the number of records returned.

false

sort query string

The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

cursor query string

A token identifying the page of results to retrieve.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/soda/synonyms?version=2018-09-20"
        

Response

SynonymCollection
Name Description
synonyms Synonym[]

An array of synonyms.

pagination Pagination

The pagination data for the returned objects.

Synonym
Name Description
synonym string

The text of the synonym.

created DateTime

The timestamp for creation of the synonym.

updated DateTime

The timestamp for the most recent update to the synonym.

Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "synonyms" : [ {
    "synonym" : "pop"
  }, {
    "synonym" : "soft drink"
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/entities/beverage/values/soda/synonyms?version=2018-09-20"
  }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

value path string

The text of the entity value.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body CreateSynonym

The new synonym.

CreateSynonym
Name Description
synonym string

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.
Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"synonym\":\"OJ\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice/synonyms?version=2018-09-20"
        

Response

Synonym
Name Description
synonym string

The text of the synonym.

created DateTime

The timestamp for creation of the synonym.

updated DateTime

The timestamp for the most recent update to the synonym.

Example response


{
  "synonym" : "OJ"
}
        

Response Codes

Status Description
201

Successful request.

400

Invalid request.

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.

Request

GET /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

value path string

The text of the entity value.

synonym path string

The text of the synonym.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

@curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice/synonyms/OJ?version=2018-09-20"
        

Response

Synonym
Name Description
synonym string

The text of the synonym.

created DateTime

The timestamp for creation of the synonym.

updated DateTime

The timestamp for the most recent update to the synonym.

Example response


{
  "synonym" : "OJ"
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

POST /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

value path string

The text of the entity value.

synonym path string

The text of the synonym.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body UpdateSynonym

The updated entity value synonym.

UpdateSynonym
Name Description
synonym string

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.
Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"synonym\":\"O.J.\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice/synonyms/OJ?version=2018-09-20"
        

Response

Synonym
Name Description
synonym string

The text of the synonym.

created DateTime

The timestamp for creation of the synonym.

updated DateTime

The timestamp for the most recent update to the synonym.

Example response


{
  "synonym" : "O.J."
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

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.

Request

DELETE /v1/workspaces/{workspace_id}/entities/{entity}/values/{value}/synonyms/{synonym}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

entity path string

The name of the entity.

value path string

The text of the entity value.

synonym path string

The text of the synonym.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/entities/beverage/values/orange%20juice/synonyms/OJ?version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
200

Successful request.

400

Invalid request.

Dialog nodes

Create, update, and manage dialog nodes.

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.

Request

GET /v1/workspaces/{workspace_id}/dialog_nodes
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

page_limit query integer

The number of records to return in each page of results.

100

include_count query boolean

Whether to include information about the number of records returned.

false

sort query string

The attribute by which returned results will be sorted. To reverse the sort order, prefix the value with a minus sign (-).

cursor query string

A token identifying the page of results to retrieve.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/dialog_nodes?version=2018-09-20"
        

Response

DialogNodeCollection

An array of dialog nodes.

Name Description
dialog_nodes DialogNode[]

An array of objects describing the dialog nodes defined for the workspace.

pagination Pagination

The pagination data for the returned objects.

DialogNode
Name Description
dialog_node string

The dialog node ID.

description string

The description of the dialog node.

conditions string

The condition that triggers the dialog node.

parent string

The ID of the parent dialog node. This property is not returned if the dialog node has no parent.

previous_sibling string

The ID of the previous sibling dialog node. This property is not returned if the dialog node has no previous sibling.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

context object

The context (if defined) for the dialog node.

metadata object

Any metadata for the dialog node.

next_step DialogNodeNextStep

The next step to execute following this dialog node.

created DateTime

The timestamp for creation of the dialog node.

updated DateTime

The timestamp for the most recent update to the dialog node.

actions DialogNodeAction[]

The actions for the dialog node.

title string

The alias used to identify the dialog node.

type string

How the dialog node is processed.

Possible values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Possible values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

digress_in string

Whether this top-level dialog node can be digressed into.

Possible values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Possible values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Possible values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Possible values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Possible values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Possible values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Possible values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Possible values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Possible values:
  • client
  • server
parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

Pagination

The pagination data for the returned objects.

Name Description
refresh_url string

The URL that will return the same page of results.

next_url string

The URL that will return the next page of results.

total integer

Reserved for future use.

matched integer

Reserved for future use.

refresh_cursor string

A token identifying the current page of results.

next_cursor string

A token identifying the next page of results.

Example response


{
  "dialog_nodes" : [ {
    "type" : "standard",
    "title" : "Greeting",
    "output" : {
      "generic" : [ {
        "values" : [ {
          "text" : "Hi! How can I help you?"
        } ],
        "response_type" : "text"
      } ]
    },
    "conditions" : "#hello",
    "dialog_node" : "greeting"
  } ],
  "pagination" : {
    "refresh_url" : "/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/dialog_nodes?version=2018-09-20"
  }
}
        

Response Codes

Status Description
200

Successful request

400

Invalid request

Create dialog node

Create a new dialog node.

This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Request

POST /v1/workspaces/{workspace_id}/dialog_nodes
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body CreateDialogNode

A CreateDialogNode object defining the content of the new dialog node.

CreateDialogNode
Name Description
dialog_node string

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 string

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 string

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 string

The ID of the parent dialog node.

previous_sibling string

The ID of the previous dialog node.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

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 DialogNodeAction[]

An array of objects describing any actions to be invoked by the dialog node.

title string

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.
type string

How the dialog node is processed.

Allowable values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Allowable values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

digress_in string

Whether this top-level dialog node can be digressed into.

Allowable values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Allowable values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Allowable values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Allowable values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Allowable values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

\n

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Allowable values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

true

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Allowable values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Allowable values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Allowable values:
  • client
  • server

client

parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

Example request

curl -u "{username}:{password}" -H "Content-Type: application/json" -X POST -d "{\"dialog_node\": \"greeting\",\"conditions\":\"#hello\",\"output\":{\"generic\":[{\"response_type\":\"text\",\"values\":[{\"text\":\"Hi! How can I help you?\"}]}]},\"title\":\"Greeting\"}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/dialog_nodes?version=2018-09-20"
        

Response

DialogNode
Name Description
dialog_node string

The dialog node ID.

description string

The description of the dialog node.

conditions string

The condition that triggers the dialog node.

parent string

The ID of the parent dialog node. This property is not returned if the dialog node has no parent.

previous_sibling string

The ID of the previous sibling dialog node. This property is not returned if the dialog node has no previous sibling.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

context object

The context (if defined) for the dialog node.

metadata object

Any metadata for the dialog node.

next_step DialogNodeNextStep

The next step to execute following this dialog node.

created DateTime

The timestamp for creation of the dialog node.

updated DateTime

The timestamp for the most recent update to the dialog node.

actions DialogNodeAction[]

The actions for the dialog node.

title string

The alias used to identify the dialog node.

type string

How the dialog node is processed.

Possible values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Possible values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

digress_in string

Whether this top-level dialog node can be digressed into.

Possible values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Possible values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Possible values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Possible values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Possible values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Possible values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Possible values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Possible values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Possible values:
  • client
  • server
parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

Example response


{
  "type" : "standard",
  "title" : "Greeting",
  "output" : {
    "generic" : [ {
      "values" : [ {
        "text" : "Hi! How can I help you?"
      } ],
      "response_type" : "text"
    } ]
  },
  "conditions" : "#hello",
  "dialog_node" : "greeting"
}
        

Response Codes

Status Description
201

Successful request

400

Invalid request

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.

Request

GET /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

dialog_node path string

The dialog node ID (for example, get_order).

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

include_audit query boolean

Whether to include the audit properties (created and updated timestamps) in the response.

false

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/dialog_nodes/greeting?version=2018-09-20"
        

Response

DialogNode
Name Description
dialog_node string

The dialog node ID.

description string

The description of the dialog node.

conditions string

The condition that triggers the dialog node.

parent string

The ID of the parent dialog node. This property is not returned if the dialog node has no parent.

previous_sibling string

The ID of the previous sibling dialog node. This property is not returned if the dialog node has no previous sibling.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

context object

The context (if defined) for the dialog node.

metadata object

Any metadata for the dialog node.

next_step DialogNodeNextStep

The next step to execute following this dialog node.

created DateTime

The timestamp for creation of the dialog node.

updated DateTime

The timestamp for the most recent update to the dialog node.

actions DialogNodeAction[]

The actions for the dialog node.

title string

The alias used to identify the dialog node.

type string

How the dialog node is processed.

Possible values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Possible values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

digress_in string

Whether this top-level dialog node can be digressed into.

Possible values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Possible values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Possible values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Possible values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Possible values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Possible values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Possible values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Possible values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Possible values:
  • client
  • server
parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

Example response


{
  "type" : "standard",
  "title" : "Greeting",
  "output" : {
    "generic" : [ {
      "values" : [ {
        "text" : "Hi! How can I help you?"
      } ],
      "response_type" : "text"
    } ]
  },
  "conditions" : "#hello",
  "dialog_node" : "greeting"
}
        

Response Codes

Status Description
200

Successful request

400

Invalid request

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.

Request

POST /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

dialog_node path string

The dialog node ID (for example, get_order).

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

body body UpdateDialogNode

The updated content of the dialog node.

Any elements included in the new data will completely replace the equivalent existing elements, including all subelements. (Previously existing subelements are not retained unless they are also included in the new data.) For example, if you update the actions for a dialog node, the previously existing actions are discarded and replaced with the new actions specified in the update.

UpdateDialogNode
Name Description
dialog_node string

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 string

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 string

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 string

The ID of the parent dialog node.

previous_sibling string

The ID of the previous sibling dialog node.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

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.

title string

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.
type string

How the dialog node is processed.

Allowable values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Allowable values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

actions DialogNodeAction[]

An array of objects describing any actions to be invoked by the dialog node.

digress_in string

Whether this top-level dialog node can be digressed into.

Allowable values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Allowable values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Allowable values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Allowable values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Allowable values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

\n

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Allowable values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

true

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Allowable values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Allowable values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Allowable values:
  • client
  • server

client

parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

Example request

curl -u "{username}:{password}" -H "Content-Type: application/json" -X POST -d "{\"output\":{\"generic\":[{\"response_type\":\"text\",\"values\":[{\"text\":\"Hello! What can I do for you?\"}]}]}}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/9978a49e-ea89-4493-b33d-82298d3db20d/dialog_nodes/greeting?version=2018-09-20"
        

Response

DialogNode
Name Description
dialog_node string

The dialog node ID.

description string

The description of the dialog node.

conditions string

The condition that triggers the dialog node.

parent string

The ID of the parent dialog node. This property is not returned if the dialog node has no parent.

previous_sibling string

The ID of the previous sibling dialog node. This property is not returned if the dialog node has no previous sibling.

output DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

context object

The context (if defined) for the dialog node.

metadata object

Any metadata for the dialog node.

next_step DialogNodeNextStep

The next step to execute following this dialog node.

created DateTime

The timestamp for creation of the dialog node.

updated DateTime

The timestamp for the most recent update to the dialog node.

actions DialogNodeAction[]

The actions for the dialog node.

title string

The alias used to identify the dialog node.

type string

How the dialog node is processed.

Possible values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
event_name string

How an event_handler node is processed.

Possible values:
  • focus
  • input
  • filled
  • validate
  • filled_multiple
  • generic
  • nomatch
  • nomatch_responses_depleted
  • digression_return_prompt
variable string

The location in the dialog context where output is stored.

digress_in string

Whether this top-level dialog node can be digressed into.

Possible values:
  • not_available
  • returns
  • does_not_return
digress_out string

Whether this dialog node can be returned to after a digression.

Possible values:
  • allow_returning
  • allow_all
  • allow_all_never_return
digress_out_slots string

Whether the user can digress to top-level nodes while filling out slots.

Possible values:
  • not_allowed
  • allow_returning
  • allow_all
user_label string

A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters.

DialogNodeOutput

The output of the dialog node. For more information about how to specify dialog node output, see the documentation.

Name Description
generic DialogNodeOutputGeneric[]

An array of objects describing the output defined for the dialog node.

modifiers DialogNodeOutputModifiers

Options that modify how specified output is handled.

DialogNodeOutputGeneric
Name Description
response_type string

The type of response returned by the dialog node. The specified response type must be supported by the client application or channel.

Possible values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
values DialogNodeOutputTextValuesElement[]

A list of one or more objects defining text responses. Required when response_type=text.

selection_policy string

How a response is selected from the list, if more than one response is specified. Valid only when response_type=text.

Possible values:
  • sequential
  • random
  • multiline
delimiter string

The delimiter to use as a separator between responses when selection_policy=multiline.

time integer

How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when response_type=pause.

typing boolean

Whether to send a "user is typing" event during the pause. Ignored if the channel does not support this event. Valid only when response_type=pause.

source string

The URL of the image. Required when response_type=image.

title string

An optional title to show before the response. Valid only when response_type=image or option. This string must be no longer than 512 characters.

description string

An optional description to show with the response. Valid only when response_type=image or option. This string must be no longer than 256 characters.

preference string

The preferred type of control to display, if supported by the channel. Valid only when response_type=option.

Possible values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when response_type=option.

message_to_human_agent string

An optional message to be sent to the human agent who will be taking over the conversation. Valid only when reponse_type=connect_to_agent. This string must be no longer than 256 characters.

DialogNodeOutputTextValuesElement
Name Description
text string

The text of a response. This string can include newline characters (), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

InputData

The user input.

Name Description
text string

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.

DialogNodeOutputModifiers

Options that modify how specified output is handled.

Name Description
overwrite boolean

Whether values in the output will overwrite output values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

DialogNodeNextStep

The next step to execute following this dialog node.

Name Description
behavior string

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.

Possible values:
  • get_user_input
  • skip_user_input
  • jump_to
  • reprompt
  • skip_slot
  • skip_all_slots
dialog_node string

The ID of the dialog node to process next. This parameter is required if behavior=jump_to.

selector string

Which part of the dialog node to process next.

Possible values:
  • condition
  • client
  • user_input
  • body
DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Possible values:
  • client
  • server
parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

Example response


{
  "type" : "standard",
  "title" : "Greeting",
  "output" : {
    "generic" : [ {
      "values" : [ {
        "text" : "Hello! What can I do for you?"
      } ],
      "response_type" : "text"
    } ]
  },
  "conditions" : "#hello",
  "dialog_node" : "greeting"
}
        

Response Codes

Status Description
200

Successful request

400

Invalid request

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.

Request

DELETE /v1/workspaces/{workspace_id}/dialog_nodes/{dialog_node}
Parameter Description
workspace_id path string

Unique identifier of the workspace.

dialog_node path string

The dialog node ID (for example, get_order).

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/dialog_nodes/greeting?version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
200

Successful request

400

Invalid request

Logs

Query logged user input and responses.

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.

Request

GET /v1/workspaces/{workspace_id}/logs
Parameter Description
workspace_id path string

Unique identifier of the workspace.

version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

sort query string

How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

request_timestamp

filter query string

A cacheable parameter that limits the results to those matching the specified filter. For more information, see the documentation.

page_limit query integer

The number of records to return in each page of results.

100

cursor query string

A token identifying the page of results to retrieve.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/workspaces/bec28d8f-18c1-4e97-8d08-9c842c658b51/logs?version=2018-09-20"
        

Response

LogCollection
Name Description
logs LogExport[]

An array of objects describing log events.

pagination LogPagination

The pagination data for the returned objects.

LogExport
Name Description
request MessageRequest

A request received by the workspace, including the user input and context.

response MessageResponse

The response sent by the workspace, including the output text, detected intents and entities, and context.

log_id string

A unique identifier for the logged event.

request_timestamp string

The timestamp for receipt of the message.

response_timestamp string

The timestamp for the system response to the message.

workspace_id string

The unique identifier of the workspace where the request was made.

language string

The language of the workspace where the message request was made.

MessageRequest

A message request formatted for the Watson Assistant service.

Name Description
input InputData

An input object that includes the input text.

alternate_intents boolean

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

InputData

The user input.

Name Description
text string

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.

Context

State information for the conversation. To maintain state, include the context from the previous response.

Name Description
conversation_id string

The unique identifier of the conversation.

system SystemResponse

For internal use only.

RuntimeEntity

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

Name Description
entity string

An entity detected in the input.

location integer[]

An array of zero-based character offsets that indicate where the detected entity values begin and end in the input text.

value string

The term in the input text that was recognized as an entity value.

confidence number

A decimal percentage that represents Watson's confidence in the entity.

metadata object

Any metadata for the entity.

groups CaptureGroup[]

The recognized capture groups for the entity, as defined by the entity pattern.

CaptureGroup
Name Description
group string

A recognized capture group for the entity.

location integer[]

Zero-based character offsets that indicate where the entity value begins and ends in the input text.

RuntimeIntent

An intent identified in the user input.

Name Description
intent string

The name of the recognized intent.

confidence double

A decimal percentage that represents Watson's confidence in the intent.

OutputData

An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.

Name Description
log_messages LogMessage[]

An array of up to 50 messages logged with the request.

text string[]

An array of responses to the user.

generic DialogRuntimeResponseGeneric[]

Output intended for any channel. It is the responsibility of the client application to implement the supported response types.

nodes_visited string[]

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.

nodes_visited_details DialogNodeVisitedDetails[]

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.

LogMessage

Log message details.

Name Description
level string

The severity of the log message.

Possible values:
  • info
  • error
  • warn
msg string

The text of the log message.

DialogRuntimeResponseGeneric
Name Description
response_type string

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.

Possible values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
  • suggestion
text string

The text of the response.

time integer

How long to pause, in milliseconds.

typing boolean

Whether to send a "user is typing" event during the pause.

source string

The URL of the image.

title string

The title or introductory text to show before the response.

description string

The description to show with the the response.

preference string

The preferred type of control to display.

Possible values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose.

message_to_human_agent string

A message to be sent to the human agent who will be taking over the conversation.

topic string

A label identifying the topic of the conversation, derived from the user_label property of the relevant node.

suggestions DialogSuggestion[]

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.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

DialogSuggestion
Name Description
label string

The user-facing label for the disambiguation option. This label is taken from the user_label property of the corresponding dialog node.

value DialogSuggestionValue

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

output object

The dialog output that will be returned from the Watson Assistant service if the user selects the corresponding option.

DialogSuggestionValue

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

Name Description
input InputData

The user input.

intents RuntimeIntent[]

An array of intents to be sent along with the user input.

entities RuntimeEntity[]

An array of entities to be sent along with the user input.

DialogNodeVisitedDetails
Name Description
dialog_node string

A dialog node that was triggered during processing of the input message.

title string

The title of the dialog node.

conditions string

The conditions that trigger the dialog node.

MessageResponse

A response from the Watson Assistant service.

Name Description
input MessageInput

The user input from the request.

intents RuntimeIntent[]

An array of intents recognized in the user input, sorted in descending order of confidence.

entities RuntimeEntity[]

An array of entities identified in the user input.

alternate_intents boolean

Whether to return more than one intent. A value of true indicates that all matching intents are returned.

context Context

State information for the conversation.

output OutputData

Output from the dialog, including the response to the user, the nodes that were triggered, and log messages.

actions DialogNodeAction[]

An array of objects describing any actions requested by the dialog node.

MessageInput

The text of the user input.

Name Description
text string

The user's input.

DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Possible values:
  • client
  • server
parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

LogPagination

The pagination data for the returned objects.

Name Description
next_url string

The URL that will return the next page of results, if any.

matched integer

Reserved for future use.

next_cursor string

A token identifying the next page of results.

Example response


{
  "logs" : [ {
    "request" : {
      "input" : {
        "text" : "Good morning"
      }
    },
    "response" : {
      "intents" : [ {
        "intent" : "hello",
        "confidence" : 1
      } ],
      "entities" : [ ],
      "input" : {
        "text" : "Good morning"
      },
      "output" : {
        "text" : [ "Hi! What can I do for you?" ],
        "nodes_visited" : [ "node_2_1501875253968" ],
        "log_messages" : [ ]
      },
      "context" : {
        "conversation_id" : "30001db8-d2f9-4530-9e81-80fc75725209",
        "system" : {
          "dialog_stack" : [ {
            "dialog_node" : "root"
          } ],
          "dialog_turn_counter" : 1,
          "dialog_request_counter" : 1,
          "_node_output_map" : {
            "node_2_1501875253968" : [ 0 ]
          },
          "branch_exited" : true,
          "branch_exited_reason" : "completed"
        }
      }
    },
    "language" : "en",
    "workspace_id" : "9978a49e-ea89-4493-b33d-82298d3db20d",
    "request_timestamp" : "2017-09-13T16:39:56.284Z",
    "response_timestamp" : "2017-09-13T16:39:58.828Z",
    "log_id" : "dcceece9-acfc-49aa-94c3-ddc2b9776cbe"
  } ],
  "pagination" : { }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

500

Internal server error.

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.

Request

GET /v1/logs
Parameter Description
version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

filter query string

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.

sort query string

How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-).

request_timestamp

page_limit query integer

The number of records to return in each page of results.

100

cursor query string

A token identifying the page of results to retrieve.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/logs?version=2018-09-20&filter=(language::en,request.context.metadata.deployment::testDeployment)"
        

Response

LogCollection
Name Description
logs LogExport[]

An array of objects describing log events.

pagination LogPagination

The pagination data for the returned objects.

LogExport
Name Description
request MessageRequest

A request received by the workspace, including the user input and context.

response MessageResponse

The response sent by the workspace, including the output text, detected intents and entities, and context.

log_id string

A unique identifier for the logged event.

request_timestamp string

The timestamp for receipt of the message.

response_timestamp string

The timestamp for the system response to the message.

workspace_id string

The unique identifier of the workspace where the request was made.

language string

The language of the workspace where the message request was made.

MessageRequest

A message request formatted for the Watson Assistant service.

Name Description
input InputData

An input object that includes the input text.

alternate_intents boolean

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

InputData

The user input.

Name Description
text string

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.

Context

State information for the conversation. To maintain state, include the context from the previous response.

Name Description
conversation_id string

The unique identifier of the conversation.

system SystemResponse

For internal use only.

RuntimeEntity

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

Name Description
entity string

An entity detected in the input.

location integer[]

An array of zero-based character offsets that indicate where the detected entity values begin and end in the input text.

value string

The term in the input text that was recognized as an entity value.

confidence number

A decimal percentage that represents Watson's confidence in the entity.

metadata object

Any metadata for the entity.

groups CaptureGroup[]

The recognized capture groups for the entity, as defined by the entity pattern.

CaptureGroup
Name Description
group string

A recognized capture group for the entity.

location integer[]

Zero-based character offsets that indicate where the entity value begins and ends in the input text.

RuntimeIntent

An intent identified in the user input.

Name Description
intent string

The name of the recognized intent.

confidence double

A decimal percentage that represents Watson's confidence in the intent.

OutputData

An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.

Name Description
log_messages LogMessage[]

An array of up to 50 messages logged with the request.

text string[]

An array of responses to the user.

generic DialogRuntimeResponseGeneric[]

Output intended for any channel. It is the responsibility of the client application to implement the supported response types.

nodes_visited string[]

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.

nodes_visited_details DialogNodeVisitedDetails[]

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.

LogMessage

Log message details.

Name Description
level string

The severity of the log message.

Possible values:
  • info
  • error
  • warn
msg string

The text of the log message.

DialogRuntimeResponseGeneric
Name Description
response_type string

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.

Possible values:
  • text
  • pause
  • image
  • option
  • connect_to_agent
  • suggestion
text string

The text of the response.

time integer

How long to pause, in milliseconds.

typing boolean

Whether to send a "user is typing" event during the pause.

source string

The URL of the image.

title string

The title or introductory text to show before the response.

description string

The description to show with the the response.

preference string

The preferred type of control to display.

Possible values:
  • dropdown
  • button
options DialogNodeOutputOptionsElement[]

An array of objects describing the options from which the user can choose.

message_to_human_agent string

A message to be sent to the human agent who will be taking over the conversation.

topic string

A label identifying the topic of the conversation, derived from the user_label property of the relevant node.

suggestions DialogSuggestion[]

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.

DialogNodeOutputOptionsElement
Name Description
label string

The user-facing label for the option.

value DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

DialogNodeOutputOptionsElementValue

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Name Description
input InputData

The user input.

DialogSuggestion
Name Description
label string

The user-facing label for the disambiguation option. This label is taken from the user_label property of the corresponding dialog node.

value DialogSuggestionValue

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

output object

The dialog output that will be returned from the Watson Assistant service if the user selects the corresponding option.

DialogSuggestionValue

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

Name Description
input InputData

The user input.

intents RuntimeIntent[]

An array of intents to be sent along with the user input.

entities RuntimeEntity[]

An array of entities to be sent along with the user input.

DialogNodeVisitedDetails
Name Description
dialog_node string

A dialog node that was triggered during processing of the input message.

title string

The title of the dialog node.

conditions string

The conditions that trigger the dialog node.

MessageResponse

A response from the Watson Assistant service.

Name Description
input MessageInput

The user input from the request.

intents RuntimeIntent[]

An array of intents recognized in the user input, sorted in descending order of confidence.

entities RuntimeEntity[]

An array of entities identified in the user input.

alternate_intents boolean

Whether to return more than one intent. A value of true indicates that all matching intents are returned.

context Context

State information for the conversation.

output OutputData

Output from the dialog, including the response to the user, the nodes that were triggered, and log messages.

actions DialogNodeAction[]

An array of objects describing any actions requested by the dialog node.

MessageInput

The text of the user input.

Name Description
text string

The user's input.

DialogNodeAction
Name Description
name string

The name of the action.

type string

The type of action to invoke.

Possible values:
  • client
  • server
parameters object

A map of key/value pairs to be provided to the action.

result_variable string

The location in the dialog context where the result of the action is stored.

credentials string

The name of the context variable that the client application will use to pass in credentials for the action.

LogPagination

The pagination data for the returned objects.

Name Description
next_url string

The URL that will return the next page of results, if any.

matched integer

Reserved for future use.

next_cursor string

A token identifying the next page of results.

Example response


{
  "logs" : [ {
    "request" : {
      "input" : {
        "text" : "Good morning"
      },
      "context" : {
        "metadata" : {
          "deployment" : "deployment_1"
        }
      }
    },
    "response" : {
      "intents" : [ {
        "intent" : "hello",
        "confidence" : 1
      } ],
      "entities" : [ ],
      "input" : {
        "text" : "Good morning"
      },
      "output" : {
        "text" : [ "Hi! What can I do for you?" ],
        "nodes_visited" : [ "node_2_1501875253968" ],
        "log_messages" : [ ]
      },
      "context" : {
        "metadata" : {
          "deployment" : "testDeployment"
        },
        "conversation_id" : "81a43b48-7dca-4a7d-a0d7-6fed03fcee69",
        "system" : {
          "dialog_stack" : [ {
            "dialog_node" : "root"
          } ],
          "dialog_turn_counter" : 1,
          "dialog_request_counter" : 1,
          "_node_output_map" : {
            "node_2_1501875253968" : [ 0 ]
          },
          "branch_exited" : true,
          "branch_exited_reason" : "completed"
        }
      }
    },
    "language" : "en",
    "workspace_id" : "9978a49e-ea89-4493-b33d-82298d3db20d",
    "request_timestamp" : "2017-09-13T19:52:32.611Z",
    "response_timestamp" : "2017-09-13T19:52:32.628Z",
    "log_id" : "aa886a8a-bac5-4b91-8323-2fd61a69c9d3"
  } ],
  "pagination" : { }
}
        

Response Codes

Status Description
200

Successful request.

400

Invalid request.

500

Internal server error.

User data

Delete data that has been labeled with a customer ID.

Delete labeled data

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID.

You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see Information security.

Request

DELETE /v1/user_data
Parameter Description
version query string

Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-09-20.

customer_id query string

The customer ID for which all data is to be deleted.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/assistant/api/v1/user_data?customer_id={id}&version=2018-09-20"
        

Response

Response type: object.

Response Codes

Status Description
202

The request to delete data was successfully submitted.

400

Bad Request. The request did not pass a customer ID:

  • No customer ID found in the request
500

Internal server error.