For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inSign up
Support
  • Core
    • Overview
    • Authorization
    • Base URL
    • Data formats
    • Paging
    • Error codes
    • Permissions
  • Calling
  • Datasphere
  • Logs
  • Messaging
      • PATCHRedact a message
      • POSTSend a message
  • Phone Number Management
  • Platform
  • Resource Management
LogoLogoSignalWire Docs
Log inSign up
Support
MessagingMessages

Send a message

|View as Markdown|Open in Claude|
POST
https://{your_space_name}.signalwire.com/api/messaging/messages
POST
/api/messaging/messages
$curl -X POST https://{your_space_name}.signalwire.com/api/messaging/messages \
>     -H "Content-Type: application/json" \
>     -u "<project_id>:<api_token>" \
>     -d '{
>  "to": "+15551234567",
>  "from": "+15559876543"
>}'
1{
2  "id": "c2d3e4f5-a6b7-8901-cdef-234567890abc",
3  "from": "+15559876543",
4  "to": "+15551234567",
5  "body": "Your order #12345 has shipped!",
6  "status": "queued",
7  "direction": "outbound",
8  "kind": "sms",
9  "media": [],
10  "number_of_segments": 1,
11  "error_code": null,
12  "error_message": null,
13  "created_at": "2024-05-06T12:20:00Z",
14  "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
15  "status_callback_url": null,
16  "message_uri": "/api/messaging/logs/c2d3e4f5-a6b7-8901-cdef-234567890abc"
17}
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](/docs/platform/your-signalwire-api-space).
Was this page helpful?
Previous

Create brand

Next
Built with

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.

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.
tostringRequired

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

fromstringRequired

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.

bodystringOptional

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

medialist of stringsOptional
Array of HTTP or HTTPS URLs for media attachments. Presence of media makes the message MMS. Maximum 8 items.
send_as_mmsbooleanOptionalDefaults to false
Force the message to be sent as MMS even when no media attachments are provided.
status_callbackstringOptionalformat: "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.

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

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)