REST Client Methods

Messaging

View as Markdown

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_sidstringRequiredformat: "uuid"
The unique identifier of the project that sent or received this message.
api_versionstringRequired
The version number of the SignalWire cXML REST API used to handle this message.
bodystring or nullRequired
The text of the message. Up to 1600 characters long. May be null if filtered for spam.
num_segmentsintegerRequired
The number of segments that make up the entire message.
num_mediaintegerRequired
The number of media files that were included with the message.
date_createdstringRequired
The date and time the message was created in RFC 2822 format.
date_sentstring or nullRequired
The date and time the message was sent in RFC 2822 format, or null if not yet sent.
date_updatedstringRequired
The date and time the message was last updated in RFC 2822 format.
directionenumRequired
The direction of the message.
Allowed values:
error_codestring or nullRequired
If an error has occurred on the message, the error code will give you a specific code, or null if no error.
error_messagestring or nullRequired
A human readable description of the error that occurred, or null if no error.
fromstringRequired
The phone number in E.164 format that sent the message.
pricedouble or nullRequired
The cost of the individual message billed to your project, or null if not yet calculated.
price_unitstringRequired

The currency in which price is charged as.

sidstringRequiredformat: "uuid"
A unique ID that identifies this specific message.
statusenumRequired
Current status of the message.
tostringRequired
The phone number in E.164 format that received the message.
messaging_service_sidstring or nullRequiredformat: "uuid"
If a number group was used when sending an outbound message, the number group's ID will be present, or null otherwise.
uristringRequired
The URI of this particular message.
subresource_urisobjectRequired
The URIs for any subresources associated with this message.

Example object

The Message Object
1{
2  "account_sid": "string",
3  "api_version": "string",
4  "body": "string",
5  "num_segments": 0,
6  "num_media": 0,
7  "date_created": "string",
8  "date_sent": "string",
9  "date_updated": "string",
10  "direction": "inbound",
11  "error_code": "string",
12  "error_message": "string",
13  "from": "string",
14  "price": 1,
15  "price_unit": "string",
16  "sid": "string",
17  "status": "queued",
18  "to": "string",
19  "messaging_service_sid": "string",
20  "uri": "string",
21  "subresource_uris": {
22    "media": "string"
23  }
24}

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.

Payload
1{
2  "MessageStatus": "delivered",
3  "MessageSid": "b3877c40-da60-4998-90ad-b792e98472ms",
4  "AccountSid": "b3877c40-da60-4998-90ad-b792e98472af",
5  "From": "+15551234567",
6  "To": "+15559876543",
7  "Body": "Hey, your order has shipped!",
8  "NumMedia": 0,
9  "NumSegments": 1
10}