SwaigFunctionResult Methods Reference 🔗

This document provides a complete reference for all methods available in the SwaigFunctionResult class. These methods provide convenient abstractions for SWAIG actions, eliminating the need to manually construct action JSON objects.

Core Methods 🔗

Basic Construction & Control 🔗

__init__(response=None, post_process=False) 🔗

Creates a new result object with optional response text and post-processing behavior.

result = SwaigFunctionResult("Hello, I'll help you with that")
result = SwaigFunctionResult("Processing request...", post_process=True)

set_response(response) 🔗

Sets or updates the response text that the AI will speak.

result.set_response("I've updated your information")

set_post_process(post_process) 🔗

Controls whether AI gets one more turn before executing actions.

result.set_post_process(True)  # AI speaks response before executing actions
result.set_post_process(False)  # Actions execute immediately

Action Methods 🔗

Call Control Actions 🔗

execute_swml(swml_content, transfer=False) 🔗

Execute SWML content with flexible input support and optional transfer behavior.

# Raw SWML string
result.execute_swml('{"version":"1.0.0","sections":{"main":[{"say":"Hello"}]}}')

# SWML dictionary
swml_dict = {"version": "1.0.0", "sections": {"main": [{"say": "Hello"}]}}
result.execute_swml(swml_dict, transfer=True)

# SWML SDK object
from signalwire.swml import SWML
swml_doc = SWML()
swml_doc.add_application("main", "say", {"text": "Connecting now"})
result.execute_swml(swml_doc)

[IMPLEMENTED] - Transfer/connect call to another destination using SWML. 🔗

result.connect("+15551234567", final=True)  # Permanent transfer
result.connect("support@company.com", final=False, from_addr="+15559876543")  # Temporary transfer

send_sms(to_number, from_number, body=None, media=None, tags=None, region=None) 🔗

[HELPER METHOD] - Send SMS message to PSTN phone number using SWML.

# Simple text message
result.send_sms(
    to_number="+15551234567",
    from_number="+15559876543", 
    body="Your order has been confirmed!"
)

# Media message with images
result.send_sms(
    to_number="+15551234567",
    from_number="+15559876543",
    media=["https://example.com/receipt.jpg", "https://example.com/map.png"]
)

# Full featured message with tags and region
result.send_sms(
    to_number="+15551234567",
    from_number="+15559876543",
    body="Order update with receipt attached",
    media=["https://example.com/receipt.pdf"],
    tags=["order", "confirmation", "customer"],
    region="us"
)

Parameters:

Variables Set:

pay(payment_connector_url, **options) 🔗

[HELPER METHOD] - Process payments using SWML pay action with extensive customization.

# Simple payment setup
result.pay(
    payment_connector_url="https://api.example.com/accept-payment",
    charge_amount="10.99",
    description="Monthly subscription"
)

# Advanced payment with custom prompts
from signalwire_agents.core.function_result import SwaigFunctionResult

# Create custom prompts
welcome_actions = [
    SwaigFunctionResult.create_payment_action("Say", "Welcome to our payment system"),
    SwaigFunctionResult.create_payment_action("Say", "Please enter your credit card number")
]
card_prompt = SwaigFunctionResult.create_payment_prompt("payment-card-number", welcome_actions)

error_actions = [
    SwaigFunctionResult.create_payment_action("Say", "Invalid card number, please try again")
]
error_prompt = SwaigFunctionResult.create_payment_prompt(
    "payment-card-number", 
    error_actions, 
    error_type="invalid-card-number timeout"
)

# Create payment parameters
params = [
    SwaigFunctionResult.create_payment_parameter("customer_id", "12345"),
    SwaigFunctionResult.create_payment_parameter("order_id", "ORD-789")
]

# Full payment configuration
result.pay(
    payment_connector_url="https://api.example.com/accept-payment",
    status_url="https://api.example.com/payment-status",
    timeout=10,
    max_attempts=3,
    security_code=True,
    postal_code=False,
    token_type="one-time",
    charge_amount="25.50",
    currency="usd",
    language="en-US",
    voice="polly.Sally",
    description="Premium service upgrade",
    valid_card_types="visa mastercard amex",
    parameters=params,
    prompts=[card_prompt, error_prompt]
)

Core Parameters:

Security & Validation:

Payment Configuration:

Customization:

Helper Methods for Payment Setup:

# Create payment action
action = SwaigFunctionResult.create_payment_action("Say", "Enter card number")

# Create payment prompt
prompt = SwaigFunctionResult.create_payment_prompt(
    "payment-card-number", 
    [action], 
    error_type="invalid-card-number"
)

# Create payment parameter
param = SwaigFunctionResult.create_payment_parameter("customer_id", "12345")

Variables Set:

record_call(control_id=None, stereo=False, format="wav", direction="both", **options) 🔗

[HELPER METHOD] - Start background call recording using SWML.

Unlike foreground recording, the script continues executing while recording happens in the background.

# Simple background recording
result.record_call()

# Recording with custom settings
result.record_call(
    control_id="support_call_001",
    stereo=True,
    format="mp3",
    direction="both",
    max_length=300  # 5 minutes max
)

