Setting up SMS Double Opt-In

Iterable's SMS Double Opt-In feature is an automated flow that leverages a double opt-in message type in combination with an API endpoint to confirm a user's subscription to SMS message types. There is some setup required to use SMS Double Opt-In, including creating a double opt-in message type and a web form that triggers the double opt-in flow.

This article explains how to set up and use SMS Double Opt-In.

# In this article

# Getting started

To use Iterable's SMS Double Opt-In, you need to set up the following:

• SMS channel set up in Iterable (either Iterable SMS or your own account from Telnyx or Twilio)
• A message type with a double opt-in subscription policy.
• A web form that posts to Iterable's API (from a server-side context, not client-side), which starts the SMS Double Opt-In flow.

# Step 1: Create a double opt-in message type

First, create a message type with a double opt-in subscription policy.

You can create a brand new double opt-in message type, or you can change an existing opt-in message type to double opt-in.

# Option 1: Create a new double opt-in message type

1. In Iterable, go to Settings > Message Channels and Types.

2. Go to the SMS tab using the left-hand navigation.

3. Find the subscription channel where you want to add a double opt-in message type.

4. Click Add Message Type.

   

5. Enter a Name for the new message type and select Double Opt-In as the Subscription Policy.

6. Enter the details for the double opt-in message type:

   • Brand Name: The brand name to display in the double opt-in messages. This field is required and can contain up to 50 characters.
   • Messaging Initiative: A description of messages your users can expect to receive on this message type. This field is required and can contain up to 100 characters.
   • SMS Disclaimer Link: A valid URL that begins with https://. This field is required and can contain up to 100 characters.

7. Select a Sender to use for the double opt-in confirmation and legal disclaimer messages.

8. Click Create Message Type.

# Option 2: Change an existing message type to double opt-in

You can change an existing opt-in message type to double opt-in. This is useful if you want to change the subscription policy for an existing message type.

Users who are already subscribed to the opt-in message type aren't affected by the change from opt-in to double opt-in. They continue to be eligible for this message type and don't need to confirm their subscription when you make this change.

To change an opt-in message type to double opt-in, follow these steps:

1. In Iterable, go to Settings > Message Channels and Types.

2. Go to the SMS tab using the left-hand navigation.

3. Find the opt-in message type you want to change to double opt-in.

4. In the overflow menu for the message type, select Update to Double Opt-In.

5. In the dialog that appears, click Next.

6. Enter the details for the double opt-in message type:

   • Brand Name: The brand name to display in the double opt-in messages. This field is required and can contain up to 50 characters.
   • Messaging Initiative: A description of what kind of messages that the users are subscribing to with this message type. This field is required and can contain up to 100 characters.
   • SMS Disclaimer Link: A valid URL that begins with https://. This field is required and can contain up to 100 characters.

7. Select a Sender to use for the double opt-in confirmation and legal disclaimer messages.

8. Click Update to Double Opt-In.

# Step 2: Create a web form

Create a web form of your design that collects the user's phone number and asks for their consent to receive SMS messages. The form should post to Iterable's API to trigger the double opt-in subscription flow.

# Web form components

The web form should contain these components:

• A field for the user's phone number (stored as phoneNumber in Iterable).
• A field to identify the user (either email or userId depending on your project type).
• Checkboxes or radio buttons for each double opt-in message type that the user can subscribe to.
• A submit button that triggers the API that starts the SMS Double Opt-In subscription flow.

# Web form submission

When the form is submitted, your server should send an API request to the POST /api/subscriptions/subscribeToDoubleOptIn endpoint.

A server-side API key is required to make the API call. (Note that server-side API keys should not be exposed in client-side code. To learn more, read Make API calls from your server, not the browser.)

To learn more about this endpoint's request body, parameters, and response, read POST /api/subscriptions/subscribeToDoubleOptIn.

# Step 3: Test the double opt-in flow

After setting up the double opt-in message type and web form, test the flow to ensure that users can subscribe to SMS messages.

1. Complete the web form with a phone number that you can use to receive SMS messages.

2. Submit the form to trigger the SMS Double Opt-In subscription flow.

3. Check your phone for the confirmation message, and make sure the message is correct.

4. Reply 'Y' to the confirmation message to confirm your subscription.

5. Check your phone for the automated legal disclaimer message, and make sure the message is correct.

6. Check the SMS usage info events on the test user's profile history to learn how many segments each message type has. This can help you estimate the usage & cost of SMS Double Opt-In.