Skip to navigation
MessagingMessages

Send a message

View as MarkdownOpen in Claude

Create and queue an outbound message for delivery. The channel is determined by the from number:

  • SMS/MMS when from is a purchased SignalWire phone number or shortcode. The message is MMS when media is present or send_as_mms is set, otherwise SMS.
  • WhatsApp when from is a whatsapp:-prefixed WhatsApp number. Set message_type for a content message, or template_id for an approved template. Free-form WhatsApp content is only allowed within the 24-hour customer service window.

Use this SignalWire REST operation for JSON requests. Integrations built around form-encoded requests and Message SIDs can use the Compatibility API’s Create message operation instead.

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)

Request

This endpoint expects an object.
Message.CreateMessageRequestobjectRequired
Request body for sending a new SMS or MMS message.
OR
Message.WhatsAppContentMessageRequestobjectRequired

A WhatsApp content message. The message_type field determines the shape of body.

OR
Message.WhatsAppTemplateMessageRequestobjectRequired

Send an approved WhatsApp template. Use this to reach a customer for the first time or outside the 24-hour window. Do not include body or message_type.

Response

Response returned when a message is successfully created and queued for delivery.
idstringformat: "uuid"

The unique ID of the message. This is the MessageSegment ID, consistent with the dashboard and the /api/messaging/logs endpoint.

fromstring
The source phone number.
tostring
The destination phone number.
bodystring
The message body text. Returns an empty string when the message has been redacted.
statusenum
Delivery state of the message.
directionenum
The direction of the message.
Allowed values:
kindenum
The kind of message.
Allowed values:
medialist of strings
Array of URLs for any media attachments on the message. Empty for SMS.
number_of_segmentsinteger
Number of segments the message body was split into for delivery.
error_codestring or null

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

error_messagestring or null

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

created_atdatetime
Date and time when the message was created.
project_idstringformat: "uuid"
The ID of the project the message belongs to.
status_callback_urlstring or nullformat: "uri"
Callback URL configured to receive message status events. Null if no callback was configured.
message_uristring

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

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
500
Internal Server Error