Skip to main content

Messages

A Message is an inbound or outbound message sent or received by your SignalWire project. Messages are identified by a unique, random ID, and can have attachments, called Media, associated with them. These Media files are managed separately from the Messages themselves, and are stored in Media subresource objects. To retrieve a list of the media associated with a message, use the Media subresource for that Message instance.

The Message Object​

A sample message returned from the API.

{
  "account_sid": "ea108133-d6b3-407c-9536-9fad8a929a6a",
  "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": null,
  "date_updated": "Mon, 13 Aug 2018 21:38:46 +0000",
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": "+15551234567",
  "price": 0.005,
  "price_unit": "USD",
  "sid": "0a059168-ead0-41af-9d1f-343dae832527",
  "status": "queued",
  "to": "+15557654321",
  "messaging_service_sid": null,
  "uri": "/api/laml/2010-04-01/Accounts/ea108133-d6b3-407c-9536-9fad8a929a6a/Messages/0a059168-ead0-41af-9d1f-343dae832527",
  "subresource_uris": {
    "media": "/api/laml/2010-04-01/Accounts/ea108133-d6b3-407c-9536-9fad8a929a6a/Messages/0a059168-ead0-41af-9d1f-343dae832527/Media"
  }
}

AttributeDescription
account_sid stringThe unique identifier of the project that sent or received this message.
api_version stringThe version number of the SignalWire cXML REST API used to handle this message.
body stringThe text of the message. Up to 1600 characters long and can be null if no message was sent.
date_created datetimeThe date and time the message was created in RFC 2822 format.
date_sent datetimeThe date and time the message was sent in RFC 2822 format.
date_updated datetimeThe date and time the message was last updated in RFC 2822 format.
direction stringThe direction of the message:
  • inbound for incoming messages.
  • outbound-api for messages created via the REST API.
  • outbound-call for messages created during a call.
  • outbound-reply for messages created in response to an inbound message.
error_code stringIf an error has occurred on the message, the error code will give you a specific code to help lookup more information on the failure. If no error occurred, error_code will be null.
error_message stringA human readable description of the error that occurred. If no error occurred, error_message will be null.
from stringThe phone number in E.164 format. For inbound messages, this will be the remote phone number who sent the message. For outbound messages, this will be one of your SignalWire phone numbers.
messaging_service_sid stringIf a number group was used when sending an outbound message, the number group's ID will be present. If no number group was used, the value will be null.
num_media integerThe number of media files that were included with the message.
num_segments integerThe number of segments that make up the entire message. If the body of the message is larger than 160 GSM-7 characters or 70 UCS-2 characters, it will automatically be broken up into smaller messages and annotated to attempt proper reconstruction on the recipient handset. Not all carriers and handsets support this. SignalWire will recombine inbound messages into a single message. Your project will be charged for each segment sent or received.
price decimalThe cost of the individual message billed to your project.
price_unit stringThe currency in which price is charged as.
sid stringA unique ID that identifies this specific message.
status stringCurrent status of the message. See Message Status for a detailed description of each status.
subresource_uris objectThe URIs for any subresources associated with this message.
to stringThe phone number in E.164 format that received the message. For inbound messages, this is one of your SignalWire phone numbers; for outbound messages, this is the remote phone number that received the message.
uri stringThe URI of this particular message.

Message Status​

The status attribute of a Message indicates the last known state of the Message.

StateDescription
queuedThe API request to send this message was processed successfully, and the message is currently waiting to be sent out.
sendingThe message is currently being transmitted by SignalWire to the nearest carrier upstream in the network.
sentThe nearest carrier upstream in the network has accepted the message.
deliveredConfirmation of receipt of the message by the nearest carrier upstream in the network.
undeliveredSignalWire has received notice from the nearest carrier upstream in the network that the message was not delivered.
failedSignalWire could not send the message. There is no charge for failed messages.
receivingSignalWire has received and is currently processing an inbound message.
receivedThe message has been received by one of the numbers in your account. Applies to inbound messages only.

Subresources: Media​

Any media associated with a message can be listed using the media URI in the Subresources object:

https://example.signalwire.com/api/laml/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Media

StatusCallback Parameters​

In addition to the standard request parameters, the following are parameters passed back to your application when SignalWire sends an update to a message's StatusCallback URL.

ParameterDescription
MessageStatus stringThe current status of the message at the time of the callback.
ErrorCode stringIf your message has failed or is undelivered, the error code may provide you with more information about what went wrong.