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.

The code examples on this tab use the client library that is provided for Node.js.

Installation


npm install --save watson-developer-cloud
            

GitHub

https://github.com/watson-developer-cloud/node-sdk

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. If you pass in the API key, the SDK manages the lifecycle of the tokens. If you pass a token, you maintain the token lifecycle. Learn more about IAM authentication with the SDK.

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

SDK managing the IAM token. Replace {iam_api_key}, {version}, and {url}.


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

var watsonAssistant = new AssistantV1({
    version: '{version}',
    iam_apikey: '{iam_api_key}',
    url: '{url}'
  });
        

Basic authentication. Replace {username}, {password}, {version}, and {url}.


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

var watsonAssistant = new AssistantV1({
    version: '{version}',
    username: '{username}',
    password: '{password}',
    url: '{url}'
  });
        

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 AssistantV1 = require('watson-developer-cloud/assistant/v1');

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

assistant = AssistantV1(
    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::AssistantV1.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.

When the Node SDK receives an error response from the Watson Assistant service, it creates an Error object with information describing the error that occurred. This error object is passed as the first parameter to the callback function for the method. The contents of the error object are as shown in the following table.

Error
Field Description
code The HTTP status code returned.
message A message describing the error.

Example error handling


assistant.method(params,
    function(err, response) {
        // The error will be the first argument of the callback
        if (err.code == 404) {
            // Handle Not Found (404) error
        } else if (err.code == 413) {
            // Handle Request Too Large (413) error
        } else {
            console.log('Unexpected error: ', err.code);
            console.log('error:', err);
        }
    });
        

Data handling

Additional headers

Some Watson services accept special parameters in headers that are passed with the request. You can pass request header parameters in all requests or in a single request to the service.

To pass header parameters with every request, use the setDefaultHeaders method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, use the addHeader method as a modifier on the request before you execute the request.

To pass header parameters with every request, specify the headers parameter when you create the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, the headers parameter accepts a dictionary of header names and values that you can include in the request.

To pass header parameters with every request, specify the set_default_headers method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, include headers as a dict in the request.

To pass header parameters with every request, specify the add_default_headers method of the service object. See Data collection for an example use of this method.

To pass header parameters in a single request, specify the headers method as a chainable method in the request.

Example header parameter in a request


ReturnType returnValue = assistant.methodName(parameters)
        .addHeader("Custom-Header", "{header_value}")
        .execute();
                

assistant.methodName(
    {
        parameters,
        headers: {
            'Custom-Header': '{header_value}'
        }
    }, function(err, response) {
        if (err)
            console.log('error:', err);
        else
            console.log(response);
    }
);
                

response = assistant.methodName(
    parameters,
    headers = {
        'Custom-Header': '{header_value}'
    })
                

response = assistant.headers(
  "Custom-Header" => "{header_value}"
).methodName(parameters)
                

Response details

The Watson Assistant service might return information to the application in response headers.

To access information in the response headers, use one of the request methods that returns details with the response: executeWithDetails(), enqueueWithDetails(), or rxWithDetails(). These methods return a Response<T> object, where T is the expected response model. Use the getResult() method to access the response object for the method, and use the getHeaders() method to access information in response headers.

To access information in the response headers, specify the headers attribute on the third parameter (response) that is passed to the callback function.

The return value from all service methods is a DetailedResponse object. To access information in the result object or response headers, use the following methods.

DetailedResponse
Method Description
get_result() The response for the specific service method
get_headers() A <dict> containing the response header information
get_status_code() The HTTP response code

The return value from all service methods is a DetailedResponse object. To access information in the response object, use the following properties

DetailedResponse
Property Description
result Returns the response for the specific service method
headers Returns a containing the response header information
status The HTTP status code returned

Example request to access response headers


Response<ReturnType> response = assistant.methodName(parameters)
        .executeWithDetails();
// Access response from methodName
ReturnType returnValue = response.getResult();
// Access information in response headers
Headers responseHeaders = response.getHeaders();
                

assistant.methodName(
    {
        parameters
    }, function(err, result, response) {
        if (err)
            console.log('error:', err);
        else
            console.log(response.headers);
    }
);
                

assistant.set_detailed_response(True)
response = assistant.methodName(parameters)
// Access response from methodName
print(json.dumps(response.get_result(), indent=2))
// Access information in response headers
print(response.get_headers())
// Access HTTP response status
print(response.get_status_code())
                

response = assistant.methodName(parameters)
# Access response from methodName
print response.result
# Access information in response headers
print response.headers
# Access HTTP response status
print response.status
                

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 AssistantV1 = require('watson-developer-cloud/assistant/v1');

var watsonAssistant = new AssistantV1({
  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

message(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

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.

nodes_visited_details 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 number[]

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

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 number

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 number

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

assistant.message({
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  input: {'text': 'Hello'}
},  function(err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
            

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 number

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

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

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 number

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.

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

listWorkspaces(params, callback())
Parameter Description
page_limit number

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

100

include_count boolean

Whether to include information about the number of records returned.

false

sort string

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

cursor string

A token identifying the page of results to retrieve.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

assistant.listWorkspaces(function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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 string

The timestamp for creation of the workspace.

updated string

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 number

Reserved for future use.

matched number

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

createWorkspace(params, callback())
Parameter 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.

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

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.

value_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.
node_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 number

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.

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var workspace = {
  name: 'API test',
  description: 'Example workspace created via API.'
};

assistant.createWorkspace(workspace, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Workspace
Name Description
name string

The name of the workspace.

language string

The language of the workspace.

created string

The timestamp for creation of the workspace.

updated string

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

getWorkspace(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

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

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d'
};

assistant.getWorkspace(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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 string

The timestamp for creation of the workspace.

updated string

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_name string

The name of the intent.

created string

The timestamp for creation of the intent.

updated string

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
example_text string

The text of the user input example.

created string

The timestamp for creation of the example.

updated string

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

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

EntityExport
Name Description
entity_name string

The name of the entity.

created string

The timestamp for creation of the entity.

updated string

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_text string

The text of the entity value.

metadata Object

Any metadata related to the entity value.

created string

The timestamp for creation of the entity value.

updated string

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.

value_type string

Specifies the type of value.

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

The text of the counterexample.

created string

The timestamp for creation of the counterexample.

updated string

The timestamp for the last update to the counterexample.

DialogNode
Name Description
dialog_node_id 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 string

The timestamp for creation of the dialog node.

updated string

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.

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 number

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.

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

updateWorkspace(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

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.

append 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 number[]

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.

value_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.
node_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 number

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.

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '6b5c216e-4755-437e-bf20-db94c1660120',
  name: 'Updated workspace',
  description: 'Test workspace modified via API.'
};

assistant.updateWorkspace(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});

            

Response

Workspace
Name Description
name string

The name of the workspace.

language string

The language of the workspace.

created string

The timestamp for creation of the workspace.

updated string

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

deleteWorkspace(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '164cca2d-8af7-4034-a121-89049a665183'
};

assistant.deleteWorkspace(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

No response body.

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

listIntents(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

export 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 number

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

100

include_count boolean

Whether to include information about the number of records returned.

false

sort string

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

cursor string

A token identifying the page of results to retrieve.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
};

assistant.listIntents(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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_name string

The name of the intent.

created string

The timestamp for creation of the intent.

updated string

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
example_text string

The text of the user input example.

created string

The timestamp for creation of the example.

updated string

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

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 number

Reserved for future use.

matched number

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

createIntent(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

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.

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

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

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  examples: [
    {
      text: 'Good morning'
    },
    {
      text: 'Hi there'
    }
  ]
};

assistant.createIntent(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Intent
Name Description
intent_name string

The name of the intent.

created string

The timestamp for creation of the intent.

updated string

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

getIntent(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

intent string

The intent name.

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

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{username}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello'
};

assistant.getIntent(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

IntentExport
Name Description
intent_name string

The name of the intent.

created string

The timestamp for creation of the intent.

updated string

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
example_text string

The text of the user input example.

created string

The timestamp for creation of the example.

updated string

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

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

updateIntent(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

intent string

The intent name.

new_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.
new_description string

The description of the intent.

new_examples CreateExample[]

An array of user input examples for the intent.

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

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

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  new_examples: [
    {
      text: 'Good afternoon'
    }
  ],
  new_description: 'Updated intent'
};

assistant.updateIntent(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Intent
Name Description
intent_name string

The name of the intent.

created string

The timestamp for creation of the intent.

updated string

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

deleteIntent(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

intent string

The intent name.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello'
};

assistant.deleteIntent(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

No response body.

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

listExamples(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

intent string

The intent name.

page_limit number

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

100

include_count boolean

Whether to include information about the number of records returned.

false

sort string

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

cursor string

A token identifying the page of results to retrieve.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello'
};

assistant.listExamples(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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
example_text string

The text of the user input example.

created string

The timestamp for creation of the example.

updated string

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

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 number

Reserved for future use.

matched number

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

createExample(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

intent string

The intent name.

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.

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

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

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  text: 'Howdy!'
};

assistant.createExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

Example
Name Description
example_text string

The text of the user input example.

created string

The timestamp for creation of the example.

updated string

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

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

getExample(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

intent string

The intent name.

text string

The text of the user input example.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  text: 'Good afternoon'
};

assistant.getExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Example
Name Description
example_text string

The text of the user input example.

created string

The timestamp for creation of the example.

updated string

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

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

updateExample(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

intent string

The intent name.

text string

The text of the user input example.

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

An array of contextual entity mentions.

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

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

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  text: 'Hi there',
  new_text: 'Hello there!'         
};

assistant.updateExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Example
Name Description
example_text string

The text of the user input example.

created string

The timestamp for creation of the example.

updated string

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

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

deleteExample(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

intent string

The intent name.

text string

The text of the user input example.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  intent: 'hello',
  text: 'Good afternoon'
};

assistant.deleteExample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

No response body.

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

listCounterexamples(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

page_limit number

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

100

include_count boolean

Whether to include information about the number of records returned.

false

sort string

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

cursor string

A token identifying the page of results to retrieve.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d'
};

assistant.listCounterexamples(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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 string

The timestamp for creation of the counterexample.

updated string

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 number

Reserved for future use.

matched number

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

createCounterexample(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  text: 'Make me a sandwich'
};

assistant.createCounterexample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Counterexample
Name Description
text string

The text of the counterexample.

created string

The timestamp for creation of the counterexample.

updated string

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

getCounterexample(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

text string

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

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  text: 'Make me a sandwich'
};

assistant.getCounterexample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

Counterexample
Name Description
text string

The text of the counterexample.

created string

The timestamp for creation of the counterexample.

updated string

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

updateCounterexample(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

text string

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

new_text string

The text of a user input counterexample.

UpdateCounterexample
Name Description
text string

The text of a user input counterexample.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  text: 'Make me a sandwich',
  new_text: 'Make me a cheeseburger'
};

assistant.updateCounterexample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Counterexample
Name Description
text string

The text of the counterexample.

created string

The timestamp for creation of the counterexample.

updated string

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

deleteCounterexample(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

text string

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

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  text: 'Make me a sandwich'
};

assistant.deleteCounterexample(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

No response body.

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

listEntities(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

export 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 number

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

100

include_count boolean

Whether to include information about the number of records returned.

false

sort string

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

cursor string

A token identifying the page of results to retrieve.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d'
};

assistant.listEntities(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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_name string

The name of the entity.

created string

The timestamp for creation of the entity.

updated string

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_text string

The text of the entity value.

metadata Object

Any metadata related to the entity value.

created string

The timestamp for creation of the entity value.

updated string

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.

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 number

Reserved for future use.

matched number

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

createEntity(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

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.

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.

value_type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  values: [
    {
      value: 'water'
    },
    {
      value: 'orange juice'
    },
    {
      value: 'soda'
    }
  ]
};

assistant.createEntity(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response,null, 2));
  } 
});
            

Response

Entity
Name Description
entity_name string

The name of the entity.

created string

The timestamp for creation of the entity.

updated string

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

getEntity(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

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

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage'
};

assistant.getEntity(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

EntityExport
Name Description
entity_name string

The name of the entity.

created string

The timestamp for creation of the entity.

updated string

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_text string

The text of the entity value.

metadata Object

Any metadata related to the entity value.

created string

The timestamp for creation of the entity value.

updated string

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.

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

updateEntity(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

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

new_metadata Object

Any metadata related to the entity.

new_fuzzy_match boolean

Whether to use fuzzy matching for the entity.

new_values CreateValue[]

An array of entity values.

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.

value_type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  new_entity: 'beverage',
  new_description: 'Liquid refreshment'
};

assistant.updateEntity(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

Entity
Name Description
entity_name string

The name of the entity.

created string

The timestamp for creation of the entity.

updated string

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

deleteEntity(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage'
};

assistant.deleteEntity(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

No response body.

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

listMentions(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

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

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

false

Example request

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

var assistant = new watson.AssistantV1({
  version: '2018-09-20',
  username: '{username}',
  password: '{password}'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage'
};

assistant.listMentions(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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
example_text string

The text of the user input example.

intent_name string

The name of the intent.

location number[]

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 number

Reserved for future use.

matched number

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

listValues(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

export 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 number

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

100

include_count boolean

Whether to include information about the number of records returned.

false

sort string

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

cursor string

A token identifying the page of results to retrieve.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage'
};

assistant.listValues(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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_text string

The text of the entity value.

metadata Object

Any metadata related to the entity value.

created string

The timestamp for creation of the entity value.

updated string

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.

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 number

Reserved for future use.

matched number

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

createValue(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

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.

value_type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

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.

value_type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'beer'
};

assistant.createValue(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

Value
Name Description
value_text string

The text of the entity value.

metadata Object

Any metadata related to the entity value.

created string

The timestamp for creation of the entity value.

updated string

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.

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

getValue(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

value string

The text of the entity value.

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

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice'
};

assistant.getValue(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

ValueExport
Name Description
value_text string

The text of the entity value.

metadata Object

Any metadata related to the entity value.

created string

The timestamp for creation of the entity value.

updated string

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.

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

updateValue(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

value string

The text of the entity value.

new_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.
new_metadata Object

Any metadata related to the entity value.

new_type string

Specifies the type of value.

Allowable values:
  • synonyms
  • patterns

synonyms

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

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.

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'soda',
  new_synonyms: [
    'pop',
    'soft drink'
  ]         
};

assistant.updateValue(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Value
Name Description
value_text string

The text of the entity value.

metadata Object

Any metadata related to the entity value.

created string

The timestamp for creation of the entity value.

updated string

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.

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

deleteValue(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

value string

The text of the entity value.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'beer'
};

assistant.deleteValue(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

No response body.

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

listSynonyms(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

value string

The text of the entity value.

page_limit number

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

100

include_count boolean

Whether to include information about the number of records returned.

false

sort string

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

cursor string

A token identifying the page of results to retrieve.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'soda'
};

assistant.listSynonyms(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  } 
});
            

Response

SynonymCollection
Name Description
synonyms Synonym[]

An array of synonyms.

pagination Pagination

The pagination data for the returned objects.

Synonym
Name Description
synonym_text string

The text of the synonym.

created string

The timestamp for creation of the synonym.

updated string

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 number

Reserved for future use.

matched number

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

createSynonym(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

value string

The text of the entity value.

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

assistant.createSynonym(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Synonym
Name Description
synonym_text string

The text of the synonym.

created string

The timestamp for creation of the synonym.

updated string

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

getSynonym(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

value string

The text of the entity value.

synonym string

The text of the synonym.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{usernamne}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

assistant.getSynonym(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Synonym
Name Description
synonym_text string

The text of the synonym.

created string

The timestamp for creation of the synonym.

updated string

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

updateSynonym(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

value string

The text of the entity value.

synonym string

The text of the synonym.

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ',
  new_synonym: 'O.J.'         
};

assistant.updateSynonym(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

Synonym
Name Description
synonym_text string

The text of the synonym.

created string

The timestamp for creation of the synonym.

updated string

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

deleteSynonym(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

entity string

The name of the entity.

value string

The text of the entity value.

synonym string

The text of the synonym.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  entity: 'beverage',
  value: 'orange juice',
  synonym: 'OJ'
};

assistant.deleteSynonym(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

No response body.

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

listDialogNodes(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

page_limit number

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

100

include_count boolean

Whether to include information about the number of records returned.

false

sort string

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

cursor string

A token identifying the page of results to retrieve.

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
};

assistant.listDialogNodes(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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_id 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 string

The timestamp for creation of the dialog node.

updated string

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.

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 number

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.

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 number

Reserved for future use.

matched number

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

createDialogNode(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

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

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

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.

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  dialog_node: 'greeting',
  conditions:'#hello',
  output: {
    text: 'Hi! How can I help you?'
  },
  title: 'Greeting'
};

assistant.createDialogNode(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

DialogNode
Name Description
dialog_node_id 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 string

The timestamp for creation of the dialog node.

updated string

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.

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 number

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.

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

getDialogNode(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

dialog_node string

The dialog node ID (for example, get_order).

include_audit boolean

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

false

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  dialog_node: 'greeting'
};

assistant.getDialogNode(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

DialogNode
Name Description
dialog_node_id 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 string

The timestamp for creation of the dialog node.

updated string

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.

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 number

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.

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

updateDialogNode(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

dialog_node string

The dialog node ID (for example, get_order).

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

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

new_parent string

The ID of the parent dialog node.

new_previous_sibling string

The ID of the previous sibling dialog node.

new_output DialogNodeOutput

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

new_context Object

The context for the dialog node.

new_metadata Object

The metadata for the dialog node.

new_next_step DialogNodeNextStep

The next step to be executed in dialog processing.

new_title 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.
new_type string

How the dialog node is processed.

Allowable values:
  • standard
  • event_handler
  • frame
  • slot
  • response_condition
  • folder
new_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
new_variable string

The location in the dialog context where output is stored.

new_actions DialogNodeAction[]

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

new_digress_in string

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

Allowable values:
  • not_available
  • returns
  • does_not_return
new_digress_out string

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

Allowable values:
  • allow_returning
  • allow_all
  • allow_all_never_return
new_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
new_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.

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

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.

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

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  dialog_node: 'greeting',
  new_dialog_node: 'greeting',
  new_output: {
    text: 'Hello! What can I do for you?'
  }
};

assistant.updateDialogNode(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

DialogNode
Name Description
dialog_node_id 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 string

The timestamp for creation of the dialog node.

updated string

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.

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 number

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.

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

deleteDialogNode(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

dialog_node string

The dialog node ID (for example, get_order).

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d',
  dialog_node: 'greeting'
};

assistant.deleteDialogNode(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

Response

No response body.

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

listLogs(params, callback())
Parameter Description
workspace_id string

Unique identifier of the workspace.

sort 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 string

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

page_limit number

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

100

cursor string

A token identifying the page of results to retrieve.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  workspace_id: '9978a49e-ea89-4493-b33d-82298d3db20d'
};

assistant.listLogs(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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

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

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 number

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 number

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.

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 number

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

listAllLogs(params, callback())
Parameter Description
filter 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 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 number

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

100

cursor string

A token identifying the page of results to retrieve.

Example request

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

var assistant = new watson.AssistantV1({
  username: '{username}',
  password: '{password}',
  version: '2018-09-20'
});

var params = {
  filter: 'language::en,request.context.metadata.deployment::testDeployment'
};

assistant.listAllLogs(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});
            

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

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

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 number

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 number

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.

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 number

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

deleteUserData(params, callback())
Parameter Description
customer_id string

The customer ID for which all data is to be deleted.

Example request

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

var assistant = new watson.AssistantV1({
  version: '2018-09-20',
  username: '{username}',
  password: '{password}'
});

var params = {
  customer_id: '{id}'
};

assistant.deleteUserData(params, function(err, response) {
  if (err) {
    console.error(err);
  } else {
    console.log(JSON.stringify(response, null, 2));
  }
});

            

Response

No response body.

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.