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

function_name

strRequired

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.

description

Alias for purpose — set the function description.

error_keys

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.

fallback_output

Set the fallback output when no webhook or expression matches.

global_error_keys

Set top-level error detection keys.

params

Set query or form parameters for a webhook.

parameter

Add a function parameter to the tool definition.

purpose

Set the function description shown to the AI.

to_swaig_function

Convert the DataMap to a SWAIG function definition dictionary.

webhook

Add an API call to the DataMap.

webhook_expressions

Add post-processing expressions for a webhook response.

Examples

Weather lookup

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

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

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