DataMap | SignalWire

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

Pattern	Description
`${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

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 ${args.city}: ${response.current.condition.text}, ${response.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());