Repository navigation
fix(swml): align the SWML method reference with platform behavior - #852
Merged
Devon-White merged 70 commits intoOct 29, 2026
Merged
Conversation
…sult timing cond: a when/then entry can no longer carry its own else; the else fallback is a standalone entry, at most one per list, and the schema now enforces both. The reference explains first-match selection, fallback and no-match continuation, and the user-input example tests the collected digit instead of the call type. execute: result runs after the section or URL returns and before on_return, only when a return_value was set; the object/array choice is made on the shape of result itself. params documents the 63-level nesting limit. The hosted-server example keeps some_info numeric and reads the parameter it actually sends. Audit keys: - calling/cond::SWML-COND-001 - calling/cond::SWML-COND-002 - calling/cond::SWML-COND-003 - calling/cond::SWML-COND-004 - calling/execute::SWML-EXECUTE-001 - calling/execute::SWML-EXECUTE-002 - calling/execute::SWML-EXECUTE-003 - calling/execute::SWML-EXECUTE-004 - calling/execute::SWML-EXECUTE-005 - calling/execute::SWML-EXECUTE-006
…variables timeout and connect_timeout default to 5 seconds (0 uses the default, values above 30 are capped), not "no timeout". headers is a map of header names to string values; the page now says which names are allowed and which characters a value may contain, and that invalid entries are skipped. method accepts a SWML variable reference. request_result is defined by the 2xx response code, return_value is no longer listed as an output, the unsupported 64-header response limit is gone, and the 62-level nesting limit for saved responses is documented. Audit keys: - calling/request::SWML-REQUEST-001 - calling/request::SWML-REQUEST-002 - calling/request::SWML-REQUEST-003 - calling/request::SWML-REQUEST-004 - calling/request::SWML-REQUEST-005 - calling/request::SWML-REQUEST-006 - calling/request::SWML-REQUEST-007 - calling/request::SWML-REQUEST-008
label: names must be nonempty (now enforced by the schema) and unique within the section. goto.label gets its own description of the label it jumps to instead of inheriting the label method's text. goto.max is documented as accepting a SWML variable reference, as the schema already allowed, and explains that the jump count belongs to the target label and is shared by every goto to it. Audit keys: - calling/label::SWML-LABEL-001 - calling/label::SWML-LABEL-002 - calling/goto::SWML-GOTO-002 - calling/goto::SWML-GOTO-003 - calling/goto::SWML-GOTO-004
…and depth limit return takes a string, number, object or array; booleans and null only work nested or as the result of a variable reference. The page now explains that variables are resolved in string values throughout the returned data (keys stay literal, a lone reference keeps its JSON type), that resolved values deeper than 62 object/array levels are not stored, and adds an example returning an object built from variables. Audit keys: - calling/return::SWML-RETURN-001 - calling/return::SWML-RETURN-002 - calling/return::SWML-RETURN-003
set and unset only accept identifier-style variable names (an ASCII letter or underscore, then up to 255 letters, digits or underscores, with an optional vars. prefix). A shared SetVariableName scalar now validates set's keys and unset's names in the schema. set documents the 62-level nesting limit for assigned values; unset explains that it removes whole top-level variables of the current call and cannot target child paths or other namespaces. Audit keys: - calling/set::SWML-SET-001 - calling/set::SWML-SET-002 - calling/unset::SWML-UNSET-001 - calling/unset::SWML-UNSET-002
The case entry is described as a value-to-methods mapping under switch.case rather than a second variable name. The page and schema now say the inspected value is converted to a string before lookup (so 5 matches "5"), and that with no match and no default no branch runs, a relay_script_method_no_matching_condition warning is reported and script_error is set, documented in a new Variables section. Audit keys: - calling/switch::SWML-SWITCH-001 - calling/switch::SWML-SWITCH-002 - calling/switch::SWML-SWITCH-003
…uto-answer event is documented as the payload of one custom event (an object), and can also be a SWML variable reference that resolves to an event object; the schema now allows that form. The page explains that string values in the payload are expanded, that SignalWire adds call details at the top level so custom data belongs under its own key, and that the method answers an unanswered inbound call before sending. The multi-field example is retitled as one event, and a variable-payload example is added. Audit keys: - calling/user_event::SWML-USER_EVENT-001 - calling/user_event::SWML-USER_EVENT-002 - calling/user_event::SWML-USER_EVENT-003 - calling/user_event::SWML-USER_EVENT-004 - calling/user_event::SWML-USER_EVENT-005
…ocument dest and params limits - Remove Relay application and inline JSON document destinations; state that relay: destinations are not supported. - Require a nonempty dest (minLength 1) and document that a value expanding to an empty string stops execution. - Document the 63-level object/array nesting limit on params after expansion. - Fix the sub-parameters example to use object form (was arrays of objects). - Interpolate params.where in the Express server example. Audit keys: calling/transfer::SWML-TRANSFER-001 calling/transfer::SWML-TRANSFER-002 calling/transfer::SWML-TRANSFER-003 calling/transfer::SWML-TRANSFER-004 calling/transfer::SWML-TRANSFER-006 calling/transfer::SWML-TRANSFER-007
…eferences - New SleepDuration union (positive integer, -1, or SWML variable reference) used by both sleep.duration and the sleep shorthand, so 0 and values below -1 no longer validate. - MDX parameter types now include the SWML variable reference string form. Audit keys: calling/sleep::SWML-SLEEP-001 calling/sleep::SWML-SLEEP-002
…lling.error events - Add `to` as an alias for `to_uri`; the schema now requires at least one of the two (both allowed), with to_uri taking precedence unless empty. - Enumerate sip_refer_result values and params.state values, including the intermediate inProgress state. - Qualify event_type and describe the calling.error event that can be sent to status_url instead of a calling.call.refer event. Audit keys: calling/sip_refer::SWML-SIP_REFER-001 calling/sip_refer::SWML-SIP_REFER-002 calling/sip_refer::SWML-SIP_REFER-003
…ocument answer_result - codecs accepts a comma-separated string or an array of strings (entries may be variable references); valid codecs listed per call type, with the not-applied-and-error behavior for invalid preferences. - username is applied only with a nonempty password after expansion. - New Variables section for answer_result (success/failed) with its caveats. - MDX max_duration type and prose cover SWML variable references; new YAML/JSON examples for codec arrays and a variable max_duration. Audit keys: calling/answer::SWML-ANSWER-001 calling/answer::SWML-ANSWER-002 calling/answer::SWML-ANSWER-003 calling/answer::SWML-ANSWER-004 calling/answer::SWML-ANSWER-005
…plain when reason applies - reason accepts hangup, cancel, busy, noAnswer, decline, error, or a SWML variable reference. - TypeSpec and MDX explain that reason only affects unanswered inbound calls (busy vs declined); answered calls end normally and unanswered outbound calls are canceled. - MDX reason is now a ParamField; new Variables section for hangup_result; the reason example no longer answers first. Audit keys: calling/hangup::SWML-HANGUP-001 calling/hangup::SWML-HANGUP-002 calling/hangup::SWML-HANGUP-003 calling/hangup::SWML-HANGUP-004
…paths, document calling.error - status_url accepts a SWML variable reference (existing SWMLVar scalar); the resolved value must still be an HTTP(S) URL. - Callback fields use full params.fax.type / params.fax.params.* paths with a params.fax.params object entry, for finished and page events. - Scope event_type to calling.call.fax and add an Error events section for calling.error (params.error.code, params.error.message, diagnostic params.request). - Replace the invented API download route in the example document URL with a neutral illustrative URL. Audit keys: calling/receive_fax::SWML-RECEIVE_FAX-001 calling/receive_fax::SWML-RECEIVE_FAX-002 calling/receive_fax::SWML-RECEIVE_FAX-003 calling/receive_fax::SWML-RECEIVE_FAX-004
…callback paths and calling.error - header_info falls back to the call's destination address and identity to the originating address (number for phone calls); removed the universal caller-ID default badge. - Note that the method attempts to answer a live, unanswered inbound call. - Qualify output variables: strings, check send_fax_result first, details may be unset on failure. - Callback fields use full params.fax.* paths; event_type scoped to calling.call.fax with a new Error events section for calling.error. Audit keys: calling/send_fax::SWML-SEND_FAX-001 calling/send_fax::SWML-SEND_FAX-002 calling/send_fax::SWML-SEND_FAX-003 calling/send_fax::SWML-SEND_FAX-004 calling/send_fax::SWML-SEND_FAX-005 calling/send_fax::SWML-SEND_FAX-006
…-answer and result meaning - digits: lowercase a-d accepted; at least one valid character and at most 99 characters (including W/w) after variable expansion; longer sequences are not sent. - Note that the method attempts to answer a live, unanswered inbound call. - Explain what send_digits_result success and failed mean. Audit keys: calling/send_digits::SWML-SEND_DIGITS-001 calling/send_digits::SWML-SEND_DIGITS-002 calling/send_digits::SWML-SEND_DIGITS-003 calling/send_digits::SWML-SEND_DIGITS-004
…result variables - to_number, from_number and the text-only body now have minLength 1, and the docs say they must be nonempty after variable expansion (media-branch body unchanged). - Explain what send_sms_result success/failed mean and add the send_sms_response_code output variable. Audit keys: calling/send_sms::SWML-SEND_SMS-001 calling/send_sms::SWML-SEND_SMS-002 calling/send_sms::SWML-SEND_SMS-003 Withheld: calling/send_sms::SWML-SEND_SMS-004 (legacy schema artifact only; canonical TypeSpec and calling schema already include status_callback)
… accurate ringtone and callback behavior - Add loop (default 1, 0 repeats continuously) to the spec and page. - Add volume, say_voice, say_language, say_gender ParamFields with the property > SWML variable > fallback precedence; drop the fixed Polly.Salli say_voice default. - auto_answer: false does not currently prevent answering. - urls entries may each be a literal or a SWML variable; status_url accepts a SWML variable. - Accept the bong ringtone; align the ringtone list with the 50 supported names and drop us-old. - Document play_result, scope calling.call.play to playback notifications, and note the separate calling.error event. Audit keys: calling/play::SWML-PLAY-001, SWML-PLAY-002, SWML-PLAY-003, SWML-PLAY-004, SWML-PLAY-005, SWML-PLAY-006, SWML-PLAY-007, SWML-PLAY-008, SWML-PLAY-009, SWML-PLAY-010, SWML-PLAY-011
…rect outputs and callbacks - Spec: speech_engine enum (Google, Google.V2, Deepgram); say_gender male/female; say_voice, say_language, speech_language and status_url literal syntax; timeouts and max_digits at least 1 (max_digits capped at 100); volume accepts a SWML variable; speech_hints are literal strings; play accepts mixed literal/variable arrays. - Shared play_url: supported ringtone names only, non-empty say: text, ring and silence durations of at least 1 second. - Page: speech activators and initial_timeout clarified; prompt_value normalization, new prompt_value_raw, open prompt_result values; callbacks cover calling.call.collect and calling.call.play, drop params.final and start_of_input/finished result types, note calling.error; prompt.play is string or string array only. Audit keys: calling/prompt::SWML-PROMPT-002, -003, -004, -005, -006, -007, -008, -009, -010, -011, -012, -013, -014, -015, -016, -017, -018, -019, -020, -021, -022, -023
…nds, max_length default, accurate beep and callbacks - direction accepts both; format and direction accept SWML variables. - input_sensitivity bounded to 0..100 in the schema. - max_length defaults to 0 (no maximum length). - beep plays as recording starts and can be in the recording. - Callback: drop the error recording state, scope calling.call.record, note the separate calling.error event, add params.record.audio and full params.record.audio.* paths with mp4/both, add params.first_frame_time. Audit keys: calling/record::SWML-RECORD-001, SWML-RECORD-002, SWML-RECORD-003, SWML-RECORD-004, SWML-RECORD-005, SWML-RECORD-006, SWML-RECORD-007, SWML-RECORD-008, SWML-RECORD-009, SWML-RECORD-010
…length default and record_call_start, correct beep and callbacks
- control_id: literal IDs exclude {, }, comma, semicolon, apostrophe,
backslash and ASCII control characters (recording fails to start
otherwise); fix the stop_record_call name in the description.
- format and direction accept SWML variables; input_sensitivity bounded
0..100 and documented as ignored in continuous recording.
- max_length defaults to 0 (no maximum length).
- beep plays as recording starts and can be in the recording.
- Document record_call_start; callback drops the error state, scopes
calling.call.record, notes calling.error, adds params.record.audio
with full paths, and corrects first_frame_time presence.
Audit keys: calling/record_call::SWML-RECORD_CALL-001, -002, -003,
-004, -005, -006, -007, -008, -009, -010, -011, -012
…stop_record_call_result Audit keys: calling/stop_record_call::SWML-STOP_RECORD_CALL-001
… accept variables Explain that start.direction is ordered and how the first and second directions map to from_lang/to_lang, voices and filters; require at least one direction; correct the Deepgram vad_silence_ms default (700), the omitted-voice default, and drop the bogus inject.direction default; note that debug_level only applies when service debugging is enabled; document the string summarize form; add false defaults for live_events/ai_summary; accept SWML variable references for action, direction and its items, inject.direction, filters and speech_engine. Audit keys: - calling/live_translate::SWML-LIVE_TRANSLATE-001 - calling/live_translate::SWML-LIVE_TRANSLATE-002 - calling/live_translate::SWML-LIVE_TRANSLATE-003 - calling/live_translate::SWML-LIVE_TRANSLATE-004 - calling/live_translate::SWML-LIVE_TRANSLATE-005 - calling/live_translate::SWML-LIVE_TRANSLATE-006 - calling/live_translate::SWML-LIVE_TRANSLATE-007 - calling/live_translate::SWML-LIVE_TRANSLATE-008 - calling/live_translate::SWML-LIVE_TRANSLATE-009
…ept variables Document start.hints recognition vocabulary; correct the Deepgram vad_silence_ms default (700) and explain that 0 falls back to the engine default; explain that vad_thresh 0 uses 400 rather than a zero threshold; document the string summarize form with an example; accept SWML variable references for start.direction (whole array or items) and speech_engine. Audit keys: - calling/live_transcribe::SWML-LIVE_TRANSCRIBE-001 - calling/live_transcribe::SWML-LIVE_TRANSCRIBE-002 - calling/live_transcribe::SWML-LIVE_TRANSCRIBE-003 - calling/live_transcribe::SWML-LIVE_TRANSCRIBE-004 - calling/live_transcribe::SWML-LIVE_TRANSCRIBE-005
…en-US language Say that transcribe records from the moment it runs until transcribe_stop or the call ends, and transcribes asynchronously afterwards, instead of claiming whole-call coverage completed at hangup; state the fixed en-US language; document the recording (calling.call.transcribe), transcript result and startup error events sent to status_url, with the recording event fields; accept a SWML variable reference for status_url. Audit keys: - calling/transcribe::SWML-TRANSCRIBE-001 - calling/transcribe::SWML-TRANSCRIBE-002 - calling/transcribe::SWML-TRANSCRIBE-003 - calling/transcribe::SWML-TRANSCRIBE-004
…callback docs Constrain rtp_ptime to multiples of 10 from 10 to 120 and show its variable form; state that RTP destinations need a public IPv4 address and port and replace the private address in the callback example; accept SWML variable references for direction and codec; show the speak/PCMU defaults and remove stray tokens; describe tap_ptime/tap_rate as the tapped call's audio values; use full params.* paths for callback fields and note the calling.error failure event; mention the answer attempt; document the generated control_id in TypeSpec. Audit keys: - calling/tap::SWML-TAP-001 - calling/tap::SWML-TAP-002 - calling/tap::SWML-TAP-003 - calling/tap::SWML-TAP-004 - calling/tap::SWML-TAP-005 - calling/tap::SWML-TAP-006 - calling/tap::SWML-TAP-007 - calling/tap::SWML-TAP-008 - calling/tap::SWML-TAP-009 - calling/tap::SWML-TAP-010
…answer attempt Accept SWML variable references for track, status_url and status_url_method; state that calling.call.stream status events are always sent with POST regardless of status_url_method; mention that the method attempts to answer an unanswered inbound call first. Audit keys: - calling/stream::SWML-STREAM-001 - calling/stream::SWML-STREAM-002 - calling/stream::SWML-STREAM-003
Clarify that success means the stop request was accepted, not that the stream has finished. Audit keys: - calling/stop_stream::SWML-STOP_STREAM-001
… the real connector/result contract Customers can now see and validate the pay contract the engine actually runs: security_code/postal_code take strings, payment_method accepts ach-debit with a new bank_account_type, prompts use the singular attempt selector and may use a play array instead of actions, the prompt targets/card types/error types match what is recognized, payment_connector_url must be HTTPS, say_voice is documented, and the connector request/response, status callback fields and result variables (pay_payment_results is a JSON-encoded string, payment_token is a token-type label, failed result) match deployed behaviour. Audit keys: - calling/pay::SWML-PAY-001 security_code string flag - calling/pay::SWML-PAY-002 postal_code string input - calling/pay::SWML-PAY-003 payment_method ach-debit - calling/pay::SWML-PAY-004 bank_account_type - calling/pay::SWML-PAY-005 prompts[].attempt - calling/pay::SWML-PAY-006 prompts[].for targets - calling/pay::SWML-PAY-007 card_type tokens - calling/pay::SWML-PAY-008 error_type tokens - calling/pay::SWML-PAY-009 prompts[].play / optional actions - calling/pay::SWML-PAY-010 say_voice - calling/pay::SWML-PAY-011 HTTPS payment_connector_url - calling/pay::SWML-PAY-012 max_attempts semantics - calling/pay::SWML-PAY-013 timeout minimum - calling/pay::SWML-PAY-014 charge_amount default - calling/pay::SWML-PAY-015 connector response charge_id - calling/pay::SWML-PAY-016 payment_token meaning - calling/pay::SWML-PAY-017 pay_payment_results JSON string - calling/pay::SWML-PAY-018 decoded result fields - calling/pay::SWML-PAY-019 connector_error presence - calling/pay::SWML-PAY-020 pay_result failed - calling/pay::SWML-PAY-021 connector parameters - calling/pay::SWML-PAY-022 connector raw card values - calling/pay::SWML-PAY-023 progress attempt/bank and ACH connector fields - calling/pay::SWML-PAY-024 masked progress fields - calling/pay::SWML-PAY-025 action type descriptions - calling/pay::SWML-PAY-026 payment-completed/failed prompt semantics
… and status events Adds the caller-side whisper_url input, lets status_url take a SWML variable, limits queue_result to the outcomes the method actually returns, explains when wait_time/entry_position/entry_size are set, and corrects the meaning of the status event id and the dequeue event. Audit keys: - calling/enter_queue::SWML-ENTER_QUEUE-001 whisper_url - calling/enter_queue::SWML-ENTER_QUEUE-004 status_url variable alternative - calling/enter_queue::SWML-ENTER_QUEUE-005 queue_result outcomes - calling/enter_queue::SWML-ENTER_QUEUE-006 result variables availability - calling/enter_queue::SWML-ENTER_QUEUE-007 params.id is the queue id - calling/enter_queue::SWML-ENTER_QUEUE-008 dequeue precedes the bridge Not changed (legacy orphaned schema, no generation route): - calling/enter_queue::SWML-ENTER_QUEUE-002 - calling/enter_queue::SWML-ENTER_QUEUE-003
…e, name length, and failure reason Explains that join_room first tries to answer an unanswered inbound call, that an automatically created room is set to be deleted after its room sessions end, that the resolved room name can be at most 100 characters, and adds the join_room_failed_reason variable. Audit keys: - calling/join_room::SWML-JOIN_ROOM-001 resolved name length (prose only) - calling/join_room::SWML-JOIN_ROOM-002 join_room_failed_reason - calling/join_room::SWML-JOIN_ROOM-003 auto-created room lifecycle - calling/join_room::SWML-JOIN_ROOM-004 automatic answer attempt
Devon-White
changed the title
…ptions Follow-up to the SWML reference corrections, after a review against the deployed behavior. Corrections: - join_conference: an invalid min_participants from a variable makes the join fail (a value above 100000 without max_participants falls back to 2); the blanket "falls back to 2" claim is removed. - pay: payment_connector_url accepts a SWML variable again (literals must be HTTPS); max_attempts outside 1-3 uses the default; the unsupported ringtone "no time limit" claim is removed; TTS gender defaults to female. - connect: from_name accepts text mixed with variables; the 1-70 character rule applies after expansion. An empty serial_parallel group is skipped. - ai_sidecar: POM numbering flags and MCP resources accept variables again, without changing ai or amazon_bedrock. - ai: context post_prompt no longer offers model; valid_steps, reset, data_map webhook fallback, settings action and form_param behavior stated precisely; transfer action documents the string form and required dest. - request: separates responses too deep to store from responses that can't be parsed. stream: status_url_method has no effect on status callbacks. - messaging: return in an executed document sets the caller's return_value; overview fetch methods, execute/transfer destinations and variable access corrected; errors page lists the execute fetch and document errors. - Calling overview: transcribe and join_conference.wait_url entries corrected. Descriptions across the changed specs and pages were also reworded to explain usage in customer terms. Regenerated SWML JSON Schemas and REST OpenAPI.
- connect: document `call:` destinations, the leading `+` on E.164 numbers, `sips:`, `wss://` streams, prefix case rules, and the `from` formats (#547) - ai.languages and Voices and languages: the `:model` suffix needs an engine prefix and overrides `languages[].model`; link the voice-unresolved warning (#523, #524) - ai.SWAIG and Errors: say which failures produce SWML error codes and where to trace the rest (#524) - ai and ai.params: link Conversation analytics from the post-prompt and debug webhook references (#519) - ai.SWAIG and the webhook security guide: protect credentials in the SWML document with HTTPS, signature checks, and basic auth in the URL (#522)
Collaborator
Author
SWML issues addressed in b6da4cbBefore writing anything, I checked each SWML issue on the tracker against the platform source (mod_infrastructure 268f330, mod_openai 21281c1, prime-rails 2bb2f88f2). This commit adds what the source confirmed. #547:
|
Collaborator
|
Review verdict: Changes requested (one blocker, rest is minor) Reviewed head Blocker
Minor
Questions
Not cross-checked against source (read for internal consistency and valid examples only): receive_fax, send_fax, send_sms, user_event, denoise, ai prompt contexts/steps, ai_sidecar, bedrock SWAIG, and the messaging reply/request/switch/return/transfer pages. |
This was referenced Oct 28, 2026
Merged
Per Product's decision, the documented default is 250. The platform currently falls back to 100000 when max_participants is unset; see the PR notes. Refs signalwire/docs-legacy#812.
With the documented max_participants default now 250, the note about a 100000 fallback no longer applies.
Match the spec bounds to the documented 250 limit (Product decision), and state the maximum in the max_participants description. Refs signalwire/docs-legacy#812.
busy maps to USER_BUSY (486 Busy Here) and decline to DECLINE (603 Decline) in the FreeSWITCH fork's cause-to-SIP mapping. Refs signalwire/docs-legacy#810.
from_lang and to_lang are recognized by speech_engine (Deepgram Nova-3 by default) as well as spoken by a voice, so link Deepgram's Nova-3 language table instead of only the Voices and languages page. Refs signalwire/docs-legacy#778.
join_conference sets only join_conference_result (joined or failed); it never sets return_value. Refs #877.
prompt: show say_voice, say_language, and speech_language in use, and stop naming auto_answer among play properties (it has no effect). connect: show ringback with answer_on_bridge. Refs signalwire/docs-legacy#483, signalwire/docs-legacy#689.
specs/swml/tsp-output/ is built by nothing, and the REST ai-agent models/ai/ tree (including the LanguagesBase fork) is imported by nothing; the REST AI agent imports the SWML models directly. Refs #590.
…uble turns, ai_response - multi works only on Deepgram and code-switches across a narrower set; auto fillers are skipped for multi (#597) - filler picks never repeat the previous phrase (#597) - a :0 turn_filler_sources suffix does not clear turn_filler_min_ms (#597) - check_time, wait_for_user, wait_seconds, adjust_response_latency fillers apply only to native functions (#597) - listen_language takes at most three codes (#597) - codes Nova-3 lacks fall back to Nova-2, then Google (#597) - fix two bare #anchor links in commented spec text (#608) - document params.double_turns and languages[].double_turn_fillers (#589) - document the ai_response variable (#618) Refs #597, #608, #589, #618.
…ng/ai Every link now uses the canonical path instead of relying on the wildcard redirect, and the broken data-map #output anchor points at #outputaction. Includes regenerated spec output. Refs #599.
…ct_machine - pay: restore the tokenization response tabs. A 200 reply with token_id, no charge_id and no error succeeds when charge_amount is zero or omitted, and payment_token then carries the token_id. Describe security_code and postal_code as the strings the platform reads, and widen security_code to string. - prompt: drop the Polly.Salli default for say_voice, matching play. - live_translate: a voice without a supported lowercase engine prefix is replaced by azure.en-US-RyanMultilingualNeural; lowercase the examples. - connect: per-destination stream status_url must be https; the top-level status_url accepts http or https, including for a single stream. - detect_machine: timing and threshold params must be at least 1. - send_digits: a sequence over 99 characters still reports success. - Regenerate the SWML schema and REST OpenAPI.
Collaborator
Author
|
@Manny-r31 thanks for the review. I merged 1.
The 2. 3. 4. 5. Checking this turned up a gotcha: a postal code made only of digits is read as a number first. On the schema break: rejecting a YAML boolean is deliberate, and the PR body already lists it under "Documents the schemas now reject". SWML itself rejects a boolean here. 6. 7. 8. Checks
|
This was referenced Oct 29, 2026
# Conflicts: # fern/apis/signalwire-rest/openapi.yaml # fern/products/swml/pages/reference/methods/calling/enter_queue.mdx # specs/swml/calling/Methods/enter_queue/main.tsp # specs/swml/calling/tsp-output/@typespec/json-schema/SWMLObject.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR corrects the SWML method reference for calling and messaging. Each method's documented parameters, types, defaults, limits, results and callbacks now match how SignalWire runs SWML. The TypeSpec sources, the reference pages, and the generated calling and messaging JSON Schemas are updated together, so validators built on the schemas agree with the docs.
What changes in the docs
cond,execute,goto,label,request,return,set,unset,switch,transfer,user_event)gotocounts jumps and when it stops.condpicks a branch:elsecan't appear besidewhen/thenin the same entry, and there can be at most oneelse.requesttimeout defaults, header rules and output variables.returnaccepts and how nesting depth is limited.transferdestinations.answer,hangup,sleep,send_digits,send_sms,send_fax,receive_fax,sip_refer)answeraccepts codec lists, andhanguplists all six reasons.sleepno longer accepts0or values below-1.send_digits.send_smsrequires non-empty numbers and a text body.toalias and the REFER states forsip_refer.play,prompt,record,record_call,stop_record_call)playloop, volume and text-to-speech settings, plusplay_result.promptinputs limited to supported values, with corrected outputs and callbacks.recordsupports directionboth; sensitivity bounds and themax_lengthdefault for both recording methods.stream,stop_stream,tap,transcribe,live_transcribe,live_translate,denoise,stop_denoise,detect_machine)taprtp_ptimelimits, and RTP targets must be public IPv4 addresses.live_transcribeandlive_translate, and the order of translation directions.start.hintsforlive_transcribe.connect,join_conference,join_room,enter_queue,pay)connectdocumentsstop_all_on_reject, ringback and codecs, and its confirmcondfollows the same rules ascond.join_conferencedropsresultand addsmin_participantsandemit_call_quality.enter_queuedocumentswhisper_urland corrects queue results.paydocuments ACH payments and its result variables.ai,amazon_bedrock,ai_sidecar)agent).startup_hookandhangup_hook.reset,gather_infoand top-levelsteps.data_map, actions and function parameters.amazon_bedrocknow lists only the prompt, params, functions anddata_mapfields it supports.ai_sidecarcorrects transcription, permissions, actions and tuning, and documents summarize requests, which don't needlang.reply,request,switch,execute,goto,transfer,return)replyrequires content; length limits, and queued vs. delivered status.requestresults and body serialization.switchmatches cases.executeandtransfer.The REST API reference changes only where it embeds SWML definitions. That covers SWML-based request bodies, the AI agent
hintsdescription, andcalling.ai_sidecar, which now also accepts a summarize request.Documents the schemas now reject
These changes affect schema validation only, for example editor tooling that uses the published JSON Schemas. Each change rejects input SignalWire already rejects, ignores or reads differently than the old docs suggested:
aiparams,pronounce.ignore_case, POMnumbered, functionactive, and webhookinput_args_as_paramsandforeach.max.digit_timeoutmust be between 1 and 29,999 ms, andhard_stop_timedoesn't accept unit suffixes.textis replaced byprompt.data_mapwebhooks accept onlyGETandPOST, and header values must be strings.toggle_functions.functiontakes a single name, andunset_global_data/unset_meta_datadon't accept an object.amazon_bedrockno longer acceptsai-only fields:confidence,max_tokensand penalties, and post-prompt tuningactive, thesayandhangupactions, and webhookrequire_argsattention_timeoutabove 60,000 msai_sidecar:directionmust list both call legs.cond,executeresults and theconnectconfirmcond: noelsebesidewhen/then, and no more than oneelse.labelandgotoreject an empty label.setandunsetaccept only plain variable names.sleeprejects0and values below-1.transferrejects an emptydest.requestheader values must be strings.connectrejects:parallel,serialandserial_parallellistshttp://streamstatus_urlon a destination insideparallel,serialorserial_parallel(the top-levelstatus_urlstill acceptshttp://)answerinside a confirmcondpromptrejects:say_gendervaluesmax_digits: 0status_urlthat doesn't use HTTP or HTTPSsaytextplay)recordandrecord_call:input_sensitivitymust be 0–100. Inrecord_call,control_idcan't contain{ } , ; ' \or line breaks outside${...}/%{...}references.detect_machinerejectsinitial_timeout,end_silence_timeout,machine_ready_timeout,machine_voice_thresholdandmachine_words_thresholdbelow1.join_conferenceno longer acceptsresult.live_translatedirectionneeds at least one entry.payrejects:security_codeandpostal_codeattemptson a payment prompt (the field isattempt)http://payment_connector_urlsend_smsrejects empty numbers and an empty text-only body.taprtp_ptimemust be a multiple of 10 between 10 and 120.replyrejects an empty string, or an emptymedialist with no body, including inside inlineswitchoutcomes.Linked issues
call:destination, nonexistenttransfer_after_bridgeproperty, and destination-format precision gaps #547:connectdestination formats, includingcall::modelsuffix in voice stringsai.languages,ai.SWAIGand Voices and languagesNot included
The older combined schema file
specs/swml/tsp-output/@typespec/json-schema/SWMLObject.jsonis no longer produced by the build, and this PR doesn't update it. The maintained schemas arespecs/swml/calling/...andspecs/swml/messaging/....Checks
yarn build:specspasses, and a rebuild reproduces the committed generated files.yarn fern-md-checkpasses.join_conference.max_participantsdefault (signalwire/docs-legacy#812)250in the spec and on the page. This follows Product's decision.100000whenmax_participantsisn't set (the conference controller's built-in default). That's the value the reference documented before this change. Until the platform default changes, a conference withmax_participantsunset still accepts more than 250 participants.max_participantsandmin_participantsis now250(was100000), so a document that sets either above 250 fails schema validation. The platform itself still accepts values up to 100000.min_participantsdescription no longer mentions the 100000 fallback.join_conferencehelper already defaults to and caps at 250.Closes signalwire/docs-legacy#812.
hangupreason SIP codes (signalwire/docs-legacy#810)reasondescription now names the SIP response sent for an unanswered inbound call:486 Busy Herewhen the reason is omitted,hangup, orbusy;603 Declinefor any other value. This follows the FreeSWITCH cause-to-SIP mapping (USER_BUSY→ 486,DECLINE→ 603).hangup_result, and a realistic example.Closes signalwire/docs-legacy#810.
connectfrom_name(signalwire/docs-legacy#811)from_namewas already documented on main. This PR adds the per-destination override and the length and character rules. The page states that it applies to SIP calls only; the platform sends it only to SIP destinations.Closes signalwire/docs-legacy#811.
live_translatelanguages (signalwire/docs-legacy#778, with #888)start.from_langandstart.to_langno longer link only to the text-to-speech voices page. Speech recognition has to recognize each language too:speech_engine, Deepgram Nova-3 by default. Both fields now say to use a code the engine recognizes (linking Deepgram's Nova-3 table) and that the voice speaking it supports. This answers the Slack report that the page listed only output languages. Thefrom_voice/to_voicewording was already fixed in this PR.Also resolves
These were already fixed by changes in this PR:
Pronounce.ignore_caseno longer documents a default the parser doesn't apply. ClosesPronounce.ignore_casedocuments a default the parser does not apply #595.ai.paramsno longer claims SWML variable support that isn't substituted. Closesai.paramsdocumentsSWMLVarsupport that is never substituted #596.promptspeech_engineis limited to the supported engines. Closes SWML prompt: constrain speech_engine in the calling schema to supported values #824.transferandexecutedocument section, URL, and inline document destinations. Closes [SWML Messaging] transfer and execute now accept a URL, section name, or inline document #510.join_conference_resultlists onlyjoinedandfailed, and the incorrectreturn_valueentry is removed (join_conferencenever sets it). Closesjoin_conferencereference lists five invalid result values #877.join_conference.resultis removed from the reference and the schema; the platform rejects it as an unknown parameter. Closes SWML join_conference: remove unsupported result input from reference and schema #821.ai.params.inner_dialog_syncedis documented as having no effect. Closes SWML AI: inner_dialog_synced is documented as a timing control but has no effect #822.ai.params.max_emotionis documented as having no effect. Closes SWML AI: max_emotion is documented as a voice control but has no effect #823.Remaining SWML issues (verified against source)
promptpage now has an example that setssay_voice,say_language, andspeech_language. Closes Improve SWMLpromptexamples docs-legacy#483.connectpage now has aringbackexample withanswer_on_bridge. Closes [DOC] - SWML connect lacks ringback examples docs-legacy#689.status_urlpayloads are documented on every method that acceptsstatus_url. Closes [DOC] - Get payload and events for new SMWL status_url docs-legacy#149.play.auto_answeris no longer listed; it's accepted but has no effect, becauseplayalways answers. Closes Document: can't early answer outbound docs-legacy#770.holdstep/timeout_stepare documented, and the two descriptions that said the object has onlytimeoutare fixed. Closes SWML spec: hold action is missingstepandtimeout_step#666.specs/swml/tsp-output/and the unused RESTai-agent/models/ai/tree.yarn build:specsoutput is unchanged by the deletion. Closes Delete the orphan spec artifacts: the RESTLanguagesBasefork andspecs/swml/tsp-output/#590./docs/swml/reference/ai…link now uses/docs/swml/reference/calling/ai…, and the brokendata-map#outputanchor is fixed. Closes Normalize/docs/swml/reference/ai/…links to carry thecalling/segment #599.#anchorlinks in commented-out spec text now use full paths. Closes Bare#anchorlinks in SWML spec@doctext do not resolve on the REST reference #608.aicorrections (Smallaireference corrections deferred from the #578 review #597):multiis Deepgram-only and switches between fewer languages;autofillers are skipped formulti; filler picks never repeat; a:0turn_filler_sourcessuffix doesn't clearturn_filler_min_ms; four internal fillers apply only to native functions;listen_languagetakes at most 3 codes; codes Nova-3 doesn't support fall back to Nova-2, then Google. Closes Smallaireference corrections deferred from the #578 review #597.params.provider, because which values are supported for customers needs Product/engineering; andacoustic_eot_*, which mod_openai marks as testing-only.params.double_turnsandlanguages[].double_turn_fillers. Closes Documentdouble_turns, thendouble_turn_fillers#589.ai_responsevariable on the Variables page. Closes SWML reference: document theai_responsevariable #618.Notes for reviewers
double_turnsbilling: it bills under its own SKU (ai_agent_double_turn_per_minute). The page says it's billed separately but gives no rate. Product should confirm the rate, and confirm the feature should be public.ai_responsewithpay(likely bug): the content-redaction guide and the Python SDK'spay()putset ai_responsebeforepay. In source,setfills in${pay_result}when it runs, which would leave it empty. The new reference text says to set it after the method; the guide and SDK default need a live test.OPENAI_ASR_ENGINEtodeepgram:nova-3. Engineering should confirm.Review follow-up (Manny's review of b6da4cb)
Merged
origin/main(a3a9cbc), then addressed the review in 1e7a589:pay: the "Successful tokenization" and "Failed tokenization" response tabs are back. A200reply with atoken_id, nocharge_idand no error succeeds whencharge_amountis omitted or all zeros, andpayment_tokenthen carries thattoken_id. With any other amount,token_idis ignored.security_codeis now typedstring, and bothsecurity_codeandpostal_codelist the string values the platform reads.prompt: nosay_voicedefault; the wording matchesplay.live_translate: a voice without a supported lowercase engine prefix falls back toazure.en-US-RyanMultilingualNeural. The spec examples now usepolly.instead ofPolly..connect: a per-destination streamstatus_urlmust behttps://; the top-levelstatus_urlaccepts either scheme, including for a singlestream:destination.detect_machine: the timing and threshold params must be at least1.send_digits: the page says that a sequence over 99 characters isn't sent but still setssend_digits_resulttosuccess.Notes for reviewers (review follow-up)
detect_machineminimum: taken from the current validator source. I couldn't confirm which revision is deployed.pay.postal_codewith a digits-only value (likely bug): the platform readspostal_codeas a boolean first, and any all-digit string counts as a number."94107"is read as true, so the caller is prompted and the value is not sent;"00000"is read as false. The page now says this and uses"K1A 0B1"as the pass-through example. Engineering should decide whether a 5-digit ZIP should pass through.live_translatevoice casing: the engine prefix check is case-sensitive, soPolly.Joannafalls back to the Azure voice. No other live_translate page used a capitalized prefix.