[DOC] - Add Documentation for New Message Endpoint `api/messaging/messages`

[cassieemb]

Describe the requested update
We have a new SW REST API endpoint for creating messages, and we're ready to add it to the docs. The Internal doc for the endpoint has all of the key details:

• request params
• response params
• error responses
• error codes and messages
• validation rules
• examples
• status callback events
• message statuses

Accepted Parameters (SMS/MMS)

Parameter	Type	Required	Description
to	String	Yes	Destination phone number in E.164 format (+ followed by 5-17 digits). Also accepts passthrough numbers like 988/+988.
from	String	Yes	Source phone number. Must be E.164 format or a shortcode (5-6 digits). Must be a purchased number on the project.
body	String	Conditional	Message body text. Required if no media is provided. Subject to provider-specific character limits.
media	Array<String>	No	Array of HTTP/HTTPS URLs for media attachments. Max 8 items. Presence of media makes the message MMS.
send_as_mms	Boolean	No	Force the message to be sent as MMS even without media attachments.
status_callback	String	No	A valid URL to receive message status callback events at each state change.

Possible status values:

Status	Description
queued	Message has been created and queued for delivery.
initiated	Message delivery has been initiated.
sent	Message has been sent to the carrier network.
delivered	Message was successfully delivered to the recipient.
undelivered	Message could not be delivered to the recipient.
failed	Message delivery failed. Check error_code and error_message for details.
read	Message has been read by the recipient (when supported by the channel).

Examples

curl -X POST https://<space>.signalwire.com/api/messaging/messages \
  -u "<project_id>:<auth_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "from": "+15559876543",
    "body": "Your order #12345 has shipped!",
    "media": ["https://example.com/tracking.png"]
  }'

Success:

{
  "id": "c2d3e4f5-a6b7-8901-cdef-234567890abc",
  "from": "+15559876543",
  "to": "+15551234567",
  "body": "Your order #12345 has shipped!",
  "status": "queued",
  "direction": "outbound",
  "kind": "mms",
  "media": ["https://example.com/tracking.png"],
  "number_of_segments": 1,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-02-25T15:30:00Z",
  "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status_callback_url": null,
  "message_uri": "/api/messaging/logs/c2d3e4f5-a6b7-8901-cdef-234567890abc"
}

Failure:

{
  "errors": [
    {
      "type": "validation_error",
      "code": "body_or_media_required",
      "message": "Body must be included if there is no Media.",
      "attribute": "body",
      "url": "https://developer.signalwire.com/rest/overview/error-codes/#body_or_media_required"
    }
  ]
}

Reason for the request
Development is completed, so we are ready to expose this to customers.

Sections to be updated

• api/messaging endpoints
• SW REST Error Codes
• messaging guides or something to draw new users towards it maybe?

Additional context
The internal documentation has several advisories on features that are incomplete and not ready to be exposed yet. We should leave these out of the initial release.

If there are any other questions, please feel free to reach out!

Related Issues or PRs
If this request is related to any existing issues or pull requests, please link them here.

https://github.com/signalwire/cloud-product/issues/18347
https://github.com/signalwire/cloud-product/issues/18247