ServiceNow Virtual Agent & Third-Party Chatbots

I recently worked on a project where I had to configure ServiceNow to integrate with a third-party chatbot. In this setup, ServiceNow’s Virtual Agent acted as a secondary assistant, responding to the external bot’s requests when needed.

Below is a high-level design of how ServiceNow interacts with the third-party bot through Virtual Agent API.

The tricky part? Several departments within the organization were already using their own customized “chat experiences”. Though they shared the same Virtual Agent, each department had unique configurations, different knowledge bases, catalogs, and AI Search behaviors, all tailored to their users.

Our goal was to ensure the out-of-the-box Virtual Agent API responded correctly when queried by the third-party bot. For example, if a user from Department A made a request, the response should only reflect Department A’s context, not generic or irrelevant results.

This raised an important question: how do we configure Virtual Agent so it knows how to respond differently for each department? The answer lies in ServiceNow’s Custom Greetings and Setup feature.

What Is a “Chat experience” or “Custom Greeting and Setup”?

In ServiceNow, a Custom Greetings and Setup defines a distinct chat experience. It determines:

• The structure of the conversation (setup topics)
• Initial topics displayed to the user (promoted topics)
• The AI Search configuration used to retrieve relevant results

This makes it possible for Virtual Agent to offer personalized, context-aware experiences based on the user’s department, region, or entry point.

In this article, I’ll walk through the exact steps I followed to implement this configuration, both as a reference for myself and a guide for others tackling similar integrations.

With that background in mind, let’s walk through the end-to-end steps I followed to get ServiceNow’s Virtual Agent working smoothly with a third-party chatbot.

Steps to Configure ServiceNow Virtual Agent for 3rd-Party Integration

1. Set Up Inbound Authentication
   Enable authentication for the Scripted Inbound REST API used by the Virtual Agent API.
2. Enable Account Linking
   This allows the third-party bot to act on behalf of a real ServiceNow user. It’s essential when you have multiple chat experiences scoped to specific user groups.
3. Create a Provider Application
   Set up a unique Provider Application (Channel Identity) for the third-party bot to handle routing and responses securely.
4. Configure Outbound REST Message
   Define the webhook endpoint (i.e., the third-party bot’s receiving URL) where ServiceNow will post its responses.
5. Define a Chat Experience
   Create a Custom Greeting and Setup tailored to a specific audience (e.g., department, region, user group).

With this setup, your ServiceNow Virtual Agent can seamlessly support third-party bots while preserving context and delivering accurate, group-specific responses.

Step 1: Set Up Inbound Authentication

The Virtual Agent API plugin adds a Scripted REST API called “VA Bot Integration.” This is where incoming messages from your third-party bot land.

To configure it:

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

1. Go to System Web Services > Scripted Web Services > Scripted REST APIs.
2. Find and open the VA Bot Integration record.
3. Under “Resources,” click the Bot Integration record.

   

4. On the Security tab:
   Check Requires authentication to enable Basic Auth.
   Uncheck Requires ACL authorization.

   

Step 2: Enable Account Linking

Account linking allows your third-party bot to start conversations on behalf of real ServiceNow users. This means users can see their own data, perform actions with their identity, and get a personalized response from the Virtual Agent.

Each message must include the user’s identity. This is done using:

• userId: Typically the user’s username or user ID in ServiceNow
• emailId: The user’s email (must match a record in sys_user)
• A static token, passed either in the request header or in the message body. I recommend always using the request header!

---

Steps to Set Up Account Linking

1. Create a Static Token

This token will be passed in the request headers when the third-party bot sends REST messages to ServiceNow.

1. In the ServiceNow filter navigator, type token_verification.list
2. Click New
3. Fill out the fields:
   Name: e.g., GoogleDialogFlow
   Token: Choose a secure value like mySecret123! (this will be referenced in requests)

   

4. Click Submit

2. Configure Message Authentication

This step creates a Message Authentication record that links to the static token created earlier. This record will later be associated with your Provider Application to ensure secure communication between the third-party bot and ServiceNow.

1. Go to message_auth.list
2. Click New
3. Set:
   Name: e.g., Google Static Auth
   Provider: any provider name (can match provider app name DialogFlow)
   Inbound Message Verification: choose the token you just created above, i.e., GoogleDialogFlow
   Outbound Message Creation: choose the same token,i.e.,GoogleDialogFlow

   

4. Click Submit

Step 3. Create a Provider Application

A Provider Application in ServiceNow links the necessary components for securely integrating a third-party bot with the Virtual Agent API. This includes the inbound identity, authentication token, and outbound messaging configuration. You should create one Provider Application per third-party bot that will interact with ServiceNow.

This setup ensures:

• Each bot uses its own authentication token via a Message Auth record.
• Responses are posted to the correct outbound webhook endpoint.
• ServiceNow can identify which bot is calling the API using a unique Inbound ID (appInboundId).

Why this matters

Unlike Chat Experiences, which determine how users interact with the Virtual Agent and what content they see, the Provider Application is focused on security, identity, and routing for external bots and channels.

Steps to Create a Provider Application

