Skip to main content

Sending broadcast messages

Ahmed Boghdady
Updated

Sending broadcast messages

A broadcast message targets multiple subscribers in one transaction.

When sending a broadcast message, an MT will be generated for each targeted subscriber, and it will be linked to the broadcast. A DLR will be received for each MT as well.

The MTs topic addresses the prerequisites and expectations of sending MTs:

  • Company and originator setup

  • Profile status as it applies to subscriber consent

Sending inline broadcasts via the programs API

In the Mobile API, a broadcast is created and managed as a specific type of program targeting a defined list of subscribers. The Inline Broadcast endpoint provides a single endpoint to create these broadcasts:

Copy 
curl -X 'POST' \
  'https://us-api.mobilecommons.com/umm/api/v3/programs/inline_broadcast' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-csrf-token: WTsyFUsxSi4PYB4baWYcNGYsFQMFPBsBjZQ83K0By8zH1WPQQKEruR-R' \
  -d '{
  "description": "Create broadcast using an inline mdn_list.",
  "mdn_list": [
    "15557324567",
    "15553347048",
    "15552802680"
  ],
  "message": {
    "text": "text your Date of Birth to confirm receiving messages"
  },
  "name": "Broadcast_inline_test",
  "originator_address": "68557",
  "originator_type": "shortcode",
  "send_now": true,
  "type": "broadcast"
}'

API Docs: POST /umm/api/v3/programs/inline_broadcast

Broadcast Program Payload

Copy 
{
  "name": "Broadcast_inline_test",
  "description": "Create broadcast using an inline mdn_list.",
  "type": "broadcast",
  "mdn_list": [
    "15557324567",
    "15553347048",
    "15552802680"
  ],
  "auto_enroll": true,
  "message": {
    "text": "text your Date of Birth to confirm receiving messages"
  },
  "originator_address": "68557",
  "originator_type": "shortcode",
  "send_now": true
}

where:

  • name (string, required): The textual name of the broadcast.

    • This text can be recalled or searched on later.

  • description (string, optional) the textual description of the broadcast.

    • This text can be recalled later.

  • type (string, required): The type of program: in this screnario, broadcast.

    • The programs API documents the possible values, but only broadcast works for this endpoint.

  • mdn_list (array[string], required): A list of valid phone numbers for mobile devices to be targeted for this broadcast, mirroring the to field for a single MT.

    • 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.

  • auto_enroll (boolean, optional): Whether to auto-enroll numbers targeted by the broadcast so that they are textable.

    • When true, the service will ensure that targeted subscribers have their profile status updated to record an opt-in consent, ensuring an attempt to reach every subscriber listed.

    • When false or omitted, the service checks the subscribers' profiles, only sending to those recorded with an opt-in status to ensure compliance with their consent.

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

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

  • originator_address (string, required): The address of the originator of the broadcast, mirroring the from field for a single MT.

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

  • originator_type (string, required): The type of originator of the broadcast, needed to disambiguate brands from long codes in particular.

    • Accepted values are shortcode, longcode, brand or rcs_bot.

  • send_now (boolean, required): Whether to send the broadcast immediately.

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

    • This must be omitted for an immediate broadcast where send_now is true, and must be specified for a scheduled broadcast.

    • 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.

Sending RCS broadcast

Broadcast messages can be of type RCS. Having originator_type set to “rcs_bot” and originator_adress is your rcs bot name in the request payload, the individual MTs produced by the broadcast are treated as RCS MTs. The message object will differ according to RCS message components to be sent.

For text RCS broadcast, the request body will be identical to the normal SMS broadcast, except for originator_type and originator_address which will refer to the RCS bot you are using.

Copy 
{
  "type": "broadcast",
  "name": "my text based broadcast",
  "originator_type": "rcs_bot",
  "originator_address": "My bot",
  "mdn_list": ["17811234567", "19781234567"],
  "send_now": true,
  "auto_enroll": true,
  "message": {
    "text": "text that end-user will recieve as RCS message"
  }
}

Broadcast fallbacks

