{"slug":"swml-data-map","title":"DataMap — Server-Side SWAIG API Passthrough","tags":["signalwire","swaig","datamap","api-integration","no-server"],"agent_summary":"DataMap executes REST API calls on SignalWire's infrastructure — no webhook on your side. Variable substitution table, GET/POST/foreach patterns, expression-only matching, and the right use cases for DataMap vs a Python @tool handler.","trigger_phrases":["DataMap SignalWire","SWAIG without server","API passthrough SignalWire","DataMap foreach loop","DataMap expression match","${args.param} substitution"],"runnable":true,"markdown":"\n# DataMap — Server-Side SWAIG API Passthrough\n\nDataMap is the \"no-webhook\" mode of [SWAIG](/topic/swaig-functions). Instead of you hosting a function handler, you describe the API call once and SignalWire executes it on its infrastructure. The response is templated into a `FunctionResult` and spoken to the caller.\n\nUse DataMap when:\n\n- The integration is a straightforward HTTP call to a public or token-auth API.\n- You want zero servers.\n- The transformation from API response to spoken reply fits a template.\n\nSkip DataMap when:\n\n- You need to mutate database state.\n- The handler needs custom auth flows (OAuth refresh, signed payloads).\n- The logic needs branching beyond simple `expression()` regex matches.\n\n## Variable substitution\n\n| Pattern | Expands to |\n|---|---|\n| `${args.param}` | Function argument value |\n| `${enc:args.param}` | URL-encoded argument |\n| `${lc:args.param}` | Lowercased argument |\n| `${fmt_ph:args.phone}` | Formatted phone number (E.164 → human-readable) |\n| `${response.field}` | API response field |\n| `${response.arr[0]}` | Array element from response |\n| `${global_data.key}` | Session-wide data |\n| `${this.field}` | Current item inside a `foreach` loop |\n\nModifiers chain right-to-left. `${enc:lc:args.city}` lowercases first, then URL-encodes.\n\n## GET request\n\n```python\nfrom signalwire import DataMap, FunctionResult\n\nweather = (\n DataMap(\"get_weather\")\n .description(\"Get current weather for a city\")\n .parameter(\"city\", \"string\", \"City name\", required=True)\n .webhook(\"GET\", \"https://api.weatherapi.com/v1/current.json?key=API_KEY&q=${enc:args.city}\")\n .output(FunctionResult(\n \"Weather in ${args.city}: ${response.current.condition.text}, ${response.current.temp_f}F\"\n ))\n .fallback_output(FunctionResult(\"Sorry, couldn't get weather for ${args.city}.\"))\n)\n\nagent.register_swaig_function(weather.to_swaig_function())\n```\n\n## POST with body and foreach loop\n\n`foreach` iterates over an array in the response and accumulates a template into a single output variable.\n\n```python\nsearch_docs = (\n DataMap(\"search_docs\")\n .purpose(\"Search documentation\")\n .parameter(\"query\", \"string\", \"Search query\", required=True)\n .webhook(\"POST\", \"https://api.docs.example.com/search\",\n headers={\"Authorization\": \"Bearer TOKEN\"})\n .body({\"query\": \"${args.query}\", \"limit\": 3})\n .foreach({\n \"input_key\": \"results\",\n \"output_key\": \"formatted_results\",\n \"max\": 3,\n \"append\": \"- ${this.title}: ${this.summary}\\n\",\n })\n .output(FunctionResult(\"Found:\\n${formatted_results}\"))\n .fallback_output(FunctionResult(\"Search unavailable.\"))\n)\n```\n\n`foreach` parameters:\n\n| Key | Notes |\n|---|---|\n| `input_key` | Array path in the response JSON. |\n| `output_key` | Variable name where the concatenated string lands. |\n| `max` | Stop after this many items. |\n| `append` | Template per item, using `${this.field}`. |\n\n## Expression-only (no HTTP)\n\nFor pure pattern matching with no API call, use `.expression()`:\n\n```python\nvolume = (\n DataMap(\"set_volume\")\n .description(\"Control audio volume\")\n .parameter(\"level\", \"string\", \"Volume level\", required=True)\n .expression(\"${args.level}\", r\"high|loud|up\", FunctionResult(\"Volume increased\"))\n .expression(\"${args.level}\", r\"low|quiet|down\", FunctionResult(\"Volume decreased\"))\n .expression(\"${args.level}\", r\"mute|off\", FunctionResult(\"Audio muted\"))\n)\n\nagent.register_swaig_function(volume.to_swaig_function())\n```\n\nEach `.expression(value, regex, result)` is evaluated in order. First match wins. Useful for IVR-like routing without a real backend.\n\n## Helper shortcuts\n\n```python\nfrom signalwire import create_simple_api_tool, create_expression_tool\n\n# Simple GET tool\nweather_tool = create_simple_api_tool(\n name=\"get_weather\",\n url=\"https://api.weather.com/v1/current?key=KEY&q=${args.location}\",\n response_template=\"Weather in ${args.location}: ${response.current.condition.text}\",\n parameters={\"location\": {\"type\": \"string\", \"description\": \"City name\", \"required\": True}},\n)\n\n# Pattern-matching tool\ncmd_tool = create_expression_tool(\n name=\"playback_control\",\n patterns={\n \"${args.command}\": (r\"play.*\", FunctionResult(\"Playing.\")),\n },\n parameters={\"command\": {\"type\": \"string\", \"description\": \"Command\", \"required\": True}},\n)\n```\n\nThese wrap the full DataMap builder when you only need a single GET or single regex tool.\n\n## Auth patterns\n\n| Auth style | How |\n|---|---|\n| API key in URL | Inline: `https://api.example.com/?key=ABC&q=${enc:args.q}` |\n| Bearer token | `.webhook(\"GET\", \"...\", headers={\"Authorization\": \"Bearer TOKEN\"})` |\n| Static header | Same `headers={}` pattern |\n| OAuth refresh / signed requests | **Use a `@tool` handler, not DataMap** |\n\n## Fallback behavior\n\n`.fallback_output(...)` fires when:\n\n- The HTTP call returns a non-2xx status.\n- The response JSON doesn't contain the expected fields.\n- A timeout (default ~10s) elapses.\n\nAlways provide a fallback. Without it, a failed call returns nothing and the AI invents a response.\n\n## Anti-patterns\n\n- Putting secrets directly in `headers` and checking the SWML into git — secrets land in version control. Inject at runtime.\n- Using DataMap for mutation endpoints (POST that creates records) — race conditions, no retry strategy.\n- Foreach with `max > 10` — spoken response gets unbearably long.\n- Skipping `fallback_output` — AI hallucinates results when the API errors.\n- Mixing `%{...}` (SWML) and `${...}` (DataMap) prefixes — DataMap is `${...}` only.\n\n## See also\n\n- [SWAIG functions](/topic/swaig-functions)\n- [Python Agents SDK](/topic/signalwire-python-agents-sdk)\n- [SWML AI verb](/topic/swml-ai-verb)\n","html":"

DataMap — Server-Side SWAIG API Passthrough

\n

DataMap is the \"no-webhook\" mode of SWAIG. Instead of you hosting a function handler, you describe the API call once and SignalWire executes it on its infrastructure. The response is templated into a FunctionResult and spoken to the caller.

\n

Use DataMap when:

\n\n

Skip DataMap when:

\n\n

Variable substitution

\n

| Pattern | Expands to |\n|---|---|\n| ${args.param} | Function argument value |\n| ${enc:args.param} | URL-encoded argument |\n| ${lc:args.param} | Lowercased argument |\n| ${fmt_ph:args.phone} | Formatted phone number (E.164 → human-readable) |\n| ${response.field} | API response field |\n| ${response.arr[0]} | Array element from response |\n| ${global_data.key} | Session-wide data |\n| ${this.field} | Current item inside a foreach loop |

\n

Modifiers chain right-to-left. ${enc:lc:args.city} lowercases first, then URL-encodes.

\n

GET request

\n
from signalwire import DataMap, FunctionResult\n\nweather = (\n    DataMap(\"get_weather\")\n    .description(\"Get current weather for a city\")\n    .parameter(\"city\", \"string\", \"City name\", required=True)\n    .webhook(\"GET\", \"https://api.weatherapi.com/v1/current.json?key=API_KEY&q=${enc:args.city}\")\n    .output(FunctionResult(\n        \"Weather in ${args.city}: ${response.current.condition.text}, ${response.current.temp_f}F\"\n    ))\n    .fallback_output(FunctionResult(\"Sorry, couldn't get weather for ${args.city}.\"))\n)\n\nagent.register_swaig_function(weather.to_swaig_function())\n
\n

POST with body and foreach loop

\n

foreach iterates over an array in the response and accumulates a template into a single output variable.

\n
search_docs = (\n    DataMap(\"search_docs\")\n    .purpose(\"Search documentation\")\n    .parameter(\"query\", \"string\", \"Search query\", required=True)\n    .webhook(\"POST\", \"https://api.docs.example.com/search\",\n             headers={\"Authorization\": \"Bearer TOKEN\"})\n    .body({\"query\": \"${args.query}\", \"limit\": 3})\n    .foreach({\n        \"input_key\": \"results\",\n        \"output_key\": \"formatted_results\",\n        \"max\": 3,\n        \"append\": \"- ${this.title}: ${this.summary}\\n\",\n    })\n    .output(FunctionResult(\"Found:\\n${formatted_results}\"))\n    .fallback_output(FunctionResult(\"Search unavailable.\"))\n)\n
\n

foreach parameters:

\n

| Key | Notes |\n|---|---|\n| input_key | Array path in the response JSON. |\n| output_key | Variable name where the concatenated string lands. |\n| max | Stop after this many items. |\n| append | Template per item, using ${this.field}. |

\n

Expression-only (no HTTP)

\n

For pure pattern matching with no API call, use .expression():

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

Each .expression(value, regex, result) is evaluated in order. First match wins. Useful for IVR-like routing without a real backend.

\n

Helper shortcuts

\n
from signalwire import create_simple_api_tool, create_expression_tool\n\n# Simple GET tool\nweather_tool = create_simple_api_tool(\n    name=\"get_weather\",\n    url=\"https://api.weather.com/v1/current?key=KEY&q=${args.location}\",\n    response_template=\"Weather in ${args.location}: ${response.current.condition.text}\",\n    parameters={\"location\": {\"type\": \"string\", \"description\": \"City name\", \"required\": True}},\n)\n\n# Pattern-matching tool\ncmd_tool = create_expression_tool(\n    name=\"playback_control\",\n    patterns={\n        \"${args.command}\": (r\"play.*\", FunctionResult(\"Playing.\")),\n    },\n    parameters={\"command\": {\"type\": \"string\", \"description\": \"Command\", \"required\": True}},\n)\n
\n

These wrap the full DataMap builder when you only need a single GET or single regex tool.

\n

Auth patterns

\n

| Auth style | How |\n|---|---|\n| API key in URL | Inline: https://api.example.com/?key=ABC&q=${enc:args.q} |\n| Bearer token | .webhook(\"GET\", \"...\", headers={\"Authorization\": \"Bearer TOKEN\"}) |\n| Static header | Same headers={} pattern |\n| OAuth refresh / signed requests | Use a @tool handler, not DataMap |

\n

Fallback behavior

\n

.fallback_output(...) fires when:

\n\n

Always provide a fallback. Without it, a failed call returns nothing and the AI invents a response.

\n

Anti-patterns

\n\n

See also

\n\n"}