Class: SignalWire::Swaig::FunctionResult

Inherits:
Object
  • Object
show all
Defined in:
lib/signalwire/swaig/function_result.rb

Overview

Response builder that tool handlers return. All mutating methods return self for fluent chaining.

result = FunctionResult.new("Found your order")
  .update_global_data("order_id" => "12345")
  .say("Let me look that up")

The result object has three main components:

1. response     - Text the AI should say back to the user
2. action       - List of structured actions to execute
3. post_process - Whether to let AI take another turn before executing actions

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(response = nil, post_process: false) ⇒ FunctionResult

Returns a new instance of FunctionResult.

Parameters:

  • response (String, nil) (defaults to: nil) —

    text the AI speaks back to the user

  • post_process (Boolean) (defaults to: false) —

    whether to let AI take another turn before executing actions



29
30
31
32
33
 
# File 'lib/signalwire/swaig/function_result.rb', line 29

def initialize(response = nil, post_process: false)
  @response = response || ""
  @action = []
  @post_process = post_process
end

Instance Attribute Details

#action ⇒ Object

Returns the value of attribute action.



25
26
27
 
# File 'lib/signalwire/swaig/function_result.rb', line 25

def action
  @action
end

#post_process ⇒ Object

Returns the value of attribute post_process.



25
26
27
 
# File 'lib/signalwire/swaig/function_result.rb', line 25

def post_process
  @post_process
end

#response ⇒ Object

Returns the value of attribute response.



25
26
27
 
# File 'lib/signalwire/swaig/function_result.rb', line 25

def response
  @response
end

Class Method Details

.create_payment_action(action_type, phrase) ⇒ Hash

Create a payment action for use inside payment prompts.

Parameters:

  • action_type (String) —

    “Say” or “Play”

  • phrase (String)

Returns:

  • (Hash) 


733
734
735
 
# File 'lib/signalwire/swaig/function_result.rb', line 733

def self.create_payment_action(action_type, phrase)
  { "type" => action_type, "phrase" => phrase }
end

.create_payment_parameter(name, value) ⇒ Hash

Create a payment parameter for use with pay.

Parameters:

  • name (String)
  • value (String)

Returns:

  • (Hash) 


742
743
744
 
# File 'lib/signalwire/swaig/function_result.rb', line 742

def self.create_payment_parameter(name, value)
  { "name" => name, "value" => value }
end

.create_payment_prompt(for_situation, actions, card_type: nil, error_type: nil) ⇒ Hash

Create a payment prompt structure for use with pay.

Parameters:

  • for_situation (String) —

    e.g. “payment-card-number”

  • actions (Array<Hash>) —

    actions with “type” and “phrase” keys

  • card_type (String, nil) (defaults to: nil)
  • error_type (String, nil) (defaults to: nil)

Returns:

  • (Hash) 


718
719
720
721
722
723
724
725
726
 
# File 'lib/signalwire/swaig/function_result.rb', line 718

def self.create_payment_prompt(for_situation, actions, card_type: nil, error_type: nil)
  prompt = {
    "for"     => for_situation,
    "actions" => actions
  }
  prompt["card_type"]  = card_type  if card_type
  prompt["error_type"] = error_type if error_type
  prompt
end

Instance Method Details

#add_action(name, data) ⇒ self

Add a single structured action.

Parameters:

  • name (String) —

    action key

  • data (Object) —

    action value

Returns:

  • (self) 


57
58
59
60
 
# File 'lib/signalwire/swaig/function_result.rb', line 57

def add_action(name, data)
  @action << { name => data }
  self
end

#add_actions(actions) ⇒ self

Add multiple structured actions at once.

Parameters:

  • actions (Array<Hash>)

Returns:

  • (self) 


65
66
67
68
 
# File 'lib/signalwire/swaig/function_result.rb', line 65

def add_actions(actions)
  @action.concat(actions)
  self
end

#add_dynamic_hints(hints) ⇒ self

Add dynamic speech recognition hints.

Parameters:

  • hints (Array<String, Hash>)

Returns:

  • (self) 


342
343
344
 
# File 'lib/signalwire/swaig/function_result.rb', line 342

