Merge branch 'main' into worktree-swml-transcribe-docs

Author: Devon-White

fern/apis/signalwire-rest/openapi.yaml

@@ -36532,6 +36532,11 @@ components:
           examples:
             - - notification
               - order-confirmation
+        status_callback:
+          type: string
+          description: URL to receive delivery status callbacks for the outbound message (e.g., `queued`, `sent`, `delivered`, `failed`). Not set if not specified. The callback uses the [message status callback payload](/docs/apis/rest/messages/webhooks/message-status-callback).
+          examples:
+            - https://example.com/message_status
         body:
           type: string
           description: Required if `media` is not present. The body of the SMS message.
@@ -36570,6 +36575,11 @@ components:
           examples:
             - - notification
               - order-confirmation
+        status_callback:
+          type: string
+          description: URL to receive delivery status callbacks for the outbound message (e.g., `queued`, `sent`, `delivered`, `failed`). Not set if not specified. The callback uses the [message status callback payload](/docs/apis/rest/messages/webhooks/message-status-callback).
+          examples:
+            - https://example.com/message_status
         media:
           type: array
           items:

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

@@ -46,6 +46,11 @@ The `send_sms` object accepts the following properties depending on the message
 </ParamField>
 
 
+<ParamField path="send_sms.status_callback" type="string" toc={true}>
+  URL to receive delivery status callbacks for the outbound message (e.g., `queued`, `sent`, `delivered`, `failed`). Default is not set. See [Status callbacks](#status-callbacks) below.
+</ParamField>
+
+
 </Tab>
 <Tab title="MMS">
 
@@ -79,6 +84,11 @@ The `send_sms` object accepts the following properties depending on the message
 </ParamField>
 
 
+<ParamField path="send_sms.status_callback" type="string" toc={true}>
+  URL to receive delivery status callbacks for the outbound message (e.g., `queued`, `sent`, `delivered`, `failed`). Default is not set. See [Status callbacks](#status-callbacks) below.
+</ParamField>
+
+
 </Tab>
 </Tabs>
 
@@ -88,6 +98,19 @@ Set by the method:
 
 - **send_sms_result:** (out) `success` | `failed`.
 
+## **Status callbacks**
+
+When `status_callback` is set, SignalWire sends an HTTP `POST` to that URL each time the outbound
+message transitions to a new state. Callback delivery is independent of SWML execution: the document
+continues as soon as the message is accepted, and delivery-state callbacks fire afterwards.
+
+The callback uses the same payload as other outbound messages sent through SignalWire:
+
+<WebhookPayloadSnippet webhook="messageStatusCallback" />
+
+See the [Message status callback](/docs/apis/rest/messages/webhooks/message-status-callback)
+webhook page for the full field reference and the list of possible `status` values.
+
 ## **Examples**
 
 <Tabs>
@@ -168,5 +191,44 @@ sections:
 </CodeBlock>
 </CodeBlocks>
 
+</Tab>
+<Tab title="Status callbacks">
+
+Send a message and receive delivery status updates at a callback URL:
+
+<CodeBlocks>
+<CodeBlock title="YAML">
+```yaml
+version: 1.0.0
+sections:
+  main:
+    - send_sms:
+        from_number: "+155512312345"
+        to_number: "+15555554321"
+        body: "Hi, I hope you're well."
+        status_callback: "https://example.com/message_status"
+```
+</CodeBlock>
+<CodeBlock title="JSON">
+```json
+{
+  "version": "1.0.0",
+  "sections": {
+    "main": [
+      {
+        "send_sms": {
+          "from_number": "+155512312345",
+          "to_number": "+15555554321",
+          "body": "Hi, I hope you're well.",
+          "status_callback": "https://example.com/message_status"
+        }
+      }
+    ]
+  }
+}
+```
+</CodeBlock>
+</CodeBlocks>
+
 </Tab>
 </Tabs>

specs/swml/calling/Methods/send_sms/main.tsp

@@ -21,6 +21,10 @@ model SMSBase {
   @doc("Array of tags to associate with the message to facilitate log searches.")
   @example(#["notification", "order-confirmation"])
   tags?: string[];
+
+  @doc("URL to receive delivery status callbacks for the outbound message (e.g., `queued`, `sent`, `delivered`, `failed`). Not set if not specified. The callback uses the [message status callback payload](/docs/apis/rest/messages/webhooks/message-status-callback).")
+  @example("https://example.com/message_status")
+  status_callback?: string;
 }
 
 @summary("SMS")

specs/swml/calling/tsp-output/@typespec/json-schema/SWMLObject.json

@@ -4363,6 +4363,13 @@
                     ],
                     "description": "Array of tags to associate with the message to facilitate log searches."
                 },
+                "status_callback": {
+                    "type": "string",
+                    "examples": [
+                        "https://example.com/message_status"
+                    ],
+                    "description": "URL to receive delivery status callbacks for the outbound message (e.g., `queued`, `sent`, `delivered`, `failed`). Not set if not specified. The callback uses the [message status callback payload](/docs/apis/rest/messages/webhooks/message-status-callback)."
+                },
                 "body": {
                     "type": "string",
                     "examples": [
@@ -4418,6 +4425,13 @@
                     ],
                     "description": "Array of tags to associate with the message to facilitate log searches."
                 },
+                "status_callback": {
+                    "type": "string",
+                    "examples": [
+                        "https://example.com/message_status"
+                    ],
+                    "description": "URL to receive delivery status callbacks for the outbound message (e.g., `queued`, `sent`, `delivered`, `failed`). Not set if not specified. The callback uses the [message status callback payload](/docs/apis/rest/messages/webhooks/message-status-callback)."
+                },
                 "media": {
                     "type": "array",
                     "items": {