Skip to navigation
Calling

send_sms

View as MarkdownOpen in Claude

Send an outbound message to a PSTN phone number.

Properties

send_sms
objectRequired

An object that accepts the following properties. Supports both SMS and MMS messages. See message types below for the properties specific to each type.

Message types

The send_sms object accepts the following properties depending on the message type:

send_sms.to_number
stringRequired

Phone number to send SMS message to in e.164 format. Must not be empty, including after variable expansion.

send_sms.from_number
stringRequired

Phone number SMS message will be sent from. Must not be empty, including after variable expansion.

send_sms.body
stringRequired

Body of the text message. Must not be empty, including after variable expansion.

send_sms.region
stringDefaults to Chosen based on account preferences or device location

Region of the world to originate the message from

send_sms.tags
string[]

Array of tags to associate with the message to facilitate log searches

send_sms.status_callback
string

URL to receive delivery status callbacks for the outbound message (e.g., queued, sent, delivered, failed). Default is not set. See Status callbacks below.

Variables

Set by the method:

  • send_sms_result: (out) success | failed. success means the message was accepted for sending (the submission returned an HTTP 2xx status); delivery can still fail later, so use status callbacks to track it. failed covers execution errors, such as a missing body or phone number after variable expansion, and any other HTTP status. A document that fails validation stops before this method runs, so the method sets neither variable.
  • send_sms_response_code: (out) The HTTP status code returned when the message was submitted, stored as a string (for example, "200"). It’s "0" when no HTTP status was received. It’s only updated when the message is submitted, so after an execution error that happens before submission it may still hold a value from an earlier send_sms. It isn’t a message ID, a delivery status, or a carrier error code.

Status callbacks

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

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.

Payload
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"project_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"status": "delivered",
"to": "+15551234567",
"from": "+15559876543",
"body": "Hello World!",
"number_of_segments": 1,
"timestamp": "2026-03-17T22:26:57Z",
"error_code": null,
"error_message": null
}

See the Message status callback webhook page for the full field reference and the list of possible status values.

Examples

Send a text-only message:

version: 1.0.0
sections:
main:
- send_sms:
from_number: "+155512312345"
to_number: "+15555554321"
body: "Hi, I hope you're well."