Skip to main content

Receiving mobile-originated messages (MOs)

Ahmed Boghdady
Updated

Receiving mobile-originated messages (MOs)

Mobile-originated messages (MOs) are in-bound messages that are sent from a subscriber to Mobile API. MOs are sent from an MDN/profile (mobile phone number) to an originator (short code or long code). MOs consist of critical metadata for routing the message (sender and recipient identifiers), and content, like text or multimedia. It also may be tagged with additional inferred metadata, such as interpretation of the contents by our service’s programs, for example, the STOP keyword indicating opting out of a subscription for that originator.

If you have MO webhook callbacks enabled, Mobile API will send you every MO it receives on a specific endpoint.

Additionally, Mobile API may be configured to handle and respond to certain keywords inside an MO. For more information, see Automated responses.

Webhook MO events

Just like the delivery receipt (DLR) events, the MO events payloads are predefined. Work with your account manager to enable and customize webhook events.

You’ll need to provide this information:

  1. Endpoint (mandatory): The URL to which Mobile API will send the event.

  2. HTTP verb/method (mandatory): The HTTP method used to send the request. Mobile API supports standard verbs with a body: POST, PUT, PATCH, (advisedly) GET.

  3. Custom headers (optional): Custom headers that Mobile API may add to the webhook request.

  4. Authentication scheme (optional): You may provide us with credentials to confirm the authenticity of requests being sent to your endpoint. Mobile API currently supports the following authentication schemes:

    • Basic: A username/password combination that is base64 encoded (Base64({username}:{password})).

    • Token: An access token that you can validate. You will also have to provide us with the token header location.

  5. In addition to the authentication scheme, Mobile API is able to provide a list of IP ranges for our servers that the client may use as a whitelist to authenticate incoming requests.

You will need to set up the event listeners/handlers on the endpoints you've provided for us. Mobile API will expect that any response with HTTP status code of 200 is a successful confirmation, while any other status response will be considered a failure. In case of failures, Mobile API will retry the request according to an exponential back-off strategy.

After setting up your listeners, you will need to inform us when you want to enable webhooks for MO events.

MO payload

MO SMS

Copy 
{
  "mobileOriginate": {
    "mo_id": "2dd767d9-e5d9-4ce9-a16c-9c03bad7bb37",
    "type": "SMS",
    "gateway": "OpenMarketApi",
    "destination": {
      "address": "58870",
      "ton": 3
    },
    "message": {
      "content": "I wish to register a complaint",
      "type": "text"
    },
    "source": {
      "address": "447700900999",
      "mobileOperatorId": 71,
      "ton": 1
    },
    "submittedDate": "2015-08-29T15:10:03.029-05:00",
    "ticketId": "8514F-01278-17445-23FSJ"
  }
}

where:

  • mobileOriginate: JSON object.

    • mo_id: ID of the MO in Mobile API.

    • type: String indicating the channel on which the MO was sent (SMS or RCS).

    • gateway: String indicating the gateway that sent the MO.

    • destination: JSON object that includes address and ton.

      • address: String with short-code or long-code number.

      • ton: Type of number, an integer with value 3 for short code, 1 for long code or toll-free line or landline.

    • source: JSON object that includes address, mobileOperatorId, and ton.

      • address: String value of the handset phone number.

      • mobileOperatorId: Integer that reflects the carrier ID according to OpenMarket.

      • ton: Type of number, an integer with value 3 for shortcode, 1 for long code or toll-free or landline.

    • submittedDate: String ISO 8601 formatted date/time.

    • ticketId: String that reflects the OpenMarket ID.

MO RCS

The Mobile API currently supports forwarding RCS text MOs. Support for other RCS MO content types (for example, files) is still in progress.

RCS MOs will use the same schema as SMS MOs, with some minor variations:

  • The gateway used for RCS might differ from SMS.

  • The destination object will not contain a ton field since it does not apply for RCS.

Below is a sample of an RCS MO:

