Virtual Agent API Lab

Use REST to Initiate, Communicate,

Transfer, and Terminate
1.0
660m
Conversations with Virtual Agent

Lab Objectives
You will achieve the following objectives:
• Setup authentication credentials to allow third-party systems to connect to Virtual Agent
• Use REST calls to initiate, communicate, and terminate conversations with Virtual Agent

Lab Dependency: ServiceNow instance on Quebec or after, access to the ServiceNow Store

Required Resource(s): Personal Developer Instance (PDI), Postman app, Virtual Agent API Lab
update set, Sample Request file, Sample Request – SWITCH file, and Sample Request – Static
Token file

Scenario

For this lab, Virtual Agent is a standalone bot that you will integrate with another third-party
chat interface/collaboration tool. Using REST, you will initiate, communicate, request live
agent support, and terminate conversations.

A. Request Developer Instance

1. Navigate to https://developer.servicenow.com.
2. Log into your account. If you are already logged in, go to the next step.

3. Click Request Instance.

4. Select the latest release version.

5. Click Request. Setting up your instance may take a few minutes.

6. Click Open Instance.

B. Install Plugins
1. Navigate to System Definition > Plugins.

2. Search for the Virtual Agent plugin and click Install/Update All.

3. Select the Load demo data check box.

4. Click Install. Installing the Virtual Agent plugin will take a few minutes.

5. Click Close.
 6. Search for the Virtual Agent API plugin and click Install. The version number may be
different than the screenshot below. Please visit the ServiceNow Store for current
information about the store app.

7. Click Install. Installing the Virtual Agent API store app may take a few minutes.

8. Click Close.

C. Update Properties
You will be using Postman (an application for building and testing APIs) to send REST requests
to your ServiceNow instance. A formatted response (REST response) is sent to the sender
(Postman). By default, ServiceNow will send either a success or failure response. You will
enable a few additional settings to view the complete REST response for this exercise.

1. In the Filter navigator, enter sys_properties.list and hit enter.

Discussion: Not all tables have modules in the application navigator. If a module is not
available, you will be instructed to type in the table name in the filter navigator.

2. Find and open the va.bot.to.bot.logging_enabled property and update the Value
field to true. You may see a message about being in the Global application scope.
You can edit this system property by clicking here.
 3. Click Update.

4. In the Filter navigator, enter sys_cs_channel.list and hit enter.

5. Personalize the list view and add the Synchronous field.

6. On the Bot to Bot record, set the Synchronous field to true. This will allow you to
view the entire response message in Postman.

D. Apply Update Set

A few Virtual Agent topics were created to help you follow our expert demonstrating VA API.
These topics will be reused throughout this lab guide. Make sure to download the Virtual
Agent API Lab Update Set file from the VA API - Before You Get Started module in Now
Learning.

1. Navigate to System Update Sets > Retrieved Update Sets.

 2. Click Import Update Set from XML.

Note: You may not have any update sets visible in your list.

3. Select and upload the Virtual Agent API Lab Update Set file.

4. Next, open the Virtual Agent API Lab update set.

5. Click Preview Update Set. There should be no errors.

6. Click Commit Update Set.

E. Configure Inbound Authentication

1. Navigate to System Web Services > Scripted Web Services > Scripted REST APIs.

2. Click on the VA Bot Integration record.

 3. On the Resource related list, click on the Bot Integration record.

4. Navigate to the Security tab on the Scripted REST Resource page for Bot Integration.
Select the Requires authentication check box. This enables basic authentication,
which is used in Postman. Unselect the Requires ACL authorization checkbox.

Note: Guest usage is already supported out of the box for Basic or OAuth when selecting the
Requires Authentication checkbox. However, you must also add Static or Hash token-based
authentication to support user account linking.

5. Click Update.

Enable Account Linking

You will enable account linking, allowing you to start conversations as specific users. Account
linking requires a static or hash token. For this exercise, you will create a static token that will
be passed in the request's header. Later in the lab, we will show you how to pass the token in
the message.

6. To create the token, enter token_verification.list in the Filter navigator and hit
enter.
7. Click New.

8. Complete the Token Verification form as follows:

Name: Provide any name

Token: Provide any password

9. Click Submit.

