ChatGateway

A chat widget in a page can’t hold a SignalWire API token: the token carries the whole project, and every visitor could read it. ChatGateway mounts inside a web application you already run, holds the credentials on the server, and forwards on the widget’s behalf.

The browser learns two things, the gateway’s URL and a publishable key. It doesn’t learn the project, the Space, the token, or which agent runs, because the gateway sends config_url itself and a key only reaches the one agent it was issued for.

import { AgentBase, ChatGateway } 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', // never leaves the server
  key: '<YOUR_PUBLISHABLE_KEY>', // safe in the page
  allowedOrigins: ['https://bayviewtaxi.example.com'],
  secret: process.env.SIGNALWIRE_CHAT_GATEWAY_SECRET,
  conversationTimeout: 1800,
  maxNewConversations: 60,
  maxTurns: 200,
});
agent.mount(gateway.router(), { prefix: '/chat' });
await agent.serve();

npm install @signalwire/sdk

An agent already serves a Hono app, so agent.mount() hosts the gateway with no new infrastructure. router() returns a standard Hono app, so app.route() works on any other Hono server.

Parameters

The constructor takes one options object, ChatGatewayOptions. It throws an Error when configUrl is empty, and, when client is omitted, when SIGNALWIRE_PROJECT_ID isn’t set or no service URL resolves from SIGNALWIRE_SPACE.

Properties

Exports

All of these are importable from @signalwire/sdk.

The browser-facing wire

One endpoint: POST / on the router, with the key in Authorization: Bearer. Mounted at /chat, the path is /chat/. A preflight OPTIONS / is answered for allowed origins. The body is JSON with a method of start, chat, log, or end; method defaults to chat.

A start or chat with no handle creates a conversation and returns its handle in the X-Chat-Handle response header. start opens the conversation with no user message, so the agent speaks first. log and end require a handle. Any other method is a 400.

Rejections return { error: reason } with the status: 400 malformed request or handle, 401 bad key, 403 origin not allowed or a bad or expired handle, 413 a request, message, or metadata over its limit, 429 a cap was reached. A failure reaching the chat service before any reply is sent returns 502 with { error: 'chat service error' }.

Page context

user_meta_data is the one field forwarded rather than replaced: the page context a widget collects about itself, such as URL, title, referrer, locale, and viewport. It reaches the agent’s config request as params.user_meta_data, so a chat agent can tailor its greeting.

The service reads it when it creates a conversation, which is the start call or whichever chat auto-creates one. Metadata sent on later turns is accepted and unused. The browser writes it, so treat it as the visitor’s claim about themselves, never as authority; a page can put anything in it, including text aimed at your prompt.

What a leaked key can do

A publishable key is public by definition, so design for it being taken.

A key alone can’t read a conversation. The full chat_log isn’t exposed, and handles are signed by the gateway, so they can’t be forged, guessed, or enumerated. log returns only the user and assistant turns.

It can start and continue conversations, and every turn is billed. maxNewConversations and maxTurns bound that: the first limits conversations created per window, the second limits turns in each. The caps are counted in the serving process. Behind several replicas each keeps its own, so the effective cap multiplies by the replica count; set them with that in mind, or put a shared limiter in front.

The origin allowlist stops a key pasted into someone else’s page, because a browser sends that page’s origin and the gateway refuses it. It doesn’t stop a script that sends no origin or a false one. Treat it as leak containment, not access control.

To rotate a key, construct the gateway with a new key and redeploy. Change secret at the same time to invalidate outstanding handles too.

Methods

checkKey

Verifies the publishable key a request presented, comparing in constant time. router() and prepare() call it for you.

Returns void. Throws GatewayRejection with status 401 and reason bad key when the key is missing or wrong.

checkOrigin

Allows localhost and listed origins, and refuses any other. A missing Origin is allowed: browsers send one on the cross-origin requests this serves, so its absence means a caller that isn’t a browser, and refusing it would break server-side use without stopping an attacker.

Returns void. Throws GatewayRejection with status 403 and reason origin not allowed for an origin that isn’t allowed.

readUserMetadata

Validates the user_meta_data field of a browser request. Absent, null, and empty all yield null.

Returns Record<string, unknown> | null. Throws GatewayRejection with status 400 when the field isn’t a JSON object or can’t be serialized, and 413 when it is larger than MAX_USER_METADATA_BYTES serialized.

Example

Checking a request’s key and origin by hand, and reading its page context, in a handler you wrote yourself:

import { ChatGateway, GatewayRejection } from '@signalwire/sdk';
const gateway = new ChatGateway({
  configUrl: 'https://bayview-taxi.example.com/dispatch',
  key: '<YOUR_PUBLISHABLE_KEY>',
  allowedOrigins: ['https://bayviewtaxi.example.com'],
});
export function guard(origin: string | undefined, authorization: string | undefined): void {
  const key = authorization?.startsWith('Bearer ') ? authorization.slice(7) : null;
  try {
    gateway.checkKey(key);
    gateway.checkOrigin(origin);
  } catch (err) {
    if (err instanceof GatewayRejection) {
      console.warn(err.status, err.reason); // 401 bad key, 403 origin not allowed
    }
    throw err;
  }
}
export function pageContext(body: Record<string, unknown>) {
  return gateway.readUserMetadata(body); // Record<string, unknown> | null
}