Sending mobile-terminated messages (MTs)

Mobile-terminated messages (MTs) are outbound messages sent from Mobile API to a subscriber. The word terminated means that the message is terminated (delivered) on a mobile device.

Within Mobile API, an MT may be sent from the messages API (/api/messages) being used to send a direct message to a single phone number.

Sending MTs via the messages API

To send MTs through the messages API, you must ensure your company/account is correctly provisioned on Mobile API.

To set up your company/account, a Mobile API admin will do the following:

1. Set up a Company for your organization/account.

   • The company is the entity that represents your account.

   • This provides a company_id that can be used with all Mobile API endpoints.

2. Set up your Originator code:

   • An originator is a short code, long code, or brand that you will send messages through.

   • This step includes provisioning your originator with mobile operators and associating the originator with your company.

This API asynchronously sends an SMS or RCS MT to a single profile: asynchronously in the sense that a successful response (202) is not a confirmation that Mobile API has successfully sent the message, but it is a guarantee that Mobile API will attempt to send it:

curl -X 'POST' \
  'https://us-api.mobilecommons.com/umm/api/v3/messages \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-csrf-token: ehkoGAw-TF4vLCkANGU0DlY9IhU6GxsaIxK5tD62YtMSlTxkaZrdJu-I' \
  -d '{
  "body": "Hey there!",
  "from": "Mobile Commons",
  "from_brand": "true",
  "to": "447158432442"
}'

An MT ID is returned in the response, which can be used to later inspect the status of the MT by checking the GET /mts/{id} endpoint.

In case you’ve enabled delivery receipt (DLR) callbacks, Mobile API may also send you a DLR event indicating the delivery status of the message. Typically, you should expect a DLR to be sent within seconds of sending a message, but in case the receiving device has issues receiving the message (network issues, it’s turned off, etc.), Mobile API and carriers may retry sending a message to that device up to 72 hours. This is the default validity period, or the input (if specified) in seconds. If all retries have been exhausted after about 72 hours, you should expect a final DLR indicating delivery failure. For more information, see Receiving delivery receipts (DLRs).

API Docs: POST /umm/api/v3/messages

Scheduled sending

To send scheduled or delayed MTs through the /messages/scheduled API, you must ensure your company/account is correctly provisioned on Mobile API.

To set up your company/account, a Mobile API admin will do the following:

1. Set up your Company for your organization/account.

   • The company is the entity that represents your account.

   • This provides a company_id that can be used with all Mobile API endpoints.

2. Set up your Originator code:

   • An originator is a short code, long code, or brand that you will send messages through.

   • This step includes provisioning your originator with mobile operators and associating the originator with your company.

This API asynchronously sends an SMS or RCS MT to a single profile: asynchronously in the sense a successful response (202) is not a confirmation that Mobile API has successfully sent the message, but it is a guarantee that Mobile API will attempt to send it:

curl -X 'POST' \
  'https://us-api.mobilecommons.com/api/v3/messages/scheduled \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-csrf-token: ehkoGAw-TF4vLCkANGU0DlY9IhU6GxsaIxK5tD62YtMSlTxkaZrdJu-I' \
  -d '{
  "body": "Hey there!",
  "from": "Mobile Commons",
  "from_brand": "true",
  "scheduled_at": "2029-12-15 00:00",
  "to": "447158432442"
}'

An MT ID is returned in the response, which can be used to later inspect the status of the MT by checking the GET /mts/{id} endpoint.

In case you’ve enabled Delivery Receipt (DLR) callbacks, Mobile API may also send you a DLR event indicating the delivery status of the message. Typically, you should expect a DLR to be sent within seconds of sending a message, but in case the receiving device has issues receiving the message (network issues, it’s turned off, etc.), Mobile API and carriers may retry sending a message to that device up to 72 hours. This is the default validity period, or the input (if specified) in seconds. If all retries have been exhausted after about 72 hours, you should expect a final DLR indicating delivery failure. For more information, see Receiving delivery receipts (DLRs).

API Docs: POST /umm/api/v3/messages/scheduled

MT payload

MT SMS

{
  "body": "Hey there!",
  "to": "16592389123",
  "from": "10950",
  "originating_platform_mt_id": "1234",
  "from_brand": false
}