10. Next, you will set up a provider authentication record, defining which token to use
for inbound and outbound messages. In the Filter navigator, enter
message_auth.list and hit enter.

11. Click New.

12. Complete the Message Auth form as follows:

Name: Provide any name of the message authentication

Provider: Provide the name of the provider
Inbound message verification: Select the static token you created in step 8
Outbound message creation: Select the static token you created in step 8

13. Click Submit.

14. In the Filter navigator, enter sys_cs_provider_application.list and hit enter.

15. Open the VA Bot to Bot Provider Application record.

16. Update the Message auth field to the message auth you set up in step 12. Note you
may be in a different application scope. You can edit the record by clicking the here
link.
 17. Click Update.

F. Install Postman
Postman is an API platform that you will be using to build and test APIs. If you have another
tool to test APIs, skip to section D.

1. Navigate to http://www.postman.com.
2. Sign up for a free account.

3. Install the Postman application on your computer.

4. Open the Postman app. Please note that the following steps and screenshots were
recorded with the MAC version. Therefore, the screens may differ for the PC version.

5. Click on the Workspace tab and select New Workspace.

6. In the Name field, enter Virtual Agent API.

7. Click Create Workspace and Team.

8. Click Go to Workspace.
9. Under the Collections tab, click Create collection.

10. In the Collection name field, enter VA API.

11. Under your VA API collection, click Add a request.

12. In the Request drop-down, change the value to POST and enter https://<your-
instance>.service-now.com/api/sn_va_as_service/bot/integration.

Discussion: The last part of the URL “/api/sn_va_as_service/bot/integration” is the

resource path from the VA Bot Integration Scripted REST API.

13. Click on the Authorization tab and update the Type to Basic Auth.

14. Next, you will provide your admin credentials. Update the Username field to admin.
To get your password, navigate to https://developer.servicenow.com. Click on your
initials in the upper right-hand corner and click Manage instance password. Copy
the password into the Password field in Postman.
 Postman:

15. Click on the Headers tab. Some parameters are hidden. Click on the hidden button
and add the following parameter:

Key: Content-Type
Value: application/json
 16. Next, you will add a new line to include the static token you created earlier in the
lab. Enter the following:

Key: token
Value: Enter the VALUE of the token you created in section E. To get this value,
enter token_verification.list in the Filter navigator and hit enter. Open the token
you created. Next to the Token field, click on the lock icon and copy the value.
Paste the value into the Value field in Postman.

Note: Your token value will differ from the value in the screenshot.

G. Starting Conversations with Virtual Agent

This section will show you three different ways to start a conversation with Virtual Agent.

Initiating Conversations With the START_CONVERSATION Action

Parameter

1. In Postman, click on the Body tab and select the Raw radio button.

2. Open the Virtual Agent API - Sample Request text file and copy the contents into
the body field.
3. Click Send. You should see the JSON response of Virtual Agent initiating a
conversation.
4. In the JSON response, you will see a few available topics such as Incident Details and
Live Agent Support. To invoke a topic, you can pass the label or value of the topic.
Go back to your message, update the text parameter value to Incident Details, and
remove START_CONVERSATION from the action parameter.

5. Click Send. You should see the response asking you to enter an incident number.
6. Go back to your message and update the text parameter value to INC0009005.

7. Click Send. You should see the short description of the incident displayed in the
response.
Initiating Conversations as a Guest User and Entering Text
Greeting

8. Go back to your message and update the following parameters:

text: “Hi”
userId: “guest”
emailId: “”

9. Click Send. You should see the response of Virtual Agent initiating a conversation.
10. You will invoke the Incident Details topic again. However, you will pass the value of
the topic instead of the name. From the response message, copy the value of the
Incident Details topic and update the text parameter value. Also, update the typed
parameter value to false.

11. Click Send. You should see the response asking you to enter an incident number.
12. Go back to your message and update the text parameter to INC0009005.

13. Click Send. In the response, you should see that the user does not have access to
view the record. This is because they are a guest user.
Initiating Conversations with Topic Names

14. Go back to your message and update the text parameter value to Incident Details.

15. Click Send. You should see the response asking you to enter an incident number.
 16. Update the text parameter value to INC0009005.

17. Click Send. In the response, you should see that the user does not have access to
view the record. This is because they are a guest user.

