Watson Virtual Agent

Live

Watson Virtual Agent

+ Day(s) remaining in the trial

Overview

The IBM Watson Virtual Agent enables business users to quickly configure a virtual agent that can answer typical customer service questions and perform basic business transactions through natural conversation.
Use these APIs to incorporate the Watson Virtual Agent into your company website or mobile application.


Getting started

About the Runtime APIs

The current runtime REST APIs enable you to retrieve the bot that is assigned to you (GET /bots), initiate a new conversation with that bot (POST /dialogs), and send questions and requests to the bot for it to respond to or take action on (POST /messages). These APIs are leveraged by the Watson Virtual Chat Widget API to create rich user interface experiences that combine conversational interactions with traditional graphical user interface elements, such as buttons and text fields. We also provide a Virtual Agent SDK written in javascript, which together with the User Interface SDK, facilitates the integration between the bot's cognitive services and the company's back-end systems of record. For more information about these APIs, see the product documentation accessible through this link.

API keys

You must include the following two parameters in the header of every call that you make with this API. The parameters specify keys that authenticate you as a valid user of the virtual agent:
  • X-IBM-Client-Id
  • X-IBM-Client-Secret
To obtain the key values:
  1. Sign in.
  2. Select the key that you want to use on the left column of this page.
  3. Hover over the X-IBM-Client-Id or X-IBM-Client-Secret fields, and then click the SHOW button.

Versioning

All API calls include in the URI a major version (currently /api/v1), and a minor version, specified with a query parameter ?version=. The only currently supported value is version=2016-09-16.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

Documentation

Watson Virtual Agent:

Runtime API

Get Bot
Gets the unique ID of the bot that has been assigned to you. The service determines which bot is yours based on the X-IBM-Client-Id and X-IBM-Client-Secret that you presented when you connected to the service. You must include this bot_id on all subsequent calls that you make to interact with the bot.

GET   /bots

			https://api.ibm.com/virtualagent/run/api/v1/bots
		
Keys
Path and Query parameters

version

STRING , required

Date used for minor versioning (currently only supports 2016-09-16)

Request code
								
HttpResponse<String> response = Unirest.get("https://api.ibm.com/virtualagent/run/api/v1/bots?version=SOME_STRING_VALUE") .header("accept", "application/json") .header("content-type", "application/json") .asString();
Response model

200

Returns the bot_id associated with this virtual agent.

Body

-bot_id

STRING , required

-subscription_id

STRING , required

-last_updated_date

STRING , required

-creation_date

STRING , required

-factory_id

STRING , required

Response example

200

Returns the bot_id associated with this virtual agent.

								{
  "-bot_id" : string,
  "-subscription_id" : string,
  "-last_updated_date" : string,
  "-creation_date" : string,
  "-factory_id" : string
}
							
New Dialog

This API is used to initiate a new conversation with the virtual agent. The API returns a dialog_id that will be used in every subsequent call to the POST /messages API to hold a conversation.

POST   /bots/{bot_id}/dialogs

			https://api.ibm.com/virtualagent/run/api/v1/bots/{bot_id}/dialogs
		
Keys
Path and Query parameters

bot_id

URL , required

Unique identifier representing a bot

version

STRING , required

Date used for minor versioning (currently only supports 2016-09-16)

Request code
								
HttpResponse<String> response = Unirest.post("https://api.ibm.com/virtualagent/run/api/v1/bots/%7Bbot_id%7D/dialogs?version=SOME_STRING_VALUE") .header("accept", "application/json") .header("content-type", "application/json") .asString();
Request model

user_latlon

STRING , optional

Location coordinates specified in decimal degrees. Separate the latitude and longitude values with a comma. Use a numbers-only format, no degree symbols. Use a minus sign (-) for negative degrees; omit the plus sign (+) for positive degrees. For example: [-]DD.DDDD,[-]DD.DDDD.

user_id

STRING , optional

A unique user ID. Use only non-personally identifiable user IDs. For example, do not use an email address or anything else that fully or partially includes a user name. Supports String values that are specified with alphanumeric characters plus dashes and underscores.

Request example
{"user_latlon": "38.8897,-77.0089", "user_id": "js-08-31-001"}
Response model

201

Responds with a new dialog_id used to start a conversation

Body

message

OBJECT , required

dialog_id

STRING , required

bot_id

STRING , required

text

ARRAY , optional

LogData

OBJECT , optional

layout

STRING , required

Data

OBJECT , optional

Context

