ServiceNow

​

About ServiceNow

​

What the ServiceNow integration enables

​

Catalog import

​

Improve with Catalyst

​

Importing user criteria as access profiles

• Who it matches - groups, roles, user attribute conditions (attribute criteria such as department or location map to Serval access-profile attribute conditions), and individual users.
• What it makes requestable - the catalog items the criterion gates, including whether each link is an allow (“Available”) or deny (“Not available”) relationship.
• Proposed access profile - a preview of the Serval equivalent before you import.

​

Mirroring knowledge articles into Serval

• Mirrored knowledge bases appear in the Knowledge Bases sidebar under an External Connections section.
• Mirrored documents are sync-locked and read-only, with a banner - “This document is synced from ServiceNow and is read-only.” - and a View in ServiceNow link.
• Article HTML is converted to native editor blocks (tables, lists, and headings are supported), and the folder hierarchy from ServiceNow is preserved.
• Re-syncs update content in place and record version history.
• Clicking a knowledge item reference offers a destination choice: Open in Serval or Open in ServiceNow.

​

Sync settings: frequency and catalog filter

• Catalog filter - an optional ServiceNow encoded query (for example category=hardware^active=true). Only matching catalog items are imported; leaving it blank imports everything. The filter is combined (AND) with the standard active-items filter. This field appears only for integrations that support it - currently ServiceNow.
• Sync frequency - Automatic (recommended, the default), Every hour, Every 6 hours, Every 12 hours, Once a day, or Once a week.

• Unset means the platform default: catalog sync fan-out runs every 30 minutes for ServiceNow, and entity ingestion ticks every 4 hours.
• A configured interval is a floor, not an exact cadence - scheduled ticks are skipped until the interval has elapsed since the last completed sync. For entity syncs, values at or below about 4 hours behave like Automatic; only the 6-hour, 12-hour, daily, and weekly settings genuinely throttle.

​

How formatting translates to ServiceNow

​

How the connection works

