REST ClientMessages

create

View as MarkdownOpen in Claude

Send an SMS or MMS message. Pass the destination and source numbers first, then any other fields in options. A message with media is sent as 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.

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"
}

Examples

Send an SMS

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});
const message = await client.messages.create("+15559876543", "+15551234567", {
  body: "Your Bayview Taxi van is 5 minutes away.",
});
console.log(message.id, message.status);

Send an MMS with a status callback

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});
const message = await client.messages.create("+15559876543", "+15551234567", {
  body: "Here is your receipt.",
  media: ["https://example.com/receipts/4410.png"],
  status_callback: "https://example.com/webhooks/message-status",
  custom_variables: { ride_id: "ride-4410" },
});