REST ClientMessages

create

View as MarkdownOpen in Claude

messages.create

Send an outbound SMS or MMS message. The from_ number determines the channel; pass media or send_as_mms=True to send an MMS.

Request

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

idstringRequiredformat: "uuid"
The unique ID of the message. This is the `MessageSegment` ID, consistent with the dashboard and the `/api/messaging/logs` endpoint.
fromstringRequired
The source phone number.
tostringRequired
The destination phone number.
bodystringRequired
The message body text. Returns an empty string when the message has been redacted.
statusenumRequired
Delivery state of the message.
directionenumRequired
The direction of the message.
kindenumRequired
The kind of message.
medialist of stringsRequired
Array of URLs for any media attachments on the message. Empty for SMS.
number_of_segmentsintegerRequired
Number of segments the message body was split into for delivery.
error_codestring or nullRequired
Provider-specific error code if delivery failed. Null when no error occurred.
error_messagestring or nullRequired
Human-readable error message if delivery failed. Null when no error occurred.
created_atdatetimeRequired
Date and time when the message was created.
project_idstringRequiredformat: "uuid"
The ID of the project the message belongs to.
status_callback_urlstring or nullRequiredformat: "uri"
Callback URL configured to receive message status events. Null if no callback was configured.
message_uristringRequired
Relative URL for retrieving the message via the `/api/messaging/logs` endpoint.

Parameters

All parameters are keyword-only.

to
strRequired

Destination phone number in E.164 format.

from_
strRequired

Sending phone number in E.164 format. It must belong to your project. The trailing underscore avoids Python’s reserved word; the SDK sends it as from.

body
str | NoneDefaults to None

Text content of the message.

media
list[str] | NoneDefaults to None

URLs of media attachments. Supplying media sends the message as MMS.

send_as_mms
bool | NoneDefaults to None

Send as MMS even when no media is attached.

status_callback
str | NoneDefaults to None

URL that receives delivery status updates for this message.

custom_variables
dict[str, str] | NoneDefaults to None

Your own key/value string pairs, up to 20. When status_callback is set, every status callback includes them as a custom_variables object so you can match it to a record in your own system.

extras
Mapping[str, Any] | NoneDefaults to None

Additional request body fields merged into the payload as sent.

request_options
RequestOptions | NoneDefaults to None

Per-call timeout and retry overrides. See RequestOptions.

Returns

Message — the queued message, including its id, status, direction, and number_of_segments.

Response Example

Response
{
  "id": "c2d3e4f5-a6b7-8901-cdef-234567890abc",
  "from": "+15559876543",
  "to": "+15551234567",
  "body": "Your order #12345 has shipped!",
  "status": "queued",
  "direction": "outbound",
  "kind": "sms",
  "media": [],
  "number_of_segments": 1,
  "error_code": null,
  "error_message": null,
  "created_at": "2024-05-06T12:20:00Z",
  "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status_callback_url": null,
  "message_uri": "/api/messaging/logs/c2d3e4f5-a6b7-8901-cdef-234567890abc"
}

Example

from signalwire.rest import RestClient
client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)
message = client.messages.create(
    to="+15551234567",
    from_="+15559876543",
    body="Your order #4821 has shipped.",
    media=["https://example.com/receipts/4821.png"],
    status_callback="https://example.com/sms-status",
)
print(message["id"], message["status"])