DataMap

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

What a template can read depends on where it is. A webhook’s url and params, the top-level expressions, and the fallback output read the call data, where an argument is ${args.city}. A webhook’s output, expressions, and foreach read that webhook’s response instead: a JSON object’s fields from the root (${temp}), a JSON array under array (${array[0].joke}), and the call data under input, so an argument there is ${input.args.city}; ${args.city} expands to nothing. Header values are sent as written, with no templates expanded.

Pattern	Description
`${args.param}`	Function argument value, in a webhook’s `url` and `params`, top-level expressions, and the fallback output
`${input.args.param}`	Function argument value, in a webhook’s `output`, `expressions`, and `foreach`
`${enc:args.param}`	URL-encoded argument (use in webhook URLs)
`${lc:args.param}`	Lowercase argument value
`${fmt_ph:args.phone}`	Format as phone number
`${field}`	Field of the webhook’s JSON response, read from the root
`${array[0].field}`	Element of a webhook response that is a JSON array
`${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.

gate

Add a semantic gate that must pass before the function runs.

gateFillers

Set what the AI says while the function’s semantic gates are checked.

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 the JSON request body for a webhook.

fallbackOutput

Set the fallback output when no webhook or expression matches.

globalErrorKeys

Set error keys on the DataMap object, where no request reads them.

enableEnvExpansion

Enable environment variable expansion.

setAllowedEnvPrefixes

Override allowed env var prefixes for this DataMap.

registerWithAgent

Examples

Weather lookup

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

Expression-based control

import { AgentBase, DataMap, FunctionResult } from '@signalwire/sdk';
const volumeControl = new DataMap('set_volume')
  .purpose('Control audio volume')
  .parameter('level', 'string', 'Volume level', { required: true })
  .expression(
    '${args.level}', /high|loud|up/,
    new FunctionResult('Volume increased'),
  )
  .expression(
    '${args.level}', /low|quiet|down/,
    new FunctionResult('Volume decreased'),
  )
  .expression(
    '${args.level}', /mute|off/,
    new FunctionResult('Audio muted'),
  );
const agent = new AgentBase({ name: 'media-agent' });
agent.setPromptText('You are a helpful assistant.');
agent.registerSwaigFunction(volumeControl.toSwaigFunction());
await agent.run();

POST with body and foreach

import { DataMap, FunctionResult } from '@signalwire/sdk';
const searchDocs = new DataMap('search_docs')
  .purpose('Search documentation')
  .parameter('query', 'string', 'Search query', { required: true })
  .webhook('POST', 'https://api.docs.example.com/search', {
    headers: { Authorization: 'Bearer TOKEN' },
  })
  .body({ query: '${args.query}', limit: 3 })
  .foreach({
    input_key: 'results',
    output_key: 'formatted_results',
    max: 3,
    append: '- ${this.title}: ${this.summary}\n',
  })
  .output(new FunctionResult('Found:\n${formatted_results}'))
  .fallbackOutput(new FunctionResult('Search is currently unavailable.'));
console.log(searchDocs.toSwaigFunction());