SMS and RCS subscription groups

Subscription groups are the foundation for sending SMS, MMS, and RCS messages through Braze. A subscription group is a collection of sending entities (such RCS-verified senders, SMS short codes, SMS long codes, or SMS alphanumeric sender IDs) that are used for a specific type of messaging purpose. For example, if a brand has plans to send both transactional and promotional SMS messaging, two subscription groups with separate pools of sending phone numbers will need to be set up within your Braze dashboard.

Subscription group states

There are two subscription states for SMS and RCS users: subscribed and unsubscribed. A user’s subscription state resides at the subscription group level and is not shared across subscription groups, meaning a user can be subscribed to a transactional subscription group but unsubscribed to a promotional one. For brands, this separation of states ensures that they can continue to send relevant SMS and RCS messages to their users.

Setting a user’s state

When a phone number is updated on a user profile, the new phone number inherits the subscription group status of the user. If the phone number is updated to a number that already exists in Braze, the subscription status of that existing phone number is inherited.

For example, if User A has a phone number that is subscribed to several subscription groups and that phone number then gets added to User B, User B will be subscribed to the same subscription groups. To prevent a user from inheriting the existing subscriptions, you can reset the subscription groups of the old number through the Braze REST API whenever a user changes their number. If multiple users share this phone number, they will all be unsubscribed.

To set a user’s subscription group state, use one of the following methods:

• Rest API: User profiles can be programmatically set by the /subscription/status/set endpoint by using the Braze REST API.
• SDK Integration Users can be added to an email or SMS and RCS subscription group using the addToSubscriptionGroup method for Android, iOS, or Web.
• Automatically handled upon user opt-in/opt-out: By users texting a default opt-in or opt-out keyword, Braze automatically sets and updates users’ subscription state.
• User import: Users can be added into email or SMS and RCS subscription groups through Import Users. When updating subscription group status, you must have these two columns in your CSV: subscription_group_id and subscription_state. Refer to User import for more information.

Checking a user’s group

To check a user’s subscription group, use one of the following methods:

• User Profile: Individual user profiles can be accessed through the Braze dashboard by selecting User Search from the sidebar. Here, you can look up user profiles by email address, phone number, or external user ID. When inside a user profile, under the Engagement tab, you can view a user’s SMS and RCS subscription groups.
• Rest API: Individual user profiles subscription group can be viewed by the List user’s subscription groups endpoint or List user’s subscription group status endpoint by using the Braze REST API.

Sending messages with a subscription group

To launch an SMS or RCS campaign through Braze, select a subscription group from the SMS/MMS/RCS Variants dropdown. After it’s selected, an audience filter will be added to your campaign or Canvas automatically, ensuring that only users subscribed to the selected subscription group are in the target audience.

Enabling subscription groups

To enable subscription groups for SMS, MMS, or RCS, refer to the following:

• sms
• mms
• rcs

Migrating SMS traffic to RCS

If you have separate SMS and RCS subscription groups, you can migrate users from SMS to RCS using a one-step Canvas.

Braze recommends that you test sending RCS to smaller volumes of users initially and migrate more users to the RCS subscription group over time. For example, if you have 1,000,000 users subscribed to an SMS subscription group, this could look like first migrating all users to the new subscription group and then segmenting on a smaller audience of 50,000 to 100,000 (5-10%) to test the RCS messages.

Step 1: Create a Canvas and fill out the Entry Schedule

Create a Canvas and name it something easily identifiable (such as “SMS-RCS Subscription Group User Transfer”). Then, schedule the campaign whenever is convenient for you.

Step 2: Define your audience

Define your audience using one of the following methods. Next, go to the Send Settings step and select Users who are subscribed or opted-in.

Step 3: Configure a User Update step

Add a User Update Step to your Canvas. In the step, open the Advanced JSON Editor and input the following (for the unique user identifier field, we recommend using the braze_id field):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "attributes": [
    {
      "braze_id": "{{${braze_id}}}",
      "subscription_groups": [
        {
          "subscription_group_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
          "subscription_state": "subscribed",
          "use_double_opt_in_logic": true
        }
      ]
    }
  ]
}

Step 4: Test the Canvas

We highly recommend testing your Canvas to confirm it works as expected before sending it to your broader audience.

Step 5: Launch your Canvas

After you have successfully tested your Canvas, go ahead and launch it for your subset of users!

To confirm that your users were successfully migrated, we recommend checking a few individual user profiles that were updated. In the Engagement tab, look for Contact Settings and scroll to view the subscription groups the user is subscribed to. The RCS subscription group toggle should now be on.