SignalWire SWAIG post_data Complete Reference 🔗 ↑ TOC

This document comprehensively details all possible keys that can be present in the post_data JSON object sent to SWAIG functions, based on analysis of the execute_user_function implementation in server_code/mod_openai.c.

Overview 🔗 ↑ TOC

The post_data object is constructed differently depending on whether it's: - Webhook SWAIG Functions: Traditional HTTP-based functions with Python handlers - DataMap Functions: Serverless functions that execute on SignalWire servers

Base post_data Keys (All Functions) 🔗 ↑ TOC

These keys are always present in post_data for both webhook and DataMap functions:

Core Identification 🔗 ↑ TOC

Key	Type	Description	Example
`app_name`	string	Name of the AI application	`"my_ai_agent"`
`function`	string	Name of the SWAIG function being called	`"search_knowledge"`
`call_id`	string	Unique UUID of the current call session	`"12345678-1234-5678-9012-123456789abc"`
`ai_session_id`	string	Unique UUID of the AI session	`"87654321-4321-8765-2109-cba987654321"`

Call Context 🔗 ↑ TOC

Key	Type	Description	Example
`caller_id_name`	string	Caller ID name (if available)	`"John Doe"`
`caller_id_num`	string	Caller ID number (if available)	`"+15551234567"`
`channel_active`	boolean	Whether the channel is currently up	`true`
`channel_offhook`	boolean	Whether the channel is off-hook	`true`
`channel_ready`	boolean	Whether the AI session is ready	`true`

Function Details 🔗 ↑ TOC

Key	Type	Description	Example
`argument`	object	Parsed function arguments	`{"query": "test search"}`
`argument_desc`	object	Function argument schema/description	`{"type": "object", "properties": {...}}`
`purpose`	string	Description of what the function does	`"Search knowledge base"`

Protocol Information 🔗 ↑ TOC

Key	Type	Description	Example
`content_type`	string	Always "text/swaig"	`"text/swaig"`
`version`	string	SWAIG protocol version	`"1.0"`
`content_disposition`	string	Always "SWAIG Function"	`"SWAIG Function"`

Optional Context Data 🔗 ↑ TOC

Key	Type	Description	Present When
`global_data`	object	Application-level global data	App has global data set
`conversation_id`	string	Conversation identifier	App has conversation tracking
`project_id`	string	SignalWire project ID	Available in channel vars
`space_id`	string	SignalWire space ID	Available in channel vars

Conditional Keys (Webhook Functions Only) 🔗 ↑ TOC

These keys are only added for traditional webhook SWAIG functions (not DataMap):

Metadata 🔗 ↑ TOC

Key	Type	Description	Present When
`meta_data_token`	string	Token for metadata access	Function has metadata token
`meta_data`	object	Function-level metadata object	Function has metadata token

Metadata Details:

meta_data_token: Either specified in function definition or auto-generated (hash of function name + webhook URL)
meta_data: Function-level key/value store, similar to global_data but scoped per function
Functions sharing the same token share access to the same metadata
Can be manipulated via SWAIG actions in responses
Persists across function calls for the same token

SWML Integration 🔗 ↑ TOC

Key	Type	Description	Present When
`SWMLVars`	object	SWML variables	`swaig_post_swml_vars` parameter set
`SWMLCall`	object	SWML call state	`swaig_post_swml_vars` parameter set

SWML Variable Filtering:

swaig_post_swml_vars=true: Includes all SWML variables
swaig_post_swml_vars=[array]: Includes only specified variables from the array
Variables may come from other SWML verbs executed before the AI verb
Part of SWML's variable system for cross-verb communication

Conversation Data 🔗 ↑ TOC

Key	Type	Description	Present When
`call_log`	array	Processed conversation history	`swaig_post_conversation` parameter true
`raw_call_log`	array	Raw conversation history	`swaig_post_conversation` parameter true

Conversation History Structure: Both arrays use OpenAI conversation format with additional SignalWire fields:

{
  "role": "assistant",
  "content": "Response text",
  "latency": 438,
  "utterance_latency": 445,
  "audio_latency": 599
}

Key Differences:

call_log: May shrink after conversation resets (consolidation)
raw_call_log: Preserves full history from beginning regardless of resets
Both include timing data (latency, utterance_latency, audio_latency)
User messages include confidence scores when available

DataMap-Specific Additions 🔗 ↑ TOC

For DataMap functions, additional keys are merged into post_data:

