Datamap
DataMap
DataMap provides serverless API integration - define functions that call REST APIs directly from SignalWire’s infrastructure without running code on your server.
DataMap is one of the most powerful features for building production agents quickly. Instead of writing webhook handlers that receive requests, process them, and return responses, you declaratively describe what API to call and how to format the response. SignalWire’s infrastructure handles the actual HTTP request, meaning your server doesn’t need to be involved at all for simple integrations.
This approach has significant advantages: reduced latency (no round-trip to your server), simplified deployment (fewer endpoints to maintain), and improved reliability (SignalWire’s infrastructure handles retries and timeouts). However, it’s not suitable for every situation—complex business logic, database operations, and multi-step processing still require traditional handler functions.
When to Use DataMap vs Handler Functions
Choosing between DataMap and handler functions is one of the first decisions you’ll make when adding functionality to your agent. Here’s a framework to help you decide:
Choose DataMap when:
- You’re calling a REST API that returns JSON
- The response can be formatted with simple variable substitution
- You don’t need to transform data, just extract and present it
- You want to minimize server-side code and infrastructure
- The API is reliable and has predictable response formats
Choose Handler Functions when:
- You need to access a database or internal systems
- Business logic requires conditionals, loops, or calculations
- You need to call multiple APIs and combine results
- Error handling requires custom logic beyond simple fallbacks
- You need to validate or sanitize input before processing
- The response format varies and requires dynamic handling
DataMap Flow
DataMap Execution Steps:
-
AI decides to call function
- Function:
get_weather - Args:
{"city": "Seattle"}
- Function:
-
SignalWire executes DataMap (no webhook to your server!)
GET https://api.weather.com?city=Seattle
-
API response processed
- Response:
{"temp": 65, "condition": "cloudy"}
- Response:
-
Output template filled
- Result: “Weather in Seattle: 65 degrees, cloudy”
Basic DataMap
Variable Substitution
DataMap supports these variable patterns:
Chained Modifiers
Modifiers are applied right-to-left:
Examples
DataMap Builder Methods
description() / purpose()
Set the function description:
parameter()
Add a function parameter:
webhook()
Add an API call:
body()
Set request body for POST/PUT:
output()
Set the response for a webhook:
fallback_output()
Set fallback if all webhooks fail:
Complete Example
Error Handling Patterns
DataMap provides several mechanisms for handling errors gracefully. Since you can’t write custom error handling code, you need to configure fallback responses declaratively.
Handling HTTP Errors
DataMap automatically treats HTTP 4xx and 5xx responses as failures. Combined with fallback_output, this ensures your agent always has something meaningful to say:
Timeout Considerations
DataMap uses reasonable timeout defaults for API calls. For APIs that may be slow, consider using function fillers to provide feedback to the user while waiting:
Real-World Integration Examples
Example 1: CRM Customer Lookup
A common pattern is looking up customer information from a CRM system. This example shows how to query a REST API and present the results conversationally:
Example 2: Appointment Scheduling API
This example shows a POST request to check appointment availability:
Example 3: Order Status Tracking
This example demonstrates looking up order status with multiple possible response fields:
Example 4: Multi-Service Agent
This example shows an agent with multiple DataMap functions for different services:
Performance Considerations
When using DataMap, keep these performance factors in mind:
Latency: DataMap calls execute on SignalWire’s infrastructure, eliminating the round-trip to your server. This typically reduces latency by 50-200ms compared to webhook-based handlers. For time-sensitive interactions, this improvement is significant.
API Rate Limits: Your external APIs may have rate limits. Since DataMap calls don’t go through your server, you can’t implement custom rate limiting logic. Consider:
- Choosing APIs with generous rate limits
- Using fallback responses when rate limited
- Monitoring API usage through your provider’s dashboard
Response Size: DataMap works best with reasonably-sized JSON responses. Very large responses (>1MB) may cause timeouts or memory issues. If your API returns large datasets, consider:
- Using query parameters to limit response size
- Requesting specific fields only
- Using a handler function instead for complex data processing
Caching: DataMap doesn’t cache responses. Each function call makes a fresh API request. If your data doesn’t change frequently, consider:
- APIs with built-in caching headers
- Using handler functions with server-side caching for high-frequency lookups
DataMap Best Practices
DO:
- Always set
fallback_outputfor every DataMap—users should never encounter silent failures - Use
${enc:args.param}for any value in a URL to prevent injection and encoding issues - Test your DataMap functions with
swaig-testbefore deploying - Store API keys in
global_datarather than hardcoding them - Use descriptive function names and descriptions to help the AI choose correctly
- Start simple and add complexity only when needed
DON’T:
- Put API keys directly in webhook URLs where they might be logged
- Use DataMap for operations that require transactions or rollback
- Assume API responses will always have the expected structure—test edge cases
- Chain multiple DataMap calls for operations that need atomicity
- Forget that DataMap has no access to your server’s state or databases
- Use DataMap when you need to transform data beyond simple extraction
Debugging DataMap
When DataMap functions don’t work as expected, use these debugging strategies:
- Test the API directly: Use curl or Postman to verify the API works with your parameters
- Check variable substitution: Ensure
${args.param}matches your parameter names exactly - Verify JSON paths: Response field access like
${response.data.items[0].name}must match the actual response structure - Use swaig-test: The testing tool shows you exactly what SWML is generated
Migrating from Handler Functions to DataMap
If you have existing handler functions that make simple API calls, consider migrating them to DataMap:
Before (Handler Function):
After (DataMap):
The DataMap version is more concise, doesn’t require the requests library, and includes built-in error handling.
