class IBMWatson::AssistantV2

The Assistant V2 service.

Constants

DEFAULT_SERVICE_NAME
DEFAULT_SERVICE_URL

Attributes

version[RW]

Public Class Methods

new(args = {}) click to toggle source

@!method initialize(args) Construct a new client for the Assistant service.

@param args [Hash] The args to initialize with @option args version [String] Release date of the API version you want to use. Specify dates in YYYY-MM-DD

format. The current version is `2020-09-24`.

@option args service_url [String] The base service URL to use when contacting the service.

The base service_url may differ between IBM Cloud regions.

@option args authenticator [Object] The Authenticator instance to be configured for this service. @option args service_name [String] The name of the service to configure. Will be used as the key to load

any external configuration, if applicable.
Calls superclass method
# File lib/ibm_watson/assistant_v2.rb, line 52
def initialize(args = {})
  @__async_initialized__ = false
  defaults = {}
  defaults[:service_url] = DEFAULT_SERVICE_URL
  defaults[:service_name] = DEFAULT_SERVICE_NAME
  defaults[:authenticator] = nil
  defaults[:version] = nil
  user_service_url = args[:service_url] unless args[:service_url].nil?
  args = defaults.merge(args)
  @version = args[:version]
  raise ArgumentError.new("version must be provided") if @version.nil?

  args[:authenticator] = IBMCloudSdkCore::ConfigBasedAuthenticatorFactory.new.get_authenticator(service_name: args[:service_name]) if args[:authenticator].nil?
  super
  @service_url = user_service_url unless user_service_url.nil?
end

Public Instance Methods

bulk_classify(skill_id:, input: nil) click to toggle source

@!method bulk_classify(skill_id:, input: nil) Identify intents and entities in multiple user utterances. Send multiple user inputs to a dialog skill in a single request and receive

information about the intents and entities recognized in each input. This method
is useful for testing and comparing the performance of different skills or skill
versions.

This method is available only with Enterprise with Data Isolation plans.

@param skill_id [String] Unique identifier of the skill. To find the skill ID in the Watson Assistant user

interface, open the skill settings and click **API Details**.

@param input [Array] An array of input utterances to classify. @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.

# File lib/ibm_watson/assistant_v2.rb, line 304
def bulk_classify(skill_id:, input: nil)
  raise ArgumentError.new("skill_id must be provided") if skill_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "bulk_classify")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  data = {
    "input" => input
  }

  method_url = "/v2/skills/%s/workspace/bulk_classify" % [ERB::Util.url_encode(skill_id)]

  response = request(
    method: "POST",
    url: method_url,
    headers: headers,
    params: params,
    json: data,
    accept_json: true
  )
  response
end
create_session(assistant_id:) click to toggle source

@!method create_session(assistant_id:) Create a session. Create a new session. A session is used to send user input to a skill and receive

responses. It also maintains the state of the conversation. A session persists
until it is deleted, or until it times out because of inactivity. (For more
information, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-settings).

@param assistant_id [String] Unique identifier of the assistant. To find the assistant ID in the Watson

Assistant user interface, open the assistant settings and click **API Details**.
For information about creating assistants, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

**Note:** Currently, the v2 API does not support creating assistants.

@return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.

# File lib/ibm_watson/assistant_v2.rb, line 88
def create_session(assistant_id:)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "create_session")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  method_url = "/v2/assistants/%s/sessions" % [ERB::Util.url_encode(assistant_id)]

  response = request(
    method: "POST",
    url: method_url,
    headers: headers,
    params: params,
    accept_json: true
  )
  response
end
delete_session(assistant_id:, session_id:) click to toggle source

@!method delete_session(assistant_id:, session_id:) Delete session. Deletes a session explicitly before it times out. (For more information about the

session inactivity timeout, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-settings)).

@param assistant_id [String] Unique identifier of the assistant. To find the assistant ID in the Watson

Assistant user interface, open the assistant settings and click **API Details**.
For information about creating assistants, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

**Note:** Currently, the v2 API does not support creating assistants.

@param session_id [String] Unique identifier of the session. @return [nil]

# File lib/ibm_watson/assistant_v2.rb, line 128
def delete_session(assistant_id:, session_id:)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  raise ArgumentError.new("session_id must be provided") if session_id.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "delete_session")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  method_url = "/v2/assistants/%s/sessions/%s" % [ERB::Util.url_encode(assistant_id), ERB::Util.url_encode(session_id)]

  request(
    method: "DELETE",
    url: method_url,
    headers: headers,
    params: params,
    accept_json: true
  )
  nil
end
delete_user_data(customer_id:) click to toggle source

@!method delete_user_data(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](https://cloud.ibm.com/docs/assistant?topic=assistant-information-security#information-security).

**Note:** This operation is intended only for deleting data associated with a
single specific customer, not for deleting data associated with multiple customers
or for any other purpose. For more information, see [Labeling and deleting data in
Watson
Assistant](https://cloud.ibm.com/docs/assistant?topic=assistant-information-security#information-security-gdpr-wa).

@param customer_id [String] The customer ID for which all data is to be deleted. @return [nil]

# File lib/ibm_watson/assistant_v2.rb, line 409
def delete_user_data(customer_id:)
  raise ArgumentError.new("version must be provided") if version.nil?

  raise ArgumentError.new("customer_id must be provided") if customer_id.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "delete_user_data")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version,
    "customer_id" => customer_id
  }

  method_url = "/v2/user_data"

  request(
    method: "DELETE",
    url: method_url,
    headers: headers,
    params: params,
    accept_json: true
  )
  nil