OBJECT , optional

intents

ARRAY , optional

entities

ARRAY , optional

location_data

OBJECT , optional

regionCode

STRING , required

Phone

OBJECT , optional

title

STRING , required

postalCode

STRING , required

Email

OBJECT , optional

Hour

OBJECT , optional

address1

STRING , required

lng

STRING , required

address2

STRING , required

lat

STRING , required

city

STRING , required

location_data

OBJECT , optional

location_data

OBJECT , optional

value

STRING , required

type

STRING , required

open

STRING , required

close

STRING , required

isOpen

BOOLEAN , required

System

OBJECT , optional

location_type

STRING , required

conversation_id

STRING , required

user_location

STRING , required

system

OBJECT , optional

text

ARRAY , optional

dialog_request_counter

INTEGER , required

dialog_turn_counter

INTEGER , required

Response example

201

Responds with a new dialog_id used to start a conversation

								{
  "message" : {
    "text" : [array],
    "LogData" : {
    "intents" : [array],
    "entities" : [array]
  },
    "layout" : string,
    "Data" : {
    "location_data" : {
    "regionCode" : string,
    "Phone" : {
    "location_data" : object
  },
    "title" : string,
    "postalCode" : string,
    "Email" : {
    "location_data" : {
    "value" : string,
    "type" : string
  }
  },
    "Hour" : {
    "open" : string,
    "close" : string,
    "isOpen" : boolean
  },
    "address1" : string,
    "lng" : string,
    "address2" : string,
    "lat" : string,
    "city" : string
  }
  },
    "Context" : {
    "System" : {
    "system" : object,
    "text" : [array],
    "dialog_request_counter" : integer,
    "dialog_turn_counter" : integer
  },
    "location_type" : string,
    "conversation_id" : string,
    "user_location" : string
  }
  },
  "dialog_id" : string,
  "bot_id" : string
}
							
New Message
Posts a message into an existing dialog resource. A conversation is started with the POST /dialogs API, and then the POST /messages API is used for every new utterance that the user wants to send to Watson.

POST   /bots/{bot_id}/dialogs/{dialog_id}/messages

			https://api.ibm.com/virtualagent/run/api/v1/bots/{bot_id}/dialogs/{dialog_id}/messages
		
Keys
Path and Query parameters

bot_id

URL , required

Unique identifier representing a bot

dialog_id

URL , required

Unique identifier representing a dialog

version

STRING , required

Date used for minor versioning (currently only supports 2016-09-16)

Request code
								
HttpResponse<String> response = Unirest.post("https://api.ibm.com/virtualagent/run/api/v1/bots/{bot_id_string}/dialogs/{dialog_id_string}/messages?version=string") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .body("{\"context\":{\"description\":\"Lists context variable name and value pairs to pass to a custom Conversation service dialog\",\"example\":\"null\",\"type\":\"object\"},\"message\":\"null\"}") .asString();
Request model

message

STRING , required

User utterance

context

OBJECT , optional

Lists context variable name and value pairs to pass to a custom Conversation service dialog

Request example
{"message":"I want to change my order",
"context":{"customertier":"Gold","nickname":"Joe"}}
Response model

201

JSON object in response holds the virtual agent's reply to the utterance

Body

message

object , required

dialog_id

STRING , required

bot_id

STRING , required

text

ARRAY , optional

LogData

object , optional

layout

STRING , required

Data

object , optional

Context

object , optional

intents

ARRAY , optional

entities

ARRAY , optional

location_data

object , optional

regionCode

STRING , required

Phone

object , optional

title

STRING , required

postalCode

STRING , required

Email

object , optional

Hour

object , optional

address1

STRING , required

lng

STRING , required

address2

STRING , required

lat

STRING , required

city

STRING , required

location_data

OBJECT , optional

location_data

object , optional

value

STRING , required

type

STRING , required

open

STRING , required

close

STRING , required

isOpen

BOOLEAN , required

System

object , optional

location_type

STRING , required

conversation_id

STRING , required

user_location

STRING , required

system

OBJECT , optional

text

ARRAY , optional

dialog_request_counter

INTEGER , required

dialog_turn_counter

INTEGER , required

Response example

201