# Recording with terminator and status webhook
result.record_call(
    control_id="customer_voicemail", 
    format="wav",
    direction="speak",           # Only record customer voice
    terminators="#",             # Stop on '#' press
    beep=True,                   # Play beep before recording
    initial_timeout=4.0,         # Wait 4 seconds for speech
    end_silence_timeout=3.0,     # Stop after 3 seconds of silence
    status_url="https://api.example.com/recording-status"
)

Core Parameters:

Control Options:

Timing Options:

Webhook Options:

Variables Set:

stop_record_call(control_id=None) 🔗

[HELPER METHOD] - Stop an active background call recording using SWML.

# Stop the most recent recording
result.stop_record_call()

# Stop specific recording by ID
result.stop_record_call("support_call_001")

# Chain to stop recording and provide feedback
result.stop_record_call("customer_voicemail") \
      .say("Thank you, your message has been recorded")

Parameters:

Variables Set:

join_room(name) 🔗

[HELPER METHOD] - Join a RELAY room using SWML.

RELAY rooms enable multi-party communication and collaboration features.

# Join a conference room
result.join_room("support_team_room")

# Join customer meeting room
result.join_room("customer_meeting_001") \
      .say("Welcome to the customer meeting room")

# Join room and set metadata
result.join_room("sales_conference") \
      .set_metadata({"participant_role": "moderator", "join_time": "2024-01-01T12:00:00Z"})

Parameters:

Variables Set:

sip_refer(to_uri) 🔗

[HELPER METHOD] - Send SIP REFER for call transfer using SWML.

SIP REFER is used for call transfer in SIP environments, allowing one endpoint to request another to initiate a new connection.

# Basic SIP refer to transfer call
result.sip_refer("sip:support@company.com")

# Transfer to specific SIP address with domain
result.sip_refer("sip:agent123@pbx.company.com:5060")

# Chain with announcement
result.say("Transferring your call to our specialist") \
      .sip_refer("sip:specialist@company.com")

Parameters:

Variables Set:

join_conference(name, **options) 🔗

[HELPER METHOD] - Join an ad-hoc audio conference with RELAY and CXML calls using SWML.

Provides extensive configuration options for conference call management and recording.

# Simple conference join
result.join_conference("my_conference")

# Basic conference with recording
result.join_conference(
    name="daily_standup",
    record="record-from-start",
    max_participants=10
)

# Advanced conference with callbacks and coaching
result.join_conference(
    name="customer_support_conf", 
    muted=False,
    beep="onEnter",
    start_on_enter=True,
    end_on_exit=False,
    max_participants=50,
    record="record-from-start",
    region="us-east",
    trim="trim-silence",
    status_callback="https://api.company.com/conference-events",
    status_callback_event="start end join leave",
    recording_status_callback="https://api.company.com/recording-events"
)

# Chain with other actions
result.say("Joining you to the team conference") \
      .join_conference("team_meeting") \
      .set_metadata({"meeting_type": "team_sync", "participant_role": "attendee"})

Core Parameters:

Capacity & Region:

Recording Options:

Status & Coaching:

Control Flow:

Variables Set:

tap(uri, **options) 🔗

[HELPER METHOD] - Start background call tap using SWML.

Media is streamed over Websocket or RTP to customer controlled URI for real-time monitoring and analysis.

# Simple WebSocket tap
result.tap("wss://example.com/tap")

# RTP tap with custom settings
result.tap(
    uri="rtp://192.168.1.100:5004",
    control_id="monitoring_tap_001",
    direction="both",
    codec="PCMA",
    rtp_ptime=30
)

# Advanced tap with status callbacks
result.tap(
    uri="wss://monitoring.company.com/audio-stream",
    control_id="compliance_tap",
    direction="speak",  # Only what the party says
    status_url="https://api.company.com/tap-status"
) \
.set_metadata({"tap_purpose": "compliance", "session_id": "sess_123"})

Core Parameters:

Audio Configuration:

Status & Monitoring:

Variables Set:

stop_tap(control_id=None) 🔗

[HELPER METHOD] - Stop an active tap stream using SWML.

# Stop the most recent tap
result.stop_tap()

# Stop specific tap by ID
result.stop_tap("monitoring_tap_001")

# Chain to stop tap and provide feedback
result.stop_tap("compliance_tap") \
      .say("Audio monitoring has been stopped") \
      .update_global_data({"tap_active": False})

Parameters:

Variables Set:

hangup() 🔗

Terminate the call immediately.

result.hangup()

Call Flow Control 🔗

hold(timeout=300) 🔗

Put call on hold with timeout (max 900 seconds).

result.hold(60)    # Hold for 1 minute
result.hold(600)   # Hold for 10 minutes

wait_for_user(enabled=None, timeout=None, answer_first=False) 🔗

Control how agent waits for user input with flexible parameters.

result.wait_for_user(True)                    # Wait indefinitely
result.wait_for_user(timeout=30)              # Wait 30 seconds
result.wait_for_user(answer_first=True)       # Special answer_first mode
result.wait_for_user(False)                   # Disable waiting

stop() 🔗

Stop agent execution completely.