where:

• body (string, required): The SMS message body.

  • The maximum length of an SMS within Mobile API is 1600 characters.

• to (string, required): A valid phone number for a mobile device that will receive the message.

  • Format: The phone number has to include an international code and should only contain digits (non-digit characters like +, -, space, or otherwise won’t be accepted).

  • Regional requirements: It also has to conform to the phone length requirements of devices in the region that the number belongs to and should not contain a trunk prefix (for example, a number containing a zero trunk prefix that won’t be accepted: 4407591831237).

    Mobile API is able to send to multiple international regions (among them North America and the United Kingdom), but there may be some restrictions on certain regions across the platform and depending on the originator you’re sending the message from.

• from (string, required): The originator address you’ll send the message from.

  In Mobile API parlance, you’re able to send from a short code, long code, or brand name.

• originating_platform_mt_id (string, optional): An optional reference for the MT on your side. Passing this field may be helpful in multiple ways:

  • It’s passed back to you in delivery receipts (DLRs) from Mobile API.

  • You may use it to search for MTs through the MTs search endpoint. For more information, see Searching MTs.

  • Mobile API uses it to de-duplicate message requests in case you’ve employed a retry strategy when calling the API. For more information, see Retries and requests idempotency.

• from_brand (boolean, optional): Passed as the string "true". You should pass this flag if you’re sending from a brand originator. Otherwise, it becomes impossible for us to disambiguate between fully numeric brands and long codes.

• scheduled_at (string, optional): an optional date and time in the future to schedule sending this message:

  • If not given, the message is sent immediately.

  • Mobile API only accepts date-time values represented by strings of the format YYYY-MM-DD HH:MM per ISO 8601.

  • Mobile API interprets these date-time values in Coordinated Universal Time ( UTC). This interpretation will be unambiguously represented in the response.

  • The date and time value must not be in the past: scheduling cannot work for a past value and an error response will result.

  MT RCS

  Mobile API currently sends RCS text messages (with support for rich media on the way). RCS provides additional benefits to SMS like:

  • Verified sender: RCS messages are sent from an agent. The agent is an entity that represents your brand, which includes, among other things, a display name, a brand logo, color scheme, and outgoing web URLs to your brand’s internet pages.

  • Read receipts: Webhook callbacks that indicate a subscriber has read your message. For more information, see read receipts.

  • RCS message types

    • Basic message: Similar to SMS, the maximum character length is 160.

    • Single message: Any RCS message longer than 160 characters and can include rich media.

  The expected RCS payload matches the SMS one, with some slight variation.

{
  "type": "RCS",
  "body": "Hey there!",
  "sms_fallback_body": "Hey there!",
  "to": "16592389123",
  "from": "Mobile Commons",
  "originating_platform_mt_id": "1234"
}

where:

• type (string, required for RCS): The type of the message (SMS or RCS). While this field isn’t required for SMS, it’s required to send RCS messages.

• body (string, required): The RCS message body.

  • The maximum length of an RCS within Mobile API is 1000 characters.

• sms_fallback_body (string, optional): An SMS text that will be sent to the receiving device if it doesn’t support RCS.

  • The maximum length for the SMS fallback is the same as normal SMS (1600 characters).

  • If this field isn’t provided, the body field will be used as the SMS fallback content.

  • The originator for SMS fallback (short code or long code) is pre-configured. For more information, see "SMS fallback" section.

• to (string, required): Same as other channels.

• from (string, required): The originator address you’ll send the message from. For RCS, this is the RCS agent name.

• originating_platform_mt_id (string, optional): Same as other channels.

• scheduled_at (string, required for /scheduled): Same as other channels.

SMS fallback

When the receiving device doesn’t support RCS, an SMS fallback message is automatically sent to that device. An optional sms_fallback_body may be provided to specify the text that is sent, but when one isn’t provided, the Mobile API will automatically generate an SMS based on the original body that was sent.

The originator (short code or long code) used when sending SMS fallback needs to be pre-configured so that SMS fallback behavior works properly. Within Mobile API, this originator is referred to as the SMS Originator (also known as the Failover Originator). The SMS originator may be configured during the setup stage of your RCS agent.

