Skip to navigation
Compatibility REST APIMessages

Create a Message

View as MarkdownOpen in Claude

Sends a message through the account and creates a Message resource for tracking its delivery. Use this form-encoded route for SID-based integrations; use SignalWire REST Send a message for a JSON request.

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.

Authentication

AuthorizationBasic

SignalWire Basic Authentication using Project ID and API Token.

The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.

Example:

Authorization: Basic base64(project_id:token)

Path parameters

AccountSidstringRequiredformat: "uuid"
The unique identifier of the project that sent or received this message.

Request

This endpoint expects an object.
TostringRequired
The phone number in E.164 format that will receive the message.
FromstringOptional

The phone number in E.164 format that will send the message. Either From or MessagingServiceSid must be provided.

BodystringOptional

The text of the message. Either Body or MediaUrl must be provided.

MediaUrlstring or list of stringsOptional

URL(s) of media you wish to attach and send with the message. Can be specified multiple times for up to 8 media items.

SendAsMmsbooleanOptional
When set to true, forces the message to be sent as an MMS.
ApplicationSidstringOptionalformat: "uuid"
The SID of a SignalWire cXML Application used to configure the message's status callback.
MaxPricestringOptionalformat: "^\d+\.?\d{0,4}$"

The maximum price in USD acceptable for the message to be sent. Format: decimal with up to 4 decimal places.

StatusCallbackstringOptionalformat: "uri"

A URL endpoint to receive callbacks each time the status of the message changes. See the SMS status callback webhook for the payload your URL will receive.

ValidityPeriodintegerOptional1-172800Defaults to 14400

The number of seconds a message will allow being queued before canceling. Must be between 1 and 172800 (48 hours). Default is 14400 (4 hours).

MessagingServiceSidstringOptionalformat: "uuid"

The ID of a number group to use when sending the message. Either From or MessagingServiceSid must be provided.

Response

Response returned when a message is created.
account_sidstringformat: "uuid"
The unique identifier of the project that sent or received this message.
api_versionstring
The version number of the SignalWire cXML REST API used to handle this message.
bodystring or null
The text of the message. Up to 1600 characters long. May be null if filtered for spam.
num_segmentsinteger
The number of segments that make up the entire message.
num_mediainteger
The number of media files that were included with the message.
date_createdstring
The date and time the message was created in RFC 2822 format.
date_sentstring or null
The date and time the message was sent in RFC 2822 format, or null if not yet sent.
date_updatedstring
The date and time the message was last updated in RFC 2822 format.
directionenum
The direction of the message.
Allowed values:
error_codestring or null
If an error has occurred on the message, the error code will give you a specific code, or null if no error.
error_messagestring or null
A human readable description of the error that occurred, or null if no error.
fromstring
The phone number in E.164 format that sent the message.
pricefloat or null
The cost of the individual message billed to your project, or null if not yet calculated.
price_unitstring

The currency in which price is charged as.

sidstringformat: "uuid"
A unique ID that identifies this specific message.
statusenum
Current status of the message.
tostring
The phone number in E.164 format that received the message.
messaging_service_sidstring or nullformat: "uuid"
If a number group was used when sending an outbound message, the number group's ID will be present, or null otherwise.
uristring
The URI of this particular message.
subresource_urisobject
The URIs for any subresources associated with this message.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error