Curl Node Java

Dialog

API Reference

Introduction

The IBM Watson™ Dialog service provides a comprehensive, robust, platform for managing conversations between virtual agents and users through an application programming interface (API). These conversations are commonly referred to as dialogs. Dialogs are created by using the REST API for the Dialog service or by calling the functions in the SDKS for Watson Developer Cloud applications in Node.js, Java, and Python.

API Endpoint

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

Important: If you have IBM® Cloud Dedicated, this might not be your endpoint. Check your endpoint URL on the Service credentials page for your instance of the Dialog service.

The code examples on this tab use the client-side library that is provided for Node.js, rather than issuing REST calls.

Node

npm install watson-developer-cloud

The code examples on this tab use the client-side library that is provided for java, rather than issuing REST calls.

Maven

<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-wrapper</artifactId>
  <version>3.9.1</version>
</dependency>

Gradle


    compile 'com.ibm.watson.developer_cloud:java-wrapper:3.9.1'
    

API explorer

To interact with this API, use the Dialog Service API explorer. Use the explorer to test your calls to the API, and to view live responses from the server.

Authentication

You authenticate to the Dialog API by providing the username and password that are provided in the service credentials for the service instance that you want to use. The API uses Basic Authentication.

After creating an instance of the Dialog service, select Service Credentials from the left navigation for its dashboard to see the username and password that are associated with that instance.

Replace {username} and {password} with your credentials


curl -u "{username}":"{password}" \
"https://gateway.watsonplatform.net/dialog/api/v1"

