SWAIG Functions

Results Actions

View as MarkdownOpen in Claude

Results & Actions

SwaigFunctionResult is the return type for all SWAIG functions. It contains response text for the AI to speak and optional actions like transfers, SMS, or context changes.

Basic Results

Return a simple response:

1from signalwire_agents import SwaigFunctionResult
2
3
4def check_order(self, args, raw_data):
5    order_number = args.get("order_number")
6    return SwaigFunctionResult(f"Order {order_number} shipped yesterday")

SwaigFunctionResult Components

ComponentDescription
responseText the AI will speak to the caller
actionList of actions to execute (transfers, SMS, context changes, etc.)
post_processIf True, AI speaks once more before actions execute (useful for confirmations)

Method Chaining

SwaigFunctionResult methods return self for chaining:

1def transfer_to_support(self, args, raw_data):
2    department = args.get("department", "support")
3
4    return (
5        SwaigFunctionResult("I'll transfer you now")
6        .connect("+15551234567", final=True)
7    )

Call Transfer

Transfer to another number:

1def transfer_call(self, args, raw_data):
2    department = args.get("department")
3
4    numbers = {
5        "sales": "+15551111111",
6        "support": "+15552222222",
7        "billing": "+15553333333"
8    }
9
10    dest = numbers.get(department, "+15550000000")
11
12    return (
13        SwaigFunctionResult(f"Transferring you to {department}")
14        .connect(dest, final=True)
15    )

Transfer options:

1## Permanent transfer - call leaves agent completely
2.connect("+15551234567", final=True)
3
4## Temporary transfer - returns to agent if far end hangs up
5.connect("+15551234567", final=False)
6
7## With custom caller ID
8.connect("+15551234567", final=True, from_addr="+15559876543")
9
10## Transfer to SIP address
11.connect("support@company.com", final=True)

SIP REFER transfer:

Use SIP REFER for attended transfers:

1def transfer_to_extension(self, args, raw_data):
2    extension = args.get("extension")
3
4    return (
5        SwaigFunctionResult(f"Transferring to extension {extension}")
6        .sip_refer(f"sip:{extension}@pbx.example.com")
7    )

SWML-specific transfer:

Transfer with AI response for context handoff:

1def transfer_with_context(self, args, raw_data):
2    department = args.get("department")
3
4    return (
5        SwaigFunctionResult("Let me connect you")
6        .swml_transfer(
7            dest="+15551234567",
8            ai_response=f"Customer needs help with {department}",
9            final=True
10        )
11    )

Send SMS

Send a text message during the call:

1def send_confirmation(self, args, raw_data):
2    phone = args.get("phone_number")
3    order_id = args.get("order_id")
4
5    return (
6        SwaigFunctionResult("I've sent you a confirmation text")
7        .send_sms(
8            to_number=phone,
9            from_number="+15559876543",
10            body=f"Your order {order_id} has been confirmed!"
11        )
12    )

SMS with media:

1def send_receipt(self, args, raw_data):
2    phone = args.get("phone_number")
3    receipt_url = args.get("receipt_url")
4
5    return (
6        SwaigFunctionResult("I've sent your receipt")
7        .send_sms(
8            to_number=phone,
9            from_number="+15559876543",
10            body="Here's your receipt:",
11            media=[receipt_url]
12        )
13    )

Payment Processing

Process credit card payments during the call:

1def collect_payment(self, args, raw_data):
2    amount = args.get("amount")
3    description = args.get("description", "Purchase")
4
5    return (
6        SwaigFunctionResult("I'll collect your payment information now")
7        .pay(
8            payment_connector_url="https://api.example.com/payment",
9            charge_amount=amount,
10            description=description,
11            input_method="dtmf",
12            security_code=True,
13            postal_code=True
14        )
15    )

Payment with custom prompts:

1def subscription_payment(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Let's set up your monthly subscription")
4        .pay(
5            payment_connector_url="https://api.example.com/subscribe",
6            charge_amount="29.99",
7            description="Monthly Subscription",
8            token_type="reusable",
9            prompts=[
10                {
11                    "say": "Please enter your credit card number",
12                    "type": "card_number"
13                },
14                {
15                    "say": "Enter the expiration month and year",
16                    "type": "expiration"
17                }
18            ]
19        )
20    )