H. Ending Conversations with Virtual Agent

This section will show you how to terminate conversations with VA. We will continue to use
the same message as the previous section. However, if you are following along with the pre-
recorded videos, the message will look different.
1. Initiate a new conversation by updating the text parameter value to Hi.

2. Click Send. You should see the response of Virtual Agent initiating a conversation.
3. Invoke the Incident Details topic. Go to your message and update the text parameter
value to Incident Details.

4. Pretend that you are a user that does not want to continue the conversation. You
can send a message to end the conversation. Go to your message and update the
following parameters:

action: “END_CONVERSATION”
text: “”
 5. Click Send. You should see the response that the conversation has ended.

I. Ending Conversations Using the Bye Keyword

This section will show you how to terminate conversations with VA using the Bye keyword. We
will continue to use the same message as the previous sections. However, if you are following
along with the pre-recorded videos, the lab steps will differ.

1. Initiate a conversation by updating the text parameter value to Incident Details and
the typed parameter value to true. Remove END_CONVERSATION from the action
parameter.

2. Click Send.
3. You have invoked the Incident Details topics. However, you now want to end the
conversation. You can end the conversation using the bye keyword. Go to your
message and update the text parameter value to bye.

4. Click Send. You should see the response asking you to confirm if you want to end the
conversation.
 5. You can end the conversation using the option label or value. Go to your message
and update the text parameter value to End conversation.

6. Click Send. You should see the response confirming that the conversation has ended.

J. Switching Topics
1. Copy the contents of the Sample Request – SWITCH file and past it into the body
field.
2. Initiate a conversation by updating the text parameter value to hi.

3. Click Send. You should see the response of Virtual Agent initiating a conversation.

4. Invoke the Incident Details topic by updating the text parameter value to Incident
Details.
5. Click Send. You should see the response asking you to enter an incident number.

6. Instead of completing the topic flow, you want to switch to a different topic. You can
change topics by updating the action parameter value to SWITCH.

7. You need to provide either the topic name or ID in the message to switch topics.
Update the topic name parameter value to Create an Incident and clear the text
parameter value.
 8. Click Send. You should see the response asking you to enter a brief description of
your issue.

9. Send a message to end the conversation.

K. Starting and Ending Conversations with a Live Agent

This section will show you how to start and end conversations with a live agent. In a different
browser, you will need to impersonate the user, Beth Anglin. If you have any issues routing
chats to Beth, you may need to repair the Agent Chat plugin. See instructions at the end of the
guide to fix the plugin.

1. Go to your ServiceNow instance and impersonate Beth Anglin.

2. Navigate to Workspace Experience > Agent Workspace Home. This should open
Agent Workspace in a separate browser tab or window.
3. Click on the Inbox icon.

4. Click on the Status drop-down and select Available.

5. In Postman, start a new conversation by updating the text parameter value to hi.
Also, clear the URL parameter value we used in the previous section.
6. Click Send. You should see the response of Virtual Agent initiating a conversation.

7. You want to be transferred to a live agent. Update the text parameter value to Live
Agent Support..

8. Click Send. You should see the response that your request is being routed to a live
agent.
9. Go to your ServiceNow instance and accept the chat request.

10. Send a message as the agent.

11. The agent’s message is sent to the user. An example of this can be seen in the logs.
 12. You will now end the conversation. Go to your message and update the action
parameter value to END_CONVERSATION.

13. Click Send. You should see a response that the conversation has ended.

L. Passing Static Tokens in Messages

You have passed a static token in the request header until now. However, ServiceNow does
allow static tokens to be passed in the message itself. You will learn how to pass a static token
in the message in the steps below.

1. In Postman, copy the contents of the Sample Request – Static Token file into the
body field.

2. Add the following line below the action parameter:

“token”: “Enter the token value you created in Section E. The value you use will be
different from the screenshot.”
 3. Click on the Header tab and clear the token checkbox.

4. Click Send. You should see the response of Virtual Agent initiating a conversation.

Congratulations on completing the lab!

M. Repairing Plugin
1. Navigate to System Definition > Plugins.

2. Search for the Agent Chat plugin.

3. On the Agent Chat plugin, click on the three dots and select Repair. If it is not active,
please install the plugin.
4. Select the Load demo data check box and click Repair.