Send a message | SignalWire

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.

Permissions

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

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](/docs/platform/messaging/whatsapp/send-messages). Set `message_type` for a content message, or `template_id` for an [approved template](/docs/platform/messaging/whatsapp/message-templates). Free-form WhatsApp content is only allowed within the 24-hour customer service window. #### 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).

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)

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.

Message.WhatsAppContentMessageRequestobjectRequired

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

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.

kindenum

The kind of message.

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

$	curl -X POST https://{your_space_name}.signalwire.com/api/messaging/messages \
>	-H "Content-Type: application/json" \
>	-u "<project_id>:<api_token>" \
>	-d '{
>	"from": "+15559876543",
>	"to": "+15551234567"
>	}'

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	}