def add_dynamic_hints(hints)
  add_action("add_dynamic_hints", hints)
end

#clear_dynamic_hints ⇒ self

Clear all dynamic speech recognition hints.

Returns:

  • (self) 


348
349
350
351
 
# File 'lib/signalwire/swaig/function_result.rb', line 348

def clear_dynamic_hints
  @action << { "clear_dynamic_hints" => {} }
  self
end

#connect(destination, final: true, from_addr: nil) ⇒ self

Connect / transfer the call to another destination.

Parameters:

  • destination (String) —

    phone number, SIP address, etc.

  • final (Boolean) (defaults to: true) —

    permanent (true) or temporary (false) transfer

  • from_addr (String, nil) (defaults to: nil) —

    optional caller-ID override

Returns:

  • (self) 


80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/signalwire/swaig/function_result.rb', line 80

def connect(destination, final: true, from_addr: nil)
  connect_params = { "to" => destination }
  connect_params["from"] = from_addr if from_addr

  swml_action = {
    "SWML" => {
      "sections" => {
        "main" => [{ "connect" => connect_params }]
      },
      "version" => "1.0.0"
    },
    "transfer" => final.to_s
  }

  @action << swml_action
  self
end

#enable_extensive_data(enabled = true) ⇒ self

Send full data to LLM for this turn only.

Parameters:

  • enabled (Boolean) (defaults to: true)

Returns:

  • (self) 


384
385
386
 
# File 'lib/signalwire/swaig/function_result.rb', line 384

def enable_extensive_data(enabled = true)
  add_action("extensive_data", enabled)
end

#enable_functions_on_timeout(enabled = true) ⇒ self

Enable function calls on speaker timeout.

Parameters:

  • enabled (Boolean) (defaults to: true)

Returns:

  • (self) 


377
378
379
 
# File 'lib/signalwire/swaig/function_result.rb', line 377

def enable_functions_on_timeout(enabled = true)
  add_action("functions_on_speaker_timeout", enabled)
end

#execute_rpc(method, params: nil, call_id: nil, node_id: nil) ⇒ self

Execute a generic RPC method via SWML.

Parameters:

  • method (String) —

    RPC method name

  • params (Hash, nil) (defaults to: nil)
  • call_id (String, nil) (defaults to: nil)
  • node_id (String, nil) (defaults to: nil)

Returns:

  • (self) 


640
641
642
643
644
645
646
647
648
649
650
651
 
# File 'lib/signalwire/swaig/function_result.rb', line 640

def execute_rpc(method, params: nil, call_id: nil, node_id: nil)
  rpc_params = { "method" => method }
  rpc_params["call_id"] = call_id if call_id
  rpc_params["node_id"] = node_id if node_id
  rpc_params["params"]  = params  if params && !params.empty?

  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "execute_rpc" => rpc_params }] }
  }
  execute_swml(swml_doc)
end

#execute_swml(swml_content, transfer: false) ⇒ self

Execute SWML content with optional transfer.

Parameters:

  • swml_content (Hash, String) —

    SWML data structure or JSON string

  • transfer (Boolean) (defaults to: false) —

    whether call should exit agent after execution

Returns:

  • (self) 


404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
 
# File 'lib/signalwire/swaig/function_result.rb', line 404

def execute_swml(swml_content, transfer: false)
  swml_data = case swml_content
              when String
                begin
                  JSON.parse(swml_content)
                rescue JSON::ParserError
                  { "raw_swml" => swml_content }
                end
              when Hash
                swml_content.dup
              else
                if swml_content.respond_to?(:to_h)
                  swml_content.to_h
                else
                  raise TypeError, "swml_content must be a String, Hash, or respond to #to_h"
                end
              end

  swml_data["transfer"] = "true" if transfer
  add_action("SWML", swml_data)
end

#hangup ⇒ self

Terminate the call.

Returns:

  • (self) 


124
125
126
 
# File 'lib/signalwire/swaig/function_result.rb', line 124

def hangup
  add_action("hangup", true)
end

#hold(timeout = 300) ⇒ self

Put the call on hold.

Parameters:

  • timeout (Integer) (defaults to: 300) —

    seconds, clamped to 0..900

