HandoffRouter

ChatGateway lets a browser hold a text conversation. HandoffRouter is the other half the SignalWire address widget expects: three routes, served at the same URL prefix as the gateway, that move that conversation to a phone call and back, and let a visitor type into a live call. Without these routes, a gateway answers the widget’s chat requests and returns 404 for the rest.

Every route checks the request origin against the gateway’s allowlist. Unknown, expired, and already-redeemed nonces all answer 404, so a caller can’t probe whether a given call is live.

This class implements the wire contract: the routes, the nonce, the ordering guarantee, and the spend limits. What a conversation is belongs to your application, and arrives as callbacks: where a leg’s transcript is written, and how a call is ended or spoken into.

npm install @signalwire/sdk

How the nonce works

A browser can’t be trusted to name a call, since a page-supplied call ID would let anyone inject speech into a stranger’s call. Instead the browser proves which call it is on. Your application puts a random handoff_nonce in the user variables of one dial, registers it against that call from a per-call config callback (see addPerCallConfig()), and the browser presents it later. The same dial carries the chat_handle, so the callback recovers the conversation id with readHandle().

Exchanging a nonce for a chat handle works once. Typing is repeatable, up to maxMessagesPerCall, until /handoff uses the nonce or nonceTtl seconds pass from its registration, even if the call is still live.

The ordering guarantee

A new medium doesn’t start until the one it replaces has ended and its record is written. /handoff ends the call and waits for your captureLeg callback to confirm the capture before it issues a handle. /escalate waits for the chat leg’s capture before it returns. Without the wait, the new medium’s config fetch can run before the record exists, and the new leg starts with no history.

Parameters

The constructor takes one options object, HandoffRouterOptions.

Properties

gateway, captureLeg, endCall, sendMessage, nextConversationId, nonceTtl, maxMessagesPerCall, and captureTimeout are readable and writable on the instance. captureLeg, endCall, and sendMessage are null when not set.

Exports

All of these are importable from @signalwire/sdk.

MAX_REQUEST_BODY_BYTES (64 KiB) and MAX_MESSAGE_BYTES (8 KiB of UTF-8) apply to these routes as they do to the gateway. A body over the first, or /say text over the second, is answered with 413. Both are checked before the nonce is looked up, so the answer says nothing about whether the nonce is live.

Methods

Examples

Register the nonce from the per-call config callback of the dial that carried it, reading the call id from the platform’s request and never from anything the browser sent.

import { AgentBase, ChatGateway, HandoffRouter, userVariables } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'dispatch', route: '/dispatch' });
agent.setPromptText('You are Ada, the dispatcher for Bayview Taxi.');
const gateway = new ChatGateway({
  configUrl: 'https://bayview-taxi.example.com/dispatch',
  key: '<YOUR_PUBLISHABLE_KEY>',
  allowedOrigins: ['https://bayviewtaxi.example.com'],
});
const handoff = new HandoffRouter({
  gateway,
  // Write the leg's transcript, then return true once it is saved.
  captureLeg: async (conversationId, medium) => {
    console.log(`saving ${medium} leg of ${conversationId}`);
    return true;
  },
  // End the call server-side.
  endCall: async (callId) => {
    console.log(`hanging up ${callId}`);
  },
  // Speak typed text into the call.
  sendMessage: async (callId, text) => {
    console.log(`sending to ${callId}: ${text}`);
    return true;
  },
});
agent.addPerCallConfig((_query, body) => {
  const variables = userVariables(body);
  const nonce = variables['handoff_nonce'];
  const chatHandle = variables['chat_handle'];
  const call = body['call'] as { call_id?: string } | undefined;
  if (typeof nonce === 'string' && typeof chatHandle === 'string') {
    handoff.register(nonce, {
      conversationId: gateway.readHandle(chatHandle),
      callId: call?.call_id ?? null,
    });
  }
});
agent.mount(gateway.router(), { prefix: '/chat' });
agent.mount(handoff.router(), { prefix: '/chat' });
await agent.serve();

A captureLeg, endCall, or sendMessage that throws is logged and treated as a failure. A sendMessage that throws or returns false doesn’t count against maxMessagesPerCall.

The option types and a shared registry:

import { HandoffRouter, NonceEntry, ChatGateway } from '@signalwire/sdk';
import type { CaptureLeg, EndCall, SendMessage, HandoffRouterOptions } from '@signalwire/sdk';
const gateway = new ChatGateway({ configUrl: 'https://bayview-taxi.example.com/dispatch' });
const captureLeg: CaptureLeg = async (conversationId, medium) => {
  console.log(conversationId, medium);
  return true;
};
const endCall: EndCall = (callId) => {
  console.log(callId);
};
const sendMessage: SendMessage = (callId, text) => {
  console.log(callId, text);
  return true;
};
// A shared nonce table: any Map<string, NonceEntry> works.
const registry = new Map<string, NonceEntry>();
const options: HandoffRouterOptions = {
  gateway,
  captureLeg,
  endCall,
  sendMessage,
  nextConversationId: (id) => `${id}.next`,
  nonceTtl: 1800,
  maxMessagesPerCall: 100,
  captureTimeout: 5,
  registry,
};
const handoff = new HandoffRouter(options);
console.log(handoff.nonceTtl, handoff.maxMessagesPerCall, handoff.captureTimeout, new NonceEntry('chat-8f21', 'call-1'));