Agents

DataMap

View as MarkdownOpen in Claude

DataMap builds SWAIG function definitions that execute REST API calls directly on SignalWire’s infrastructure — no webhook endpoint required on your server. This reduces latency, simplifies deployment, and is ideal for straightforward API-to-response integrations.

Use DataMap when you need to call an external REST API and format the response with simple variable substitution. For complex business logic, database access, or multi-step processing, use a standard SWAIG function with a handler instead.

See SwaigFunction for handler-based tool definitions, and FunctionResult for the response builder used in DataMap outputs.

DataMap generates a SWML data_map object within a SWAIG function definition. See the SWML data_map reference for the full specification.

Properties

functionName
stringRequired

Name of the SWAIG function this DataMap will create.

Variable Substitution Patterns

PatternDescription
${args.param}Function argument value
${enc:args.param}URL-encoded argument (use in webhook URLs)
${lc:args.param}Lowercase argument value
${fmt_ph:args.phone}Format as phone number
${response.field}API response field
${response.arr[0]}Array element in response
${global_data.key}Global session data
${meta_data.key}Call metadata
${this.field}Current item in foreach

Modifiers are applied right-to-left: ${enc:lc:args.param} lowercases first, then URL-encodes.

Methods

body

Set the request body for a webhook.

errorKeys

Set error detection keys for webhook responses.

expression

Add a pattern-based response without an API call.

foreach

Process an array from the webhook response.

Helper Functions

Convenience functions for creating common DataMap patterns.

output

Set the output template for a webhook.

parameter

Add a function parameter to the tool definition.

purpose

Set the function description shown to the AI.

toSwaigFunction

Convert the DataMap to a SWAIG function definition object.

webhook

Add an API call to the DataMap.

webhookExpressions

Add post-processing expressions for a webhook response.

description

Alias for purpose — set the function description.

params

Set query or form parameters for a webhook.

fallbackOutput

Set the fallback output when no webhook or expression matches.

globalErrorKeys

Set top-level error detection keys.

enableEnvExpansion

Enable environment variable expansion.

setAllowedEnvPrefixes

Override allowed env var prefixes for this DataMap.

registerWithAgent

Register this DataMap tool with an AgentBase instance.

Examples

Weather lookup

1import { DataMap, FunctionResult } from '@signalwire/sdk';
2
3const dm = new DataMap('get_weather');
4dm.purpose('Look up current weather for a location');
5dm.parameter('city', 'string', 'City name', { required: true });
6dm.webhook('GET', 'https://api.weather.com/v1/current?q=${args.city}');
7dm.output(new FunctionResult('Weather in ${args.city}: ${response.current.condition.text}, ${response.current.temp_f}F'));

Expression-based control

1import { AgentBase, DataMap, FunctionResult } from '@signalwire/sdk';
2
3const volumeControl = new DataMap('set_volume')
4  .purpose('Control audio volume')
5  .parameter('level', 'string', 'Volume level', { required: true })
6  .expression(
7    '${args.level}', /high|loud|up/,
8    new FunctionResult('Volume increased'),
9  )
10  .expression(
11    '${args.level}', /low|quiet|down/,
12    new FunctionResult('Volume decreased'),
13  )
14  .expression(
15    '${args.level}', /mute|off/,
16    new FunctionResult('Audio muted'),
17  );
18
19const agent = new AgentBase({ name: 'media-agent' });
20agent.setPromptText('You are a helpful assistant.');
21agent.registerSwaigFunction(volumeControl.toSwaigFunction());
22await agent.run();

POST with body and foreach

1import { DataMap, FunctionResult } from '@signalwire/sdk';
2
3const searchDocs = new DataMap('search_docs')
4  .purpose('Search documentation')
5  .parameter('query', 'string', 'Search query', { required: true })
6  .webhook('POST', 'https://api.docs.example.com/search', {
7    headers: { Authorization: 'Bearer TOKEN' },
8  })
9  .body({ query: '${args.query}', limit: 3 })
10  .foreach({
11    input_key: 'results',
12    output_key: 'formatted_results',
13    max: 3,
14    append: '- ${this.title}: ${this.summary}\n',
15  })
16  .output(new FunctionResult('Found:\n${formatted_results}'))
17  .fallbackOutput(new FunctionResult('Search is currently unavailable.'));
18
19console.log(searchDocs.toSwaigFunction());