result.stop()

Speech & Audio Control 🔗

say(text) 🔗

Make the agent speak specific text immediately.

result.say("Please hold while I look that up for you")

play_background_audio(filename, wait=False) 🔗

Play audio file in background with attention control.

result.play_background_audio("hold_music.wav")                    # AI tries to get attention
result.play_background_audio("announcement.mp3", wait=True)       # AI suppresses attention

stop_background_audio() 🔗

Stop currently playing background audio.

result.stop_background_audio()

Speech Recognition Settings 🔗

set_end_of_speech_timeout(milliseconds) 🔗

Set silence timeout after speech detection for finalizing recognition.

result.set_end_of_speech_timeout(2000)  # 2 seconds of silence

set_speech_event_timeout(milliseconds) 🔗

Set timeout since last speech event - better for noisy environments.

result.set_speech_event_timeout(3000)  # 3 seconds since last speech event

Data Management 🔗

update_global_data(data) 🔗

[IMPLEMENTED] - Update global agent data variables.

result.update_global_data({"user_name": "John", "step": 2})

remove_global_data(keys) 🔗

Remove global data variables by key(s).

result.remove_global_data("temporary_data")           # Single key
result.remove_global_data(["step", "temp_value"])     # Multiple keys

set_metadata(data) 🔗

Set metadata scoped to current function's meta_data_token.

result.set_metadata({"session_id": "abc123", "user_tier": "premium"})

remove_metadata(keys) 🔗

Remove metadata from current function's scope.

result.remove_metadata("temp_session_data")           # Single key  
result.remove_metadata(["cache_key", "temp_flag"])    # Multiple keys

Function & Behavior Control 🔗

toggle_functions(function_toggles) 🔗

Enable/disable specific SWAIG functions dynamically.

result.toggle_functions([
    {"function": "transfer_call", "active": False},
    {"function": "lookup_info", "active": True}
])

enable_functions_on_timeout(enabled=True) 🔗

Control whether functions can be called on speaker timeout.

result.enable_functions_on_timeout(True)
result.enable_functions_on_timeout(False)

enable_extensive_data(enabled=True) 🔗

Send full data to LLM for this turn only, then use smaller replacement.

result.enable_extensive_data(True)   # Send extensive data this turn
result.enable_extensive_data(False)  # Use normal data

Agent Settings & Configuration 🔗

update_settings(settings) 🔗

Update agent runtime settings with validation.

# AI model settings
result.update_settings({
    "temperature": 0.7,
    "max-tokens": 2048,
    "frequency-penalty": -0.5
})

# Speech recognition settings  
result.update_settings({
    "confidence": 0.8,
    "barge-confidence": 0.7
})

Supported Settings:

switch_context(system_prompt=None, user_prompt=None, consolidate=False, full_reset=False) 🔗

Change agent context/prompt during conversation.

# Simple context switch
result.switch_context("You are now a technical support agent")

# Advanced context switch
result.switch_context(
    system_prompt="You are a billing specialist",
    user_prompt="The user needs help with their invoice",
    consolidate=True
)

simulate_user_input(text) 🔗

Queue simulated user input for testing or flow control.

result.simulate_user_input("Yes, I'd like to speak to billing")

Low-Level Methods 🔗

Manual Action Construction 🔗

add_action(name, data) 🔗

Add a single action manually (for custom actions not covered by helper methods).

result.add_action("custom_action", {"param": "value"})

add_actions(actions) 🔗

Add multiple actions at once.

result.add_actions([
    {"say": "Hello"},
    {"hold": 300}
])

Output Generation 🔗

to_dict() 🔗

Convert result to dictionary format for JSON serialization.

result_dict = result.to_dict()
# Returns: {"response": "...", "action": [...], "post_process": true/false}

Method Chaining 🔗

All methods return self to enable fluent method chaining:

result = SwaigFunctionResult("Processing your request", post_process=True) \
    .update_global_data({"status": "processing"}) \
    .play_background_audio("processing.wav", wait=True) \
    .set_end_of_speech_timeout(2500)

# Complex chaining example
result = SwaigFunctionResult("Let me transfer you to billing") \
    .set_metadata({"transfer_reason": "billing_inquiry"}) \
    .update_global_data({"last_action": "transfer_to_billing"}) \
    .connect("+15551234567", final=True)

Implementation Status 🔗

Best Practices 🔗

  1. Use post_process=True when you want the AI to speak before executing actions
  2. Chain methods for cleaner, more readable code
  3. Use specific methods instead of manual action construction when available
  4. Handle errors gracefully - methods may raise TypeError for invalid inputs
  5. Validate settings - update_settings() relies on server-side validation

Final State 🔗

The framework now includes 10 virtual helpers total: 1. connect() - Call transfer/connect 2. send_sms() - SMS messaging
3. pay() - Payment processing 4. record_call() - Start background recording 5. stop_record_call() - Stop background recording 6. join_room() - Join RELAY room 7. sip_refer() - SIP REFER transfer 8. join_conference() - Join audio conference with extensive options 9. tap() - Start background call tap for monitoring 10. stop_tap() - Stop background call tap