Download OpenAPI specification:Download

Inbounds

Inbounds, or Mobile Originated (MO) messages, 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

With the list operation, you can list all inbound messages that you have received. This operation supports pagination. Inbounds are returned in reverse chronological order.

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
query Parameters
page
integer >= 0
Default: 0

The page number starting from 0.

Example: page=2
page_size
integer <= 100
Default: 30

Determines the size of a page

to
string

Only list messages sent to this destination. Multiple phone numbers formatted as either E.164 or short codes can be comma separated.

Example: to=+14155553421, +13435552671, +14325552677
start_date
string <ISO-8601>
Default: "Now-24"

Only list messages received at or after this date/time. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

Default: Now-24

end_date
string <ISO-8601>

Only list messages received before this date/time. Formatted as ISO-8601: YYYY-MM-DDThh:mm:ss.SSSZ.

Example: end_date=2016-10-02T09:34:18.542Z
client_reference
string [ 0 .. 2048 ] characters

Using a client reference in inbound messages requires additional setup on your account. Contact your account manager to enable this feature.

Only list inbound messages that are in response to messages with a previously provided client reference.

Example: client_reference=myReference
Responses
200

OK. A successful response , or an Error.

Response Schema: application/json
page
integer

The requested page.

page_size
integer

The number of inbounds returned in this request.

count
integer

The total number of inbounds matching the given filters

Array of objects (inboundsObject)

The page of inbounds matching the given filters

get/xms/v1/{service_plan_id}/inbounds
Request samples
import fetch from 'node-fetch';

async function run() {
  const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
  const region = 'us';
  const resp = await fetch(
    `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/inbounds`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "count": 100,
  • "inbounds": [
    • {
      }
    ]
}

Retrieve inbound message

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

Request
Security:
BearerAuth
path Parameters
service_plan_id
required
string

Your service plan ID. You can find this on your Dashboard.

Example: jd63jf88477ll123ab4567cd89012ef3
inbound_id
required
string

The inbound ID found when listing inbound messages.

Example: 01FC66621VHDBN119Z8PMV1QPA
Responses
200

OK. A successful response , or an Error.

Response Schema: application/json
type
string

The object type. Either mo_text or mo_binary.

id
string

The ID of this inbound message.

from
string

The phone number that sent the message.

to
string

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

body
string

The message body. Base64 encoded if type is mo_binary.

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.

send_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

received_at
string <date-time>

When the system received the message.

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

get/xms/v1/{service_plan_id}/inbounds/{inbound_id}
Request samples
import fetch from 'node-fetch';

async function run() {
  const servicePlanId = 'YOUR_service_plan_id_PARAMETER';
  const inboundId = 'YOUR_inbound_id_PARAMETER';
  const region = 'us';
  const resp = await fetch(
    `https://${region}.sms.api.sinch.com/xms/v1/${servicePlanId}/inbounds/${inboundId}`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "type": "mo_text",
  • "id": "01FC66621VHDBN119Z8PMV1QPA",
  • "from": 11203494390,
  • "to": 11203453453,
  • "body": "This is a test message",
  • "client_reference": "string",
  • "operator_id": "string",
  • "send_at": "2019-08-24T14:15:22Z",
  • "received_at": "2019-08-24T14:15:22Z"
}

Incoming SMSWebhook

An inbound message is a message sent to one of your short codes or long numbers from a mobile phone.

To receive inbound message callbacks, a URL needs to be added to your REST API. This URL can be specified in your Dashboard.

Request
Request Body schema: application/json

The incoming Message to your sinch number

type
string

The object type. Either mo_text or mo_binary.

id
string

The ID of this inbound message.

from
string

The phone number that sent the message.

to
string

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

body
string

The message body. Base64 encoded if type is mo_binary.

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.

send_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

received_at
string <date-time>

When the system received the message.

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

Responses
200

A 200 status indicates that the data was received successfully.

Request samples
application/json
{
  • "type": "mo_text",
  • "id": "01XXXXX21XXXXX119Z8P1XXXXX",
  • "from": "16051234567",
  • "to": "13185551234",
  • "body": "This is a test message.",
  • "operator_id": "string",
  • "send_at": "2022-08-24T14:15:22Z",
  • "received_at": "2022-08-24T14:15:22Z"
}