Migrating to the v2 API

Overview

With the v2 API, your client app communicates with an assistant, rather than directly with a workspace. An assistant is a new orchestration layer that offers several new capabilities, including automatic state management, skill versioning, easier deployment, and (for Plus and Premium plans) search skills. Your existing workspace (now referred to as a dialog skill) continues to function as before, but the new capabilities are provided by the new assistant layer.

All communication with an assistant takes place within the context of a session, which maintains conversation state throughout the duration of the conversation. State data, including any context variables that are defined by your dialog or client application, are automatically stored by Watson Assistant, without any action required on the part of your application.

State data persists until you explicitly delete the session, or until the session times out because of inactivity.

If you prefer to manage state yourself, the v2 API also provides a stateless message method that functions more like the v1 API. If you use the stateless message method, you do not need to explicitly create or delete sessions, and your app is responsible for maintaining context. For more information about the stateless message method, see the API Reference.

If you have an existing application that uses the v1 API to send user input directly to a workspace, migrating your app to use the v2 API is a straightforward process.

Set up an assistant

The v2 runtime API sends messages to an assistant, which routes the messages to your dialog skill (formerly workspace). To set up an assistant, use the Watson Assistant user interface:

1. Click the Skills tab. Verify that your workspace is shown as an available skill. (All existing workspaces for your service instance are automatically converted to skills in the Watson Assistant user interface. This conversion does not make any change to the underlying workspace.)

2. Click the Assistants tab. Click Create assistant to create a new assistant. When prompted to add skills, click Add dialog skill and select the dialog skill that corresponds to your workspace.

   For more information about creating assistants, see Creating an assistant.

3. After your new assistant is created, click the menu and then select Settings.

4. On the Assistant Settings page, find the assistant ID. Your application will use this ID (instead of a workspace ID) to communicate with the assistant. The service credentials are the same for both the v1 and v2 APIs.

   Currently, there is no API support for retrieving an assistant ID. To find the assistant ID, you must use the Watson Assistant user interface.

Call the v2 runtime API

After you have created an assistant, you can update your client application to use the v2 runtime API instead of the v1 runtime API.

1. Before sending the first message in a conversation, use the v2 Create a session method to create a session. Save the returned session ID:

service .createSession({ assistant_id: assistantId, }) .then(res => { sessionId = res.session_id; })

  ```python {: codeblock  python }
session_id = service.create_session(
    assistant_id = assistant_id
).get_result()['session_id']

```java {: codeblock java}

CreateSessionOptions createSessionOptions = new CreateSessionOptions.Builder(assistantId).build(); SessionResponse session = service.createSession(createSessionOptions).execute().getResult(); String sessionId = session.getSessionId();

1. Use the v2 [**Send user input to assistant**](https://{DomainName}/apidocs/assistant/assistant-v2#message){: external} method to send user input to the assistant. Instead of specifying the workspace ID as you did with the v1 API, you specify the assistant ID and the session ID:

  ```javascript {: codeblock javascript}
service
  .message({
    assistant_id: assistantId,
    session_id: sessionId,
    input: messageInput
  })

```python {: codeblock python}

response = service.message( assistant_id, session_id, input = message_input ).get_result()

  ```java {: codeblock java}
MessageInput input = new MessageInput.Builder().text(inputText).build();
MessageOptions messageOptions = new MessageOptions.Builder(assistantId, sessionId)
  .input(input)
  .build();
MessageResponse response = service.message(messageOptions)
  .execute()
  .getResult();

The basic message structure has not changed; in particular, the user input is still sent as `input.text`.

1. After a conversation ends, use the v2 Delete session method to delete the session.

service .deleteSession({ assistant_id: assistantId, session_id: sessionId, })

  ```python {: codeblock python}
service.delete_session(
    assistant_id = assistant_id,
    session_id = session_id
)

```java {: codeblock java}

DeleteSessionOptions deleteSessionOptions = new DeleteSessionOptions.Builder(assistantId, sessionId .build(); service.deleteSession(deleteSessionOptions).execute();

 If you do not explicitly delete the session, it will be automatically deleted after the configured timeout interval.

To see examples of the v2 APIs in the context of a simple client application, see [Building a client application](/docs/assistant?topic=assistant-api-client).

## Handle the v2 response format

Your application might need to be updated to handle the v2 runtime response format, depending on which parts of the response your application needs to access:

- Output for all response types (such as `text` and `option`) are still returned in the `output.generic` object. Application code for handling these responses should work without modification.

- Detected intents and entities are now returned as part of the `output` object, rather than at the root of the response JSON.

- The conversation context is now organized into two objects:

  - The **global context** contains system-level context data shared by all skills used by the assistant.

  - The **skill context** contains any user-defined context variables used by your dialog skill.

  However, keep in mind that state data, including conversation context, is now maintained by the assistant, so your application might not need to access the context at all (see [Let the assistant maintain state](#api-migration-state)).

Refer to the v2 [API Reference ](https://{DomainName}/apidocs/assistant/assistant-v2#message){: external} for complete documentation of the v2 response format.

## Let the assistant maintain state {: #api-migration-state}

For most applications, you can now remove any code included for the purpose of maintaining state. It is no longer necessary to save the context and send it back to Watson Assistant with each turn of the conversation. The context is automatically maintained by {{site.data.keassistant_classic_shortnshort}} and can be accessed by your dialog as before.

Note that with the v2 API, the context is by default not included in responses to the client application. However, your code can still access context variables if necessary:

- You can still send a `context` object as part of the message input. Any context variables you include are stored as part of the context maintained by Watson Assistant. (If the context variable you send already exists in the context, the new value overwrites the previously stored value.)

  Make sure the context object you send conforms to the v2 format. All user-defined context variables sent by your application should be part of the skill context; typically, the only global context variable you might need to set is `system.user_id`, which is used by Plus and Premium plans for billing purposes.

- You can still retrieve context variables from either the global or skill context. To have the `context` object included with message responses, use the **return_context** property in the message input options. For more information, see [Accessing context data](/docs/assistant?topic=assistant-api-client-get-context).