Call Recording

Start and stop call recording:

1def start_recording(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Starting call recording")
4        .record_call(
5            control_id="my_recording",
6            stereo=True,
7            format="mp3",
8            direction="both"
9        )
10    )
11
12
13def stop_recording(self, args, raw_data):
14    return (
15        SwaigFunctionResult("Recording stopped")
16        .stop_record_call(control_id="my_recording")
17    )

Record with auto-stop:

1def record_with_timeout(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Recording your message")
4        .record_call(
5            control_id="voicemail",
6            max_length=120.0,  # Stop after 2 minutes
7            end_silence_timeout=3.0,  # Stop after 3s silence
8            beep=True
9        )
10    )

Audio Tapping

Tap audio to external endpoint for monitoring or transcription. Supports WebSocket (wss://) or RTP (rtp://) URIs:

WebSocket tap:

1def start_websocket_monitoring(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Call monitoring started")
4        .tap(
5            uri="wss://monitor.example.com/audio",
6            control_id="supervisor_tap",
7            direction="both",
8            codec="PCMU"
9        )
10    )

RTP tap:

1def start_rtp_tap(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Recording to RTP endpoint")
4        .tap(
5            uri="rtp://192.168.1.100:5004",
6            control_id="rtp_tap",
7            direction="both",
8            codec="PCMU",
9            rtp_ptime=20
10        )
11    )
12
13
14def stop_monitoring(self, args, raw_data):
15    return (
16        SwaigFunctionResult("Monitoring stopped")
17        .stop_tap(control_id="supervisor_tap")
18    )

Call Control

Hold:

Put caller on hold:

1def hold_for_agent(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Please hold while I find an available agent")
4        .hold(timeout=60)  # Hold for up to 60 seconds
5    )

Hang Up

End the call:

1def end_call(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Thank you for calling. Goodbye!")
4        .hangup()
5    )

Speech Control

Direct speech with .say():

Make the AI speak specific text immediately:

1def announce_status(self, args, raw_data):
2    order_status = args.get("status")
3
4    return (
5        SwaigFunctionResult()
6        .say(f"Your order status is: {order_status}")
7    )

Stop AI from speaking:

1def interrupt_speech(self, args, raw_data):
2    return (
3        SwaigFunctionResult()
4        .stop()  # Immediately stop AI speech
5        .say("Let me start over")
6    )

Wait for user input:

Pause and wait for the user to speak:

1def wait_for_confirmation(self, args, raw_data):
2    return (
3        SwaigFunctionResult("I'll wait for your response")
4        .wait_for_user(enabled=True, timeout=10)
5    )

Simulate user input:

Inject text as if the user spoke it:

1def auto_confirm(self, args, raw_data):
2    return (
3        SwaigFunctionResult()
4        .simulate_user_input("yes, I confirm")
5    )

Background Audio

Play audio files in the background during conversation:

1def play_hold_music(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Please hold")
4        .play_background_file(
5            filename="https://example.com/hold-music.mp3",
6            wait=False
7        )
8    )
9
10
11def stop_hold_music(self, args, raw_data):
12    return (
13        SwaigFunctionResult("I'm back")
14        .stop_background_file()
15    )

Update Global Data

Store data accessible throughout the call:

1def save_customer_info(self, args, raw_data):
2    customer_id = args.get("customer_id")
3    customer_name = args.get("name")
4
5    return (
6        SwaigFunctionResult(f"I've noted your information, {customer_name}")
7        .update_global_data({
8            "customer_id": customer_id,
9            "customer_name": customer_name,
10            "verified": True
11        })
12    )

Remove global data:

1def clear_session_data(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Session data cleared")
4        .remove_global_data(["customer_id", "verified"])
5    )

Metadata Management

Store function-specific metadata (separate from global data):

1def track_function_usage(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Usage tracked")
4        .set_metadata({
5            "function_called": "check_order",
6            "timestamp": "2024-01-15T10:30:00Z",
7            "user_id": args.get("user_id")
8        })
9    )

Remove metadata:

1def clear_function_metadata(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Metadata cleared")
4        .remove_metadata(["timestamp", "user_id"])
5    )

Context Switching

Advanced context switch:

Change the agent’s prompt/context with new system and user prompts:

1def switch_to_technical(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Switching to technical support mode")
4        .switch_context(
5            system_prompt="You are now a technical support specialist. "
6                         "Help the customer with their technical issue.",
7            user_prompt="The customer needs help with their account"
8        )
9    )

SWML context switch:

Switch to a named SWML context:

1def switch_to_billing(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Let me connect you with billing")
4        .swml_change_context("billing_context")
5    )

SWML step change:

Change to a specific workflow step:

1def move_to_checkout(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Moving to checkout")
4        .swml_change_step("checkout_step")
5    )

Function Control

Dynamically enable or disable functions during the call:

1def enable_payment_functions(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Payment functions are now available")
4        .toggle_functions([
5            {"function": "collect_payment", "active": True},
6            {"function": "refund_payment", "active": True},
7            {"function": "check_balance", "active": False}
8        ])
9    )

Enable functions on timeout:

1def enable_escalation_on_timeout(self, args, raw_data):
2    return (
3        SwaigFunctionResult("I'll help you with that")
4        .enable_functions_on_timeout(enabled=True)
5    )

Update AI settings:

1def adjust_speech_timing(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Adjusting response timing")
4        .update_settings({
5            "end_of_speech_timeout": 1000,
6            "attention_timeout": 30000
7        })
8    )

Set speech timeouts:

1def configure_timeouts(self, args, raw_data):
2    return (
3        SwaigFunctionResult()
4        .set_end_of_speech_timeout(800)  # 800ms
5        .set_speech_event_timeout(5000)  # 5s
6    )

Conference & Rooms

Join a conference:

1def join_team_conference(self, args, raw_data):
2    conf_name = args.get("conference_name")
3
4    return (
5        SwaigFunctionResult(f"Joining {conf_name}")
6        .join_conference(
7            name=conf_name,
8            muted=False,
9            beep="true",
10            start_conference_on_enter=True
11        )
12    )

Join a SignalWire room:

1def join_support_room(self, args, raw_data):
2    return (
3        SwaigFunctionResult("Connecting to support room")
4        .join_room(name="support-room-1")
5    )

Post-Processing

Let AI speak once more before executing actions:

1def transfer_with_confirmation(self, args, raw_data):
2    return (
3        SwaigFunctionResult(
4            "I'll transfer you to billing. Is there anything else first?",
5            post_process=True  # AI can respond to follow-up before transfer
6        )
7        .connect("+15551234567", final=True)
8    )

Multiple Actions

Chain multiple actions together:

1def complete_interaction(self, args, raw_data):
2    customer_phone = args.get("phone")
3
4    return (
5        SwaigFunctionResult("I've completed your request")
6        .update_global_data({"interaction_complete": True})
7        .send_sms(
8            to_number=customer_phone,
9            from_number="+15559876543",
10            body="Thank you for calling!"
11        )
12    )

Action Execution Order and Interactions

When chaining multiple actions, understanding how they interact is important.

Execution Order

Actions execute in the order they’re added to the SwaigFunctionResult. The response text is processed first, then actions execute sequentially.

1# These execute in order: 1, 2, 3
2return (
3    SwaigFunctionResult("Starting process")
4    .update_global_data({"step": 1})      # 1st
5    .send_sms(to_number=phone, ...)       # 2nd
6    .update_global_data({"step": 2})      # 3rd
7)

Terminal Actions

Some actions end the call or AI session. Once a terminal action executes, subsequent actions may not run:

Terminal actions:

  • .connect(final=True) - Transfers call away permanently
  • .hangup() - Ends the call
  • .swml_transfer(final=True) - Transfers to another SWML endpoint

Non-terminal actions:

  • .update_global_data() - Continues normally
  • .send_sms() - Continues normally
  • .say() - Continues normally
  • .connect(final=False) - Returns to agent if far end hangs up

Best practice: Put terminal actions last in the chain.

1# Good - data saved before transfer
2return (
3    SwaigFunctionResult("Transferring you now")
4    .update_global_data({"transferred": True})  # Executes
5    .send_sms(to_number=phone, body="...")      # Executes
6    .connect("+15551234567", final=True)        # Terminal
7)
8
9# Risky - SMS might not send
10return (
11    SwaigFunctionResult("Transferring you now")
12    .connect("+15551234567", final=True)        # Terminal - call leaves
13    .send_sms(to_number=phone, body="...")      # May not execute
14)

Conflicting Actions

Some action combinations don’t make sense together:

CombinationResult
Multiple .connect()Last one wins
.hangup() then .connect()Hangup executes, connect ignored
.connect(final=True) then .say()Say won’t execute (call transferred)
Multiple .update_global_data()Merged (later keys overwrite earlier)
Multiple .send_sms()All execute (multiple SMS sent)

Using post_process with Actions

When post_process=True, the AI speaks the response and can respond to follow-up before actions execute:

1return (
2    SwaigFunctionResult(
3        "I'll transfer you. Anything else first?",
4        post_process=True  # AI waits for response
5    )
6    .connect("+15551234567", final=True)  # Executes after AI finishes
7)

This is useful for:

  • Confirming before transfers
  • Last-chance questions before hangup
  • Warning before destructive actions

Action Timing Considerations

Immediate actions execute as soon as the function returns:

  • .update_global_data()
  • .toggle_functions()

Speech actions execute during AI’s turn:

  • .say()
  • .stop()

Call control actions affect the call flow:

  • .connect() - Immediate transfer
  • .hangup() - Immediate disconnect
  • .hold() - Immediate hold

External actions may have latency:

  • .send_sms() - Network delay possible
  • .record_call() - Recording starts immediately but storage is async

Advanced: Execute Raw SWML

For advanced use cases, execute raw SWML documents directly:

1def execute_custom_swml(self, args, raw_data):
2    swml_doc = {
3        "version": "1.0.0",
4        "sections": {
5            "main": [
6                {"play": {"url": "https://example.com/announcement.mp3"}},
7                {"hangup": {}}
8            ]
9        }
10    }
11
12    return (
13        SwaigFunctionResult()
14        .execute_swml(swml_doc, transfer=False)
15    )

Note: Most use cases are covered by the convenience methods above. Use execute_swml() only when you need SWML features not available through other action methods.

Action Reference

Call Control Actions

MethodDescription
.connect(dest, final, from_addr)Transfer call to another number or SIP URI
.swml_transfer(dest, ai_response, final)SWML-specific transfer with AI response
.sip_refer(to_uri)SIP REFER transfer
.hangup()End the call
.hold(timeout)Put caller on hold (default 300s, max 900s)
.send_sms(to, from, body, media)Send SMS message
.record_call(control_id, stereo, ...)Start call recording
.stop_record_call(control_id)Stop call recording
.tap(uri, control_id, direction, ...)Tap call audio to external URI
.stop_tap(control_id)Stop call tapping
.pay(payment_connector_url, ...)Process payment
.execute_swml(doc, transfer)Execute raw SWML document
.join_room(name)Join a SignalWire room
.join_conference(name, muted, ...)Join a conference

Speech & Audio Actions

MethodDescription
.say(text)Have AI speak specific text
.stop()Stop AI from speaking
.play_background_file(url, wait)Play background audio
.stop_background_file()Stop background audio
.simulate_user_input(text)Inject text as user speech
.wait_for_user(enabled, timeout, answer_first)Wait for user to speak

Context & Workflow Actions

MethodDescription
.switch_context(system_prompt, user_prompt)Advanced context switch with new prompts
.swml_change_context(ctx)Switch to named context
.swml_change_step(step)Change to specific workflow step

Data Management Actions

MethodDescription
.update_global_data(data)Set global session data
.remove_global_data(keys)Remove keys from global data
.set_metadata(data)Set function-specific metadata
.remove_metadata(keys)Remove function metadata keys

AI Behavior Actions

MethodDescription
.toggle_functions(funcs)Enable/disable specific functions
.enable_functions_on_timeout(enabled)Enable functions when timeout occurs
.update_settings(config)Modify AI settings dynamically
.set_end_of_speech_timeout(ms)Adjust speech timeout
.set_speech_event_timeout(ms)Adjust speech event timeout
.enable_extensive_data(enabled)Enable extended data in webhooks

Events

MethodDescription
.swml_user_event(data)Fire custom user event