var watson = require('watson-developer-cloud');
var dialog_service = watson.dialog({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

DialogService service = new DialogService();
service.setUsernameAndPassword("{username}","{password}");

Methods

List dialogs

Returns the dialogs.


GET  /v1/dialogs

Request

No arguments.

Example request


curl -u "{username}":"{password}" \
"https://gateway.watsonplatform.net/dialog/api/v1/dialogs"

var watson = require('watson-developer-cloud');
var dialog_service = watson.dialog({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});
dialog_service.getDialogs({}, function(err, dialogs) {
  if (err)
    console.log(err)
  else
    console.log(dialogs);
});

DialogService service = new DialogService();
service.setUsernameAndPassword("{username}","{password}");

List<Dialog> dialogs = service.getDialogs();
System.out.println(dialogs);

Response

Name Description
dialog_id The dialog template identifier.
name The dialog template name.

Example response


com.ibm.watson.developer_cloud.dialog.v1.model.Dialog

{
  "dialogs": [
    {
      "name": "pizza",
      "dialog_id": "ad1842ba-c642-4295-b747-1953432bc38a"
    },
    {
      "name": "phone",
      "dialog_id": "08f67ba1-e325-4db3-a6fe-20aea8d657b3"
    }
  ]
}

Create a dialog

Creates a dialog template for maintaining conversations.


POST  /v1/dialogs

Request

Name Type Description
name form The dialog template name.
file form The dialog template file. Valid extensions are .mct for encrypted dialog files, .json, and .xml.

Example request


  curl -u "{username}":"{password}" \
  -X POST
  --form file=@template.xml
  --form name=templateName
  "https://gateway.watsonplatform.net/dialog/api/v1/dialogs"
  

var fs     = require('fs');
var watson = require('watson-developer-cloud');
var dialog_service = watson.dialog({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  name: 'my-dialog',
  file: fs.createReadStream('template.xml')
};

dialog_service.createDialog(params, function(err, dialog) {
  if (err)
    console.log(err)
  else
    console.log(dialog);
});

DialogService service = new DialogService();
service.setUsernameAndPassword("{username}","{password}");

Dialog dialog = service.createDialog("my-dialog", new File("template.xml"));
System.out.println(dialog);

Response

Name Description
id The dialog identifier.

Example response


com.ibm.watson.developer_cloud.dialog.v1.model.Dialog

{
  "id": "944356ac-8b29-4bf4-83b7-df631a5f615f"
}

Delete a dialog

Deletes a dialog template and all associated data.


DELETE  /v1/dialogs/{dialog_id}

Request

Name Type Description
dialog_id path The dialog template identifier.

Example request


  curl -u "{username}":"{password}" \
  -X DELETE
  "https://gateway.watsonplatform.net/dialog/api/v1/dialogs/{dialog_id}"
  

var watson = require('watson-developer-cloud');
var dialog_service = watson.dialog({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

dialog_service.deleteDialog({dialog_id: '{dialog_id}'}, function(err, dialog) {
    if (err)
      console.log(err)
    else
      console.log(dialog);
});

DialogService service = new DialogService();
service.setUsernameAndPassword("{username}","{password}");

service.deleteDialog("{dialog_id}");

Update a dialog

Updates an existing dialog template.


PUT  /v1/dialogs/{dialog_id}

Request

Name Type Description
dialog_id path The dialog template identifier.
file form The dialog template file. Valid file extensions are .mct for encrypted dialog files, .json, and .xml.

Example request


  curl -u "{username}":"{password}" \
  -X PUT
  --form file=@template.xml
  "https://gateway.watsonplatform.net/dialog/api/v1/dialogs/{dialog_id}"
  

var fs     = require('fs');
var watson = require('watson-developer-cloud');
var dialog_service = watson.dialog({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  dialog_id: '{dialog_id}',
  file: fs.createReadStream('template.xml')
};

dialog_service.updateDialog(params, function(err, dialog) {
  if (err)
    console.log(err)
  else
    console.log(dialog);
});

DialogService service = new DialogService();
service.setUsernameAndPassword("{username}","{password}");

Dialog dialog = service.updateDialog("{dialog_id}", new File("template.xml"));
System.out.println(dialog);

Response

Name Description
id The dialog identifier.

Example response


com.ibm.watson.developer_cloud.dialog.v1.model.Dialog

{
  "id": "944356ac-8b29-4bf4-83b7-df631a5f615f"
}

Converse

Start a new conversation or continue an existing one.


POST /v1/dialogs/{dialog_id}/conversation

Request

Name Type Description
dialog_id path The dialog template identifier.
conversation_id form A generated conversation identifier number. If it is not specified, a new conversation is started.
client_id form A generated client identifier number. If it is not specified, a new client identifier is issued.
input form The user input to be processed. If the conversation_id parameter is blank, this parameter is optional.
Name Type Description
dialog_id string The dialog template identifier.
conversation_id int A generated conversation identifier number. If it is not specified, a new conversation is started.
client_id int A generated client identifier number. If it is not specified, a new client identifier is issued.
input string The user input message to be processed. If the conversation_id parameter is blank, this parameter is optional.

Example request


  curl -u "{username}":"{password}" \
  -X POST
  -d conversation_id={conversation_id}
  -d client_id={client_id}
  -d input="Hi Hello"
  "https://gateway.watsonplatform.net/dialog/api/v1/dialogs/{dialog_id}/conversation"
  

var watson = require('watson-developer-cloud');
var dialog_service = watson.dialog({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  conversation_id: '{conversation_id}',
  dialog_id: '{dialog_id}',
  client_id: '{client_id}',
  input:     '{input}'
};

dialog_service.conversation(params, function(err, conversation) {
  if (err)
    console.log(err)
  else
    console.log(conversation);
});

DialogService service = new DialogService();
service.setUsernameAndPassword("{username}","{password}");

Map<String, Object> params = new HashMap<String, Object>();
params.put(DialogService.DIALOG_ID, "{dialog_id}");
params.put(DialogService.CLIENT_ID, {client_id});
params.put(DialogService.INPUT, "Hi Hello");
params.put(DialogService.CONVERSATION_ID, {conversation_id});

Conversation conversation = service.converse(params);
System.out.println(conversation);

Response

Name Description
response An array of strings with the service responses to the user input.
input The processed user input.
conversation_id The conversation identifier number.
confidence The dialog identifier.
client_id The client identifier number.

Example response


com.ibm.watson.developer_cloud.dialog.v1.model.Conversation

{
  "response": [
    "Hi this is Watson"
  ],
  "input": "Hi Hello",
  "conversation_id": 11231,
  "confidence": 1,
  "client_id": 4435
}

Get conversation history

Retrieves a recorded conversation session history for a specified date range.


GET /v1/dialogs/{dialog_id}/conversation

Request

Name Type Description
dialog_id path The dialog template identifier.
date_from query The start of the range in YYYY-MM-DD HH:MM:SS format.
date_to query The end of the range in YYYY-MM-DD HH:MM:SS format.
offset query The offset starting point in the conversation result list. The default value is 0.
limit query The maximum number of conversations to retrieve. The default value is 10000.
Name Type Description
dialog_id string The dialog template identifier.
date_from stringDate The start of the range in YYYY-MM-DD HH:MM:SS format.
date_to stringDate The end of the range in YYYY-MM-DD HH:MM:SS format.
offset int The offset starting point in the conversation result list. The default value is 0.
limit int The maximum number of conversations to retrieve. The default value is 10000.

Example request


curl -u "{username}":"{password}" \
-X GET
"https://gateway.watsonplatform.net/dialog/api/v1/dialogs/{dialog_id}/conversation?offset=10&limit=5&date_from={date_from}&date_to={date_from}"

var watson = require('watson-developer-cloud');
var dialog_service = watson.dialog({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  dialog_id: '{dialog_id}',
  date_from: '{date_from}',
  date_to:   '{date_to}',
  limit:     '{limit}',
  offset:    '{offset}'
};

dialog_service.getConversation(params, function(err, session) {
  if (err)
    console.log(err)
  else
    console.log(session);
});

DialogService service = new DialogService();
service.setUsernameAndPassword("{username}","{password}");

Map<String, Object> params = new HashMap<String, Object>();
params.put(DialogService.DIALOG_ID, "{dialog_id}");
params.put(DialogService.DATE_FROM, new Date());
params.put(DialogService.DATE_TO, new Date());
params.put(DialogService.OFFSET, {offset});
params.put(DialogService.LIMIT, {limit});

List<ConversationData> conversationData = service.getConversationData(params);
System.out.println(conversationData);

Response

Example response


com.ibm.watson.developer_cloud.dialog.v1.model.ConversationData

{
  "conversations": [
    {
      "hit_nodes": [
        {
          "details": "string",
          "label": "string",
          "type": "string",
          "node_id": 0
        }
      ],
      "conversation_id": 0,
      "client_id": 0,
      "messages": [
        {
          "text": "string",
          "date_time": "string",
          "from_client": "string"
        }
      ],
      "profile": [
        {
          "name": "string",
          "value": "string"
        }
      ]
    }
  ]
}

Get profile variables

Retrieves the profile variables for a given client_id.


GET /v1/dialogs/{dialog_id}/profile

Request

Name Type Description
dialog_id path The dialog template identifier
client_id query A client ID obtained from /dialog
Name Type Description
dialog_id string The dialog template identifier
dialog_id path The dialog template identifier
client_id query A client ID obtained from /dialog

Example request


curl -u "{username}":"{password}" \
-X GET
"https://gateway.watsonplatform.net/dialog/api/v1/dialogs/{dialog_id}/profile?client_id={client_id}"

var watson = require('watson-developer-cloud');
var dialog_service = watson.dialog({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  dialog_id: '{dialog_id}',
  client_id: {client_id},
  name: {name}
};

dialog_service.getProfile(params, function(err, profile) {
  if (err)
    console.log(err)
  else
    console.log(profile);
});

DialogService service = new DialogService();
service.setUsernameAndPassword("{username}","{password}");

List<NameValue> profile = service.getProfile("{dialog_id}", {client_id});
System.out.println(profile);

Response

Name Description
name_values An array of profile variables.
name The profile variable name.
value The profile variable value.

Example response


com.ibm.watson.developer_cloud.dialog.v1.model.ConversationData

{
  "client_id": 4435,
  "name_values": [
    {
      "name": "topping",
      "value": "cheese"
    }, {
      "name": "size",
      "value": "large"
    }, {
      "name": "size",
      "value": "large"
    }
  ]
}

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. To prevent IBM from accessing your data for general service improvements, set the X-Watson-Learning-Opt-Out header parameter to true for all requests. (Any value other than false or 0 disables request logging for that call.) You must set the header on each request that you do not want IBM to access for general service improvements.

Error handling

The Dialog service uses standard HTTP response codes to display 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.

Error information

200 - OK Success.
400 - Bad Request Missing a required parameter, or invalid parameter value.
401 - Unauthorized No API key provided, or the API key provided was not valid.
404 - Not Found The requested item or parameter doesn't exist.
500 - Server Errors Internal server error.

Error format

Name Description
error Error description.
code HTTP Status code.
help (Optional)Help message.

Catching an error


curl "https://gateway.watsonplatform.net/dialog/api/v1/translate?source=en&target=es"

dialog_service.translate({
    //text: 'hello',
    source: 'en',
    target: 'es'
  }, function(err, translation) {
  // The error will be the first argument of the callback
    if (err)
      console.log(err)
});

DialogService service = new DialogService();

TranslationResult translation = null;
try {
  translation = service.translate(null, "en", "es");
} catch (IllegalArgumentException e) {
  // Missing or invalid parameter
} catch (BadRequestException e) {
  // Missing or invalid parameter
} catch (UnauthorizedException e) {
  // Access is denied due to invalid credentials
} catch (ForbiddenException e) {
  // Forbidden: Service refuse the request
} catch (NotFoundException e) {
  // Not found
} catch (TooManyRequestsException e) {
  // Too many requests
} catch (InternalServerErrorException e) {
  // Internal Server Error
} catch (ServiceUnavailableException e) {
  // Service Unavailable
}

Example error


{
  "error": "Missing required parameter: text",
  "code": 400
}