Sign in
Messages

Send a message

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.

Use this SignalWire REST operation for JSON requests. Integrations built around form-encoded requests and Message SIDs can use the Compatibility API's Create message operation instead.

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.

post/api/messaging/messages

Request body

OR
OR

Example request

{
  "to": "+15551234567",
  "from": "+15559876543",
  "body": "Your order #12345 has shipped!",
  "media": [
    "https://example.com/tracking.png"
  ],
  "status_callback": "https://example.com/webhooks/message-status",
  "custom_variables": {
    "id": "12345",
    "case_number": "54321"
  }
}

Response

Response returned when a message is successfully created and queued for delivery.

idstring uuid required

Universal Unique Identifier.

fromstring required

The source phone number.

tostring required

The destination phone number.

bodystring required

The message body text. Returns an empty string when the message has been redacted.

status'queued' | 'initiated' | 'sent' | 'delivered' | 'undelivered' | 'failed' | 'read' required

Delivery state of a message.

direction'inbound' | 'outbound' required

The direction of a message.

kind'sms' | 'mms' | 'whatsapp' required

The kind of message.

mediastring[] required

Array of URLs for any media attachments on the message. Empty for SMS.

number_of_segmentsinteger required

Number of segments the message body was split into for delivery.

error_codestring nullable required

Provider-specific error code if delivery failed. Null when no error occurred.

error_messagestring nullable required

Human-readable error message if delivery failed. Null when no error occurred.

created_atstring date-time required

Date and time when the message was created.

project_idstring uuid required

Universal Unique Identifier.

status_callback_urlstring uri nullable required

Callback URL configured to receive message status events. Null if no callback was configured.

message_uristring required

Relative URL for retrieving the message via the /api/messaging/logs endpoint.

Example response

{
  "from": "+15559876543",
  "to": "+15551234567",
  "body": "Your order #12345 has shipped!",
  "media": [],
  "number_of_segments": 1,
  "created_at": "2024-05-06T12:20:00Z",
  "message_uri": "/api/messaging/logs/c2d3e4f5-a6b7-8901-cdef-234567890abc"
}

Changes

