***
title: DataMap
slug: /reference/typescript/agents/data-map
description: Fluent builder for server-side API tools that execute without webhooks.
max-toc-depth: 3
---------------------
For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt
[swaigfunction]: /docs/server-sdks/reference/typescript/agents/swaig-function
[functionresult]: /docs/server-sdks/reference/typescript/agents/function-result
[data-map]: /docs/swml/reference/ai/swaig/functions/data-map
[swml-data-map-reference]: /docs/swml/reference/ai/swaig/functions/data-map
[body]: /docs/server-sdks/reference/typescript/agents/data-map/body
[errorkeys]: /docs/server-sdks/reference/typescript/agents/data-map/error-keys
[expression]: /docs/server-sdks/reference/typescript/agents/data-map/expression
[foreach]: /docs/server-sdks/reference/typescript/agents/data-map/foreach
[helper-functions]: /docs/server-sdks/reference/typescript/agents/data-map/helper-functions
[output]: /docs/server-sdks/reference/typescript/agents/data-map/output
[parameter]: /docs/server-sdks/reference/typescript/agents/data-map/parameter
[purpose]: /docs/server-sdks/reference/typescript/agents/data-map/purpose
[toswaigfunction]: /docs/server-sdks/reference/typescript/agents/data-map/to-swaig-function
[webhook]: /docs/server-sdks/reference/typescript/agents/data-map/webhook
[webhookexpressions]: /docs/server-sdks/reference/typescript/agents/data-map/webhook-expressions
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`][swaigfunction] for
handler-based tool definitions, and
[`FunctionResult`][functionresult] for the
response builder used in DataMap outputs.
DataMap generates a SWML [`data_map`][data-map] object
within a SWAIG function definition. See the
[SWML data\_map reference][swml-data-map-reference] for the
full specification.
## **Properties**
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**
Set the request body for a webhook.
Set error detection keys for webhook responses.
Add a pattern-based response without an API call.
Process an array from the webhook response.
Convenience functions for creating common DataMap patterns.
Set the output template for a webhook.
Add a function parameter to the tool definition.
Set the function description shown to the AI.
Convert the DataMap to a SWAIG function definition object.
Add an API call to the DataMap.
Add post-processing expressions for a webhook response.
Alias for purpose -- set the function description.
Set query or form parameters for a webhook.
Set the fallback output when no webhook or expression matches.
Set top-level error detection keys.
Enable environment variable expansion.
Override allowed env var prefixes for this DataMap.
Register this DataMap tool with an AgentBase instance.
***
## **Examples**
### Weather lookup
```typescript {3}
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
```typescript {3}
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
```typescript {3}
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());
```