Skip to main content


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

account_sidstringThe unique identifier of the project that sent or received this message.
api_versionstringThe version number of the SignalWire XML REST API used to handle this message.
bodystringThe text of the message. Up to 1600 characters long and can be null if no message was sent.
date_createddatetimeThe date and time the message was created in RFC 2822 format.
date_sentdatetimeThe date and time the message was sent in RFC 2822 format.
date_updateddatetimeThe date and time the message was last updated in RFC 2822 format.
directionstringThe 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_codestringIf 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_messagestringA human readable description of the error that occurred. If no error occurred, error_message will be null.
fromstringThe 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_sidstringIf 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_mediaintegerThe number of media files that were included with the message.
num_segmentsintegerThe 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.
pricedecimalThe cost of the individual message billed to your project.
price_unitstringThe currency in which price is charged as.
sidstringA unique ID that identifies this specific message.
statusstringCurrent status of the message. See Message Status for a detailed description of each status.
subresource_urisobjectThe URIs for any subresources associated with this message.
tostringThe 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.
uristringThe URI of this particular message.

Message Status

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

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.

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"