---sidebar_label: Statements and Methods---# SWML Statements and Methodsimport Tabs from @theme/Tabs;import TabItem from @theme/TabItem;## StatementsIn this section we list statements for general control flow and state management.### transferTransfers the execution of the script to a new section, URL, or RELAY context (RELAY context currently not implemented). This is analogous to a goto operation.#### Parameters| Name | Type | Description || :------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || dest | string | Specifies where to transfer to. Required. The value can be one of:
relay: - relay context to notify (currently not implemented)
https:// - URL to fetch next document from. Sends HTTP POST
|| params | object | Named parameters to send to a section, URL, or context. Optional. Default is not set. || meta | object | User data, ignored by SignalWire. Option. Default is not set. |#### VariablesNone#### Examples##### Named parameteryamlsections: main: - transfer: dest: https://example.com/nextjson{ sections: { main: [ { transfer: { dest: https://example.com/next } } ] }}##### Named parameter with parametersyamlsections: main: - transfer: - dest: https://example.com/next - params: - foo: barjson{ sections: { main: [ { transfer: { dest: https://example.com/next, params: { foo: bar } } } ] }}##### Implicit first parameteryamlsections: main: - transfer: https://example.com/nextjson{ sections: { main: [ { transfer: https://example.com/next } ] }}---### executeExecute a section or URL as a subroutine and return back to current document.#### Parameters| Name | Type | Description || :---------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ || dest | string | Specifies what to execute. Required. The value can be one of:
https:// - URL pointing to the document to execute. Sends HTTP POST.
|| params | object | Named parameters to send to section or URL. Optional. Default is not set. || on_return | object | Code to execute after return. Optional. Default is not set. |#### VariablesNone#### Examples##### Executing a subroutineyamlsections: main: - execute: dest: subroutine params: - file: https://example.com/foo.wav subroutine: - answerjson{ sections: { main: [ { execute: { dest: subroutine, params: { file: https://example.com/foo.wav } } } ], subroutine: [answer] }}##### Executing a subroutine and branching on returnyamlsections: main: - execute: dest: my_menu params: - file: https://example.com/foo.wav - digits: 123 on_return: - switch: - case: - variable: return_value - 1: - transfer: sales - 2: - transfer: support - 3: - transfer: leave_a_message - default: - transfer: invalid_choice subroutine: - answerjson{ execute: { dest: my_menu, params: { file: https://example.com/foo.wav, digits: 123 }, on_return: [ { switch: { case: { variable: return_value, 1: [{ transfer: sales }], 2: [{ transfer: support }], 3: [{ transfer: leave_a_message }] }, default: [{ transfer: invalid_choice }] } } ] }}---### returnReturn from [execute](#execute) or exit script.#### ParametersNo specific parameters. Optional JSON parameter(s) of any type will be saved to return_value.#### VariablesSet by the method:- **return_value:**(out) Optional return value.#### Examples##### Return with optional valueyamlsections: main: - return: 1json{ sections: { main: [{ return: 1 }] }}##### Return with multiple valuesyamlsections: main: - return: - a: 1 - b: 2json{ sections: { main: [{ return: { a: 1, b: 2 } }] }}##### Return with no valueyamlsections: main: - returnjson{ sections: { main: [return] }}Additional examples are available in the [subroutines introduction](./introduction.mdx#implementing-subroutines-or-integrations).---### requestSend a GET, POST, PUT, or DELETE request to a remote URL.#### Parameters| Name | Type | Description || :---------------- | :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || url | string | URL to send the HTTPS request to. Required. || method | string | Request type. GET\|POST\|PUT\|DELETE. Required. || headers | object | Object containing HTTP headers to set. Valid header values are Accept, Authorization, Content-Type, Range, and custom X- headers. Optional. Default is not set. || body | string \| object | Request body. Content-Type header should be explicitly set, but if not set, the most likely type will be set based on the first non-whitespace character. Optional. Default is not set. || timeout | number | Maximum time in seconds to wait for a response. Default is 5.0. Optional. || connect_timeout | number | Maximum time in seconds to wait for a connection. Default is 5.0. Optional. || save_variables | boolean | Store parsed JSON response as variables. Default is false. Optional. |#### VariablesSet by the method:- **request_url:** (out) URL the request was sent to.- **request_result:** (out) success | failed.- **request_response_code:** (out) HTTP response code from the request.- **request_response_headers.:** (out) HTTP response headers. Header names should be normalized to lowercase and trimmed of whitespace. A maximum of 64 headers are saved. Ex: %{request_response_headers.content-type}.- **request_response_body:** (out) Raw HTTP response body. This is limited to 64KB.- **request_response.:** (out) Variables saved from the response if save_variables is true and parsed as JSON.For example, given the script: { foo: bar, foo2: bar2, foo3: { foo4: bar4 } }The variables request_response.foo, request_response.foo2, and request_response.foo3.foo4 are set.#### Examples##### Making a POST Requestyamlsections: main: - request: url: https://example.com/status_update method: POST connect_timeout: 5.0 timeout: 5.0 save_variables: true headers: content-type: application/json x-custom-header: foo body: payload: %{call.to} finished the IVR.json{ sections: { main: [ { request: { url: https://example.com/status_update, method: POST, connect_timeout: 5.0, timeout: 5.0, save_variables: true, headers: { content-type: application/json, x-custom-header: foo }, body: { payload: %{call.to} finished the IVR. } } } ] }}---### switchExecute a sequence of instructions depending on which value matches a variable.#### Parameters| Name | Type | Description || :--------- | :------- | :----------------------------------------------------------------------------------------- || variable | string | Name of the variable whose value needs to be compared. Required. || case | object | Object of values mapped to array of instructions to execute. Optional. Default is not set. || default | array | Optional array of instructions to execute if no cases match. Optional. Default is not set. |#### VariablesNone#### Examplesyamlsections: main: - switch: variable: prompt_value case: 1: - transfer: main 2: - play: https://example.com/hello.wav default: - play: https://example.com/no_match.wavjson{ sections: { main: [ { switch: { variable: prompt_value, case: { 1: [{ transfer: main }], 2: [{ play: https://example.com/hello.wav }] }, default: [{ play: https://example.com/no_match.wav }] } } ] }}---### condExecute a sequence of instructions depending on the value of a JavaScript condition.#### Parameters| Name | Type | Description || :----- | :------- | :------------------------------------------------------------------------------------- || when | string | The JavaScript condition to act on. Required. || then | array | Sequence of instructions to execute when the condition evaluates to true. Required. || else | array | Sequence of instructions to execute when the condition evaluates to false. Required. |#### VariablesNone#### Examplesyamlsections: main: - cond: - when: vars.foo < 2 then: - hangup - when: %{call.to} == +15551231234 then: - transfer: help - when: /hello/.test(vars.foo) then: - transfer: match - else: - transfer: mainjson{ sections: { main: [ { cond: [ { when: vars.foo < 2, then: [hangup] }, { when: %{call.to} == +15551231234, then: [{ transfer: help }] }, { when: /hello/.test(vars.foo), then: [{ transfer: match }] }, { else: [{ transfer: main }] } ] } ] }}---### setSet script variables to the specified values.#### ParametersNo specific parameters. Accepts an object mapping variable names to values.#### VariablesAny variable can be set by this method.#### Examples##### Setting multiple variablesyamlsections: main: - set: variable1: value1 variable2: value2json{ sections: { main: [ { set: { vars.variable1: value1, variable2: value2 } } ] }}---### unsetUnset the specified variables#### Parameters| Name | Type | Description || :----- | :--------------------- | :------------------------------- || vars | string \| string[] | Names of the variables to unset. |#### VariableAny variable can be unset by this method.#### Examples##### Unset a single variableyamlsections: main: - unset: variable1json{ sections: { main: [{ unset: variable1 }] }}##### Unset multiple variablesyamlsections: main: - unset: - variable1 - variable2json{ sections: { main: [{ unset: [variable1, variable2] }] }}---## Methods### answerAnswer the call and set an optional maximum duration.#### Parameters| Name | Type | Description || :------------- | :------- | :-------------------------------------------------------------------------------------------------------- || max_duration | number | Maximum duration in seconds. Optional Can not be less than 7 seconds. Default is 14100 seconds (4 hours). |#### VariablesNone#### Examples##### No parametersyamlsections: main: - answerjson{ sections: { main: [answer] }}##### Implicit first parameteryamlsections: main: - answer: 60json{ sections: { main: [{ answer: 60.0 }] }}##### Named parameteryamlsections: main: - answer: max_duration: 60json{ sections: { main: [ { answer: { max_duration: 60.0 } } ] }}---### hangupEnd the call with an optional reason.#### Parameters| Name | Type | Description || :------- | :------------------------------------ | :----------------------- || reason | hangup \| busy \| decline | Hangup reason, optional. |#### VariablesNone#### Examples##### No parametersyamlsections: main: - answer - hangupjson{ sections: { main: [answer, hangup] }}##### Implicit first parameteryamlsections: main: - answer - hangup: busyjson{ sections: { main: [answer, { hangup: busy }] }}##### Named parameteryamlsections: main: - answer - hangup: reason: busyjson{ sections: { main: [ answer, { hangup: { reason: busy } } ] }}---### promptPlay a prompt and wait for digit or speech input. Speech detection is not enabled unless at least one speech parameter is set. If only speech parameters are set (and no digit parameters), digit detection is not enabled. To enable both digit and speech detection, set at least one parameter for each.#### Parameters| Name | Type | Description || :------------------- | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || play | string \| string[] | URL or array of URLs to play. Allowed URLs are:
http:// - audio file to GET
https:// - audio file to GET
ring:[duration:] - ring tone to play. For example: ring:us to play single ring or ring:20.0:us to play ring for 20 seconds.
say: - Sentence to say
silence: - seconds of silence to play
|| volume | number | Optional volume gain to apply to played URLs. Allowed values from -50.0 to 50.0. Default 0. || say_voice | string | Optional voice to use for text to speech. Default is Default is Polly.Salli. || say_language | string | Optional language to use for text to speech. Default is en-US. || say_gender | string | Optional gender to use for text to speech. Default is female. || max_digits | integer | Optional number of digits to collect. Default 1. || terminators | string | Optional digits that terminate digit collection. Default unset. || digit_timeout | number | Optional time in seconds to wait for next digit. Default 5.0. || initial_timeout | number | Optional time in seconds to wait for start of input. Default 5.0. || speech_timeout | number | Optional max time in seconds to wait for speech result. Default unset. || speech_end_timeout | number | Optional time in seconds to wait for end of speech utterance. Default unset. || speech_language | string | Optional language to detect speech in. || speech_hints | string[] | Optional expected words to match. |#### VariablesRead by the method:- **say_voice:** (in) - optional voice to use for text to speech.- **say_language:** (in) - optional language to use for text to speech.- **say_gender:** (in) - optional gender to use for text to speech.Set by the method:- **prompt_result:** (out) - failed, no_input, match_speech, match_digits, or no_match.- **prompt_value:** (out) - the digits or utterance collected.- **prompt_digit_terminator:** (out) - digit terminator collected, if any.- **prompt_speech_confidence:** (out) - speech confidence measured, if any.#### Examples##### Play prompt and wait for digit pressyamlsections: main: - prompt: https://example.com/menu.wav - switch: variable: prompt_value case: 1: - transfer: sales default: - play: https://example.com/bad_input.wav - transfer: mainjson{ sections: { main: [ { prompt: https://example.com/menu.wav }, { switch: { variable: prompt_value, case: { 1: [{ transfer: sales }] } }, default: [ { play: https://example.com/bad_input.wav }, { transfer: main } ] } ] }}##### Play prompt and wait for digit or speechyamlsections: main: - prompt: play: https://example.com/press_or_say_one.wav speech_language: en max_digits: 1 hints: - one - two - three - four - five - six - seven - eight - nine - switch: variable: prompt_value case: 1: - transfer: sales one: - transfer: sales default: - play: https://example.com/bad_input.wav - transfer: mainjson{ sections: { main: [ { prompt: { play: https://example.com/press_or_say_one.wav, speech_language: en, max_digits: 1, hints: [ one, two, three, four, five, six, seven, eight, nine ] } }, { switch: { variable: prompt_value, case: { 1: [{ transfer: sales }], one: [{ transfer: sales }] }, default: [ { play: https://example.com/bad_input.wav }, { transfer: main } ] } } ] }}##### Play prompt and collect digits, then pass the data to an external actionyamlsections: main: - prompt: https://example.com/menu.wav - transfer: https://example.com/post_next_menujson{ sections: { main: [ { prompt: https://example.com/menu.wav }, { transfer: https://example.com/post_next_menu } ] }}---### playPlay file(s), ringtones, speech or silence.#### Parameters| Name | Type | Description || :---------------- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || urls (or url) | string \| string[] | URL or array of URLs to play. Required. Allowed URLs are:
http:// - audio file to GET
https:// - audio file to GET
ring:[duration:] - ring tone to play. For example: ring:us to play single ring or ring:20.0:us to play ring for 20 seconds.
say: - Sentence to say
silence: - seconds of silence to play
|| volume | number | Optional volume gain to apply to played URLs. Allowed values from -40.0 to 40.0. Default 0. || say_voice | string | Optional voice to use for text to speech. Default is Polly.Salli. || say_language | string | Optional language to use for text to speech. Default is en-US. || say_gender | string | Optional gender to use for text to speech. Default is female. |#### VariablesRead by the method:- **say_voice:** (in) - Optional voice to use for text to speech.- **say_language:** (in) - Optional language to use for text to speech.- **say_gender:** (in) - Optional gender to use for text to speech.#### Examples##### Playing a single URLyamlsections: main: - play: https://example.com/file.mp3json{ sections: { main: [{ play: https://example.com/file.mp3 }] }}##### Playing multiple URLsyamlsections: main: - play: - https://example.com/file1.wav - https://example.com/file2.wav - say:this is something to say - silence:3.0 - ring:10.0:usjson{ sections: { main: [ { play: [ https://example.com/file1.wav, https://example.com/file2.wav, say: this is something to say, silence:3.0, ring:10.0:us ] } ] }}##### Playing multiple URLs with volume adjustedyamlsections: main: - play: volume: 30 urls: - https://example.com/file1.wav - https://example.com/file2.wav - say:this is something to say - silence:3.0 - ring:10.0:usjson{ sections: { main: [ { play: { volume: 30, urls: [ https://example.com/file1.wav, https://example.com/file2.wav, say:this is something to say, silence:3.0, ring:10.0:us ] } } ] }}---### recordRecord the call audio in the foreground. Use this, for example, to record voicemails.#### Parameters| Name | Type | Description || :-------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || stereo | boolean | Whether to record in stereo mode. Optional. Default false. || format | string | Optional format (wav or mp3). Default wav. || direction | string | Optional direction of the audio to record: speak for what party says, hear for what party hears. Default speak. || terminators | string | Optional string of digits that will stop the recording when pressed. Default #. || beep | boolean | Whether to play a beep before recording. Optional. Default false. || input_sensitivity | number | How sensitive the recording voice activity detector is to background noise. A larger value is more sensitive. Allowed values from 0.0 to 100.0. Optional. Default 44.0. || initial_timeout | number | How long, in seconds, to wait for speech to start. Optional. Default 0. || end_silence_timeout | number | How much silence, in seconds, will end the recording. Optional. Default 0. |#### VariablesSet by the method:- **record_url:** (out) the URL of the newly created recording.- **record_result:** (out) success | failed.#### Examples##### Record some audio and play it backyamlsections: main: - record: end_silence_timeout: 5 - play: %{record_url}json{ sections: { main: [{ record: { end_silence_timeout: 5.0 } }, { play: %{record_url} }] }}---### record_callRecord call in the background.#### Parameters| Name | Type | Description || :-------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || control_id | string | Optional identifier for this recording, to use with [stop_call_record](#stop_record_call). Default is generated and saved to record_control_id variable. || stereo | boolean | Whether to record in stereo mode. Optional. Default false. || format | string | Optional format (wav or mp3). Default wav. || direction | string | Optional direction of the audio to record: speak for what party says, hear for what party hears, both for what the party hears and says. Default both. || terminators | string | Optional string of digits that will stop the recording when pressed. Default is unset. || beep | boolean | Whether to play a beep before recording. Optional. Default false. || input_sensitivity | number | How sensitive the recording voice activity detector is to background noise. A larger value is more sensitive. Allowed values from 0.0 to 100.0. Optional. Default 44.0. || initial_timeout | number | How long, in seconds, to wait for speech to start. Optional. Default 0. || end_silence_timeout | number | How much silence, in seconds, will end the recording. Optional. Default 0. |#### VariablesSet by the method:- **record_call_url:** (out) the URL of the newly started recording.- **record_call_result:** (out) success | failed.- **record_control_id:** (out) control ID of this recording.#### Examples##### Start an MP3 recording of the callyamlsections: main: - record_call: format: mp3json{ sections: { main: [{ record_call: { format: mp3 } }] }}---### stop_record_callStop an active background recording.#### Parameters| Name | Type | Description || :----------- | :------- | :----------------------------------------------------------------------------------------------------- || control_id | string | Optional identifier for the recording to stop. If not set, the last recording started will be stopped. |#### VariablesRead by the method:- **record_control_id:** (in) control ID of last recording started.Set by the method:- **stop_record_call_result:** (out) success | failed#### Examples##### Stop last call recordingyamlsections: main: - stop_record_calljson{ sections: { main: [stop_record_call] }}##### Stop a specific call recordingyamlsections: main: - stop_record_call: my-recording-idjson{ sections: { main: [{ stop_record_call: my-recording-id }] }}---### join_roomJoin a RELAY room.#### Parameters| Name | Type | Description || :----- | :------- | :--------------------------------- || name | string | Required name of the room to join. |#### VariablesSet by the method:- **join_room_result:** (out) joined | failed#### Examples##### Joining a roomyamlsections: main: - join_room: my_roomjson{ sections: { main: [{ join_room: my_room }] }}---### denoiseStart noise reduction.#### ParametersNone#### VariablesSet by the method:- **denoise_result:** (out) on | failed#### Examples##### Start denoiseyamlsections: main: - denoisejson{ sections: { main: [denoise] }}---### stop_denoiseStop noise reduction.#### ParametersNone#### VariablesSet by the method:- **denoise_result:** (out) off#### Examples##### Stop denoiseyamlsections: main: - stop_denoisejson{ sections: { main: [stop_denoise] }}---### receive_faxReceive a fax being delivered to this call.#### ParametersNone#### VariablesSet by the method:- **receive_fax_document:** (out) URL of received document.- **receive_fax_identity:** (out) identity of this fax station.- **receive_fax_remote_identity:** (out) identity of the sending fax station.- **receive_fax_pages:** (out) number of pages received.- **receive_fax_result_code:** (out) fax status code.- **receive_fax_result_text:** (out) description of fax status code.- **receive_fax_result:** (out) success | failed.#### Examples##### Receive a fax and post a result to a webhookyamlsections: main: - receive_fax - execute: https://example.com/handle_incoming_faxjson{ sections: { main: [receive_fax, { execute: https://example.com/handle_incoming_fax }] }}---### send_faxSend a fax#### Parameters| Name | Type | Description || :------------ | :------- | :-------------------------------------------------------------------- || document | string | Required URL to the PDF document to fax. || header_info | string | Optional text to add to the fax header. Default is not set. || identity | string | Optional station identity to report. Default is the caller ID number. |#### VariablesSet by the method:- **send_fax_document:** (out) URL of sent document.- **send_fax_identity:** (out) identity of this fax station.- **send_fax_remote_identity:** (out) identity of the receiving fax station.- **send_fax_pages:** (out) number of pages sent.- **send_fax_result_code:** (out) fax status code.- **send_fax_result_text:** (out) description of fax status code.- **send_fax_result:** (out) success | failed.#### Examples##### Send a fax and post a result to a webhookyamlsections: main: - send_fax: https//example.com/fax_to_send.pdf - execute: https://example.com/handle_outgoing_fax_resultjson{ sections: { main: [ { send_fax: https//example.com/fax_to_send.pdf }, { execute: https://example.com/handle_outgoing_fax_result } ] }}---### sip_referSend SIP REFER to a SIP call.#### Parameters| Name | Type | Description || :------- | :------- | :----------------------------- || to_uri | string | SIP URI to REFER to. Required. |#### VariablesSet by the method:- **sip_refer_to:** (out) The SIP URI the recipient is to INVITE.- **sip_refer_result:** (out) Overall SIP REFER result.- **sip_refer_response_code:** (out) Recipient response to the REFER request.- **sip_refer_to_response_code:** (out) INVITE response to the recipient.#### Examples##### Send SIP REFER and post resultyamlsections: main: - sip_refer: sip:alice@example.com - execute: https://example.com/handle_sip_refer_resultjson{ sections: { main: [ { sip_refer: sip:alice@example.com }, { execute: https://example.com/handle_sip_refer_result } ] }}---### connectDial a SIP URI or phone number.#### Parameters| Name | Type | Description || :---------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || from | string | Caller ID number. Optional. Default is calling party caller ID number. || headers | object | Custom SIP headers to add to INVITE. Has no effect on calls to phone numbers. Optional. Default is not set. || codecs | string | Comma-separated string of codecs to offer. Has no effect on calls to phone numbers. Optional. Default is set based on SignalWire settings. || webrtc_media | boolean | If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers. Optional. Default is false. || session_timeout | integer | Time, in seconds, to set the SIP Session-Expires header in INVITE. Must be a positive, non-zero number. Has no effect on calls to phone numbers. Optional. Default is set based on SignalWire settings. || ringback | string[] | Array of play URIs to play as ringback tone. Optional. Default will play audio from the provider. |In addition, specify **one and only one** of the following dialing parameters:| Name | Type | Description || :---------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------------- || serial_parallel | string[][] | Array of arrays. Inner arrays contain destinations to dial simultaneously. Outer array attempts each parallel group in order. || serial | string[] | Array of destinations to dial in order. || parallel | string[] | Array of destinations to dial simultaneously. || to | string | Single destination to dial. |#### VariablesSet by the method:- **connect_result:** (out) connected | failed.- **connect_failed_reason:** (out) Detailed reason for failure.#### Examples##### Dial a single phone numberyamlsections: main: - connect: from: +15553214321 to: +15551231234json{ sections: { main: [{ connect: { from: +15553214321, to: +15551231234 } }] }}##### Dial numbers in parallelyamlsections: main: - connect: parallel: - to: +15551231234 - to: +15553214321json{ sections: { main: [ { connect: { parallel: [{ to: +15551231234 }, { to: +15553214321 }] } } ] }}##### Dial SIP seriallyyamlsections: main: - connect: serial: - from: sip:chris@example.com to: sip:alice@example.com - codecs: PCMU to: sip:bob@example.comjson{ sections: { main: [ { connect: { serial: [ { from: sip:chris@example.com, to: sip:alice@example.com }, { codecs: PCMU, to: sip:bob@example.com } ] } } ] }}---### tapStart background call tap. Media is streamed over Websocket or RTP to customer controlled URI.#### Parameters| Name | Type | Description || :----------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- || uri | string | Required destination of the tap media stream. rtp://IP:port, ws://example.com, or wss://example.com. || control_id | string | Optional identifier for this tap to use with stop_tap. Default is generated and stored in tap_control_id variable. || direction | string | Direction of the audio to tap: speak for what party says, hear for what party hears, both for what party hears and says. Optional. Default is both. || codec | string | PCMU or PCMA. Optional. Default PCMU. || rtp_ptime | integer | If using a rtp:// URI, this optional parameter can set the packetization time of the media in milliseconds. Optional. Default 20 ms. |#### VariablesSet by the method:- **tap_uri:** (out) The destination URI of the newly started tap.- **tap_result:** (out) success | failed.- **tap_control_id:** (out) Control ID of this tap.- **tap_rtp_src_addr:** (out) If RTP, source address of the tap stream.- **tap_rtp_src_port:** (out) If RTP, source port of the tap stream.- **tap_ptime:** (out) Packetization time of the tap stream.- **tap_codec:** (out) Codec in the tap stream.- **tap_rate:** (out) Sample rate in the tap stream.#### Examples##### Start WSS tapyamlsections: main: - tap: uri: wss://example.com/tapjson{ sections: { main: [{ tap: { uri: wss://example.com/tap } }] }}---### stop_tapStop an active tap stream.#### Parameters| Name | Type | Description || :----------- | :------- | :-------------------------------------------------------------------------------- || control_id | string | Optional ID of the tap to stop. If not set, the last tap started will be stopped. |#### VariablesRead by the method:- **tap_control_id:** (in) Control ID of last tap stream started.Set by the method:- **stop_tap_result:** (out) Success or failed.#### Examples##### Stop the last call tapyamlsections: main: - stop_tapjson{ sections: { main: [stop_tap] }}##### Stop a specific call tapyamlsections: main: - stop_tap: my-tap-idjson{ sections: { main: [{ stop_tap: my-tap-id }] }}---### send_digitsSend digit presses as DTMF tones.#### Parameters| Name | Type | Description || :------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------- || digits | string | The digits to send. Required. Valid values are 0123456789*#ABCDWw. Character W is a 1 second delay, and w is a 500 ms delay. |#### VariablesSet by the method:- **send_digits_result:** (out) success | failed#### Examples##### Send digitsyamlsections: main: - send_digits: 012345json{ sections: { main: [{ send_digits: 012345 }] }}---### send_smsSend an outbound message to a PSTN phone number.#### Parameters| Name | Type | Description || :------------ | :--------- | :-------------------------------------------------------------------------------------------------------------------------------- || to_number | string | Phone number to send SMS message to in e.164 format. Required. || from_number | string | Phone number SMS message will be sent from. Required. || body | string | Body of the message. Required unless media is included. || media | string[] | Array of media URLs to include in the message. Required unless body is included. || region | string | Region of the world to originate the message from. A default is picked based on account preferences or device location. Optional. || tags | string[] | Array of tags to associate with the message to facilitate log searches. Optional. |#### VariablesSet by the method:- **send_sms_result:** (out) success | failed.#### Examples##### Send an SMSyamlsections: main: - send_sms: tags: - Custom - data region: us from_number: +155512312345 to_number: +15555554321 body: Message Body media: - url1 - url2json{ sections: { main: [ { send_sms: { tags: [Custom, client, data], region: us, from_number: +155512312345, to_number: +15555554321, body: Message Body, media: [url1, url2] } } ] }}---### aiConnect to an AI Agent.#### Parameters| Name | Type | Description || :-------------------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------ || voice | string | TTS voice the AI agent will use. Optional. Default is picked by SignalWire. || prompt | object | The initial set of instructions and settings to configure the agent. Optional. Default is not set. || post_prompt | object | The final set of instructions and configuration settings to send to the agent. Optional. Default is not set. || post_prompt_url | string | URL to send status callbacks and reports to. Optional. Default is not set. || post_prompt_auth_user | string | Auth username for post_url endpoint. Optional. Default is not set. || post_prompt_auth_password | string | Auth password for post_url endpoint. Optional. Default is not set. || SWAIG | object[] | An array of JSON objects to create user-defined functions/endpoints that can be executed during the dialogue. Optional. Default is not set. || hints | string[] | An array of hints (as strings) to provide context to the dialogue. Optional. Default is not set. || languages | object[] | An array of JSON objects defining supported languages in the conversation. Optional. Default is en-us. |##### Parameters for prompt and post_prompt| Name | Type | Description || :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ || text | string | The instructions to send to the agent. Optional. Default is not set. || temperature | number | Randomness setting. Float value between 0.0 and 2.0. Closer to 0 will make the output less random. Optional. Default is 1.0. || top_p | number | Randomness setting. Alternative to temperature. Float value between 0.0 and 1.0. Closer to 0 will make the output less random. Optional. Default is 1.0. || confidence | number | Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. Decreasing this value will reduce the pause after the user speaks, but may introduce false positives. Optional. Default is 0.6. || barge_confidence | number | Confidence threshold that applies when the user is speaking over the AI agent. Float value between 0.0 to 1.0. Decreasing this value will reduce the time it takes the agent to stop, but may introduce false positives. Optional. Default is picked by SignalWire. || presence_penalty | number | Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the models likelihood to talk about new topics. Optional. Default is 0. || frequency_penalty | number | Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the models likelihood to repeat the same line verbatim. Optional. Default is 0. |##### Parameters for SWAIG| Name | Type | Description || :----------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------- || defaults | object | Default settings for all SWAIG functions. If defaults is not set, settings may be set in each function object. Optional. Default is not set. || defaults.web_hook_url | string | Default URL to send status callbacks and reports to. Optional. Default is not set. || defaults.web_hook_auth_user | string | Defualt auth username for web_hook_url endpoint. Optional. Default is not set. || defaults.web_hook_auth_pass | string | Defualt auth password for web_hook_url endpoint. Optional. Default is not set. || defaults.meta_data | object | A JSON object containing any metadata, as a key-value map. Optional. Default is not set. || functions | object | A JSON object to define a function that can be executed during the dialogue. Optional. Default is not set. || functions.function | string | A unique name for the function. For example, get_weather. || functions.purpose | string | A description of the context and purpose of the function, to explain to the agent when to use it. || functions.argument | string | A description of the input to the function. For example, The location or name of the city. || functions.web_hook_url | string | Function specific URL to send status callbacks and reports to. Takes precedence over a default setting. Optional. Default is not set. || functions.web_hook_auth_user | string | Function speficic auth username for web_hook_url endpoint. Takes precedence over a default setting. Optional. Default is not set. || functions.web_hook_auth_pass | string | Function speficic auth password for web_hook_url endpoint. Takes precedence over a default setting. Optional. Default is not set. |##### Parameters for languages| Name | Type | Description || :------ | :------- | :-------------------------------------------------------------------------------------------------------- || name | string | Language code. For example, fr-FR. Optional. Default is en-us. || code | string | Name of the language. For example, French. Optional. Default is English. || voice | string | Voice to use for the language. For example, fr-FR-Neural2-B. Optional. Default is picked by SignalWire. |#### Variables- **ai_result:** (out) success | failed#### Examples##### A Voicemail Botyamlsections: main: - ai: post_prompt_url: https://example.com/my-api prompt: text: | You are Franklins assistant, and your job is to collect messages for him over the phone. You can reassure that Franklin will get in touch as soon as possible. Collect the users name and number if you do not already know it from the caller id. Start by presenting yourself, then let the contact know that Franklin is not available, then offer to collect a message. After collecting the message, do not wait for the user to end the conversation: say good bye and hang up the call. post_prompt: text: | Summarize the message as a valid anonymous json object by filling the upper case placeholders in this template: { contact_info: { name: CONTACT_NAME, number: CONTACT_PHONE }, message: MESSAGE } SWAIG: defaults: web_hook_url: https://example.com/my-webhook functions: - function: get_weather purpose: To determine what the current weather is in a provided location. argument: The location or name of the city to get the weather from.json{ sections: { main: [ { ai: { post_prompt_url: https://example.com/my-api, prompt: { text: You are Franklins assistant, and your job is to collect messages for him over the phone.\nYou can reassure that Franklin will get in touch as soon as possible.\nCollect the users name and number if you do not already know it from the caller id.\nStart by presenting yourself, then let the contact know that Franklin is not available, then offer to collect a message.\nAfter collecting the message, do not wait for the user to end the conversation: say good bye and hang up the call.\n }, post_prompt: { text: Summarize the message as a valid anonymous json object by filling the upper case placeholders in this template:\n{ \contact_info\: { \name\: \CONTACT_NAME\, \number\: \CONTACT_PHONE\ }, \message\: \MESSAGE\ }\n }, SWAIG: { defaults: { web_hook_url: https://example.com/my-webhook }, functions: [ { function: get_weather, purpose: To determine what the current weather is in a provided location., argument: The location or name of the city to get the weather from. } ] } } } ] }}##### Declaring functionsyamlsections: main: - ai: post_prompt_url: https://example.com/my-api prompt: text: | You are a helpful assistant that can inform users of the weather in any city. You can use the appropriate function to get the weather information. post_prompt: text: Summarize the conversation. SWAIG: defaults: web_hook_url: https://example.com/my-webhook functions: - function: get_weather purpose: To determine what the current weather is in a provided location. argument: The location or name of the city to get the weather from.json{ sections: { main: [ { ai: { post_prompt_url: https://example.com/my-api, prompt: { text: You are a helpful assistant that can inform users of the weather in any\ncity. You can use the appropriate function to get the weather information.\n }, post_prompt: { text: Summarize the conversation. }, SWAIG: { defaults: { web_hook_url: https://example.com/my-webhook }, functions: [ { function: get_weather, purpose: To determine what the current weather is in a provided location., argument: The location or name of the city to get the weather from. } ] } } } ] }}---