---
title: "Incoming SMS"
method: POST
path: "incomingSMS"
tags: ["Webhooks", "Inbounds"]
---

# Incoming SMS

`POST incomingSMS` (webhook)

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](https://dashboard.sinch.com/sms/api).

## Payload

- union — Inbounds, or Mobile Originated (MO) messages, are incoming messages
  - TextMessage — The page of inbounds matching the given filters.
    - `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](https://dashboard.sinch.com/settings/account-details) to enable this feature.
    - `from` string, required — The phone number that sent the message. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)
    - `id` string, required — The ID of this inbound message.
    - `operator_id` string — The MCC/MNC of the sender's operator if known.
    - `received_at` string, date-time, required — When the system received the message. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `sent_at` string, date-time — When the message left the originating device. Only available if provided by operator. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `to` string, required — The Sinch phone number or short code to which the message was sent.
    - `type` 'mo_text', required — Regular SMS
    - `body` string, required
  - BinaryMessage — The page of inbounds matching the given filters.
    - `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](https://dashboard.sinch.com/settings/account-details) to enable this feature.
    - `from` string, required — The phone number that sent the message. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)
    - `id` string, required — The ID of this inbound message.
    - `operator_id` string — The MCC/MNC of the sender's operator if known.
    - `received_at` string, date-time, required — When the system received the message. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `sent_at` string, date-time — When the message left the originating device. Only available if provided by operator. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `to` string, required — The Sinch phone number or short code to which the message was sent.
    - `type` 'mo_binary', required — SMS in [binary](https://community.sinch.com/t5/Glossary/Binary-SMS/ta-p/7470) format.
    - `body` string, required — The message content Base64 encoded. Max 140 bytes together with udh.
    - `udh` string, required — The UDH header of a binary message HEX encoded. Max 140 bytes together with body.
  - MediaMessage — The page of inbounds matching the given filters.
    - `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](https://dashboard.sinch.com/settings/account-details) to enable this feature.
    - `from` string, required — The phone number that sent the message. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)
    - `id` string, required — The ID of this inbound message.
    - `operator_id` string — The MCC/MNC of the sender's operator if known.
    - `received_at` string, date-time, required — When the system received the message. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `sent_at` string, date-time — When the message left the originating device. Only available if provided by operator. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `to` string, required — The Sinch phone number or short code to which the message was sent.
    - `type` 'mo_media', required — MMS
    - `body` MmsMoBody, required — The message content, including a URL to the media filters.
      - `media` MmsMedia[] — Collection of attachments in incoming message.
        - `code` integer, required — The result code. Possible values: 0 (success), 1 (content upload error), 2 (cloud bucket error), 3 (bucket key error).
        - `content_type` string, required — Content type of binary. [More info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
        - `status` 'Uploaded' | 'Failed', required — Status of the uploaded media.
        - `url` string — URL to be used to download attachment.
      - `message` string — The text message content of the MMS media message.
      - `subject` string — The subject of the MMS media message.

## Acknowledgement `200`

A `2xx` status code indicates that the data was received successfully.

## Other responses

- `400` — A `4xx` status counts as a permanent failure and will not trigger any retries, except for `429`.
- `429` — The callback will be retried and the callback throughput will be lowered.
- `500` — A `5xx` status code will trigger a retry.

---

[API](https://skmtc.net/sinch/apis/api-overview-sinch.md) · [All operations](https://skmtc.net/sinch/apis/api-overview-sinch/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sinch/api-overview-sinch/revisions/67cb925f1c81/schema)