Sign in
Messages

Send a message

Create and queue an outbound SMS or MMS message for delivery. The system determines whether the message is SMS or MMS based on the presence of media or the send_as_mms flag. The from number must be a purchased SignalWire phone number on the authenticated project.

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Messaging.

Learn more about API scopes.

post/api/messaging/messages

Request body

tostring required

Destination phone number in E.164 format (+ followed by 5-17 digits). Also accepts passthrough numbers like 988/+988.

fromstring required

Source phone number. Must be a purchased SignalWire phone number on the project in E.164 format, or a shortcode (5-6 digits). Verified caller IDs are not permitted.

bodystring

Message body text. Required if media is not provided. Subject to provider-specific character limits.

mediastring[]

Array of HTTP or HTTPS URLs for media attachments. Presence of media makes the message MMS. Maximum 8 items.

send_as_mmsboolean

Force the message to be sent as MMS even when no media attachments are provided.

status_callbackstring uri

A valid URL to receive message status callback events at each state change. See the Message status callback webhook for the payload your URL will receive.

custom_variablesobject

Your own key/value string pairs to attach to the message — for example, an order or case number you want to recognize later. When you also set status_callback, SignalWire includes these pairs as a custom_variables object in every status callback it sends to that URL, so you can match each callback to a record in your own system. If you don't set status_callback, there is nowhere for the variables to be delivered.

Each value must be a non-empty string of at most 1024 bytes. You can send at most 20 pairs. Each key must start with a letter or underscore and contain only letters, numbers, and underscores, and cannot begin with the reserved prefixes signalwire_, sw_, rtc_, or internal_ (case-insensitive). Keys are case-sensitive.

Example request

{
  "to": "+15551234567",
  "from": "+15559876543",
  "body": "Your order #12345 has shipped!",
  "media": [
    "https://example.com/tracking.png"
  ],
  "status_callback": "https://example.com/webhooks/message-status",
  "custom_variables": {
    "id": "12345",
    "case_number": "54321"
  }
}

Response

Response returned when a message is successfully created and queued for delivery.

idstring uuid required

Universal Unique Identifier.

fromstring required

The source phone number.

tostring required

The destination phone number.

bodystring required

The message body text. Returns an empty string when the message has been redacted.

status'queued' | 'initiated' | 'sent' | 'delivered' | 'undelivered' | 'failed' | 'read' required

Delivery state of a message.

direction'inbound' | 'outbound' required

The direction of a message.

kind'sms' | 'mms' required

The kind of message.

mediastring[] required

Array of URLs for any media attachments on the message. Empty for SMS.

number_of_segmentsinteger required

Number of segments the message body was split into for delivery.

error_codestring nullable required

Provider-specific error code if delivery failed. Null when no error occurred.

error_messagestring nullable required

Human-readable error message if delivery failed. Null when no error occurred.

created_atstring date-time required

Date and time when the message was created.

project_idstring uuid required

Universal Unique Identifier.

status_callback_urlstring uri nullable required

Callback URL configured to receive message status events. Null if no callback was configured.

message_uristring required

Relative URL for retrieving the message via the /api/messaging/logs endpoint.

Example response

{
  "from": "+15559876543",
  "to": "+15551234567",
  "body": "Your order #12345 has shipped!",
  "media": [],
  "number_of_segments": 1,
  "created_at": "2024-05-06T12:20:00Z",
  "message_uri": "/api/messaging/logs/c2d3e4f5-a6b7-8901-cdef-234567890abc"
}

Changes