Returns:

  • (self) 


131
132
133
134
 
# File 'lib/signalwire/swaig/function_result.rb', line 131

def hold(timeout = 300)
  timeout = [[timeout, 0].max, 900].min
  add_action("hold", timeout)
end

#join_conference(name, muted: false, beep: "true", start_on_enter: true, end_on_exit: false, wait_url: nil, max_participants: 250, record: "do-not-record", region: nil, trim: "trim-silence", coach: nil, status_callback_event: nil, status_callback: nil, status_callback_method: "POST", recording_status_callback: nil, recording_status_callback_method: "POST", recording_status_callback_event: "completed", result: nil) ⇒ self

Join an ad-hoc audio conference via SWML.

Parameters:

  • name (String) —

    conference name (required)

Returns:

  • (self)

Raises:

  • (ArgumentError) 


430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
 
# File 'lib/signalwire/swaig/function_result.rb', line 430

def join_conference(name, muted: false, beep: "true",
                    start_on_enter: true, end_on_exit: false,
                    wait_url: nil, max_participants: 250,
                    record: "do-not-record", region: nil,
                    trim: "trim-silence", coach: nil,
                    status_callback_event: nil, status_callback: nil,
                    status_callback_method: "POST",
                    recording_status_callback: nil,
                    recording_status_callback_method: "POST",
                    recording_status_callback_event: "completed",
                    result: nil)
  raise ArgumentError, "name cannot be empty" if name.to_s.strip.empty?
  raise ArgumentError, "beep must be one of: true, false, onEnter, onExit" unless %w[true false onEnter onExit].include?(beep)
  raise ArgumentError, "max_participants must be 1..250" unless max_participants.between?(1, 250)
  raise ArgumentError, "record must be 'do-not-record' or 'record-from-start'" unless %w[do-not-record record-from-start].include?(record)
  raise ArgumentError, "trim must be 'trim-silence' or 'do-not-trim'" unless %w[trim-silence do-not-trim].include?(trim)

  all_defaults = !muted && beep == "true" && start_on_enter && !end_on_exit &&
                 wait_url.nil? && max_participants == 250 && record == "do-not-record" &&
                 region.nil? && trim == "trim-silence" && coach.nil? &&
                 status_callback_event.nil? && status_callback.nil? &&
                 status_callback_method == "POST" && recording_status_callback.nil? &&
                 recording_status_callback_method == "POST" &&
                 recording_status_callback_event == "completed" && result.nil?

  if all_defaults
    join_params = name
  else
    join_params = { "name" => name }
    join_params["muted"]            = muted            if muted
    join_params["beep"]             = beep             if beep != "true"
    join_params["start_on_enter"]   = start_on_enter   unless start_on_enter
    join_params["end_on_exit"]      = end_on_exit      if end_on_exit
    join_params["wait_url"]         = wait_url         if wait_url
    join_params["max_participants"] = max_participants  if max_participants != 250
    join_params["record"]           = record           if record != "do-not-record"
    join_params["region"]           = region           if region
    join_params["trim"]             = trim             if trim != "trim-silence"
    join_params["coach"]            = coach            if coach
    join_params["status_callback_event"]            = status_callback_event            if status_callback_event
    join_params["status_callback"]                  = status_callback                  if status_callback
    join_params["status_callback_method"]           = status_callback_method           if status_callback_method != "POST"
    join_params["recording_status_callback"]        = recording_status_callback        if recording_status_callback
    join_params["recording_status_callback_method"] = recording_status_callback_method if recording_status_callback_method != "POST"
    join_params["recording_status_callback_event"]  = recording_status_callback_event  if recording_status_callback_event != "completed"
    join_params["result"]                           = result                           if result
  end

  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "join_conference" => join_params }] }
  }
  execute_swml(swml_doc)
end

#join_room(name) ⇒ self

Join a RELAY room via SWML.

Parameters:

  • name (String)

Returns:

  • (self) 


488
489
490
491
492
493
494
 
# File 'lib/signalwire/swaig/function_result.rb', line 488

def join_room(name)
  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "join_room" => { "name" => name } }] }
  }
  execute_swml(swml_doc)
