> ## Documentation Index
> Fetch the complete documentation index at: https://www.composer.id/llms.txt
> Use this file to discover all available pages before exploring further.

# ServiceNow Chat

> Run Triage's diagnostic through ServiceNow Virtual Agent, with separate guidance for external chat, identity and live-agent handoff.

ServiceNow Chat is a separate upstream intake surface for Triage. An employee can complete a configured diagnostic in a ServiceNow Virtual Agent conversation; Triage owns the questions and decision logic, and composerID carries the completed decision to the agreed destination.

> [!NOTE]
>
> This integration pattern was reviewed against ServiceNow documentation on **19 November 2026**. Customer configuration, the conversation bridge and tenant acceptance are still required. There is no deployed ServiceNow Chat transport or customer connection proven by this page.

## Three distinct ServiceNow connections

| Connection | What it is for | Guide |
| - | - | - |
| **ServiceNow Chat** | Conversational intake through Virtual Agent, with an optional live-agent handoff. | This page |
| **ServiceNow portal** | A Service Portal or Employee Center widget that presents the diagnostic within a portal page. | [ServiceNow upstream connector](https://www.composer.id/connectors/servicenow.md) |
| **ServiceNow records** | Publishing or reconciling an operational reference using the agreed record APIs and carrier field. | [ServiceNow destination](https://www.composer.id/destinations/servicenow.md) |

A chat session is not a service request, an Intent ID or evidence that a downstream record was saved. These references need an explicit, authorised mapping.

## Triage in the customer's ServiceNow Chat

The proposed upstream route uses a published Virtual Agent topic to invoke a server-side action or subflow. The action calls the agreed Triage headless interface through an authenticated bridge, passes a validated answer and renders the returned question or result in the conversation.

ServiceNow documents an [Action utility for calling actions and subflows from topics](https://www.servicenow.com/docs/r/xanadu/conversational-interfaces/virtual-agent/setup-flow-designer-va-properties.html), including inputs, outputs and waiting for a response. Applying that mechanism to Triage is the integration design here; it is not an installed connector.

```mermaid theme={"system"}
flowchart TD
  E["Employee in ServiceNow Chat"] <-->|"questions and answers"| T["Published Virtual Agent topic"]
  T <-->|"configured action or subflow"| B["Authenticated conversation bridge"]
  B <-->|"validated diagnostic state"| D["Triage decision service"]
  D -->|"completed decision"| C["composerID"]
  C -->|"operational reference"| S["Agreed destination system"]
  S -.->|"record confirmation"| C
  C -.->|"authorised receipt or link"| B
```

The diagram describes the target connection. Endpoint selection, question controls, error handling and the return path must be agreed and tested for the customer's instance. The [upstream reference implementation](https://www.composer.id/connectors/overview.md) currently has Teams, Slack and Google Chat renderers; it does not contain a ServiceNow Chat renderer.

### Diagnostic questions and policy answers

Policy search and a diagnostic have different jobs. ServiceNow may answer a question using content the employee is allowed to access. A Triage diagnostic asks the configured questions, validates the answers and applies the agreed decision method. Finding a policy does not configure that diagnostic, and a conversational answer must not be treated as its completed decision.

Where enabled and entitled, the customer's Now Assist or ServiceNow Otto experience can sit alongside the diagnostic. Availability depends on the assistant, published topics, knowledge permissions and channel configuration. The [Virtual Agent API assistant guidance](https://www.servicenow.com/docs/r/zurich/conversational-interfaces/virtual-agent/enable-now-assist-in-virtual-agent-experience-in-virtual-agent-api.html) supports these external API capabilities only in asynchronous mode. It does not establish that any AI agent can be exposed simply by wrapping it in a topic.

## External chat calling ServiceNow

ServiceNow also offers a dedicated **Virtual Agent Bot Integration API** for an external interface or primary bot to send messages into ServiceNow Virtual Agent or Live Agent:

```http theme={"system"}
POST https://<instance>/api/sn_va_as_service/bot/integration
Content-Type: application/json
```

This is a separate connection direction from a native ServiceNow topic calling Triage. The [Bot Integration API reference](https://www.servicenow.com/docs/r/api-reference/rest-apis/bot-api.html) defines its request and response fields.

| Action | Conversation purpose |
| - | - |
| `START_CONVERSATION` | Begin a conversation. |
| No action or `null` | Send an ordinary message in the conversation. |
| `SWITCH` | Select a Virtual Agent topic using the supported topic or intent identifier. |
| `AGENT` | Request escalation from Virtual Agent to a live agent. |
| `SEND_HISTORY` | Supply conversation history. |
| `END_CONVERSATION` | End the conversation; follow the documented empty message-text requirement. |

`SWITCH` selects a topic; `AGENT` requests a human handoff. Handoff success also depends on the customer's configured routing and agent availability.

In asynchronous operation, an HTTP acknowledgement precedes the conversational response delivered to the configured callback. Keep that acknowledgement separate from the response shown to the employee. Do not treat `syncResponse` as a universal switch: its documented scope is `CREATE_CONVERSATION` and `START_CREATED_CONVERSATION`.

Bind `clientSessionId` and `requestId` to the verified tenant, provider application and requester. Keep their mapping to the diagnostic session and eventual Intent ID on the server. Define duplicate, delayed and out-of-order handling without assuming the vendor request ID supplies composerID's idempotency guarantees.

For Virtual Agent API 4.1 and later, ServiceNow describes [Bot to Bot Outbound Configurations](https://www.servicenow.com/docs/r/zurich/conversational-interfaces/virtual-agent/configure-response-endpoint-auth-va-api.html) for the callback URL, REST connection, credentials, headers and timeout. Configure and verify that return path before accepting a conversation as connected.

## Authentication and employee identity

The bridge must establish both **which integration is calling** and **which employee may use the diagnostic**. They are separate checks.

For native ServiceNow chat, obtain the requester from the authenticated instance context and map that identity to an authorised Triage tenant and programme. Keep outbound credentials server-side. An email address or tenant ID supplied in a chat message is not proof of access.

For the external Bot Integration API, ServiceNow documents Basic, OAuth, Hash and Static Token options. Its [inbound authentication guidance](https://www.servicenow.com/docs/r/zurich/conversational-interfaces/virtual-agent/configure-send-request.html) distinguishes endpoint authentication from account linking: Basic or OAuth can be used for guest conversations, while account linking needs the configured Static or Hash message authentication and the required `emailId` field. Those mechanisms can be combined; a service OAuth token alone does not identify the employee.

Approve inbound authentication, [message authentication](https://www.servicenow.com/docs/r/conversational-interfaces/virtual-agent/set-up-message-auth-va-api.html) and outbound callback authentication for the selected provider. Validate instance and provider bindings on every message. Limit transcript storage and any history passed to a live agent to the agreed purpose and retention policy.

## Prerequisites depend on the selected route

| Requirement | What the customer must confirm |
| - | - |
| Native ServiceNow topic calling Triage | Virtual Agent entitlement, a published topic, permission to create the selected action or subflow, approved outbound REST authentication and the required integration entitlement. |
| External client calling the Bot Integration API | The Virtual Agent API Store app (`sn_va_as_service`), Glide Virtual Agent (`com.glide.cs.chatbot`) and its Conversational Custom Chat Integration dependency (`com.glide.cs.custom.adapter`). |
| Licensing and consumption | ServiceNow documents Pro/Enterprise entitlement for the Virtual Agent API. Confirm the actual product contract, installed app version and any Integration Hub transaction allowance. |
| Live Agent | An enabled and tested escalation route, queue behaviour, availability and an agreed response when no agent can take the conversation. |
| Assistant features | The required Now Assist or Otto entitlement and provider configuration. Check feature and mode support for the installed release. |

The separate Virtual Agent API app is a prerequisite for its external-client API, not a blanket prerequisite for every native topic that calls an external service. See [installation](https://www.servicenow.com/docs/r/zurich/conversational-interfaces/virtual-agent/install-virtual-agent-api.html), [licensing](https://www.servicenow.com/docs/r/zurich/conversational-interfaces/virtual-agent/virtual-agent-api-supported-versions-licensing.html) and the [custom chat integration framework](https://www.servicenow.com/docs/r/conversational-interfaces/virtual-agent/create-adapter-for-virtual-agent.html). Confirm family and application compatibility in the [ServiceNow Store application listing](https://store.servicenow.com/store/app/60596fae1be06a50a85b16db234bcb2a); use the [release notes](https://www.servicenow.com/docs/r/store-release-notes/store-rn-virtual-agent-api.html) to check version-specific changes. A versioned Zurich link does not mean Zurich is the latest release.

## Information needed for customer setup

1. Select native ServiceNow chat, an external chat interface, or both. Name the instance, ServiceNow family, installed application versions and technical owner.
2. Identify the approved topic and diagnostic programme, including question codes, supported answer controls, language, conditional behaviour and save/resume requirements.
3. Agree the application credentials, employee identity mapping, tenant permissions, callback authentication and network access.
4. Specify when a human handoff is allowed, what context may be shared, and what happens on timeout, abandonment or an unavailable agent.
5. Select the downstream destination and the evidence required before displaying a saved-record confirmation. This remains a separate composerID connection.

## Acceptance before a live connection claim

Verify the authorised employee journey and a rejected cross-tenant attempt; the configured questions and answer validation; reconnect and expiry behaviour; duplicate or delayed messages; callback authentication; human handoff and unavailable-agent handling; conversation closure; and any selected assistant features. Separately prove that the downstream record carries the expected reference before labelling it confirmed.

No tenant was connected during this documentation review. The current status is **documented integration pattern**, with implementation and customer acceptance still required.

> [card] [ServiceNow portal](https://www.composer.id/connectors/servicenow.md)
>
> The separate Service Portal and Employee Center widget route.

> [card] [ServiceNow records](https://www.composer.id/destinations/servicenow.md)
>
> Record APIs, the Intent ID carrier and downstream confirmation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.