• OAuth 2.0 (Client Credentials) - the default and recommended option. On each request, Serval exchanges your Client ID and Client Secret for a short-lived bearer token from your instance’s token endpoint (https://<instance>.service-now.com/oauth_token.do) and sends that token on every API call. ServiceNow runs those calls as the OAuth Application User you designate (the same dedicated integration user described below), so that user’s roles and table ACLs determine exactly what Serval can do. Serval does not request any OAuth scopes - the token is bounded entirely by the integration user’s permissions, not by a scope list.
• Basic authentication - Serval stores the integration user’s username and password and sends them as standard HTTP Basic auth on every call. Use this when inbound OAuth client credentials aren’t available on your instance, or for a quick test setup.

​

Get your credentials

1

Create a dedicated integration user

In ServiceNow, go to User Administration → Users and create a new user. Recommended values:

Field	Value
User ID	serval.integration
First name	Serval
Last name	Integration
Active	Checked
Web service access only	Checked (blocks interactive login)
Internal Integration User	Checked (if available in your ServiceNow version)

Give the user both a first and last name. ServiceNow’s inbound-OAuth user picker omits users that are missing either name - a known quirk of the picker (see this ServiceNow Community thread) - so you won’t be able to select the account as the OAuth Application User later.

If you plan to use Basic authentication, also click Set Password → Generate Password and copy the password now - you will not be able to view it again. You’ll paste it into Serval. If you use OAuth 2.0, you typically do not need a password for Serval: API access is authorized via Client ID and Client Secret, and the integration user is designated on the OAuth application below.

2

Create a custom role for Serval

Creating a custom role with granular permissions is the recommended approach for production environments. It follows the principle of least privilege and provides better security than out-of-the-box roles like itil or admin. (The simpler OOB-role alternative is covered in the next step.)

Go to User Administration → Roles and create:

Field	Value
Name	x_serval_integration
Description	Custom role for Serval integration with least-privilege API access

Then open the role and, in the Contains Roles related list, add these base roles:

Role	Purpose
rest_api_explorer	Enables REST API access
personalize_choices	Allows reading sys_choice values
personalize_dictionary	Allows reading sys_dictionary for field definitions

These base roles provide the foundational REST API capabilities; granular table access comes from the ACLs in the next step.

3

Grant table access via ACLs

Serval requires specific read/write access to ServiceNow tables. Create Access Control List (ACL) rules that grant only the necessary permissions.

Serval uses ServiceNow’s Table API, Service Catalog API, Attachment API (all active by default), and the Change Management REST API, which requires the Change Management - REST API plugin (com.snc.change_management.rest_api) - active by default on most instances.

• Required Table Access
• Create ACLs
• Alternative: Use OOB Roles

​

Incident Management Tables

Table	Read	Create	Write	Purpose
incident	Yes	Yes	Yes	Incident records (all standard fields)
sys_journal_field	Yes	-	-	Comments and work notes

​

HR Service Delivery Tables

Required only if you sync or create HR cases.

Table	Read	Create	Write	Purpose
sn_hr_core_case	Yes	Yes	Yes	HR case records, including comments and work notes

​

Service Catalog Tables

Table	Read	Create	Write	Purpose
sc_cat_item	Yes	-	-	Catalog item details
sc_category	Yes	-	-	Catalog categories
sc_request	Yes	Yes	-	Service requests
sc_req_item	Yes	Yes	Yes	Requested items
item_option_new	Yes	-	-	Catalog item variable definitions
io_set_item	Yes	-	-	Variable set to catalog item mapping
question_choice	Yes	-	-	Choices for select-type catalog variables
catalog_script_client	Yes	-	-	Catalog client scripts (fillability analysis, Understanding tab)
catalog_ui_policy	Yes	-	-	Catalog UI policies (When/Show/Hide/Require rules)
catalog_ui_policy_action	Yes	-	-	UI policy actions
sys_script_include	Yes	-	-	Script includes referenced by catalog client scripts
sys_attachment	-	Yes	-	File attachment uploads for requested items (written through the Attachment API, but the user still needs create permission)

​

Configuration Tables (Read-Only)

Table	Read	Create	Write	Purpose
sys_user	Yes	-	-	User lookup for assignment
sys_user_group	Yes	-	-	Assignment group lookup
sys_choice	Yes	-	-	Field dropdown values
sys_dictionary	Yes	-	-	Field definitions
cmdb_ci_service	Yes	-	-	Business services

​

Knowledge Base Tables (Read-Only)

Table	Read	Create	Write	Purpose
kb_knowledge_base	Yes	-	-	Knowledge base metadata
kb_category	Yes	-	-	Knowledge categories
kb_knowledge	Yes	-	-	Knowledge articles
kb_article_template	Yes	-	-	Article template metadata (templated articles)
kb_article_template_definition	Yes	-	-	Article template definitions; templated articles also read their extended template tables

​

User Criteria Tables (Read-Only)

These tables determine which users have access to knowledge articles and catalog items, and back the user criteria import.

Table	Read	Create	Write	Purpose
user_criteria	Yes	-	-	User criteria definitions (users, groups, companies, etc.)
kb_uc_can_read_mtom	Yes	-	-	Knowledge article access - users who CAN read
kb_uc_cannot_read_mtom	Yes	-	-	Knowledge article access - users who CANNOT read
sc_cat_item_user_criteria_mtom	Yes	-	-	Catalog item access - users who CAN access
sc_cat_item_user_criteria_no_mtom	Yes	-	-	Catalog item access - users who CANNOT access

​

Change Management Tables

Table	Read	Create	Write	Purpose
change_request	Yes	Yes	Yes	Change request records
sysapproval_approver	Yes	-	Yes	Change request approval records (write is needed to act on approvals)

Creating change requests uses the Change Management REST API, which requires the Change Management - REST API plugin (com.snc.change_management.rest_api) to be active on your ServiceNow instance. This plugin is active by default on most instances.

​

Problem Management Tables

Table	Read	Create	Write	Purpose
problem	Yes	Yes	Yes	Problem records

​

Access Management & Resource Sync Tables

These tables are required if you use Serval’s access profile capabilities for syncing organizational resources and provisioning/deprovisioning users.

If you are not using access profiles, you can skip these ACLs. The sys_user and sys_user_group tables listed above under Configuration Tables still require read access for basic functionality regardless.

Table	Read	Create	Write	Delete	Purpose
sys_user	-	-	Yes	-	Write access for department assignment (read access already listed above)
sys_user_grmember	Yes	Yes	-	Yes	Group membership provisioning and deprovisioning
sys_user_role	Yes	-	-	-	Role definitions for resource sync
sys_user_has_role	Yes	Yes	-	Yes	Role assignment provisioning and deprovisioning
core_company	Yes	-	-	-	Company records for resource sync
cmn_department	Yes	-	-	-	Department records for resource sync
cmn_location	Yes	-	-	-	Location records for resource sync
cmn_cost_center	Yes	-	-	-	Cost center records for resource sync

For each table that requires access, create appropriate ACLs:

1

Navigate to ACLs

1. In the navigator, search for “Access Control (ACL)”
2. Select System Security → Access Control (ACL)

2

Create Read ACLs

For each table that requires read access, create a new ACL:

1. Click New
2. Set Type to record
3. Set Operation to read
4. Set Name to the table name (e.g., incident)
5. In the Requires role related list, add your custom role x_serval_integration
6. Click Submit

Repeat for all tables listed in the Required Table Access tab.

3

Create Write ACLs

For tables that require create, write, or delete access:

1. Click New
2. Set Type to record
3. Set Operation to create, write, or delete as needed
4. Set Name to the table name
5. In the Requires role related list, add your custom role x_serval_integration
6. Click Submit

Create ACLs for the following tables:Incident, Problem & HR Case Management:

• incident (create, write)
• problem (create, write)
• sn_hr_core_case (create, write - only if you use HR cases)

Change Management:

• change_request (create, write)
• sysapproval_approver (write)

Service Catalog:

• sc_request (create)
• sc_req_item (create, write)
• sys_attachment (create)

Access Management (if using access profiles):

• sys_user (write)
• sys_user_grmember (create, delete)
• sys_user_has_role (create, delete)

Using out-of-the-box roles is simpler but grants more permissions than necessary. Only use this approach for development/testing or if your organization’s security policy permits.

Instead of creating custom ACLs, you can assign these out-of-the-box roles to the integration user:

Role	Purpose	Notes
itil	ITSM functionality (incidents, problems, changes)	Grants broad access to incident, problem, and change management
catalog	Service catalog access	For catalog item browsing, ordering, and request management
knowledge	Knowledge base access	For knowledge article sync
user_admin	User and group administration	Required only if using access profiles for provisioning/deprovisioning

The itil role includes access to the Change Management REST API. If you use the custom role approach instead, ensure the Change Management - REST API plugin (com.snc.change_management.rest_api) is active on your instance.

To assign roles:

1. Open the integration user record
2. Scroll to the Roles related list
3. Click Edit
4. Add the roles from the list above
5. Click Save

4

Assign the custom role to the integration user

1. Navigate to User Administration → Users and open the serval.integration user
2. Scroll down to the Roles related list and click Edit
3. Add the x_serval_integration role (or the OOB roles if you chose that approach)
4. Click Save

5

(OAuth only) Enable the inbound client-credentials grant

Inbound OAuth client credentials are disabled by default on most ServiceNow instances. In System Properties (sys_properties.list), find or create:

Field	Value
Name	glide.oauth.inbound.client.credential.grant_type.enabled
Type	true | false
Value	true
Application	Global

If this property is missing or false, every token request to oauth_token.do fails with access_denied, no matter how the OAuth app is configured. This is the single most common cause of a failed OAuth connection. ServiceNow may also display a banner on the Application Registry form warning that the property is disabled. ServiceNow documents this requirement in its official guide, Up your OAuth 2.0 game: Inbound Client Credentials.

6

(OAuth only) Create the OAuth Application Registry entry

Go to System OAuth → Application Registry → New. ServiceNow shows a list of OAuth application types - pick the one for inbound access (external systems calling into your instance). Do not choose Connect to a third party OAuth Provider or other outbound options; those are for ServiceNow calling external OAuth servers, not for Serval.

• Recommended: New Inbound Integration Experience - the current UI for inbound OAuth, including client credentials. When the wizard asks Select your application connection type, choose OAuth - Client credentials grant (machine-to-machine). Do not choose Authorization code, JWT bearer, Resource owner password, or third-party ID token flows for the Serval integration.
• Alternative: [Deprecated UI] Create an OAuth API endpoint for external clients - the older wizard for the same kind of inbound app. “Deprecated UI” refers to ServiceNow replacing the screen flow, not to the credentials; it still produces a working Client ID / Client Secret. Some teams see odd default forms here (for example, the OAuth Application User field hidden until you change the form layout); using the New Inbound Integration Experience often avoids that.

Give the application a clear name (for example, Serval integration) and save; ServiceNow auto-generates the Client Secret. Then:

1. Set Client type to run API calls as your integration account - for example Integration as a Service (wording varies by release). That tells ServiceNow which sys_user supplies roles, ACLs, and audit fields for requests made with a client-credentials token.
2. Allow the Client credentials grant. Often this is not on the main form: open the OAuth Entity or OAuth Entity Profile related list on the same Application Registry record, open the related row, and confirm Client credentials is enabled. Save that record if you changed it.
3. Set the OAuth Application User to your serval.integration user, so issued tokens act as that account.

If you don’t see an OAuth Application User field on the form, ServiceNow hides it on the default layout. Open the form’s context menu → Configure → Form Layout, move OAuth Application User from Available to Selected, save, and reload. Some instances instead expose the value as a column in the Application Registry list view, or on the related OAuth Entity Profile row. On the newer Inbound Integration UI, only the first 1,000 users (alphabetical) appear in the picker - a documented ServiceNow known error - search precisely for your account.

The integration user must already have the roles and ACLs from the earlier steps so token-backed API calls are authorized correctly.

7

(OAuth only) Copy the Client ID and Client Secret

From the OAuth application record, copy the Client ID and Client Secret (click the lock icon to reveal the secret). Store them securely - anyone holding both can mint tokens that act as your integration user.

8

Identify your ServiceNow Instance Name

Your Instance Name is the subdomain of your ServiceNow URL: if your instance lives at https://mycompany.service-now.com, the instance name is mycompany. You’ll enter it in Serval next.

​

Connect in Serval

​

Verifying the connection

• Test ServiceNow Connection - authenticates and queries your user table (a single row). Success reads “Successfully authenticated with ServiceNow”. Failure reads “Unable to connect to ServiceNow. Please verify your credentials are valid and have the necessary permissions.”
• List ServiceNow Users - samples up to ten rows from sys_user. Success reports the sample size; failure reads “Unable to list users from ServiceNow. Please verify the credentials have permission to read the sys_user table.”
• List ServiceNow Incidents, List ServiceNow Knowledge Articles, List ServiceNow Catalog Items, and List ServiceNow User Criteria - the same ten-row sample pattern against incident, kb_knowledge, sc_cat_item, and user_criteria. Each failure message names the table the credentials couldn’t read.

​

Gotchas and troubleshooting

​

Real-time comment sync via webhook (optional)

​

How it works

​

Get your webhook token

​

Webhook endpoint

​

Create the Business Rule

1

Navigate to Business Rules

In ServiceNow, go to System Definition → Business Rules and click New.

2

Configure the rule settings

Set the following fields:

Field	Value
Name	Serval - Sync Comment to Webhook
Table	sys_journal_field
Advanced	Checked
When	async
Insert	Checked
Update	Unchecked
Delete	Unchecked
Query	Unchecked

3

Add the script

Switch to the Advanced tab and paste the following script:

(function executeRule(current, previous /*null when async*/) {

    var tableName   = current.getValue('name');
    var elementType = current.getValue('element');

    // Validate: only Serval-managed records.
    // Replace 'serval.integration' with the user_name of your
    // Serval service account if it differs.
    var SERVAL_USER = 'serval.integration';

    var recordSysId = current.getValue('element_id');
    var parentRecord = new GlideRecord(tableName);
    if (!parentRecord.get(recordSysId)) {
        gs.warn('Serval webhook: parent record not found: '
                + tableName + '/' + recordSysId);
        return;
    }

    var openedBy = parentRecord.opened_by.user_name.toString();
    if (openedBy !== SERVAL_USER) {
        return;
    }

    // Build payload
    var instanceName = gs.getProperty('instance_name');
    var instanceUrl  = 'https://' + instanceName + '.service-now.com';

    var payload = {
        instance_url:  instanceUrl,
        table:         tableName,
        record_sys_id: recordSysId,
        number:        parentRecord.getValue('number'),
        comment: {
            sys_id:         current.getUniqueValue(),
            element:        elementType,
            value:          current.getValue('value'),
            sys_created_by: current.getValue('sys_created_by'),
            sys_created_on: current.getValue('sys_created_on')
        }
    };

    // Configuration
    // Replace the token value with the token provided by Serval.
    // For production, store this in a System Property
    // (e.g., x_serval.webhook_token) and retrieve it via
    // gs.getProperty('x_serval.webhook_token').
    var SERVAL_WEBHOOK_URL   = 'https://svwebhook.api.serval.com/servicenow/new-comment';
    var SERVAL_WEBHOOK_TOKEN = '<TOKEN_PROVIDED_BY_SERVAL>';

    try {
        var request = new sn_ws.RESTMessageV2();
        request.setEndpoint(SERVAL_WEBHOOK_URL);
        request.setHttpMethod('POST');
        request.setRequestHeader('Content-Type', 'application/json');
        request.setRequestHeader('X-Serval-Webhook-Token', SERVAL_WEBHOOK_TOKEN);
        request.setRequestBody(JSON.stringify(payload));

        // Run asynchronously so we don't block the user's transaction
        request.setEccParameter('skip_sensor', 'true');

        var response = request.executeAsync();

        gs.info('Serval webhook: sent ' + elementType + ' event for '
            + tableName + '/' + parentRecord.getValue('number')
            + ' (async)');
    } catch (e) {
        gs.error('Serval webhook: failed to send event: ' + e.message);
    }

})(current, previous);

The script references serval.integration as the Serval service account user_name. This must match the user_name of the integration user you created in Get your credentials. If you chose a different User ID, update the SERVAL_USER variable accordingly.

4

Save the Business Rule

Click Submit to save the rule. Comment sync will begin working immediately for Serval-managed records.

​

Live agent handoff via VA Bot-to-Bot (optional)

​

How the bridge works

1. Inbound to ServiceNow - Serval opens, sends messages on, and ends a Bot-to-Bot conversation by calling ServiceNow’s Virtual Agent Bot Integration endpoint (installed by the Virtual Agent API plugin). The action discriminator travels in the request body: START_CONVERSATION, AGENT_CHAT, or END_CONVERSATION.
2. Outbound from ServiceNow - when the live agent types a reply, ServiceNow’s Provider Application looks up its associated Outbound REST Message and POSTs the response to the URL you configured there. That URL is the Serval-hosted webhook.
3. Agent presence pre-flight (optional) - Serval’s availability check reads the awa_agent_presence_capacity table to know whether any agents are currently online before starting a handoff.

• channelId on the start action - maps to a ServiceNow sys_cs_channel record. Defaults to "chat". The channel record’s “Bot to Bot Synchronous” flag and its AWA queue assignment together determine where the conversation routes.
• contextVariables on the start action - a free-form key/value bag passed to ServiceNow on every turn. Customers configure their AWA routing rule against the variable name(s) of their choice (e.g. u_liveagent_optional_skills). See Customize routing with context variables below.

​

Prerequisites

• Virtual Agent + Virtual Agent API plugins installed on your ServiceNow instance (Quebec or later).
• The Serval ServiceNow integration must already be connected (everything above on this page).
• Now Assist Pro licensing is not required - Bot-to-Bot is part of the base Virtual Agent API plugin.

​

Limitations (read before you commit)

• Closing a Serval ticket does not automatically end the ServiceNow conversation. Your workflow should call the end-session action when the ticket resolves if you want symmetric cleanup. The conversation eventually times out on the ServiceNow side either way.
• Agent attribution is automatic; assignment details are not. ServiceNow’s Bot-to-Bot payloads carry per-message agent information, and Serval resolves it to the ServiceNow user - so agent replies are attributed correctly on the Serval ticket with no extra work. What the asynchronous START acknowledgment does not tell you is which queue the conversation landed in or when an agent picked up; poll the auto-created interaction record’s assigned_to field from a workflow if you need that - see the example workflow below.
• Inbound auth verification is currently advisory. The Basic-auth password on inbound webhooks is forwarded onto the event for downstream verification, but the constant-time check against the rotated token is not yet enforced server-side. The per-install webhook URL contains an unguessable UUID, which is the practical access control today. Treat the rotated token as a not-yet-load-bearing secret in the meantime - full server-side verification is on the roadmap.
• Attachments require trusted-media-domain configuration. Files do cross the bridge in both directions, but ServiceNow refuses to download attachments from URLs whose host isn’t listed under the active Provider Application record’s Trusted media domains (the sys_cs_provider_application record - labeled Provider Channel Identity on some releases). You must add Serval’s S3 attachment host (the host of the presigned URL Serval sends for attachments - visible on a test egress) to that list, otherwise the live agent will see “We couldn’t download your file using the specified URL” instead of the image. See the ServiceNow docs: Set up trusted media domains for secure file upload for the field and ACL setup.

​

What agent replies look like on the Serval ticket

• Agent text surfaces as a comment, attributed to the ServiceNow agent.
• Agent images and files surface as attachments. Serval downloads them from ServiceNow’s conversational media API using your stored integration credentials, capped at 50 MB per file. If a download fails, Serval posts the placeholder comment [attachment <name> could not be downloaded - please refresh ServiceNow Agent Workspace] instead of failing the whole message.
• System prompts (such as AWA idle-timeout warnings) surface as comments so the user can reply and keep the chat alive.

​

Step 1: Grant additional permissions to the Serval service account

​

Step 2: Generate the shared bot token in Serval

​

Step 3: Configure the four ServiceNow records that wire up Bot-to-Bot

​

Step 4: SDK building blocks

• checkLiveAgentAvailability - pre-flight: are any human agents online right now? Reads the agent-presence capacity table and returns whether agents are available plus a queue-depth figure (the sum of agents’ remaining capacity). Skill-level filtering is intentionally not exposed - routing belongs to AWA.
• startLiveAgentSession - opens a conversation. The caller supplies the Serval ticketId, the user (a ServiceNow sys_user sys_id is preferred, plus email), the verbatim message text (including any NLU trigger phrase), channelId (defaults to "chat"), contextVariables for routing (re-sent on every turn), and optionally appInboundId for multi-bot instances. connectTicket defaults to true, which wires the ServiceNow conversation onto the Serval ticket as an interaction-subtype external ticket so user replies auto-egress as AGENT_CHAT turns. It returns the session identifiers - including clientSessionId and a liveAgentData blob that the attach action below consumes.
• sendLiveAgentMessage - manually sends an AGENT_CHAT turn. Usually not needed: once the ticket is connected, user replies auto-egress through the standard pipeline. Use it for programmatic messages (auto-replies, scripted status updates, testing).
• endLiveAgentSession - force-ends a session (e.g. on ticket resolve, user abandon, or SLA timeout).
• attachInteractionSysIdToLiveAgentSession - stashes a polled interaction sys_id onto the Serval external ticket so the ticket-channels surface in the Serval UI renders a deep link to the chat in ServiceNow Agent Workspace.

​

Step 5: Customize routing with context variables

​

Step 6: Example workflow - START_CONVERSATION with routing and assignment poll

import { workflow, sleep } from "serval/core";
import * as servicenow from "serval/integrations/servicenow";

export const main = workflow({
  fn: async function (
    args: {
      email: string;       // The end-user's email
      userMessage: string; // The user's natural-language message
      ticketId: string;    // The Serval ticket to bridge onto
    },
    ctx: servicenow.context.ServiceNowIntegration,
  ) {
    // 1) Resolve the ServiceNow sys_user.sys_id for this user. The
    //    Bot-to-Bot endpoint accepts email/username but account-linking
    //    works best with a sys_id, and AWA assignment is more reliable.
    const userSysId = await servicenow.lookupUserSysIdByEmail(
      { email: args.email },
      ctx,
    );

    // 2) Compose the message text. The trailing trigger phrase is what
    //    ServiceNow's NLU classifies as the "Live Agent Support" topic -
    //    the OOB topic that drives the AWA handoff without going through
    //    the Greetings picker. Customers who have renamed that topic
    //    or have a custom topic should adapt the phrase to match.
    const ROUTING_TRIGGER_PHRASE =
      "I need a live agent. Please connect me with Live Agent Support - I want to talk to an agent.";
    const message =
      args.userMessage && args.userMessage.length > 0
        ? args.userMessage + "\n\n" + ROUTING_TRIGGER_PHRASE
        : ROUTING_TRIGGER_PHRASE;

    // 3) Open the conversation. `connectTicket: true` (default) wires
    //    the ServiceNow clientSessionId onto the Serval ticket as an
    //    interaction-subtype external ticket, so subsequent user
    //    replies on the Serval ticket auto-egress as AGENT_CHAT turns.
    const { clientSessionId, liveAgentData } =
      await servicenow.startLiveAgentSession(
        {
          ticketId: args.ticketId,
          user: { userId: userSysId, email: args.email },
          message,
          channelId: "chat",
          contextVariables: { u_liveagent_optional_skills: "IT" },
        },
        ctx,
      );

    // 4) Optional: poll the `interaction` table to learn which agent
    //    actually picked up the conversation. START returns only an
    //    async ack - the real assignment happens a moment later when
    //    AWA matches an available agent. Stop early once `assigned_to`
    //    is populated.
    let routingInteraction: Record<string, unknown> | null = null;
    for (let attempt = 0; attempt < 4; attempt++) {
      await sleep({ durationMs: 3000 });
      const { result } = await servicenow.tableApiRequest(
        {
          method: "GET",
          path: "/api/now/table/{tableName}",
          pathParams: { tableName: "interaction" },
          query: {
            sysparm_query:
              "opened_for=" + userSysId + "^type=chat^ORDERBYDESCsys_created_on",
            sysparm_fields:
              "sys_id,number,state,assigned_to,assignment_group,queue,opened_at",
            sysparm_display_value: "true",
            sysparm_exclude_reference_link: "true",
            sysparm_limit: "1",
          },
        },
        ctx,
      ) as { result: Array<Record<string, unknown>> };

      if (result.length > 0) {
        routingInteraction = result[0];
        if (routingInteraction["assigned_to"]) {
          break; // Agent picked up - done polling.
        }
      }
    }

    // 5) Optional: stash the polled `interaction.sys_id` onto the
    //    Serval external ticket so the ticket-channels surface in the
    //    Serval UI renders a canonical Agent Workspace deep link to
    //    the chat. Skip this if you don't run the post-START poll -
    //    the channel still surfaces, just without a clickable link.
    if (routingInteraction && typeof routingInteraction["sys_id"] === "string") {
      await servicenow.attachInteractionSysIdToLiveAgentSession(
        {
          ticketId: args.ticketId,
          clientSessionId,
          liveAgentData,
          interactionSysId: routingInteraction["sys_id"],
        },
        ctx,
      );
    }

    return {
      clientSessionId,
      assignedAgent: routingInteraction?.["assigned_to"] ?? null,
      assignmentGroup: routingInteraction?.["assignment_group"] ?? null,
    };
  },
});

• User → agent: any new message the user sends in their original surface fans out to the ServiceNow agent automatically as an AGENT_CHAT turn - no extra workflow code required; Serval’s ticket-channel egress handles it.
• Agent → user: ServiceNow’s Outbound REST Message posts the agent’s typed reply to the Inbound Webhook URL configured in Step 3. Serval ingresses it as a comment on the bridged ticket (attributed to the agent), which surfaces back in the user’s original surface.

​

Step 7: Optionally end the session symmetrically

​

Step 8: Real-time translation (optional)

• User → agent. Every message the user types on the upstream surface is translated from userLanguage into agentLanguage before it lands as an AGENT_CHAT turn on ServiceNow.
• Agent → user. Every reply the live agent posts is translated from agentLanguage into userLanguage before it’s persisted on the Serval ticket and fanned back out to the user’s surface.

• Both fields must be set. If either is omitted, or both share a primary subtag (e.g. en vs en-US), the conversation runs through verbatim - no translation is attempted.
• URLs, code blocks, ticket numbers, and @mentions are preserved verbatim across the translation.
• Translation failures fall back to the original text and log a warning. A passthrough turn is strictly better than a dropped turn on a live chat - the agent or user can ask the other side to rephrase.
• Translation is handled by Serval automatically - there is nothing to configure on the ServiceNow side.