> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# DataMap

> Fluent builder for server-side API tools that execute without webhooks.

[swaigfunction]: /docs/server-sdks/reference/typescript/agents/swaig-function

[functionresult]: /docs/server-sdks/reference/typescript/agents/function-result

[data-map]: /docs/swml/reference/calling/ai/swaig/functions/data-map

[swml-data-map-reference]: /docs/swml/reference/calling/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.

> **Info**
>
> See [`SwaigFunction`][swaigfunction] for
> handler-based tool definitions, and
> [`FunctionResult`][functionresult] for the
> response builder used in DataMap outputs.

> **Info**
>
> 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**

**`functionName`** `string` — required

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](/docs/server-sdks/reference/typescript/agents/data-map/body)

Set the request body for a webhook.

#### [errorKeys](/docs/server-sdks/reference/typescript/agents/data-map/error-keys)

Set error detection keys for webhook responses.

#### [expression](/docs/server-sdks/reference/typescript/agents/data-map/expression)

Add a pattern-based response without an API call.

#### [foreach](/docs/server-sdks/reference/typescript/agents/data-map/foreach)

Process an array from the webhook response.

#### [Helper Functions](/docs/server-sdks/reference/typescript/agents/data-map/helper-functions)

Convenience functions for creating common DataMap patterns.

#### [output](/docs/server-sdks/reference/typescript/agents/data-map/output)

Set the output template for a webhook.

#### [parameter](/docs/server-sdks/reference/typescript/agents/data-map/parameter)

Add a function parameter to the tool definition.

#### [purpose](/docs/server-sdks/reference/typescript/agents/data-map/purpose)

Set the function description shown to the AI.

#### [toSwaigFunction](/docs/server-sdks/reference/typescript/agents/data-map/to-swaig-function)

Convert the DataMap to a SWAIG function definition object.

#### [webhook](/docs/server-sdks/reference/typescript/agents/data-map/webhook)

Add an API call to the DataMap.

#### [webhookExpressions](/docs/server-sdks/reference/typescript/agents/data-map/webhook-expressions)

Add post-processing expressions for a webhook response.

#### [description](/docs/server-sdks/reference/typescript/agents/data-map/description)

Alias for purpose -- set the function description.

#### [params](/docs/server-sdks/reference/typescript/agents/data-map/params)

Set query or form parameters for a webhook.

#### [fallbackOutput](/docs/server-sdks/reference/typescript/agents/data-map/fallback-output)

Set the fallback output when no webhook or expression matches.

#### [globalErrorKeys](/docs/server-sdks/reference/typescript/agents/data-map/global-error-keys)

Set top-level error detection keys.

#### [enableEnvExpansion](/docs/server-sdks/reference/typescript/agents/data-map/enable-env-expansion)

Enable environment variable expansion.

#### [setAllowedEnvPrefixes](/docs/server-sdks/reference/typescript/agents/data-map/set-allowed-env-prefixes)

Override allowed env var prefixes for this DataMap.

#### [registerWithAgent](/docs/server-sdks/reference/typescript/agents/data-map/register-with-agent)

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());
```

> Fluent builder for server-side API tools that execute without webhooks.

## Docs

- [body](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/body.md): Set the request body for a webhook.
- [description](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/description.md): Alias for purpose — sets the tool description shown to the AI.
- [enableEnvExpansion](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/enable-env-expansion.md): Enable or disable environment variable expansion in URLs, bodies, and outputs.
- [errorKeys](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/error-keys.md): Set error detection keys for webhook responses.
- [expression](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/expression.md): Add a pattern-based response without an API call.
- [fallbackOutput](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/fallback-output.md): Set the top-level fallback output used when no webhook or expression matches.
- [foreach](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/foreach.md): Process an array from the webhook response.
- [globalErrorKeys](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/global-error-keys.md): Set global error-detection keys that apply to all webhooks.
- [Helper Functions](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/helper-functions.md): Convenience functions for creating common DataMap patterns.
- [output](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/output.md): Set the output template for a webhook.
- [parameter](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/parameter.md): Add a function parameter to the tool definition.
- [params](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/params.md): Set query or form parameters for the most recently added webhook.
- [purpose](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/purpose.md): Set the function description shown to the AI.
- [registerWithAgent](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/register-with-agent.md): Register this DataMap as a SWAIG function on an agent.
- [setAllowedEnvPrefixes](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/set-allowed-env-prefixes.md): Set the allowed environment variable prefixes for this DataMap instance.
- [toSwaigFunction](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/to-swaig-function.md): Convert the DataMap to a SWAIG function definition object.
- [webhook](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/webhook.md): Add an API call to the DataMap.
- [webhookExpressions](https://signalwire.com/docs/server-sdks/reference/typescript/agents/data-map/webhook-expressions.md): Add post-processing expressions for a webhook response.