ServiceNow

import { servicenow } from "@servalhq/sdk";

// Pre-flight: are any human agents online right now?
await servicenow.checkLiveAgentAvailability({}, ctx);
// → { agentsAvailable: boolean; queueDepth: number }

// Open a conversation. Caller supplies the message text (including any
// NLU trigger phrase), channelId, contextVariables for routing skills,
// and the user's SNOW sys_id.
await servicenow.startLiveAgentSession(
  {
    ticketId,
    user: { userId, email },
    message: "<full message text — see example workflow below>",
    channelId: "chat",
    contextVariables: { u_liveagent_optional_skills: "IT" },
    // connectTicket: true by default — wires the SNOW conversation onto
    // the Serval ticket as an `interaction`-subtype external ticket so
    // user replies auto-egress as AGENT_CHAT turns.
  },
  ctx,
);
// → { clientSessionId, requestId, clientMessageId, response }

// Manually send an AGENT_CHAT turn. Usually NOT needed — user replies
// on the Serval ticket auto-egress through the standard pipeline once
// the ticket is connected. Use this for programmatic messages
// (auto-replies, scripted status updates, testing).
await servicenow.sendLiveAgentMessage(
  { clientSessionId, user: { userId, email }, message, channelId, contextVariables },
  ctx,
);

// Force-end a session (e.g. on ticket resolve / user abandon / SLA timeout).
await servicenow.endLiveAgentSession(
  { clientSessionId, user: { userId, email }, reason: "ticket_resolved", channelId },
  ctx,
);

contextVariables: { u_liveagent_optional_skills: "IT" }

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 SNOW 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
    //    SNOW'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 SNOW 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 } = 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.
        }
      }
    }

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

import * as servicenow from "serval/integrations/servicenow";

await servicenow.endLiveAgentSession(
  {
    clientSessionId, // saved from the START workflow output
    user: { userId: userSysId, email: args.email },
    reason: "ticket_resolved",
    channelId: "chat",
    contextVariables: { u_liveagent_optional_skills: "IT" },
  },
  ctx,
);