Changed in 10 of the 137 revisions of this API.132621

  • 14b262a4830d182See the full diff
    • ▲

      the request's body type/format changed from object/ to /

      request-body-type-changed

    • ●

      removed the request property body

      request-property-removed

    • ●

      removed the request property custom_variables

      request-property-removed

    • ●

      removed the request property from

      request-property-removed

    • ●

      removed the request property media

      request-property-removed

    • ●

      removed the request property send_as_mms

      request-property-removed

    • ●

      removed the request property status_callback

      request-property-removed

    • ●

      removed the request property to

      request-property-removed

    • ●

      added the new whatsapp enum value to the kind/allOf[Message.MessageKind]/ response property for the response status 201

      response-property-enum-value-added

    • ○

      added Message.CreateMessageRequest Message.WhatsAppContentMessageRequest Message.WhatsAppTemplateMessageRequest to the request body anyOf list

      request-body-any-of-added

    • ○

      removed 'unevaluatedProperties' constraint from the request body

      request-body-unevaluated-properties-removed

  • 6e5c9df7036956See the full diff
    • ▲

      added the new required request property from

      new-required-request-property

    • ▲

      added the new required request property to

      new-required-request-property

    • ▲

      removed Message.CreateMessageRequest Message.WhatsAppContentMessageRequest Message.WhatsAppTemplateMessageRequest from the request body anyOf list

      request-body-any-of-removed

    • ▲

      the request's body type/format changed from / to object/

      request-body-type-changed

    • ▲

      added 'unevaluatedProperties' constraint to the request body

      request-body-unevaluated-properties-added

    • ○

      added the new optional request property body

      new-optional-request-property

    • ○

      added the new optional request property custom_variables

      new-optional-request-property

    • ○

      added the new optional request property media

      new-optional-request-property

    • ○

      added the new optional request property send_as_mms

      new-optional-request-property

    • ○

      added the new optional request property status_callback

      new-optional-request-property

    • ○

      removed the whatsapp enum value from the kind/allOf[Message.MessageKind]/ response property for the response status 201

      response-property-enum-value-removed

    This revision also has 42 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 13da5e8c3990182See the full diff
    • ▲

      the request's body type/format changed from object/ to /

      request-body-type-changed

    • ●

      removed the request property body

      request-property-removed

    • ●

      removed the request property custom_variables

      request-property-removed

    • ●

      removed the request property from

      request-property-removed

    • ●

      removed the request property media

      request-property-removed

    • ●

      removed the request property send_as_mms

      request-property-removed

    • ●

      removed the request property status_callback

      request-property-removed

    • ●

      removed the request property to

      request-property-removed

    • ●

      added the new whatsapp enum value to the kind/allOf[Message.MessageKind]/ response property for the response status 201

      response-property-enum-value-added

    • ○

      added Message.CreateMessageRequest Message.WhatsAppContentMessageRequest Message.WhatsAppTemplateMessageRequest to the request body anyOf list

      request-body-any-of-added

    • ○

      removed 'unevaluatedProperties' constraint from the request body

      request-body-unevaluated-properties-removed

  • 0f65a5bc6e5c56See the full diff
    • ▲

      added the new required request property from

      new-required-request-property

    • ▲

      added the new required request property to

      new-required-request-property

    • ▲

      removed Message.CreateMessageRequest Message.WhatsAppContentMessageRequest Message.WhatsAppTemplateMessageRequest from the request body anyOf list

      request-body-any-of-removed

    • ▲

      the request's body type/format changed from / to object/

      request-body-type-changed

    • ▲

      added 'unevaluatedProperties' constraint to the request body

      request-body-unevaluated-properties-added

    • ○

      added the new optional request property body

      new-optional-request-property

    • ○

      added the new optional request property custom_variables

      new-optional-request-property

    • ○

      added the new optional request property media

      new-optional-request-property

    • ○

      added the new optional request property send_as_mms

      new-optional-request-property

    • ○

      added the new optional request property status_callback

      new-optional-request-property

    • ○

      removed the whatsapp enum value from the kind/allOf[Message.MessageKind]/ response property for the response status 201

      response-property-enum-value-removed

    This revision also has 42 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • a888562fa415182See the full diff
    • ▲

      the request's body type/format changed from object/ to /

      request-body-type-changed

    • ●

      removed the request property body

      request-property-removed

    • ●

      removed the request property custom_variables

      request-property-removed

    • ●

      removed the request property from

      request-property-removed

    • ●

      removed the request property media

      request-property-removed

    • ●

      removed the request property send_as_mms

      request-property-removed

    • ●

      removed the request property status_callback

      request-property-removed

    • ●

      removed the request property to

      request-property-removed

    • ●

      added the new whatsapp enum value to the kind/allOf[Message.MessageKind]/ response property for the response status 201

      response-property-enum-value-added

    • ○

      added Message.CreateMessageRequest Message.WhatsAppContentMessageRequest Message.WhatsAppTemplateMessageRequest to the request body anyOf list

      request-body-any-of-added

    • ○

      removed 'unevaluatedProperties' constraint from the request body

      request-body-unevaluated-properties-removed

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 79ec4cfae7c81See the full diff
    • ○

      added the new optional request property custom_variables

      new-optional-request-property

  • c1e5ee9f10e31See the full diff
    • ●

      removed the request property custom_variables

      request-property-removed

    This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • b43c5d1683ba1See the full diff
    • ○

      added the new optional request property custom_variables

      new-optional-request-property

  • 548c8bbaf71b1See the full diff
    • ●

      removed the request property custom_variables

      request-property-removed

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 8f14f4f200f51See the full diff
    • ○

      added the new optional request property custom_variables

      new-optional-request-property

    This revision also has 21 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 137 revisions, 3 have a changelog that could not be searched.