The SMS originator configured on an RCS agent will be used for sending SMS fallback messages and may also be used for ensuring compliance (recording opt-outs and opt-ins on the RCS agent).

Canceling a scheduled message

Any scheduled MT may be canceled before it is due to send (before it’s scheduled time). Using your company_id and the MT ID returned from creating the scheduled message, perform the following request:

curl -X 'POST' \
  'https://us-api.mobilecommons.com/api/v3/messages/scheduled \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-csrf-token: ehkoGAw-TF4vLCkANGU0DlY9IhU6GxsaIxK5tD62YtMSlTxkaZrdJu-I' \
  -d '{
  "company_id": "3b00d483-3f12-480e-8620-149441685245",
  "mt_id": "ac12e5d0-fb4b-4fb6-acbf-5a0f2dd9bfd8"
}'

API Docs: POST /umm/api/v3/messages/scheduled/cancel

Responses

Successful response

202 is returned given a successful message request. The response body mirrors the request body to a large degree, but there are some notable fields:

{
  "attachments_urls": null,
  "delivery_status": null,
  "from": "10950",
  "id": "4a05e991-df22-4ef6-bb19-0d6bda42e79e",
  "message": "test MT",
  "originating_platform_mt_id": null,
  "parts": 2,
  "request_status": "pending",
  "sent_at": "2022-09-06T13:22:38Z",
  "to": "19789728675",
  "type": "SMS",
  "validity_period": null
}

where:

• id: The ID of the MT. You may use this ID to inspect the delivery status of the MT at a later time. It is also returned in DLR events from Mobile API.

• parts: The total number of SMS parts/segments this message consists of.

  Note: This value is an estimate provided by Mobile API before sending the message, but it should be accurate for the majority of messages. There may be some variability in how each mobile operator counts SMS segments, so Mobile API is only able to conclusively determine the number of parts after sending the message and receiving the DLR from the mobile operator. If you’ve enabled DLR events, you should receive the actual number of parts in the DLR Mobile API sends you. To learn more about how SMS may be segmented, see Concat/multi-part SMS.

• request_status: At this point, Mobile API hasn’t yet sent the message, so the value returned here should always be pending. This field indicates the status of the request to the message aggregator.

Error responses

{
    "errors": {
        "to": [
            "has invalid format - malformed"
        ]
    }
}

Profile status

A profile status indicates whether a profile has explicitly opted in or opted out from a particular originator. Statuses are captured at the originator level; for example, if your company has two separate originators, a profile opting out of one of them shouldn’t affect its status on the other.

Note: While Mobile API tracks opt-outs and may send you an opt-out event webhook, we don’t currently assume any responsibility for vetting the profile status before sending a message to a mobile device.

Concat/multi-part SMS

A standard SMS segment (also referred to as part) is 140 octets (8-bit bytes). When using the GSM character encoding, a single segment may consist of up to 160 characters. For more information on GSM character encoding, consult the GSM 03.38 entry in Wikipedia.

When you try to send a message containing more than 160 characters, Mobile API will automatically attempt to send that message as a multi-part/concat SMS message. Some additional message headers are added when encoding the message, so a single segment at that point consists of up to 153 characters.

When your message contains non-US-ASCII characters (or rather characters outside the GSM character set), a different message encoding is used that limits a single segment to 70 characters (66 characters when you send more than one segment). This would usually occur when you send emojis in a message (which are typically counted as 2 characters), but it could also occur, for example, if you inadvertently use an accented character.

Tip: Mobile API handles these encoding concerns, but you should be aware that each part is billed separately, so it is advisable to estimate the number of parts within your messages before sending them.

Message retries and request idempotency

We advise you to employ a retry strategy in case of network connection issues or other temporary errors when calling the API. A 5xx response from Mobile API is usually retriable, so retrying a message request when you receive that error up to a certain amount and duration is probably a good idea.

If you’re concerned about sending duplicate messages (in case you’re retrying HTTP time-out errors, for example), you may use the originating_platform_mt_id parameter as a way to guarantee request idempotency. Mobile API uses a combination of the originating_platform_mt_id and to field to de-duplicate incoming requests, and will return a 400 response in case it detects a duplicate request.