Copy 
{
  "mobileOriginate": {
    "mo_id": "2dd767d9-e5d9-4ce9-a16c-9c03bad7bb37",
    "type": "RCS",
    "gateway": "InfoBipApi",
    "destination": {
      "address": "Mobile Commons"
    },
    "message": {
      "content": "I wish to register a complaint",
      "type": "text"
    },
    "source": {
      "address": "447700900999",
      "mobileOperatorId": null,
      "ton": 1
    },
    "submittedDate": "2015-08-29T15:10:03.029-05:00",
    "ticketId": "8514F-01278-17445-23FSJ"
  }
}

where:

  • mobileOriginate:

    • mo_id: Same as SMS.

    • type: Expected to be RCS for RCS MOs.

    • gateway: Same as SMS. The gateway used for RCS MOs may differ from the one used for SMS MOs.

    • destination:

      • address: The RCS Agent ID.

    • message:

    • content: The text of the RCS MO.

    • type: The content type of the RCS MO. Only text is supported currently.

    • source:

      • address: Same as SMS.

      • mobileOperatorId: The mobile operator ID according to the aggregator. This value may be null for RCS MOs.

      • ton: Same as SMS.

    • submittedDate: Same as SMS.

    • ticketId: Same as SMS.

Multi-channel MO Webhooks

If you’re using Mobile API to receive messages on more than one channel, it is expected that a single webhook configuration will be provided for all your channels.

For instance, if you’re receiving both SMS and RCS through Mobile API, and you’ve configured a MO webhook, both SMS and RCS MOs will be sent on the same URL. A unified schema is used for all MOs, simplifying processing on your webhook handler. In addition, you will be able to use the type field returned in the DLR webhook to determine which channel the MO was sent on.

Inspecting an MO message

This API shows information about a single MO.

The MO webhook service (or MO search) returns IDs (within the body!) that can be used through this API to retrieve a particular MO’s full details later.

Provide the MO ID:

Copy 
curl -X 'GET' \
  'https://us-api.mobilecommons.com/api/v3/mos/819f52c8-b96f-408f-b55f-236b50792318' \
  -H 'accept: application/json' \
  -H 'x-csrf-token: XgV5MTgQIXwhJF8YAz81CUM9PRVkMSUhhAIkWeh3ij3-Gpqn-mEBWHsg'

This will return:

Copy 
{
  "attachments_urls": [],
  "content": "21 Wormwood street, Boston MA 02210",
  "created_at": "2020-10-30T17:23:52Z",
  "from": "19782397366",
  "id": "819f52c8-b96f-408f-b55f-236b50792318",
  "invalid_reasons": null,
  "mo_orig_platform_name": "Waterfall",
  "mobile_operator_id": 383,
  "processed_at": "2020-10-30T17:23:52",
  "ticket_id": "9120Z-10300-1723J-522JL",
  "to": {
    "originator_address": "42330",
    "originator_type": "shortcode"
  },
  "type": "SMS"
}

Searching MOs

Searching and filtering is 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.

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

This API always returns paginated results of MOs that match your filters:

Copy 
{
  "pagination_meta": {
    "after": null,
    "before": null,
    "limit": 25,
    "total_count": 3,
    "total_count_cap_exceeded": false
  },
  "records": [
    {
      "attachments_urls": [],
      "content": "21 Wormwood street, Boston MA 02210",
      "created_at": "2020-10-30T17:23:52Z",
      "from": "19782397366",
      "id": "819f52c8-b96f-408f-b55f-236b50792318",
      "invalid_reasons": null,
      "mo_orig_platform_name": "Waterfall",
      "mobile_operator_id": 383,
      "processed_at": "2020-10-30T17:23:52",
      "ticket_id": "9120Z-10300-1723J-522JL",
      "to": {
        "originator_address": "42330",
        "originator_type": "shortcode"
      },
      "type": "SMS"
    }
  ]
}

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