Enhanced Context Data 🔗 ↑ TOC

Key	Type	Description	Source
`prompt_vars`	object	Template variables for AI prompts	Built from call context, SWML vars, and global_data
`global_data`	object	Application global data (same as base)	From SWML global_data section

Parsed Arguments 🔗 ↑ TOC

Key	Type	Description	Processing
`args`	object	First parsed argument object	Extracted from `argument.parsed[0]`

Argument Processing Details:

Each function has unique argument structure based on its JSON schema definition
AI converts the schema to JSON string, engine parses and provides for expansion
args contains the first parsed argument object for easy access in templates

Processing Context 🔗 ↑ TOC

Key	Type	Description	Purpose
`input`	object	Copy of entire post_data	Variable expansion context

prompt_vars Detailed Contents 🔗 ↑ TOC

The prompt_vars object contains template variables built from multiple sources:

Call Information 🔗 ↑ TOC

Key	Source	Description	Example
`call_direction`	Call direction	"inbound" or "outbound"	`"inbound"`
`caller_id_name`	Channel variable	Caller's name	`"John Doe"`
`caller_id_number`	Channel variable	Caller's number	`"+15551234567"`
`local_date`	System time	Current date in local timezone	`"Friday, January 15, 2024"`
`spoken_date`	System time	Same as local_date	`"Friday, January 15, 2024"`
`local_time`	System time	Current time with timezone	`"02:30:15 PM -0500"`
`time_of_day`	Derived from hour	"morning", "afternoon", or "evening"	`"afternoon"`
`supported_languages`	App config	Available languages	`"English, Spanish, or French"`
`default_language`	App config	Primary language	`"English"`

SWML State Variables 🔗 ↑ TOC

Key	Source	Description	Present When
`vars`	SWML serialized state	All SWML variables (excluding system vars)	SWML vars exist
`call`	SWML serialized state	SWML call object	SWML state exists

Global Data Overlay 🔗 ↑ TOC

All keys from the global_data object are merged into prompt_vars, with global_data taking precedence over built-in values.

global_data Evolution 🔗 ↑ TOC

The global_data object has dynamic behavior:

Initial State 🔗 ↑ TOC

Populated from SWML global_data section at call start
Contains caller ID information automatically
Available to both webhook and DataMap functions

Runtime Updates 🔗 ↑ TOC

Can be modified by SWAIG actions during the call
Changes persist for subsequent function calls
Refreshed only when context switches occur
Used as overlay for prompt_vars in DataMap functions

DataMap Processing Enhancements 🔗 ↑ TOC

During DataMap processing, additional data may be added based on the processing path:

Webhook Processing Path 🔗 ↑ TOC

When DataMap uses webhooks, additional keys are added to the webhook response data:

Key	Type	Description	Added When
`prompt_vars`	object	Prompt variables for expansion	Webhook processing
`global_data`	object	Global data for expansion	Webhook processing
`input`	object	Original input for context	Webhook processing

Foreach Processing 🔗 ↑ TOC

During foreach operations, a temporary key is added:

Key	Type	Description	Scope
`this`	object	Current iteration item	During foreach loop only

Expression Processing 🔗 ↑ TOC

For expression evaluation, data is enriched with context variables for template expansion.

Variable Expansion Context 🔗 ↑ TOC

All DataMap processing uses variable expansion for template processing with access to:

All keys in the current data object
Nested object access via dot notation: ${user.name}
Array access: ${items[0].value}
Encoding functions: ${enc:url:variable}
Built-in functions: @{strftime %Y-%m-%d}, @{expr 2+2}, etc.

Template Functions: For a complete list of available @{} template functions, see the DataMap processing guide and expand_jsonvars implementation in swaig.c.

Error Handling 🔗 ↑ TOC

DataMap Webhook Errors 🔗 ↑ TOC

When DataMap webhook processing fails, special error keys may be added:

Key	Type	Description	When Present
`parse_error`	boolean	JSON parsing failed	Webhook response not valid JSON
`protocol_error`	boolean	HTTP request failed	Network/connection issues
`http_code`	number	HTTP response code	Always present with errors

These errors are only set when the webhook didn't fetch properly, allowing alternate error responses to be provided to users.

Security and Permissions 🔗 ↑ TOC

Several keys are only included based on SWML application parameters:

SWML Variables Permission 🔗 ↑ TOC