end

#pay(payment_connector_url:, input_method: "dtmf", status_url: nil, payment_method: "credit-card", timeout: 5, max_attempts: 1, security_code: true, postal_code: true, min_postal_code_length: 0, token_type: "reusable", charge_amount: nil, currency: "usd", language: "en-US", voice: "woman", description: nil, valid_card_types: "visa mastercard amex", parameters: nil, prompts: nil, ai_response: 'The payment status is ${pay_result}, do not mention anything else about collecting payment if successful.') ⇒ self

Process payment using SWML pay action.

Parameters:

  • payment_connector_url (String) —

    URL to make payment requests to

  • input_method (String) (defaults to: "dtmf") —

    “dtmf” or “voice”

Returns:

  • (self) 


586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
 
# File 'lib/signalwire/swaig/function_result.rb', line 586

def pay(payment_connector_url:, input_method: "dtmf",
        status_url: nil, payment_method: "credit-card",
        timeout: 5, max_attempts: 1, security_code: true,
        postal_code: true, min_postal_code_length: 0,
        token_type: "reusable", charge_amount: nil,
        currency: "usd", language: "en-US", voice: "woman",
        description: nil, valid_card_types: "visa mastercard amex",
        parameters: nil, prompts: nil,
        ai_response: 'The payment status is ${pay_result}, do not mention anything else about collecting payment if successful.')
  pay_params = {
    "payment_connector_url"  => payment_connector_url,
    "input"                  => input_method,
    "payment_method"         => payment_method,
    "timeout"                => timeout.to_s,
    "max_attempts"           => max_attempts.to_s,
    "security_code"          => security_code.to_s,
    "min_postal_code_length" => min_postal_code_length.to_s,
    "token_type"             => token_type,
    "currency"               => currency,
    "language"               => language,
    "voice"                  => voice,
    "valid_card_types"       => valid_card_types
  }

  pay_params["postal_code"]    = postal_code.is_a?(String) ? postal_code : postal_code.to_s
  pay_params["status_url"]     = status_url     if status_url
  pay_params["charge_amount"]  = charge_amount  if charge_amount
  pay_params["description"]    = description    if description
  pay_params["parameters"]     = parameters     if parameters
  pay_params["prompts"]        = prompts        if prompts

  swml_doc = {
    "version"  => "1.0.0",
    "sections" => {
      "main" => [
        { "set" => { "ai_response" => ai_response } },
        { "pay" => pay_params }
      ]
    }
  }
  execute_swml(swml_doc)
end

#play_background_file(filename, wait: false) ⇒ self

Play audio/video file in the background.

Parameters:

  • filename (String) —

    audio/video filename or URL

  • wait (Boolean) (defaults to: false) —

    suppress attention-getting behaviour during playback

Returns:

  • (self) 


272
273
274
275
276
277
278
 
# File 'lib/signalwire/swaig/function_result.rb', line 272

def play_background_file(filename, wait: false)
  if wait
    add_action("playback_bg", { "file" => filename, "wait" => true })
  else
    add_action("playback_bg", filename)
  end
end

#record_call(control_id: nil, stereo: false, format: "wav", direction: "both", terminators: nil, beep: false, input_sensitivity: 44.0, initial_timeout: nil, end_silence_timeout: nil, max_length: nil, status_url: nil) ⇒ self

Start background call recording via SWML.

Parameters:

  • control_id (String, nil) (defaults to: nil)
  • stereo (Boolean) (defaults to: false)
  • format (String) (defaults to: "wav") —

    “wav” or “mp3”

  • direction (String) (defaults to: "both") —

    “speak”, “listen”, or “both”

Returns:

  • (self)

Raises:

  • (ArgumentError) 


293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/signalwire/swaig/function_result.rb', line 293

