Skip to main content

Receiving opt-out events

Ahmed Boghdady
Updated

Receiving opt-out events

Opt-out events are changes in profile-originator relationship status to unsubscribe the profile from the originator.

Currently, the way that is achieved is via a default STOP program, where the subscriber can send a default keyword “STOP” or other keyword that the customer has configured for opt-out response.

In this arrangement, the event is an MO that the Mobile API service has recognized as an opt-out event. For every MO recognized as an opt-out event, you will receive the event via the MO webhook, and also receive that event via the opt-out webhook, potentially with extra metadata.

A separate configurable webhook delivers only the opt-out events in the same way: as an MO with metadata attached describing the recognized unsubscribe action.

If you have opt-out webhook callbacks enabled, Mobile API will send you every MO it receives on a specific endpoint that is recognized by your STOP program.

For details of receiving MOs via webhook in general, see Receiving mobile-originated messages (MOs).

Just like the DLR and MO events, the opt-out 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.

Opt-out event payload

Opt-out SMS

Copy 
{
  "mobileOriginate": {
    "mo_id": "2dd767d9-e5d9-4ce9-a16c-9c03bad7bb37",
    "type": "SMS",
    "gateway": "OpenMarketApi",
    "destination": {
      "address": "58870",
      "ton": 3
    },
    "message": {
      "content": "STOP",
      "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 shortcode, 1 for long code or toll-free 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.

Opt-out RCS

An opt-out from an RCS agent will take the form of a normal RCS MO. For more information, see "MO RCS" in

Receiving mobile-originated messages (MOs).

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