The response for this case will be as following:

{
  "error_code" => "E00114",
  "error_message" => "Already Exists",
  "errors" => {
    "profile_originator": [
      "has already been taken"
    ]
  }
}

Inspecting an MT message

This API shows information about a single MT.

Since the messages API sends an MT asynchronously, a successful synchronous response by the API only tells you that Mobile API will attempt to send the message, but it's not a guarantee that the message has actually been delivered.

The messages API returns an ID that can be used through this API to determine the status of a particular MT. Provide the MT ID:

curl -X 'GET' \
  'https://us-api.mobilecommons.com/api/v3/mts/22771a40-a8bd-4475-9750-248b83b7d5c2' \
  -H 'accept: application/json' \
  -H 'x-csrf-token: XgV5MTgQIXwhJF8YAz81CUM9PRVkMSUhhAIkWeh3ij3-Gpqn-mEBWHsg'

This will return:

{
  "attachment_urls": null,
  "carrier": {
    "carrier_name": "T-Mobile",
    "mobile_operator_id": 79
  },
  "company_name": "WF_Brand Company",
  "delivered_parts": null,
  "delivery_status": 4,
  "id": "22771a40-a8bd-4475-9750-248b83b7d5c2",
  "mdn": {
    "mdn_id": "f9092a35-8d33-4837-a310-9606ffeceb45",
    "phone_number": "18642018422"
  },
  "message": "Test message",
  "mt_orig_platform_name": "Waterfall",
  "originating_platform_mt_id": "62e03988166d0a1b518dc666",
  "originator": {
    "originator_address": "IBDD-10001",
    "originator_type": "brand"
  },
  "part_statuses": [],
  "parts": 1,
  "profile_id": "b4ca6596-a905-4309-8c35-430c9d04d114",
  "request_status": "success",
  "sent_at": "2022-07-26T19:05:41Z",
  "ticket_id": "NH220-0726N-1905J-41B0I",
  "type": "SMS",
  "validity_period": null
}

API Docs: GET /api/v3/mts/{id}

Searching MTs

The message search API is useful for debugging. You may filter and search MTs by content, date, originator, receiving phone number, and other filters.

Searching and filtering are applied by passing a list of filter objects. Only one filter key is allowed inside a single filter object, and you must pass at least one filter key in each object. The filter objects themselves are combined using AND.

curl -X 'POST' \
  'https://us-api.mobilecommons.com/umm/api/v3/mts/search?company_id=acda1ded-1139-47ec-9743-98399b391289' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-csrf-token: WTsyFUsxSi4PYB4baWYcNGYsFQMFPBsBjZQ83K0By8zH1WPQQKEruR-R' \
  -d '{
  "filter": [
    {
      "phone_number": "19782397366"
    }
  ],
  "page_after": null,
  "page_size": 25
}'

This will return paginated results of MTs that match your filters:

{
  "pagination_meta": {
    "after": null,
    "before": null,
    "limit": 25,
    "total_count": 4,
    "total_count_cap_exceeded": false
  },
  "records": [
    {
      "attachment_urls": null,
      "carrier": {
        "carrier_name": "AT&T",
        "mobile_operator_id": 383
      },
      "company_name": "ZZZZ MMSSS",
      "delivered_parts": null,
      "delivery_status": 4,
      "id": "0357cd9e-53ef-4422-957b-4326b195b20c",
      "mdn": {
        "mdn_id": "518482b4-6817-4869-9a08-03c54edb7226",
        "phone_number": "19782397366"
      },
      "message": "Thanks, we are all set.",
      "mt_orig_platform_name": "Waterfall",
      "originating_platform_mt_id": null,
      "originator": {
        "originator_address": "42330",
        "originator_type": "shortcode"
      },
      "part_statuses": [],
      "parts": 1,
      "profile_id": "ca020176-51d7-4eb0-ad45-bf6366861779",
      "request_status": "success",
      "sent_at": "2020-10-30T17:21:26Z",
      "ticket_id": "7620Z-10301-1721U-278H2",
      "type": "SMS",
      "validity_period": null
    }
  ]
}

API Docs: POST /umm/api/v3/mts/search