Messages

Create a Message

Changed on

Sends a message through the account and creates a Message resource for tracking its delivery. Use this form-encoded route for SID-based integrations; use SignalWire REST Send a message for a JSON request.

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/Accounts/{AccountSid}/Messages

Request

  • Base URL
    https://YOUR_SPACE.signalwire.com/api/laml/2010-04-01
  • URL
    https://YOUR_SPACE.signalwire.com/api/laml/2010-04-01/Accounts/{AccountSid}/Messages
  • Auth
    HTTP basic

Path parameters

AccountSidstring uuid required

Universal Unique Identifier.

The unique identifier of the project that sent or received this message.

Request body application/x-www-form-urlencoded

Tostring required

The phone number in E.164 format that will receive the message.

Fromstring

The phone number in E.164 format that will send the message. Either From or MessagingServiceSid must be provided.

Bodystring

The text of the message. Either Body or MediaUrl must be provided.

SendAsMmsboolean

When set to true, forces the message to be sent as an MMS.

ApplicationSidstring uuid

Universal Unique Identifier.

MaxPricestring

The maximum price in USD acceptable for the message to be sent. Format: decimal with up to 4 decimal places.

StatusCallbackstring uri

A URL endpoint to receive callbacks each time the status of the message changes. See the SMS status callback webhook for the payload your URL will receive.

ValidityPeriodinteger

The number of seconds a message will allow being queued before canceling. Must be between 1 and 172800 (48 hours). Default is 14400 (4 hours).

MessagingServiceSidstring uuid

Universal Unique Identifier.

Example request

{
  "To": "+15557654321",
  "From": "+15551234567",
  "Body": "Hello World!",
  "MaxPrice": "0.0075",
  "StatusCallback": "https://example.com/status-callback",
  "ValidityPeriod": 14400
}

Response

Response returned when a message is created.

account_sidstring uuid required

Universal Unique Identifier.

api_versionstring required

The version number of the SignalWire cXML REST API used to handle this message.

bodystring nullable required

The text of the message. Up to 1600 characters long. May be null if filtered for spam.

num_segmentsinteger required

The number of segments that make up the entire message.

num_mediainteger required

The number of media files that were included with the message.

date_createdstring required

The date and time the message was created in RFC 2822 format.

date_sentstring nullable required

The date and time the message was sent in RFC 2822 format, or null if not yet sent.

date_updatedstring required

The date and time the message was last updated in RFC 2822 format.

direction'inbound' | 'outbound-api' | 'outbound-call' | 'outbound-reply' required

Message direction.

error_codestring nullable required

If an error has occurred on the message, the error code will give you a specific code, or null if no error.

error_messagestring nullable required

A human readable description of the error that occurred, or null if no error.

fromstring required

The phone number in E.164 format that sent the message.

pricenumber float nullable required

The cost of the individual message billed to your project, or null if not yet calculated.

price_unitstring required

The currency in which price is charged as.

sidstring uuid required

Universal Unique Identifier.

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

Message status.

tostring required

The phone number in E.164 format that received the message.

messaging_service_sidstring uuid required

Universal Unique Identifier.

uristring required

The URI of this particular message.

Example response

{
  "api_version": "2010-04-01",
  "body": "Hello World!",
  "num_segments": 1,
  "num_media": 1,
  "date_created": "Mon, 13 Aug 2018 21:38:46 +0000",
  "date_sent": "Mon, 13 Aug 2018 21:38:46 +0000",
  "date_updated": "Mon, 13 Aug 2018 21:38:46 +0000",
  "error_code": "30001",
  "error_message": "Queue overflow",
  "from": "+15551234567",
  "price": 0.005,
  "price_unit": "USD",
  "to": "+15557654321",
  "uri": "/api/laml/2010-04-01/Accounts/ea108133-d6b3-407c-9536-9fad8a929a6a/Messages/0a059168-ead0-41af-9d1f-343dae832527.json",
  "subresource_uris": {
    "media": "/api/laml/2010-04-01/Accounts/ea108133-d6b3-407c-9536-9fad8a929a6a/Messages/0a059168-ead0-41af-9d1f-343dae832527/Media.json"
  }
}

Changes

  • 2916d5e3072eRevision changes
    • breaking

      added to the request property allOf list

    • breaking

      added to the request property allOf list

    • breaking

      the response's property type changed from string to no type, and format from uuid to no format for status

    • breaking

      the response's property format changed from uuid to no format for status

    • breaking

      the response's property type changed from string to no type, and format from uuid to no format for status

    • info

      the request property type was generalized from string to no type, and format from uuid to no format

    • info

      the request property type was generalized from string to no type, and format from uuid to no format

    • info

      added to the response property allOf list for the response status

    • info

      added to the response property allOf list for the response status

    • info

      added to the response property anyOf list for the response status

    • info

      removed subschema #1 from the response property anyOf list for the response status

  • 5344c0c93a4cRevision changes
    • breaking

      added 'unevaluatedProperties' constraint to the request body

    • info

      added 'unevaluatedProperties' constraint to the response body for the status

    • info

      added 'unevaluatedProperties' constraint to the response body for the status

    • info

      added 'unevaluatedProperties' constraint to the response body for the status

    • info

      added 'unevaluatedProperties' constraint to the response body for the status

    • info

      added 'unevaluatedProperties' constraint to the //// response property for the status