JSON object in response holds the virtual agent's reply to the utterance

								{
  "message" : {
    "text" : [array],
    "LogData" : {
    "intents" : [array],
    "entities" : [array]
  },
    "layout" : string,
    "Data" : {
    "location_data" : {
    "regionCode" : string,
    "Phone" : {
    "location_data" : object
  },
    "title" : string,
    "postalCode" : string,
    "Email" : {
    "location_data" : {
    "value" : string,
    "type" : string
  }
  },
    "Hour" : {
    "open" : string,
    "close" : string,
    "isOpen" : boolean
  },
    "address1" : string,
    "lng" : string,
    "address2" : string,
    "lat" : string,
    "city" : string
  }
  },
    "Context" : {
    "System" : {
    "system" : object,
    "text" : [array],
    "dialog_request_counter" : integer,
    "dialog_turn_counter" : integer
  },
    "location_type" : string,
    "conversation_id" : string,
    "user_location" : string
  }
  },
  "dialog_id" : string,
  "bot_id" : string
}
							
Retrieve Chat Transcript Data
Use this endpoint to get chat transcripts of interactions that took place between your agent and users within a specified time frame. In the request body, you can define filters to use that limit the transcripts exported to those that match characteristics you specify. Returns a JSON object that contains a list of chat transcript records.

POST   /bots/{bot_id}/interactions

			https://api.ibm.com/virtualagent/run/api/v1/bots/{bot_id}/interactions
		
Keys
Path and Query parameters

bot_id

URL , required

Unique identifier representing a bot.

version

STRING , optional

Date used for minor versioning (currently only supports 2016-09-16).

Request code
								
HttpResponse<String> response = Unirest.post("https://api.ibm.com/virtualagent/run/api/v1/bots/{bot_id_string}/interactions?version=string") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .body("{\"entities\":[null],\"intents\":[null],\"max_start_date_time\":\"null\",\"min_start_date_time\":\"null\",\"page\":\"null\"}") .asString();
Request model

page

STRING , optional

Page number to return. If more than 1,000 records were created during the specified time frame, then the records are chunked into multiple pages with 1,000 records per page. If 20,000 records are available, page=3 will return records 2,001-3,000. The records are ordered from most recent, meaning closest to the max_start_date_time and descend to the least recent. You can page through all the records within a specific time frame by making multiple calls and changing the page number only (and not changing the min and max date time values).

min_start_date_time

DATE , required

Start of the time frame during which the chat transcripts were created that you want to export. Specify the date and time in the ISO-8601 format with an offset from the UTC/Greenwich time zone. yyyy-mm-ddThh:mm:ss.000Z. Required. Use with the max_start_date_time to define a time frame that is less than 24 hours.

max_start_date_time

DATE , required

End of the time frame during which the chat transcripts were created that you want to export. Specify the date and time in the ISO-8601 format with an offset from the UTC/Greenwich time zone. yyyy-mm-ddThh:mm:ss.000Z. Required. Use with the min_start_date_time to define a time frame that is less than 24 hours. You must specify the date, even if it is the same as the date specified by min_start_date_time. The time specified in max_start_date_time must be later than the time specified in min_start_date_time.

intents

ARRAY , optional

A list of capabilities that must be referenced in the chat transcripts for the transcript to be included in the export. Specify capabilities by using their associated intent code names. See the product documentation to look up the intent code names for the core capabilities. Do not include the Number sign (#) in the name.

entities

ARRAY , optional

A list of entities that must be referenced in the chat transcripts for the transcript to be included in the export. Specify the entities as an array of entity names. Do not include the At sign (@) in the name.

Request example
{
"page":"1",
"min_start_date_time":"2017-10-03T14:45:18.399Z",
"max_start_date_time":"2017-10-04T14:44:28.370Z",
"intents": ["Account_Management-Update_Change_Address","Billing-Bill_Copy","Reservations"],
"entities": ["paymentType","sys-number","city"]
}
Response model

200

JSON object with chat transcript details.

Body

page

INTEGER , optional

Number of the page in the batch of records for the current time frame for which the interactions are being returned.

total_pages

INTEGER , optional

Total number of pages returned, where records are batched into 1,000 per page.

interaction_count

INTEGER , optional

Number of chat transcript records (one per interaction) being returned.

total_matches

INTEGER , optional

Total number of interactions matching the query (not just on the current page).

interactions

ARRAY , optional

Array of matched interactions returned by the query. Each interaction object contains associated utterance objects and additional metadata.

error

STRING , optional

Error message text, if an error is encountered.

Response example

200

JSON object with chat transcript details.

								{
"page": 1,
"total_pages": 1,
"interaction_count": 1,
"total_matches": 1,
"interactions": [],
"error": ""
}
							

Loading content...