> 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/python/agents/swaig-function

[functionresult]: /docs/server-sdks/reference/python/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/python/agents/data-map/body

[errorkeys]: /docs/server-sdks/reference/python/agents/data-map/error-keys

[expression]: /docs/server-sdks/reference/python/agents/data-map/expression

[foreach]: /docs/server-sdks/reference/python/agents/data-map/foreach

[helper-functions]: /docs/server-sdks/reference/python/agents/data-map/helper-functions

[output]: /docs/server-sdks/reference/python/agents/data-map/output

[parameter]: /docs/server-sdks/reference/python/agents/data-map/parameter

[purpose]: /docs/server-sdks/reference/python/agents/data-map/purpose

[toswaigfunction]: /docs/server-sdks/reference/python/agents/data-map/to-swaig-function

[webhook]: /docs/server-sdks/reference/python/agents/data-map/webhook

[webhookexpressions]: /docs/server-sdks/reference/python/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**

**`function_name`** `str` — 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/python/agents/data-map/body)

Set the request body for a webhook.

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

Alias for purpose — set the function description.

#### [error\_keys](/docs/server-sdks/reference/python/agents/data-map/error-keys)

Set error detection keys for webhook responses.

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

Add a pattern-based response without an API call.

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

Process an array from the webhook response.

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

Convenience functions for creating common DataMap patterns.

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

Set the output template for a webhook.

#### [fallback\_output](/docs/server-sdks/reference/python/agents/data-map/fallback-output)

Set the fallback output when no webhook or expression matches.

#### [global\_error\_keys](/docs/server-sdks/reference/python/agents/data-map/global-error-keys)

Set top-level error detection keys.

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

Set query or form parameters for a webhook.

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

Add a function parameter to the tool definition.

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

Set the function description shown to the AI.

#### [to\_swaig\_function](/docs/server-sdks/reference/python/agents/data-map/to-swaig-function)

Convert the DataMap to a SWAIG function definition dictionary.

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

Add an API call to the DataMap.

#### [webhook\_expressions](/docs/server-sdks/reference/python/agents/data-map/webhook-expressions)

Add post-processing expressions for a webhook response.

---

## **Examples**

### Weather lookup

```python {11}
from signalwire import AgentBase, DataMap
from signalwire import FunctionResult

class WeatherAgent(AgentBase):
    def __init__(self):
        super().__init__(name="weather-agent")
        self.add_language("English", "en-US", "rime.spore")
        self.prompt_add_section("Role", "You help users check the weather.")

        weather = (
            DataMap("get_weather")
            .description("Get current weather for a city")
            .parameter("city", "string", "City name", required=True)
            .webhook(
                "GET",
                "https://api.weatherapi.com/v1/current.json"
                "?key=YOUR_API_KEY&q=${enc:args.city}"
            )
            .output(FunctionResult(
                "Current weather in ${args.city}: "
                "${response.current.condition.text}, "
                "${response.current.temp_f} degrees Fahrenheit"
            ))
            .fallback_output(FunctionResult(
                "Sorry, I couldn't get weather data for ${args.city}"
            ))
        )

        self.register_swaig_function(weather.to_swaig_function())

if __name__ == "__main__":
    WeatherAgent().run()
```

### Expression-based control

```python {5}
from signalwire import AgentBase, DataMap
from signalwire import FunctionResult

volume_control = (
    DataMap("set_volume")
    .purpose("Control audio volume")
    .parameter("level", "string", "Volume level", required=True)
    .expression(
        "${args.level}", r"high|loud|up",
        FunctionResult("Volume increased")
    )
    .expression(
        "${args.level}", r"low|quiet|down",
        FunctionResult("Volume decreased")
    )
    .expression(
        "${args.level}", r"mute|off",
        FunctionResult("Audio muted")
    )
)

agent = AgentBase(name="media-agent")
agent.set_prompt_text("You are a helpful assistant.")
agent.register_swaig_function(volume_control.to_swaig_function())

if __name__ == "__main__":
    agent.run()
```

### POST with body and foreach

```python {5}
from signalwire import DataMap
from signalwire import FunctionResult

search_docs = (
    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(FunctionResult("Found:\n${formatted_results}"))
    .fallback_output(FunctionResult("Search is currently unavailable."))
)

print(search_docs.to_swaig_function())
```

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

## Docs

- [body](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/body.md): Set the request body for a webhook.
- [description](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/description.md): Alias for purpose — sets the tool description shown to the AI.
- [error_keys](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/error-keys.md): Set error detection keys for webhook responses.
- [expression](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/expression.md): Add a pattern-based response without an API call.
- [fallback_output](https://signalwire.com/docs/server-sdks/reference/python/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/python/agents/data-map/foreach.md): Process an array from the webhook response.
- [global_error_keys](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/global-error-keys.md): Set top-level error detection keys that apply regardless of webhook context.
- [Helper Functions](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/helper-functions.md): Convenience functions for creating common DataMap patterns.
- [output](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/output.md): Set the output template for a webhook.
- [parameter](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/parameter.md): Add a function parameter to the tool definition.
- [params](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/params.md): Set query or form parameters for the most recently added webhook.
- [purpose](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/purpose.md): Set the function description shown to the AI.
- [to_swaig_function](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/to-swaig-function.md): Convert the DataMap to a SWAIG function definition dictionary.
- [webhook](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/webhook.md): Add an API call to the DataMap.
- [webhook_expressions](https://signalwire.com/docs/server-sdks/reference/python/agents/data-map/webhook-expressions.md): Add post-processing expressions for a webhook response.