Parameter: swaig_post_swml_vars (boolean or array)
Adds: SWMLVars, SWMLCall
Behavior: If true, includes all SWML vars; if array, includes only specified variables

Conversation Permission 🔗 ↑ TOC

Parameter: swaig_post_conversation (boolean)
Adds: call_log, raw_call_log
Default: false (not included unless explicitly enabled)

SWML Execution Permission 🔗 ↑ TOC

Parameter: swaig_allow_swml (boolean)
Controls: Whether functions can execute SWML actions
Default: true (enabled by default)

Global Data Modification Permission 🔗 ↑ TOC

Parameter: swaig_set_global_data (boolean)
Controls: Whether functions can modify global_data
Default: true (enabled by default)

Implementation Notes 🔗 ↑ TOC

DataMap vs Webhook: The key difference is DataMap functions merge prompt_vars and create an input copy for variable expansion
Variable Expansion: DataMap functions process templates using the entire post_data as context
Memory Management: post_data is created fresh for each function call and cleaned up afterward
Error Handling: Missing or invalid data results in empty objects rather than missing keys
Dynamic Content: prompt_vars and global_data can vary between function calls based on call state
Metadata Scope: Function metadata is isolated per token, enabling function-specific data storage

Example post_data Objects 🔗 ↑ TOC

Webhook Function Example 🔗 ↑ TOC

{
  "app_name": "customer_service_agent",
  "function": "search_knowledge",
  "call_id": "12345678-1234-5678-9012-123456789abc",
  "ai_session_id": "87654321-4321-8765-2109-cba987654321",
  "caller_id_name": "John Doe",
  "caller_id_num": "+15551234567",
  "channel_active": true,
  "channel_offhook": true,
  "channel_ready": true,
  "argument": {"query": "billing question"},
  "argument_desc": {"type": "object", "properties": {"query": {"type": "string"}}},
  "purpose": "Search the knowledge base for relevant information",
  "content_type": "text/swaig",
  "version": "1.0",
  "content_disposition": "SWAIG Function",
  "global_data": {"customer_tier": "premium"},
  "conversation_id": "conv_123",
  "project_id": "proj_abc",
  "space_id": "space_xyz",
  "meta_data_token": "func_abc123",
  "meta_data": {"search_count": 5, "last_query": "previous search"},
  "call_log": [
    {
      "role": "user",
      "content": "I have a billing question",
      "confidence": 0.95
    },
    {
      "role": "assistant", 
      "content": "I'd be happy to help with billing",
      "latency": 250,
      "utterance_latency": 300,
      "audio_latency": 450
    }
  ]
}

DataMap Function Example 🔗 ↑ TOC

{
  "app_name": "data_processor",
  "function": "process_data",
  "call_id": "12345678-1234-5678-9012-123456789abc",
  "ai_session_id": "87654321-4321-8765-2109-cba987654321",
  "channel_active": true,
  "channel_offhook": true,
  "channel_ready": true,
  "argument": {"data": [{"name": "item1"}, {"name": "item2"}]},
  "argument_desc": {"type": "object", "properties": {"data": {"type": "array"}}},
  "purpose": "Process array data with template expansion",
  "content_type": "text/swaig",
  "version": "1.0",
  "content_disposition": "SWAIG Function",
  "global_data": {"prefix": "processed_", "customer_tier": "premium"},
  "prompt_vars": {
    "call_direction": "inbound",
    "caller_id_name": "John Doe", 
    "caller_id_number": "+15551234567",
    "local_date": "Friday, January 15, 2024",
    "local_time": "02:30:15 PM -0500",
    "time_of_day": "afternoon",
    "supported_languages": "English",
    "default_language": "English",
    "customer_tier": "premium",
    "prefix": "processed_"
  },
  "args": {"data": [{"name": "item1"}, {"name": "item2"}]},
  "input": { /* copy of entire post_data */ }
}

SWML Parameter Reference 🔗 ↑ TOC

The following SWML parameters control what data is included in post_data:

Parameter	Type	Default	Purpose
`swaig_allow_swml`	boolean	true	Allow functions to execute SWML actions
`swaig_allow_settings`	boolean	true	Allow functions to modify AI settings
`swaig_post_conversation`	boolean	false	Include conversation history in post_data
`swaig_set_global_data`	boolean	true	Allow functions to modify global_data
`swaig_post_swml_vars`	boolean/array	false	Include SWML variables in post_data

This reference covers all the keys that can appear in post_data based on the server implementation and configuration parameters.