def record_call(control_id: nil, stereo: false, format: "wav",
                direction: "both", terminators: nil, beep: false,
                input_sensitivity: 44.0, initial_timeout: nil,
                end_silence_timeout: nil, max_length: nil, status_url: nil)
  raise ArgumentError, "format must be 'wav' or 'mp3'" unless %w[wav mp3].include?(format)
  raise ArgumentError, "direction must be 'speak', 'listen', or 'both'" unless %w[speak listen both].include?(direction)

  record_params = {
    "stereo"            => stereo,
    "format"            => format,
    "direction"         => direction,
    "beep"              => beep,
    "input_sensitivity" => input_sensitivity
  }
  record_params["control_id"]          = control_id          if control_id
  record_params["terminators"]         = terminators         if terminators
  record_params["initial_timeout"]     = initial_timeout     if initial_timeout
  record_params["end_silence_timeout"] = end_silence_timeout if end_silence_timeout
  record_params["max_length"]          = max_length          if max_length
  record_params["status_url"]          = status_url          if status_url

  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "record_call" => record_params }] }
  }
  execute_swml(swml_doc)
end

#remove_global_data(keys) ⇒ self

Remove global agent data variables.

Parameters:

  • keys (String, Array<String>) —

    key(s) to remove

Returns:

  • (self) 


175
176
177
 
# File 'lib/signalwire/swaig/function_result.rb', line 175

def remove_global_data(keys)
  add_action("unset_global_data", keys)
end

#remove_metadata(keys) ⇒ self

Remove metadata from current function’s scope.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (self) 


189
190
191
 
# File 'lib/signalwire/swaig/function_result.rb', line 189

def remove_metadata(keys)
  add_action("unset_meta_data", keys)
end

#replace_in_history(text = true) ⇒ self

Replace the tool_call + result pair in conversation history.

Parameters:

  • text (String, true) (defaults to: true) —

    replacement text, or true to remove entirely

Returns:

  • (self) 


252
253
254
 
# File 'lib/signalwire/swaig/function_result.rb', line 252

def replace_in_history(text = true)
  add_action("replace_in_history", text)
end

#rpc_ai_message(call_id, message_text, role: "system") ⇒ self

Inject a message into an AI agent on another call.

Parameters:

  • call_id (String)
  • message_text (String)
  • role (String) (defaults to: "system")

Returns:

  • (self) 


682
683
684
685
686
687
688
689
690
691
 
# File 'lib/signalwire/swaig/function_result.rb', line 682

def rpc_ai_message(call_id, message_text, role: "system")
  execute_rpc(
    "ai_message",
    call_id: call_id,
    params: {
      "role"         => role,
      "message_text" => message_text
    }
  )
end

#rpc_ai_unhold(call_id) ⇒ self

Unhold another call via RPC.

Parameters:

  • call_id (String)

Returns:

  • (self) 


696
697
698
 
# File 'lib/signalwire/swaig/function_result.rb', line 696

def rpc_ai_unhold(call_id)
  execute_rpc("ai_unhold", call_id: call_id, params: {})
end

#rpc_dial(to_number:, from_number:, dest_swml:, device_type: "phone") ⇒ self

Dial out to a number via RPC.

Parameters:

  • to_number (String) —

    E.164 phone number

  • from_number (String) —

    E.164 caller ID

  • dest_swml (String) —

    SWML URL for the outbound leg

  • device_type (String) (defaults to: "phone")

Returns:

  • (self) 


660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
 
# File 'lib/signalwire/swaig/function_result.rb', line 660

def rpc_dial(to_number:, from_number:, dest_swml:, device_type: "phone")
  execute_rpc(
    "dial",
    params: {
      "devices" => {
        "type"   => device_type,
        "params" => {
          "to_number"   => to_number,
          "from_number" => from_number
        }
      },
      "dest_swml" => dest_swml
    }
  )
end

#say(text) ⇒ self

Make the agent speak specific text.

Parameters:

  • text (String)

Returns:

  • (self) 


263
264
265
 
# File 'lib/signalwire/swaig/function_result.rb', line 263

def say(text)
  add_action("say", text)
end

#send_sms(to_number:, from_number:, body: nil, media: nil, tags: nil, region: nil) ⇒ self

Send an SMS message via SWML.

Parameters:

  • to_number (String) —

    E.164 phone number

  • from_number (String) —

    E.164 phone number

  • body (String, nil) (defaults to: nil)
  • media (Array<String>, nil) (defaults to: nil)
  • tags (Array<String>, nil) (defaults to: nil)
  • region (String, nil) (defaults to: nil)