While RCS has been widely adopted recently, some end-users still may be unable to receive RCS messages according to their handset capabilities. In such cases, if message delivery is still required, an sms_fallback string can be set. This string will be used as the body of an SMS message to be sent instead of the failed RCS.

Example:

Copy 
{
  "type": "broadcast",
  "name": "my text based broadcast",
  "originator_type": "rcs_bot",
  "originator_address": "My bot",
  "mdn_list": ["17811234567", "19781234567"],
  "send_now": true,
  "auto_enroll": true,
  "message": {
    "text": "text that end-user will recieve as RCS message",
    "sms_fallback": "the SMS body to be sent if the device is not RCS ready"
  }
}

In this case, the optional sms_fallback string is used as the SMS body for the fallback message.

The failing-over mechanism will not require sms_fallback to send an SMS fallback if the original RCS was a text. It will use the original text of the RCS as the body of the fallback SMS if the sms_fallback was omitted.

For more information, see "SMS fallback" in Sending mobile-terminated messages (MTs).

Inspecting a broadcast program

With the id field from a broadcast program creation response, programs can be inspected via the programs REST API:

Copy 
curl -X 'GET' \
  'https://us-api.mobilecommons.com/api/v3/programs/f2456163-baff-4fe2-8db3-bf4fc677a154' \
  -H 'accept: application/json' \
  -H 'x-csrf-token: XgV5MTgQIXwhJF8YAz81CUM9PRVkMSUhhAIkWeh3ij3-Gpqn-mEBWHsg'

Yielding, for example:

Copy 
{
  "company_id": "45c1211e-4f5a-4a93-8aaf-96384c6de182",
  "created_at": "2023-07-06T21:33:25Z",
  "created_by": {
    "recorded_at": "2023-07-06T21:33:25",
    "type": "system"
  },
  "description": null,
  "ended_at": null,
  "id": "f2456163-baff-4fe2-8db3-bf4fc677a154",
  "is_pinned": false,
  "list": {
    "company_id": "45c1211e-4f5a-4a93-8aaf-96384c6de182",
    "created_on": "2023-07-06T21:20:21Z",
    "deactivated_at": null,
    "has_history": true,
    "id": "8fecc96b-f5db-43c0-89d5-b3d0efb2ea83",
    "is_pinned": false,
    "is_pinned_at": null,
    "last_targeted_at": "2023-07-06T20:38:37.000000Z",
    "name": "valid_group",
    "statistics": {
      "company_id": "45c1211e-4f5a-4a93-8aaf-96384c6de182",
      "id": "8fecc96b-f5db-43c0-89d5-b3d0efb2ea83",
      "is_refreshing": false,
      "last_enqueue_date": null,
      "last_refresh_date": null,
      "statistics": []
    },
    "status": "active",
    "total_profiles": 0,
    "type": "uploaded",
    "updated_at": "2023-07-06T21:20:21Z"
  },
  "messages": [
    {
      "message_channel": "SMS",
      "profile_attribute_enum": "full_address",
      "profile_attribute_meta_id": null,
      "text": "Hey, send us your full address here"
    },
    {
      "invalid_mt": "shalabs: Sorry, your response didn't match what we were looking for. Please try again!",
      "message_channel": "SMS",
      "profile_attribute_enum": "full_address",
      "profile_attribute_meta_id": null
    }
  ],
  "name": "test CXMM-5898 full address program second time",
  "originator": {
    "address": "19019",
    "type": "shortcode"
  },
  "program_statistics": {
    "broadcast_enqueue_time": null,
    "broadcast_start_time": null,
    "last_refresh_time": null,
    "message_generation_end_time": null,
    "opt_out_rate": null,
    "total_messages_failed_delivery": 0,
    "total_messages_pending": 0,
    "total_messages_received": 0,
    "total_messages_sent": 0,
    "total_unique_opt_outs": 0,
    "total_unique_recipients": 0
  },
  "scheduled_at": null,
  "second_retry_option": "send to unmatched",
  "status": "active",
  "type": "broadcast",
  "updated_at": "2023-07-06T21:33:25Z",
  "updated_by": null,
  "webform_profile_attributes_enum": null,
  "webform_token": null
}