Initial configuration

Before the ServiceNow Handoff can go live, configure your ServiceNow instance and your AI Agent, then share a set of values with your Ada team. Complete the sections on this page in order. Repeat the Ada steps for each AI Agent that connects to ServiceNow.

Requirements

Confirm the following before you start, so each setup step is available to you.

Ada:

• An AI Agent with a messaging channel

ServiceNow:

• ServiceNow administrator access
• The Virtual Agent plugin, active on your instance
• Integration Hub or the relevant ServiceNow messaging plugins, active on your instance

If you have problems with a ServiceNow setup step, contact ServiceNow support for help specific to your instance.

Find your instance hostname

Ada uses the instance hostname to send requests to your ServiceNow instance.

To find your instance hostname:

1. Open your ServiceNow instance in a browser.
2. Copy the subdomain from the URL. For example, if your instance URL is https://acmecorp.service-now.com, the hostname is acmecorp.

Create an OAuth application

Ada uses OAuth 2.0 with the client credentials grant to authenticate with your ServiceNow instance.

To create the OAuth application:

1. In the ServiceNow navigation bar, search for Application Registry and open it under System OAuth.
2. Click New.
3. Select Create an OAuth API endpoint for external clients.
4. Complete the form:
   • Name: Ada Integration, or another descriptive name.
   • Client ID: ServiceNow generates this value. Keep it as is, or customize it.
   • Client Secret: Click the lock icon to show and copy the secret. Store it securely.
   • Redirect URL: Leave the field empty. The client credentials grant type does not use it.
   • Default Grant type: Client Credentials
   • Accessible from: All application scopes
5. Click Submit.
6. Open the record again, then copy the Client ID and the Client Secret. Store both values securely. You share them with your Ada team in a later step.

Create the integration channel

The App Inbound ID identifies Ada as an inbound channel in your Virtual Agent configuration.

To create the integration channel:

1. In the navigation bar, search for Bot Integration or navigate to Virtual Agent > Bot Integration Channels.
2. Click New to create a new inbound integration channel.
3. Complete the form:
   • Name: Ada, or another descriptive name.
   • Channel: Select the appropriate inbound channel type. This is typically REST API / Bot to Bot.
   • Direction: Inbound
4. Click Submit.
5. Open the record again, then copy the App Inbound ID. The record can label it Inbound Integration ID, Inbound ID, or sysId.

Create an app token

ServiceNow uses the app token to validate inbound requests from Ada and confirm that they are authentic.

To create the app token:

1. In the ServiceNow address bar, enter token_verification.list, then press Enter.
2. Click New to create a new token.
3. Complete the form:
   • Application: Select or type Ada. This value corresponds to the Virtual Agent application or scope.
   • Token: Enter a secure, unique string, such as a UUID or a long random alphanumeric string. Ada includes this token with every inbound request.
   • Active: Select the check box.
4. Click Submit.
5. Copy the Token value.

Use a strong, randomly generated string for the token. An online UUID generator or a password manager can create one.

Configure the outbound webhook

ServiceNow sends agent messages and conversation events to Ada through an outbound webhook. ServiceNow authenticates each call with Basic Authentication, and Ada rejects any call with a missing or wrong password.

To configure the outbound webhook:

1. Generate a random value of 32 or more characters. Use a password manager to create it. This value is the outbound webhook password.
2. In the navigation bar, navigate to Virtual Agent > Bot Integration Channels, the same area where you created the inbound channel.
3. Open the Ada integration channel record you created.
4. Locate the Outbound endpoint or Response URL field, then enter the URL for your AI Agent’s cluster:
   • US: https://solutions.ada.support/messaging-connectors/servicenow/webhooks/servicenow
   • EU: https://solutions.eu.ada.support/messaging-connectors/servicenow/webhooks/servicenow
5. Set the authentication method to Basic Authentication.
6. Enter the credentials:
   • Username: servicenow
   • Password: The outbound webhook password from step 1.
7. Save the record.

Add Ada to trusted media domains

If your environment restricts traffic for files and attachments, add Ada’s domains to the ServiceNow trusted media domains list so that attachments can be shared.

To add the trusted media domains:

1. In the navigation bar, search for Trusted Media Domains under the Virtual Agent settings.
2. Click New, then enter the following domains:
   • *.ada.support
   • integrations-file-uploader-s3-production-us2.s3.amazonaws.com
   • integrations-file-uploader-s3-production.s3.amazonaws.com
   • integrations-file-uploader-s3-production-eu.s3.amazonaws.com
3. Click Submit.

Create the Ada Webhook

Ada sends end user messages and conversation events to the ServiceNow integration through a Webhook.

To create the Webhook:

1. In your AI Agent dashboard, navigate to Platform > Webhooks.
2. Click Add Endpoint.
3. In the Endpoint URL field, enter the URL for your AI Agent’s cluster:
   • US: https://solutions.ada.support/messaging-connectors/servicenow/webhooks/ada
   • EU: https://solutions.eu.ada.support/messaging-connectors/servicenow/webhooks/ada
4. Under Subscribe to events, select the check boxes for all conversation events.
5. Save the endpoint.
6. Open the endpoint, then copy the Signing Secret.

Create an API key

The integration uses an API key to post agent messages to the conversation and to end the Handoff.

To create the API key:

1. In your AI Agent dashboard, navigate to Platform > API keys.
2. Click New API key.
3. Copy the key. The key appears only once. Store it securely.

Share with your Ada team

Your Ada team uses these values to connect your AI Agent to ServiceNow. Share them securely, not in a shared channel or in email.

When your Ada team has these values, they finish the setup and tell you when you can configure the handoff.