Returns:

  • (self)

Raises:

  • (ArgumentError) 


559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
 
# File 'lib/signalwire/swaig/function_result.rb', line 559

def send_sms(to_number:, from_number:, body: nil, media: nil,
             tags: nil, region: nil)
  body_empty = body.nil? || (body.respond_to?(:empty?) && body.empty?)
  media_empty = media.nil? || (media.respond_to?(:empty?) && media.empty?)
  raise ArgumentError, "Either body or media must be provided" if body_empty && media_empty

  sms_params = {
    "to_number"   => to_number,
    "from_number" => from_number
  }
  sms_params["body"]   = body   if body && !(body.respond_to?(:empty?) && body.empty?)
  sms_params["media"]  = media  if media && !(media.respond_to?(:empty?) && media.empty?)
  sms_params["tags"]   = tags   if tags && !(tags.respond_to?(:empty?) && tags.empty?)
  sms_params["region"] = region if region

  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "send_sms" => sms_params }] }
  }
  execute_swml(swml_doc)
end

#set_end_of_speech_timeout(milliseconds) ⇒ self

Adjust end-of-speech timeout.

Parameters:

  • milliseconds (Integer)

Returns:

  • (self) 


356
357
358
 
# File 'lib/signalwire/swaig/function_result.rb', line 356

def set_end_of_speech_timeout(milliseconds)
  add_action("end_of_speech_timeout", milliseconds)
end

#set_metadata(data) ⇒ self

Set metadata scoped to current function’s meta_data_token.

Parameters:

  • data (Hash)

Returns:

  • (self) 


182
183
184
 
# File 'lib/signalwire/swaig/function_result.rb', line 182

def set_metadata(data)
  add_action("set_meta_data", data)
end

#set_post_process(val) ⇒ self

Enable / disable post-processing.

Returns:

  • (self) 


48
49
50
51
 
# File 'lib/signalwire/swaig/function_result.rb', line 48

def set_post_process(val)
  @post_process = val
  self
end

#set_response(text) ⇒ self

Set the natural-language response text.

Returns:

  • (self) 


41
42
43
44
 
# File 'lib/signalwire/swaig/function_result.rb', line 41

def set_response(text)
  @response = text
  self
end

#set_speech_event_timeout(milliseconds) ⇒ self

Adjust speech event timeout.

Parameters:

  • milliseconds (Integer)

Returns:

  • (self) 


363
364
365
 
# File 'lib/signalwire/swaig/function_result.rb', line 363

def set_speech_event_timeout(milliseconds)
  add_action("speech_event_timeout", milliseconds)
end

#simulate_user_input(text) ⇒ self

Queue simulated user input.

Parameters:

  • text (String)

Returns:

  • (self) 


703
704
705
 
# File 'lib/signalwire/swaig/function_result.rb', line 703

def simulate_user_input(text)
  add_action("user_input", text)
end

#sip_refer(to_uri) ⇒ self

Send SIP REFER via SWML.

Parameters:

  • to_uri (String)

Returns:

  • (self) 


499
500
501
502
503
504
505
 
# File 'lib/signalwire/swaig/function_result.rb', line 499

def sip_refer(to_uri)
  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "sip_refer" => { "to_uri" => to_uri } }] }
  }
  execute_swml(swml_doc)
end

#stop ⇒ self

Stop agent execution.

Returns:

  • (self) 


157
158
159
 
# File 'lib/signalwire/swaig/function_result.rb', line 157

def stop
  add_action("stop", true)
end

#stop_background_file ⇒ self

Stop currently playing background file.

Returns:

  • (self) 


282
283
284
 
# File 'lib/signalwire/swaig/function_result.rb', line 282

def stop_background_file
  add_action("stop_playback_bg", true)
end

#stop_record_call(control_id: nil) ⇒ self

Stop an active background call recording.

Parameters:

  • control_id (String, nil) (defaults to: nil)

Returns:

  • (self) 


324
325
326
327
328
329
330
331
332
333
 
# File 'lib/signalwire/swaig/function_result.rb', line 324

