AgentsConfigurationSessionManager

setSessionMetadata

View as MarkdownOpen in Claude

Merge metadata into a session, creating the entry if it does not exist. Automatically triggers cleanup when the metadata map exceeds 1000 entries.

Two call signatures are supported for Python SDK compatibility:

  • Bulk merge (TS-native): setSessionMetadata(sessionId, metadata) — merges every key in the metadata object into the session, returning void.
  • Single key/value (Python-compatible): setSessionMetadata(sessionId, key, value) — sets a single key, returning true for parity with Python.

Both forms merge into any existing metadata; they do not replace.

Parameters

sessionId
stringRequired

The session identifier.

metadataOrKey
Record<string, unknown> | stringRequired

A metadata record to merge into the session (bulk-merge form), or a single string key (three-argument form).

value
unknown

The value to set when metadataOrKey is a string key. Only used by the three-argument form.

Returns

void for the bulk-merge form; boolean (true) for the three-argument, Python-compatible form.

Example

1import { SessionManager } from '@signalwire/sdk';
2
3const sm = new SessionManager();
4sm.setSessionMetadata('session-1', { caller: 'John' });
5sm.setSessionMetadata('session-1', { topic: 'billing' });
6// Metadata is now { caller: "John", topic: "billing" }
7
8sm.setSessionMetadata('session-1', 'priority', 'high');
9// Metadata is now { caller: "John", topic: "billing", priority: "high" }