> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/channels-integrations/cti-plugins/servicenow.md).

# Embed WebAgent in ServiceNow

Configure the WebAgent CTI plugin for ServiceNow.

Configure the ServiceNow CTI plugin when WebAgent must be available inside ServiceNow.

The ServiceNow CTI plugin lets WebAgent authenticate with ServiceNow, load inside ServiceNow OpenFrame, and use ServiceNow CRM controls during conversations. Keep this configuration separate from CRM Service provider setup. CRM Service controls which CRM data is displayed in WebAgent; the CTI plugin controls how WebAgent is embedded in ServiceNow.

## Prerequisites

* The [shared CTI licensing and plugin enablement prerequisites](/channels-integrations/cti-plugins.md#licensing-prerequisites) are confirmed.
* Shared WebAgent sign-in is configured for ServiceNow.
* Shared WebAgent service settings are configured.
* WebAgent and the ServiceNow CTI plugin are enabled for the environment in OnePortal.
* A ServiceNow administrator can configure the application integration settings.
* The WebAgent URL for the environment is available.
* The WebAgent callback URL for the environment is available.
* The ServiceNow instance runs a supported release: Yokohama, Zurich, or Australia.

## Check the ServiceNow version

1. Sign in to the ServiceNow instance.
2. In the ServiceNow menu, enter `stats.do`, and then press **Enter**.
3. On the Statistics page, confirm the version under **Build name**.

## Configure OAuth 2.0

Create an OAuth endpoint that WebAgent can use to authenticate ServiceNow users.

1. In ServiceNow, open **System OAuth** > **Application Registry**.
2. Select **New**.
3. Create an OAuth API endpoint for external clients.

   In some ServiceNow releases, this option is labelled **\[Deprecated UI] Create an OAuth API endpoint for external clients**.
4. Configure the endpoint with these values.

   | Field             | Value                                                                                      |
   | ----------------- | ------------------------------------------------------------------------------------------ |
   | **Client ID**     | Use the generated client ID in the OpenFrame URL.                                          |
   | **Redirect URL**  | Use the exact WebAgent callback URL for the environment. The callback path is `/cti-auth`. |
   | **Public Client** | Enabled.                                                                                   |
   | **Client Type**   | Iframe Embedded.                                                                           |
   | **Token Format**  | Opaque.                                                                                    |
   | **Auth Scope**    | `useraccount`.                                                                             |
   | **Active**        | `true`.                                                                                    |
5. Save the endpoint.
6. Record the generated client ID. You need it when you configure the OpenFrame URL.

## Allow implicit grant when required

The ServiceNow WebAgent integration uses the OAuth implicit grant flow. In hardened ServiceNow instances, authentication can fail with `Invalid request` until the WebAgent OAuth client ID is explicitly allowed to use implicit grant.

1. In the ServiceNow navigation filter, enter `sys_properties.list`.
2. Search for `glide.oauth.clients.allowed.for.implicit.grant`.
3. If the property does not exist, create it as a string property.
4. Add the WebAgent OAuth client ID to the property value.

{% hint style="warning" %}
Only change this system property for the OAuth client IDs that must use implicit grant. Confirm the ServiceNow hardening policy for the customer environment before changing the property.
{% endhint %}

## Configure OpenFrame

1. In ServiceNow, activate the OpenFrame plugin.
2. Create an OpenFrame configuration for WebAgent.
3. Configure the OpenFrame entry with these values.

   | Field      | Value                                                                                                                           |
   | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
   | **Name**   | `WebAgent CTI`                                                                                                                  |
   | **Title**  | Use the display title approved for the environment.                                                                             |
   | **Width**  | `1200`                                                                                                                          |
   | **Height** | `800`                                                                                                                           |
   | **URL**    | Use the WebAgent URL for the environment and append `clientid=<clientId>`, where `<clientId>` is the generated OAuth client ID. |

   Example format:

   ```
   [WebAgent URL]?clientid=<clientId>
   ```
4. Save the OpenFrame configuration.

For DC2023.02 or later, the `clientid` parameter is required and the `referrer` parameter is optional.

For DC2023.01 or earlier, include both the `clientid` parameter and the `referrer` parameter. The `referrer` value is the base URL of the ServiceNow instance.

```
[WebAgent URL]?clientid=<clientId>&referrer=https://instance.service-now.com
```

## Technical behavior reference

The ServiceNow CTI plugin implementation supports these search fields for contacts:

| Search input  | ServiceNow fields                     |
| ------------- | ------------------------------------- |
| Phone number  | `phone`, `home_phone`, `mobile_phone` |
| Email address | `email`                               |
| Last name     | `last_name`                           |

The available create-record options depend on ServiceNow module configuration.

| Record type    | Behavior                                                                                                              |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| Contact        | Opens `sys_user`, or HR profile when HR mode is selected. Can prefill mobile phone, email, first name, and last name. |
| Incident       | Opens an incident form. Can set caller and contact type for phone or email interactions.                              |
| Problem        | Opens a problem form.                                                                                                 |
| Change request | Opens a change-request form. Can set requester and contact type for phone or email interactions.                      |
| Interaction    | Opens an interaction form. Can set interaction type and opened-for value.                                             |
| Case           | Opens a customer-service case or HR case when the relevant module is available.                                       |

For phone interactions, the plugin creates a phone-log activity and can update duration, correlation ID, and end time. By default, activity records use `sn_openframe_phone_log`; HR mode can use HR task behavior.

{% hint style="info" %}
If ServiceNow case creation is enabled but the required CSM or HR module is not available, the plugin can warn that it could not verify case creation.
{% endhint %}

## Allow the WebAgent origin

ServiceNow must allow the WebAgent origin that loads inside OpenFrame.

1. In the ServiceNow navigation filter, enter `sys_properties.list`.
2. Search for `glide.ui.concourse.onmessage_enforce_same_origin_whitelist`.
3. Add the WebAgent origin for the environment.

Use only the origin, not the full callback URL or query string.

## Prepare ServiceNow users

1. In ServiceNow, go to **User Administration** > **Users**.
2. Configure the user list columns so administrators can confirm each user's **Email** field and at least one phone field, such as **Business phone**, **Home phone**, or **Mobile phone**.
3. Assign the `sn_openframe_user` role to the users or groups that must use WebAgent inside ServiceNow.

## Configure the ServiceNow integration

1. Confirm the ServiceNow environment where WebAgent must be available.
2. Confirm the WebAgent URL, WebAgent callback URL, OAuth client ID, OpenFrame URL, and ServiceNow instance URL with the environment owner.
3. Configure OAuth 2.0 for the embedded WebAgent integration.
4. Allow implicit grant when the ServiceNow instance blocks the WebAgent OAuth flow.
5. Configure OpenFrame so it loads WebAgent with the required URL parameters.
6. Allow the WebAgent origin in ServiceNow.
7. Assign the required ServiceNow role to the users or groups that use the integration.
8. Save the integration.

## ServiceNow configuration reference

Use ServiceNow-specific configuration only when the environment owner confirms that the setting is required for the active ServiceNow instance and WebAgent deployment.

| Configuration area        | Detail                                                                                                                                                                                                                               | Use                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| OAuth application         | ServiceNow uses an OAuth API endpoint for the embedded WebAgent integration. Configure the endpoint as a public client with client type `Iframe Embedded`, token format `Opaque`, auth scope `useraccount`, and active state `true`. | Provides the client ID and authentication context for WebAgent in ServiceNow.            |
| Redirect path             | Use the full WebAgent callback URL supplied for the environment. The callback path is `/cti-auth`.                                                                                                                                   | Allows ServiceNow authentication to return to WebAgent.                                  |
| Implicit grant allowlist  | ServiceNow can block implicit grant for OAuth clients. Add the WebAgent OAuth client ID to `glide.oauth.clients.allowed.for.implicit.grant` when the instance requires explicit approval.                                            | Prevents `Invalid request` during the embedded WebAgent authentication flow.             |
| OpenFrame configuration   | ServiceNow loads WebAgent through OpenFrame. Use width `1200`, height `800`, and the WebAgent URL for the environment.                                                                                                               | Defines where WebAgent appears in ServiceNow.                                            |
| URL parameters            | The OpenFrame URL requires `clientid=<clientId>`. For DC2023.01 or earlier, also include `referrer=<ServiceNow instance base URL>`.                                                                                                  | Connects the embedded WebAgent URL to the ServiceNow OAuth and instance context.         |
| Allowed origin            | Add the WebAgent origin to `glide.ui.concourse.onmessage_enforce_same_origin_whitelist`.                                                                                                                                             | Allows ServiceNow to load WebAgent in the embedded frame.                                |
| Role and group assignment | ServiceNow users or groups must receive the `sn_openframe_user` role.                                                                                                                                                                | Controls who can open WebAgent inside ServiceNow.                                        |
| Access token lifespan     | ServiceNow token lifetime can affect embedded WebAgent sign-in behavior.                                                                                                                                                             | Controls how often users must renew the ServiceNow token.                                |
| `format-correlationid`    | Optional URL parameter. Append with `&` when another query parameter is already present.                                                                                                                                             | Controls how correlation identifiers are written for ServiceNow activity context.        |
| `phoneformat`             | Optional URL parameter. Append with `&` when another query parameter is already present.                                                                                                                                             | Controls how ServiceNow phone-number links are formatted before WebAgent uses them.      |
| `enabled-entities`        | Optional URL parameter with a comma-separated entity list.                                                                                                                                                                           | Limits which ServiceNow entities or modules are available to the embedded integration.   |
| `disable-cti-settings`    | Optional URL parameter, usually set to `true` only for environments where ServiceNow CTI settings must not load.                                                                                                                     | Disables ServiceNow CTI behavior without changing shared WebAgent sign-in configuration. |

{% hint style="warning" %}
Do not mix these CTI plugin settings with CRM Service provider settings. Configure CRM Service only on the ServiceNow CRM Service page.
{% endhint %}

### Format correlation IDs

Use the `format-correlationid` URL parameter when ServiceNow needs correlation IDs in a specific format before WebAgent writes them to CRM activity context.

Supported format values are:

| Value          | Effect                                             |
| -------------- | -------------------------------------------------- |
| `alphanumeric` | Removes characters except `a-z`, `A-Z`, and `0-9`. |
| `lowercase`    | Converts the correlation ID to lowercase.          |
| `uppercase`    | Converts the correlation ID to uppercase.          |

Separate multiple values with commas. If `lowercase` and `uppercase` are both present, the last one in the list determines the final casing.

Example:

```
https://webagent.example/?clientid=<client-id>&format-correlationid=alphanumeric,uppercase
```

The value `2d437934-4453-41a4-82c1-f21c30ccfb3d` becomes `2D437934445341A482C1F21C30CCFB3D`.

{% hint style="warning" %}
This setting is not retroactive. Existing ServiceNow activities keep the correlation ID format that was written when the activity was created.
{% endhint %}

### Adjust the ServiceNow access-token lifespan

When the embedded WebAgent signs in through ServiceNow, ServiceNow controls the access-token lifespan for the OAuth application. The default ServiceNow token lifetime can require users to renew the token during longer working sessions.

To adjust the token lifetime:

1. Sign in to ServiceNow as an administrator.
2. Open **System OAuth** > **Application Registry**.
3. Open the **WebAgent CTI App**.
4. Change **Access Token Lifespan** to the approved value.
5. Save or update the application registry record.

The access-token lifespan value is entered in seconds.

## Troubleshoot the CRM button bar

The CRM button bar appears at the bottom of WebAgent for ServiceNow and becomes active after a user accepts a conversation. If the button bar does not appear or does not become active, check this configuration:

* Verify that `servicenow.plugin.js` loads. This confirms that the ServiceNow plugin is active in OnePortal.
* Verify that the OpenFrame URL contains `clientid`. For DC2023.01 or earlier, also verify that the URL contains `referrer`.
* Verify that `glide.ui.concourse.onmessage_enforce_same_origin_whitelist` allows the WebAgent origin.
* Verify that the user or group has the `sn_openframe_user` role.
* If the authentication popup shows `Invalid request`, verify that `glide.oauth.clients.allowed.for.implicit.grant` includes the WebAgent OAuth client ID.
* If the OpenFrame URL uses `enabled-entities`, verify that the intended entities are listed. For example: `enabled-entities=contact,incident,problem,changerequest,interaction,case`.

## Validate the plugin

1. Sign in to ServiceNow as a test user with access to the integration.
2. Open the ServiceNow area where WebAgent should load.
3. Confirm that WebAgent opens and prompts for sign-in only when expected.
4. Place a test call or open a test interaction.
5. Confirm that OAuth, OpenFrame, token, entity, correlation, and phone-number behavior match the intended ServiceNow workflow.

## Related topics

* [Configure WebAgent sign-in](/channels-integrations/webagent/configure-webagent-sign-in.md)
* [Configure WebAgent service settings](/channels-integrations/webagent/configure-webagent-service-settings.md)
* [Use WebAgent in a CRM system](/use/handle-conversations/webagent/use-webagent-in-crm.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://atlas.anywhere.now/channels-integrations/cti-plugins/servicenow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.