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

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

1 from signalwire import AgentBase, DataMap
2 from signalwire import FunctionResult
3 
4 class WeatherAgent(AgentBase):
5     def __init__(self):
6         super().__init__(name="weather-agent")
7         self.add_language("English", "en-US", "rime.spore")
8         self.prompt_add_section("Role", "You help users check the weather.")
9 
10         weather = (
11             DataMap("get_weather")
12             .description("Get current weather for a city")
13             .parameter("city", "string", "City name", required=True)
14             .webhook(
15                 "GET",
16                 "https://api.weatherapi.com/v1/current.json"
17                 "?key=YOUR_API_KEY&q=${enc:args.city}"
18             )
19             .output(FunctionResult(
20                 "Current weather in ${args.city}: "
21                 "${response.current.condition.text}, "
22                 "${response.current.temp_f} degrees Fahrenheit"
23             ))
24             .fallback_output(FunctionResult(
25                 "Sorry, I couldn't get weather data for ${args.city}"
26             ))
27         )
28 
29         self.register_swaig_function(weather.to_swaig_function())
30 
31 if __name__ == "__main__":
32     WeatherAgent().run()

Expression-based control

1 from signalwire import AgentBase, DataMap
2 from signalwire import FunctionResult
3 
4 volume_control = (
5     DataMap("set_volume")
6     .purpose("Control audio volume")
7     .parameter("level", "string", "Volume level", required=True)
8     .expression(
9         "${args.level}", r"high|loud|up",
10         FunctionResult("Volume increased")
11     )
12     .expression(
13         "${args.level}", r"low|quiet|down",
14         FunctionResult("Volume decreased")
15     )
16     .expression(
17         "${args.level}", r"mute|off",
18         FunctionResult("Audio muted")
19     )
20 )
21 
22 agent = AgentBase(name="media-agent")
23 agent.set_prompt_text("You are a helpful assistant.")
24 agent.register_swaig_function(volume_control.to_swaig_function())
25 
26 if __name__ == "__main__":
27     agent.run()

POST with body and foreach

1 from signalwire import DataMap
2 from signalwire import FunctionResult
3 
4 search_docs = (
5     DataMap("search_docs")
6     .purpose("Search documentation")
7     .parameter("query", "string", "Search query", required=True)
8     .webhook(
9         "POST",
10         "https://api.docs.example.com/search",
11         headers={"Authorization": "Bearer TOKEN"}
12     )
13     .body({"query": "${args.query}", "limit": 3})
14     .foreach({
15         "input_key": "results",
16         "output_key": "formatted_results",
17         "max": 3,
18         "append": "- ${this.title}: ${this.summary}\n"
19     })
20     .output(FunctionResult("Found:\n${formatted_results}"))
21     .fallback_output(FunctionResult("Search is currently unavailable."))
22 )
23 
24 print(search_docs.to_swaig_function())