Find SMS messages

About

This API method allows you to programmatically search for previously sent or received SMS messages.

Your account and property must be enabled for SMS. Please contact client services to have SMS enabled.

Resource URI

GET /v2/Properties/{PropertySid}/Messages

Request

URI Parameters

ParameterTypeDescription
PropertySidstringThe secure identifier of the Property for which to search SMS messages for.

Resource Parameters

ParameterTypeDescription
Date_FromtimestampInclude SMS messages from this date and time (inclusive). Specified as seconds since the epoch and as UTC.
Date_TotimestampInclude SMS messages until this date and time (exclusive). Specified as seconds since the epoch and as UTC.

Optional Parameters

ParameterTypeDescription
StatusstringThe status of the SMS message.
Options: Processing, Submitted, Delivered, Failed or Received. See below table for definitions of each possible value.
DirectionstringThe direction of the SMS message. Options: Transmit or Receive
Results_CountintegerLimit the number of objects to be returned. Default is 200.
Results_SkipintegerNumber of results to skip, can be used as a cursor for pagination of results.

Example: Searching SMS messages with just date from and to specified.

{
"Date_From": 1506038400,
"Date_To": 1506427200
}

Example: Searching SMS messages with all search filters.

{
"Date_From": 1506038400,
"Date_To": 1506427200,
"Direction": "Transmit",
"Status": "Delivered",
"Results_Count": 10,
"Results_Skip": 10
}

Response

200 - OK

On successful retrieval of the SMS messages, a 200 OK is returned with a JSON formatted array of Messages Resource objects.

Note that all timestamp fields are specified as seconds since the unix epoch and all represented within UTC.

Message Resource Parameters

ParameterTypeDescription
MessageSidstringThe message secure identifier which uniquely identifies the message.
AccountSidstringThe account secure identifier associated with the message.
PropertySidstringThe property secure identifier associated with the message.
FromstringThe alphanumeric or E164 formatted sender ID of the message.
TostringThe E164 formatted recipient of the SMS message.
TextstringThe content of the SMS message.
DeliveryReceiptbooleanSet to true if a delivery receipt was requested and false otherwise.
NumSegmentsintegerThe number of message segments.
StatusstringThe message status. See below table for definitions of each possible value.
DirectionstringThe direction of the message (as a response to this request always Transmit. Possible values: Transmit and Receive).
ScheduledtimestampTimestamp of when the message is/was scheduled to be sent.
CreatedtimestampTimestamp of when the message resource was created.
SubmittedtimestampTimestamp of when the message was submitted to the SMS Center.
DeliveredtimestampTimestamp of when the message delivery occurred.
ReceivedtimestampTimestamp of when an inbound message was received.
ErrorCodestringError code (if message submission or delivery failed).

Example: An example response to the successful search of SMS messages.

{
"Messages": [
{
"MessageSid": "MJGPVTNSWHJ35HGQTGABFE27TXFSSUZI",
"From": "+61416240112",
"To": "+61488824921",
"Text": "Saaaa",
"DeliveryReceipt": false,
"NumSegments": 0,
"Status": "Received",
"Direction": "Receive",
"Scheduled": 1506321592,
"Created": 1506320553
},
{
"MessageSid": "MI6R6L455Q35QQ5VR6O4QISTOYSWBFGA",
"From": "+61416240112",
"To": "+61488824921",
"Text": "Vvvvv",
"DeliveryReceipt": false,
"NumSegments": 0,
"Status": "Received",
"Direction": "Receive",
"Scheduled": 1506321592,
"Created": 1506321575
}
]
}

Description of possible status values

StatusDescription
ProcessingThe message has been received by our system and is being processed.
SubmittedThe message has been submitted successfully to the SMS Center.
DeliveredThe message has been delivered successfully (if delivery receipts are activated).
FailedThe message has failed (submission to the SMS Center was not possible within a reasonable time limit).
ReceivedThe message has been received (for inbound messages).

400 - Error

For error codes and messages, please refer to the REST API Error Codes page.