Retrieving incoming messages

This article details commonly used API operations. Each section corresponds to an operation and includes a brief overview, a sample request and response payload, and schema information pulled directly from the API reference. Additionally, each section will include links to the corresponding API reference entry and any tutorials (if available).

Note:

For information on how complete the configuration steps required for this API, along with language-specific guides that illustrate the API's functionality with pre-populated examples, see the Getting started guides that correspond to this API.

Mobile Originated (MO) messages, or inbounds, are incoming messages. Inbound messages can be listed and retrieved like batch messages and they can also be delivered by callback requests like delivery reports.

List incoming messages

This operation enables you to list all inbound messages that you have received. Results are returned in reverse chronological order meaning users will see the most recently received messages near the top of the list. This operation is highly customizable. Users can filter results by date range and to number. If there is a high volume of batches, results can be paginated. Pagination is flexible, with the page and page_size query parameters enabling users to set the number of pages and the number of results per page.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference.

Sample response

After making this API call, you should receive a response that is similar to the example given below:

{"count": 1,
"page": 0,
"inbounds": [{"body": "Test Message",
"client_reference": "ABC123",
"from": "+11203494390",
"id": "01FC66621XXXXX119Z8PMV1QPA",
"operator_id": "35000",
"received_at": "2019-08-24T14:15:22Z",
"sent_at": "2019-08-24T14:15:22Z",
"to": "11203453453",
"type": "mo_text"
}
],
"page_size": 50
}

For the full schema of the response that corresponds to this API call, see the corresponding entry in the API reference. Alternatively, expand the schema below:

See the schema

count	integer <int64> The total number of inbounds matching the given filters
page	integer <int32> The requested page.
	Array of any (inbound) The page of inbounds matching the given filters.
page_size	integer <int32> The number of inbounds returned in this request.

Retrieve inbound message

This operation retrieves a specific inbound message with the provided inbound ID.

Making a request

Below are code samples that highlight how to make this API request in multiple languages. Click an appropriate tab to view your preferred language:

For the full schema of the request that corresponds to this API call, see the corresponding entry in the API reference.

Sample response

After making this API call, you should receive a response that is similar to the example given below:

{"body": "Test message",
"client_reference": "ABC123",
"from": "+11203494390",
"id": "01FC66621XXXXX119Z8PMV1QPA",
"operator_id": "35000",
"received_at": "2019-08-24T14:15:22Z",
"sent_at": "2019-08-24T14:15:22Z",
"to": "11203453453",
"type": "mo_text"
}

For all possible response schemas that correspond to this API call, see the corresponding entry in the API reference. Alternatively, expand the MOText schema below:

See the schema

body

required

string [ 0 .. 2000 ] characters

from

required

string

The phone number that sent the message. More info

required

string

The ID of this inbound message.

received_at

required

string <date-time>

When the system received the message.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

required

string

The Sinch phone number or short code to which the message was sent.

type

required

string

Regular SMS

Value	Description
mo_text	Regular SMS

client_reference

string

If this inbound message is in response to a previously sent message that contained a client reference, then this field contains that client reference.

Utilizing this feature requires additional setup on your account. Contact your account manager to enable this feature.

operator_id

string

The MCC/MNC of the sender's operator if known.

sent_at

string <date-time>

When the message left the originating device. Only available if provided by operator.

Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.