def stop_record_call(control_id: nil)
  stop_params = {}
  stop_params["control_id"] = control_id if control_id

  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "stop_record_call" => stop_params }] }
  }
  execute_swml(swml_doc)
end

#stop_tap(control_id: nil) ⇒ self

Stop an active tap stream via SWML.

Parameters:

  • control_id (String, nil) (defaults to: nil)

Returns:

  • (self) 


539
540
541
542
543
544
545
546
547
548
 
# File 'lib/signalwire/swaig/function_result.rb', line 539

def stop_tap(control_id: nil)
  stop_params = {}
  stop_params["control_id"] = control_id if control_id

  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "stop_tap" => stop_params }] }
  }
  execute_swml(swml_doc)
end

#switch_context(system_prompt: nil, user_prompt: nil, consolidate: false, full_reset: false, isolated: false) ⇒ self

Switch agent context/prompt during conversation.

When only system_prompt is provided and all flags are false, emits a simple string context switch. Otherwise emits the full object form.

Parameters:

  • system_prompt (String, nil) (defaults to: nil)
  • user_prompt (String, nil) (defaults to: nil)
  • consolidate (Boolean) (defaults to: false)
  • full_reset (Boolean) (defaults to: false)
  • isolated (Boolean) (defaults to: false)

Returns:

  • (self) 


233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/signalwire/swaig/function_result.rb', line 233

def switch_context(system_prompt: nil, user_prompt: nil,
                   consolidate: false, full_reset: false, isolated: false)
  if system_prompt && !user_prompt && !consolidate && !full_reset && !isolated
    return add_action("context_switch", system_prompt)
  end

  context_data = {}
  context_data["system_prompt"] = system_prompt if system_prompt
  context_data["user_prompt"]   = user_prompt   if user_prompt
  context_data["consolidate"]   = true           if consolidate
  context_data["full_reset"]    = true           if full_reset
  context_data["isolated"]      = true           if isolated
  add_action("context_switch", context_data)
end

#swml_change_context(context_name) ⇒ self

Change the conversation context.

Parameters:

  • context_name (String)

Returns:

  • (self) 


218
219
220
 
# File 'lib/signalwire/swaig/function_result.rb', line 218

def swml_change_context(context_name)
  add_action("change_context", context_name)
end

#swml_change_step(step_name) ⇒ self

Change the conversation step.

Parameters:

  • step_name (String)

Returns:

  • (self) 


211
212
213
 
# File 'lib/signalwire/swaig/function_result.rb', line 211

def swml_change_step(step_name)
  add_action("change_step", step_name)
end

#swml_transfer(dest, ai_response, final: true) ⇒ self

Transfer via SWML with an AI response when transfer completes.

Parameters:

  • dest (String) —

    destination URL for the transfer

  • ai_response (String) —

    message AI says when transfer completes

  • final (Boolean) (defaults to: true) —

    permanent or temporary transfer

Returns:

  • (self) 


104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/signalwire/swaig/function_result.rb', line 104

def swml_transfer(dest, ai_response, final: true)
  swml_action = {
    "SWML" => {
      "version" => "1.0.0",
      "sections" => {
        "main" => [
          { "set" => { "ai_response" => ai_response } },
          { "transfer" => { "dest" => dest } }
        ]
      }
    },
    "transfer" => final.to_s
  }

  @action << swml_action
  self
end

#swml_user_event(event_data) ⇒ self

Send a user event through SWML.

Parameters:

  • event_data (Hash) —

    event payload

Returns:

  • (self) 


196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/signalwire/swaig/function_result.rb', line 196

def swml_user_event(event_data)
  swml_action = {
    "sections" => {
      "main" => [{
        "user_event" => { "event" => event_data }
      }]
    },
    "version" => "1.0.0"
  }
  add_action("SWML", swml_action)
end

#tap(uri, control_id: nil, direction: "both", codec: "PCMU", rtp_ptime: 20, status_url: nil) ⇒ self

Start a background call tap via SWML.

