onSwmlRequest | SignalWire

Lifecycle hook called on every incoming SWML request before the SWML document is rendered. The default implementation is a no-op. Override this method in a subclass to inspect or modify agent state before each call is processed.

Common uses include loading caller-specific data from a database, adjusting prompts based on request metadata, or logging request details.

Parameters

rawData

Record<string, unknown>Required

The parsed request body. Contains call metadata such as call_id, caller_id_number, caller_id_name, and any custom SIP headers.

callbackPath

string

Optional callback path from the request body (callback_path field), when the request was triggered via a callback URL.

context

any

The raw Hono request context (c), providing access to headers, query parameters, and the underlying HTTP request.

Returns

Record<string, unknown> | void | Promise<Record<string, unknown> | void> — Return a modifications object to merge into the AI verb config before rendering. global_data is deep-merged; all other keys override AI config fields directly. Return void / undefined to render without modifications.

For most per-request customization scenarios, prefer setDynamicConfigCallback() which provides a higher-level interface with access to query params, body, headers, and an ephemeral agent copy.

Example

1 import { AgentBase } from '@signalwire/sdk';
2 
3 class PersonalizedAgent extends AgentBase {
4   constructor() {
5     super({ name: 'personalized', route: '/personalized' });
6     this.setPromptText('You are a helpful assistant.');
7   }
8 
9   override async onSwmlRequest(
10     rawData: Record<string, unknown>,
11   ): Promise<void> {
12     const callerId = (rawData.caller_id_number as string) ?? 'unknown';
13     console.log(`Incoming call from ${callerId}`);
14     this.updateGlobalData({ caller_number: callerId });
15   }
16 }
17 
18 const agent = new PersonalizedAgent();
19 await agent.serve();