SWML: fix shipped doc defects and document messaging transfer/execute dest forms (#510)

fern/products/swml/pages/get-started/index.mdx

@@ -150,12 +150,14 @@ paths in each context.
 When SignalWire fetches a SWML script from an external URL, it sends a POST request whose payload
 shape depends on the document type:
 
-- **Calling** — see [Calling SWML → Document-fetching webhook](/docs/swml/reference/calling#document-fetching-webhook).
-- **Messaging** — see [Messaging SWML → Document-fetching webhook](/docs/swml/reference/messaging#document-fetching-webhook).
-
-Your server must respond with a valid SWML document using one of these content types:
-`application/json`, `application/yaml`, or `text/x-yaml`. For server setup instructions, see the
-[Deployment guide](/docs/swml/guides/deployment).
+- **Calling** — see [Calling SWML → Webhook and variable payload](/docs/swml/reference/calling#webhook-payload).
+- **Messaging** — see [Messaging SWML → Webhook and variable payload](/docs/swml/reference/messaging#webhook-payload).
+
+Your server must respond with a valid SWML document as JSON or YAML. Both document types
+determine the format from the response body rather than from the `Content-Type` header, so a
+missing or mismatched content type does not on its own cause a failure. Sending an accurate one
+(`application/json`, `application/yaml`, or `text/x-yaml`) is still good practice. For server
+setup instructions, see the [Deployment guide](/docs/swml/guides/deployment).
 
 ## Next steps
 

fern/products/swml/pages/reference/errors.mdx

@@ -24,14 +24,16 @@ message describing the offending method, parameter, or condition. You can read t
 `script_error` variable on the call session or from the payload of the `calling.script.warning`
 event.
 
+### Document level
+
 <ParamField path="relay_script_parse_error" type="string" toc={true}>
-  The fetched document could not be parsed as valid JSON or YAML, or the `dest` URL of a `transfer`
-  was malformed.
+  The fetched document could not be parsed as valid JSON or YAML, or the `dest` of a `transfer` or
+  `execute` was malformed.
 </ParamField>
 
 <ParamField path="relay_script_parse_internal_error" type="string" toc={true}>
-  An internal parsing error occurred while reading the document. Verify the document is valid
-  YAML or JSON and retry.
+  The YAML parser failed internally while reading the document. A document that fails to parse as
+  JSON reports `relay_script_parse_error` instead.
 </ParamField>
 
 <ParamField path="relay_script_version_invalid" type="string" toc={true}>
@@ -47,11 +49,12 @@ event.
 </ParamField>
 
 <ParamField path="relay_script_section_code_missing" type="string" toc={true}>
-  A section is defined but contains no executable steps.
+  A section defined in object form has no `code` key. A section written directly as an array of
+  steps does not need one.
 </ParamField>
 
 <ParamField path="relay_script_section_parameter_undefined" type="string" toc={true}>
-  An `execute` step references a section that does not exist in the document.
+  A section defined in object form contains a key other than `code` or `meta`.
 </ParamField>
 
 <ParamField path="relay_script_element_undefined" type="string" toc={true}>
@@ -64,14 +67,17 @@ event.
 </ParamField>
 
 <ParamField path="relay_script_element_invalid_value" type="string" toc={true}>
-  A document element has an invalid value (for example, an enum-valued field set to an unrecognized
-  string).
+  A step's `label` is present but its value is an empty string. A `label` that is not a string
+  reports `relay_script_element_wrong_type`, and an out-of-range value on a method parameter
+  reports `relay_script_method_parameter_invalid_value`.
 </ParamField>
 
 <ParamField path="relay_script_element_duplicated" type="string" toc={true}>
   A document element that may appear at most once was provided multiple times.
 </ParamField>
 
+### Method level
+
 <ParamField path="relay_script_method_missing_name" type="string" toc={true}>
   A step in a section does not have a method name (the step entry is malformed).
 </ParamField>
@@ -108,48 +114,75 @@ event.
   cause.
 </ParamField>
 
+### Runtime
+
 <ParamField path="relay_script_js_eval_error" type="string" toc={true}>
   A JavaScript expression in a `cond`, `switch`, `eval`, or `when` clause raised an error.
 </ParamField>
 
 <ParamField path="relay_script_nested_too_deep" type="string" toc={true}>
-  A document or one of its sections is nested beyond the maximum depth.
+  A section or a nested method block exceeds the maximum nesting depth of 32. A chain of documents
+  nested too deeply reports `relay_script_internal_error` instead.
 </ParamField>
 
 <ParamField path="relay_script_too_many_transfers" type="string" toc={true}>
-  The chain of `transfer` and `goto` steps exceeded the platform maximum (32 transfers per call).
+  The chain of `transfer` and `goto` steps exceeded a platform maximum: 32 in total, or 8 without
+  caller interaction. The call is disconnected.
 </ParamField>
 
 <ParamField path="relay_script_internal_error" type="string" toc={true}>
-  An internal server error occurred during script execution.
+  An internal server error occurred during script execution. This also covers a chain of documents
+  reached through `execute` or `transfer` that is nested beyond the platform limit, in which case
+  the call is disconnected.
 </ParamField>
 
 ## Messaging errors
 
-Errors emitted when an inbound message's SWML document fails to fetch, parse, or execute. Each
-inbound message is marked `failed` with the listed `error_code` and a corresponding
-`error_message`, visible in the [Messaging logs](/docs/apis/rest/message-logs/list-message-logs).
+Errors emitted when an inbound message's SWML document fails to fetch, parse, or execute. The
+`error_code` and a corresponding `error_message` are recorded on the inbound message and are
+visible in the [Messaging logs](/docs/apis/rest/message-logs/list-message-logs). Every code below
+marks the message `failed`, with the exception of `message_filtered`, which flags the message and
+lets processing continue.
 
 ### Document fetch / route
 
-<ParamField path="unrouteable_message" type="string" toc={true}>
-  Unrouteable message received — no SWML handler is assigned to the inbound number.
+These codes cover accepting the inbound message, screening it, and fetching the handler assigned
+to its number.
+The granular fetch codes below, along with `json_or_yaml_required`, are reachable only from that
+initial fetch. A document fetch that fails partway through a run, from a `transfer` or an `execute`
+step, always reports that method's own fetch code regardless of the underlying cause.
+
+<ParamField path="unrouteable_message_received" type="string" toc={true}>
+  No inbound route exists for the destination number, so the message could not be accepted.
 </ParamField>
 
-<ParamField path="insufficient_balance" type="string" toc={true}>
-  Insufficient account balance to receive the message.
+<ParamField path="insufficient_balance_to_receive_message" type="string" toc={true}>
+  Insufficient account balance to receive the message. The message is marked `failed` and the SWML
+  document is never fetched.
 </ParamField>
 
 <ParamField path="message_filtered" type="string" toc={true}>
-  Message filtered (e.g. spam detection or carrier-level filtering).
+  The inbound message was flagged as spam. The message is not marked `failed` and your SWML
+  document still runs, but the message body is withheld from the message logs and from API
+  responses.
+</ParamField>
+
+<ParamField path="swml_invalid_message_handler" type="string" toc={true}>
+  The handler assigned to the inbound number is a Call Flow or an AI Agent rather than a SWML
+  script.
 </ParamField>
 
 <ParamField path="http_retrieval_error" type="string" toc={true}>
-  The attempt to retrieve the SWML document timed out or failed.
+  The request for the SWML document never completed. The connection failed, or the request timed
+  out before a response arrived. An endpoint that answers with a non-2xx status reports
+  `url_failed_to_parse` instead.
 </ParamField>
 
 <ParamField path="url_failed_to_parse" type="string" toc={true}>
-  The configured SWML URL could not be parsed.
+  The endpoint answered with a non-2xx status, the configured URL is not well-formed, or the
+  response was sent with a JSON content type but a body that is not valid JSON. A non-2xx status
+  is the most common cause in practice, so check what your endpoint returns before auditing the
+  URL itself.
 </ParamField>
 
 ### Document parse
@@ -189,7 +222,7 @@ inbound message is marked `failed` with the listed `error_code` and a correspond
 </ParamField>
 
 <ParamField path="swml_reply_invalid_from_number" type="string" toc={true}>
-  The reply `from` number is not a valid PhoneRoute or ShortCode in this project.
+  The reply `from` number is not a number assigned to this project.
 </ParamField>
 
 <ParamField path="swml_reply_invalid_to_number" type="string" toc={true}>
@@ -222,7 +255,18 @@ inbound message is marked `failed` with the listed `error_code` and a correspond
 ### `execute` method
 
 <ParamField path="swml_section_not_found" type="string" toc={true}>
-  The section named by `execute.dest` is not defined in the current document.
+  The section named by `execute.dest` or `transfer.dest` is not defined in the document currently
+  in scope. A `dest` that is neither a URL nor a parseable inline document is read as a section
+  name, so a malformed destination reports this code rather than a fetch or parse error.
+</ParamField>
+
+<ParamField path="swml_execute_fetch_failed" type="string" toc={true}>
+  Failed to fetch the executed SWML document from the destination URL. Covers a non-2xx response, a
+  timeout, an unparseable URL, or a body that is neither JSON nor YAML.
+</ParamField>
+
+<ParamField path="swml_execute_document_invalid" type="string" toc={true}>
+  The executed SWML document is not a valid messaging document.
 </ParamField>
 
 ### `transfer` method
@@ -232,13 +276,18 @@ inbound message is marked `failed` with the listed `error_code` and a correspond
 </ParamField>
 
 <ParamField path="swml_transfer_fetch_failed" type="string" toc={true}>
-  Failed to fetch the transferred SWML document from the destination URL.
+  Failed to fetch the transferred SWML document from the destination URL. Covers a non-2xx
+  response, a timeout, an unparseable URL, an unsupported HTTP method, or a body that is neither
+  JSON nor YAML.
 </ParamField>
 
 <ParamField path="swml_transfer_document_invalid" type="string" toc={true}>
   The transferred SWML document is not a valid messaging document.
 </ParamField>
 
+`transfer` to a section name that is not defined also reports
+[`swml_section_not_found`](#swml_section_not_found).
+
 ### `goto` method
 
 <ParamField path="swml_goto_label_not_found" type="string" toc={true}>
@@ -250,3 +299,10 @@ inbound message is marked `failed` with the listed `error_code` and a correspond
 <ParamField path="swml_request_url_required" type="string" toc={true}>
   `request.url` is required and was missing or empty.
 </ParamField>
+
+### General
+
+<ParamField path="swml_unknown_error" type="string" toc={true}>
+  An unexpected error occurred while executing the document. Contact support with the message ID if
+  this repeats.
+</ParamField>

fern/products/swml/pages/reference/methods/calling/connect/index.mdx

@@ -63,6 +63,14 @@ Dial a single destination directly using the `to` property.
   The encryption method to use for the call. Possible values: `mandatory`, `optional`, `forbidden`.
 </ParamField>
 
+<ParamField path="connect.execute_after_queue" type="string" toc={true}>
+  SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends. Applies only when connecting to a queue (when `to` starts with `queue:`); without it, the call hangs up when the queue interaction ends.
+
+  Can be either:
+  - A URL (http or https) that returns a SWML document
+  - An inline SWML document (as a JSON string)
+</ParamField>
+
 <ParamField path="connect.from" type="string" default="Calling party's caller ID number" toc={true}>
   Caller ID number. Optional.
 </ParamField>
@@ -122,16 +130,6 @@ Dial a single destination directly using the `to` property.
   Maximum time, in seconds, to wait for an answer.
 </ParamField>
 
-<ParamField path="connect.transfer_after_bridge" type="string" toc={true}>
-  SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.
-
-  Can be either:
-  - A URL (http or https) that returns a SWML document
-  - An inline SWML document (as a JSON string)
-
-  Required when connecting to a queue (when `to` starts with `queue:`).
-</ParamField>
-
 <ParamField path="connect.username" type="string" toc={true}>
   SIP authentication username (`sip_auth_username`) for the outbound leg. **Only applies to [SIP URI](/docs/platform/voice/sip) targets** — ignored for phone, Resource Address, queue, and stream destinations.
 </ParamField>
@@ -353,14 +351,6 @@ Dial multiple destinations simultaneously — the first to answer is bridged and
   Maximum time, in seconds, to wait for an answer.
 </ParamField>
 
-<ParamField path="connect.transfer_after_bridge" type="string" toc={true}>
-  SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.
-
-  Can be either:
-  - A URL (http or https) that returns a SWML document
-  - An inline SWML document (as a JSON string)
-</ParamField>
-
 <ParamField path="connect.webrtc_media" type="boolean" default="false" toc={true}>
   If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers.
 </ParamField>
@@ -563,14 +553,6 @@ Dial destinations in sequence — each destination is tried one at a time, movin
   Maximum time, in seconds, to wait for an answer.
 </ParamField>
 
-<ParamField path="connect.transfer_after_bridge" type="string" toc={true}>
-  SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.
-
-  Can be either:
-  - A URL (http or https) that returns a SWML document
-  - An inline SWML document (as a JSON string)
-</ParamField>
-
 <ParamField path="connect.webrtc_media" type="boolean" default="false" toc={true}>
   If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers.
 </ParamField>
@@ -775,14 +757,6 @@ Combine both strategies. The outer array is the **serial** dimension — groups
   Maximum time, in seconds, to wait for an answer.
 </ParamField>
 
-<ParamField path="connect.transfer_after_bridge" type="string" toc={true}>
-  SWML to execute after the bridge completes. This defines what should happen after the call is connected and the bridge ends.
-
-  Can be either:
-  - A URL (http or https) that returns a SWML document
-  - An inline SWML document (as a JSON string)
-</ParamField>
-
 <ParamField path="connect.webrtc_media" type="boolean" default="false" toc={true}>
   If true, WebRTC media is offered to the SIP endpoint. Has no effect on calls to phone numbers.
 </ParamField>
@@ -1422,7 +1396,7 @@ sections:
 </CodeBlock>
 </CodeBlocks>
 
-### Connect to a queue with transfer after bridge
+### Connect to a queue with SWML to run afterward
 
 <CodeBlocks>
 <CodeBlock title="YAML">
@@ -1432,7 +1406,7 @@ sections:
   main:
     - connect:
         to: "queue:support"
-        transfer_after_bridge: "https://example.com/post-call-swml"
+        execute_after_queue: "https://example.com/post-call-swml"
 ```
 </CodeBlock>
 <CodeBlock title="JSON">
@@ -1444,7 +1418,7 @@ sections:
       {
         "connect": {
           "to": "queue:support",
-          "transfer_after_bridge": "https://example.com/post-call-swml"
+          "execute_after_queue": "https://example.com/post-call-swml"
         }
       }
     ]

fern/products/swml/pages/reference/methods/calling/enter_queue.mdx

@@ -9,7 +9,7 @@ max-toc-depth: 3
 Place the current call in a named queue where it will wait to be connected to an available agent or resource.
 While waiting, callers will hear music or custom audio. 
 When an agent connects to the queue (using the [`connect`](/docs/swml/reference/calling/connect) method), the caller and agent are bridged together.
-After the bridge completes (when the agent or caller hangs up), execution continues with the SWML script specified in `transfer_after_bridge`.
+After the bridge completes (when the agent or caller hangs up), execution continues with the SWML script specified in `execute_after_queue`. Without that property, the call hangs up instead.
 
 ## **Properties**
 
@@ -24,9 +24,9 @@ After the bridge completes (when the agent or caller hangs up), execution contin
 </ParamField>
 
 
-<ParamField path="enter_queue.transfer_after_bridge" type="string" required={true} toc={true}>
-  SWML to execute after the bridge completes (when the agent or caller hangs up). This defines what should happen after the call is connected to an agent and the bridge ends.
-  
+<ParamField path="enter_queue.execute_after_queue" type="string" toc={true}>
+  SWML to execute after the bridge completes (when the agent or caller hangs up). This defines what should happen after the call is connected to an agent and the bridge ends. Without this property, the call hangs up when the queue interaction ends.
+
   Can be either:
   - A URL (http or https) that returns a SWML document
   - An inline SWML document (as a JSON string)
@@ -280,7 +280,7 @@ sections:
   main:
     - enter_queue:
         queue_name: "my_queue"
-        transfer_after_bridge: "https://example.com/post-call-swml"
+        execute_after_queue: "https://example.com/post-call-swml"
 ```
 </CodeBlock>
 <CodeBlock title="JSON">
@@ -292,7 +292,7 @@ sections:
       {
         "enter_queue": {
           "queue_name": "my_queue",
-          "transfer_after_bridge": "https://example.com/post-call-swml"
+          "execute_after_queue": "https://example.com/post-call-swml"
         }
       }
     ]
@@ -314,7 +314,7 @@ sections:
         queue_name: "sales_queue"
         status_url: "https://example.com/queue-status"
         wait_time: 1800
-        transfer_after_bridge: "https://example.com/post-call-swml"
+        execute_after_queue: "https://example.com/post-call-swml"
 ```
 </CodeBlock>
 <CodeBlock title="JSON">
@@ -328,7 +328,7 @@ sections:
           "queue_name": "sales_queue",
           "status_url": "https://example.com/queue-status",
           "wait_time": 1800,
-          "transfer_after_bridge": "https://example.com/post-call-swml"
+          "execute_after_queue": "https://example.com/post-call-swml"
         }
       }
     ]