Parameters:

  • uri (String) —

    destination URI (rtp://, ws://, wss://)

  • control_id (String, nil) (defaults to: nil)
  • direction (String) (defaults to: "both") —

    “speak”, “hear”, or “both”

  • codec (String) (defaults to: "PCMU") —

    “PCMU” or “PCMA”

  • rtp_ptime (Integer) (defaults to: 20) —

    packetization time in ms

  • status_url (String, nil) (defaults to: nil)

Returns:

  • (self)

Raises:

  • (ArgumentError) 


516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
 
# File 'lib/signalwire/swaig/function_result.rb', line 516

def tap(uri, control_id: nil, direction: "both", codec: "PCMU",
        rtp_ptime: 20, status_url: nil)
  raise ArgumentError, "direction must be 'speak', 'hear', or 'both'" unless %w[speak hear both].include?(direction)
  raise ArgumentError, "codec must be 'PCMU' or 'PCMA'" unless %w[PCMU PCMA].include?(codec)
  raise ArgumentError, "rtp_ptime must be positive" unless rtp_ptime.positive?

  tap_params = { "uri" => uri }
  tap_params["control_id"] = control_id if control_id
  tap_params["direction"]  = direction  if direction != "both"
  tap_params["codec"]      = codec      if codec != "PCMU"
  tap_params["rtp_ptime"]  = rtp_ptime  if rtp_ptime != 20
  tap_params["status_url"] = status_url if status_url

  swml_doc = {
    "version"  => "1.0.0",
    "sections" => { "main" => [{ "tap" => tap_params }] }
  }
  execute_swml(swml_doc)
end

#to_h ⇒ Hash

Convert to the Hash structure expected by SWAIG.

Rules:

  • response always included (string)

  • action only included if at least one action exists

  • post_process only included if true and actions exist

Returns:

  • (Hash) 


758
759
760
761
762
763
764
765
766
767
768
769
 
# File 'lib/signalwire/swaig/function_result.rb', line 758

def to_h
  result = {}

  result["response"] = @response if @response && !@response.empty?
  result["action"]   = @action   if @action && !@action.empty?
  result["post_process"] = true   if @post_process && @action && !@action.empty?

  # Ensure at least one of response or action is present
  result["response"] = "Action completed." if result.empty?

  result
end

#to_json(*args) ⇒ String

Returns JSON representation.

Returns:

  • (String) —

    JSON representation



772
773
774
 
# File 'lib/signalwire/swaig/function_result.rb', line 772

def to_json(*args)
  to_h.to_json(*args)
end

#toggle_functions(toggles) ⇒ self

Enable / disable specific SWAIG functions.

Parameters:

  • toggles (Array<Hash>) —

    each with “function” and “active” keys

Returns:

  • (self) 


370
371
372
 
# File 'lib/signalwire/swaig/function_result.rb', line 370

def toggle_functions(toggles)
  add_action("toggle_functions", toggles)
end

#update_global_data(data) ⇒ self

Update global agent data variables.

Parameters:

  • data (Hash) —

    key-value pairs to set/update

Returns:

  • (self) 


168
169
170
 
# File 'lib/signalwire/swaig/function_result.rb', line 168

def update_global_data(data)
  add_action("set_global_data", data)
end

#update_settings(settings) ⇒ self

Update agent runtime settings (temperature, top_p, etc.).

Parameters:

  • settings (Hash)

Returns:

  • (self) 


391
392
393
 
# File 'lib/signalwire/swaig/function_result.rb', line 391

def update_settings(settings)
  add_action("settings", settings)
end

#wait_for_user(enabled: nil, timeout: nil, answer_first: false) ⇒ self

Control how the agent waits for user input.

Parameters:

  • enabled (Boolean, nil) (defaults to: nil) —

    enable/disable waiting

  • timeout (Integer, nil) (defaults to: nil) —

    seconds to wait

  • answer_first (Boolean) (defaults to: false) —

    special “answer_first” mode

Returns:

  • (self) 


142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/signalwire/swaig/function_result.rb', line 142

def wait_for_user(enabled: nil, timeout: nil, answer_first: false)
  wait_value = if answer_first
                 "answer_first"
               elsif timeout
                 timeout
               elsif !enabled.nil?
                 enabled
               else
                 true
               end
  add_action("wait_for_user", wait_value)
end