1. In the ServiceNow filter navigator, type sys_cs_provider_application.list and press Enter.
2. Click New to create a new Provider Application.
3. Fill out the following fields:
   Name: e.g., DialogFlow Bot
   Inbound ID: A unique identifier, e.g., dialogflow-123. This must match the appInboundId passed in API requests.
   Message Auth: Select the Message Auth record you created in Step 2, e.g., Google Static Auth
   Provider: Select VA Bot to Bot Provider

   

4. Click Submit.

You’ll use this Provider Application’s Inbound ID and Message Auth in both your third-party bot setup and the outbound REST configuration in Step 4.

Step 4: Configure Outbound REST Message

To route Virtual Agent responses to your third-party bot, create an Outbound REST Message. It must have the same name as the Provider Application you created earlier.

1. Go to REST Message in the navigator.
2. Click New.
3. Set the following fields:
   Name: Must match the Provider Application name (e.g., DialogFlowBot)
   Endpoint: Webhook URL of the 3rd party bot (e.g., https://bot.example.com/receive)
   HTTP Method: POST
4. Add any required headers, such as:
   Content-Type: application/json
Authorization: Bearer <your_token>
5. Click Submit.

Note: ServiceNow automatically uses this REST Message when sending responses, as long as the name matches the Provider Application.

Step 5: Define a Chat Experience

Use a custom chat experience to personalize how the Virtual Agent interacts with users, based on factors like department, region, or access channel. Each experience can have unique greetings, promoted topics, and AI Search settings.

1. Go to Custom Greetings and Setups(sys_cs_context_profile.list) in the navigator or
   Go to Conversational Interfaces > Home.
   In the new tab, Go to Settings > Virtual Agent > Custom Greetings and Setup > View all

   

2. Click New.
3. Configure the fields:
   Name: DialogFlow_US_Experience
   Scope: Choose the appropriate application scope
   Active: Checked

   

4. In the Condition section, select Advanced and enter the following script (Remember to create you own Script Include):

   (function executeCondition(/* GlideRecord */ current) {
       var returnValue = false;
       try {
           var userCompany = gs.getUser().getCompanyID();      
           var USACompany = new CustomVAUtility().getCompanySysID('USA'); //Script Include that you can build yourself
           if (userCompany === USACompany) {
               returnValue = true;
           }
       } catch (error) {
           gs.error('[VirtualAgentUSAChatExperience] Error checking user company: ' + error);
       }
       return returnValue;
   })(current);

5. Set up the rest of the experience:
   • Setup Topic: Select the setup topic to greet and guide the user
   • Promoted Topics: Choose topics relevant to the targeted user group
   • AI Search Configuration: Select a tailored AI Search profile (optional)
6. Click Submit.

This chat experience will activate only when the defined condition evaluates to true, allowing precise targeting for different bots or user groups.

Example API Requests Using Virtual Agent Bot Integration (with appInboundId)

When integrating a third-party bot with ServiceNow’s Virtual Agent using the out-of-the-box Bot-to-Bot API v3, send HTTP POST requests to:

POST https://<servicenow subdomain>.service-now.com/api/sn_va_as_service/bot/integration

Key Fields:

• Authentication: Use Basic Auth with a static token in the request headers.
• appInboundId: Refers to the Provider Application ID and determines how the request is routed in ServiceNow.
• clientSessionId: A consistent ID to track a single conversation session.
• requestId: A unique ID for each API call.
• userId / emailId: Identify the user initiating the conversation.

1. Start Conversation

{
  "requestId": "req-001",
  "clientSessionId": "session-001",
  "message": {
    "text": "Hi",
    "typed": true
  },
  "appInboundId": "PROVIDER_APP_ID_1",
  "userId": "user1",
  "emailId": "user1@example.com",
  "action": "START_CONVERSATION"
}

2. Continue Conversation

{
  "requestId": "req-002",
  "clientSessionId": "session-001",
  "message": {
    "text": "I need help with a software installation",
    "typed": true
  },
  "appInboundId": "PROVIDER_APP_ID_1",
  "userId": "user1",
  "emailId": "user1@example.com"
}

3. End Conversation

{
  "requestId": "req-003",
  "clientSessionId": "session-001",
  "message": {
    "text": "",
    "typed": true
  },
  "appInboundId": "PROVIDER_APP_ID_1",
  "userId": "user1",
  "emailId": "user1@example.com",
  "action": "END_CONVERSATION"
}

Notes

• The appInboundId must match the Inbound ID of the Provider Application record you created in ServiceNow.
• Always keep the clientSessionId consistent throughout a single conversation session.
• Other API features such as switching topics, sending structured messages, or live agent escalation are also available.

For a complete list of supported message types and request formats, please refer to the official ServiceNow Virtual Agent Bot Integration API documentation.

Closing Thoughts

Integrating ServiceNow’s Virtual Agent with a third-party bot requires thoughtful planning around chat experiences, provider applications, authentication, and outbound messaging. Once your configuration is in place, the Virtual Agent API becomes a powerful interface for dynamic, personalized bot responses.

By following these steps and leveraging the appInboundId, you can scale your chatbot integrations confidently across multiple business units or platforms.