end
list_logs(assistant_id:, sort: nil, filter: nil, page_limit: nil, cursor: nil) click to toggle source

@!method list_logs(assistant_id:, sort: nil, filter: nil, page_limit: nil, cursor: nil) List log events for an assistant. List the events from the log of an assistant.

This method requires Manager access, and is available only with Enterprise plans.

@param assistant_id [String] Unique identifier of the assistant. To find the assistant ID in the Watson

Assistant user interface, open the assistant settings and click **API Details**.
For information about creating assistants, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

**Note:** Currently, the v2 API does not support creating assistants.

@param 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 (`-`).

@param filter [String] A cacheable parameter that limits the results to those matching the specified

filter. For more information, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-filter-reference#filter-reference).

@param page_limit [Fixnum] The number of records to return in each page of results. @param cursor [String] A token identifying the page of results to retrieve. @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.

# File lib/ibm_watson/assistant_v2.rb, line 358
def list_logs(assistant_id:, sort: nil, filter: nil, page_limit: nil, cursor: nil)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "list_logs")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version,
    "sort" => sort,
    "filter" => filter,
    "page_limit" => page_limit,
    "cursor" => cursor
  }

  method_url = "/v2/assistants/%s/logs" % [ERB::Util.url_encode(assistant_id)]

  response = request(
    method: "GET",
    url: method_url,
    headers: headers,
    params: params,
    accept_json: true
  )
  response
end
message(assistant_id:, session_id:, input: nil, context: nil, user_id: nil) click to toggle source

@!method message(assistant_id:, session_id:, input: nil, context: nil, user_id: nil) Send user input to assistant (stateful). Send user input to an assistant and receive a response, with conversation state

(including context data) stored by Watson Assistant for the duration of the
session.

@param assistant_id [String] Unique identifier of the assistant. To find the assistant ID in the Watson

Assistant user interface, open the assistant settings and click **API Details**.
For information about creating assistants, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

**Note:** Currently, the v2 API does not support creating assistants.

@param session_id [String] Unique identifier of the session. @param input [MessageInput] An input object that includes the input text. @param context [MessageContext] Context data for the conversation. You can use this property to set or modify

context variables, which can also be accessed by dialog nodes. The context is
stored by the assistant on a per-session basis.

**Note:** The total size of the context data stored for a stateful session cannot
exceed 100KB.

@param user_id [String] A string value that identifies the user who is interacting with the assistant. The

client must provide a unique identifier for each individual end user who accesses
the application. For user-based plans, this user ID is used to identify unique
users for billing purposes. This string cannot contain carriage return, newline,
or tab characters. If no value is specified in the input, **user_id** is
automatically set to the value of **context.global.session_id**.

**Note:** This property is the same as the **user_id** property in the global
system context. If **user_id** is specified in both locations, the value specified
at the root is used.

@return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.

# File lib/ibm_watson/assistant_v2.rb, line 190
def message(assistant_id:, session_id:, input: nil, context: nil, user_id: nil)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("session_id must be provided") if session_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "message")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  data = {
    "input" => input,
    "context" => context,
    "user_id" => user_id
  }

  method_url = "/v2/assistants/%s/sessions/%s/message" % [ERB::Util.url_encode(assistant_id), ERB::Util.url_encode(session_id)]

  response = request(
    method: "POST",
    url: method_url,
    headers: headers,
    params: params,
    json: data,
    accept_json: true
  )
  response
end
message_stateless(assistant_id:, input: nil, context: nil, user_id: nil) click to toggle source

@!method message_stateless(assistant_id:, input: nil, context: nil, user_id: nil) Send user input to assistant (stateless). Send user input to an assistant and receive a response, with conversation state

(including context data) managed by your application.

@param assistant_id [String] Unique identifier of the assistant. To find the assistant ID in the Watson

Assistant user interface, open the assistant settings and click **API Details**.
For information about creating assistants, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

**Note:** Currently, the v2 API does not support creating assistants.

@param input [MessageInputStateless] An input object that includes the input text. @param context [MessageContextStateless] Context data for the conversation. You can use this property to set or modify

context variables, which can also be accessed by dialog nodes. The context is not
stored by the assistant. To maintain session state, include the context from the
previous response.

**Note:** The total size of the context data for a stateless session cannot exceed
250KB.

@param user_id [String] A string value that identifies the user who is interacting with the assistant. The

client must provide a unique identifier for each individual end user who accesses
the application. For user-based plans, this user ID is used to identify unique
users for billing purposes. This string cannot contain carriage return, newline,
or tab characters. If no value is specified in the input, **user_id** is
automatically set to the value of **context.global.session_id**.

**Note:** This property is the same as the **user_id** property in the global
system context. If **user_id** is specified in both locations in a message
request, the value specified at the root is used.

@return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.

# File lib/ibm_watson/assistant_v2.rb, line 255
def message_stateless(assistant_id:, input: nil, context: nil, user_id: nil)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "message_stateless")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  data = {
    "input" => input,
    "context" => context,
    "user_id" => user_id
  }

  method_url = "/v2/assistants/%s/message" % [ERB::Util.url_encode(assistant_id)]

  response = request(
    method: "POST",
    url: method_url,
    headers: headers,
    params: params,
    json: data,
    accept_json: true
  )
  response
end