Texts¶

Requirements¶

For texting, as with email, you can only send messages to users who expect to hear from you.

The carriers (e.g. Verizon, AT&T) enforce their own rules. These implement the Cellular Telecommunications Industry Association (CTIA) guidelines and Telephone Consumer Protection Act (TCPA) rules and may go beyond them. The industry is in flux but the intent of these rules and guidelines is clear. Users must opt-in to receive text messages from you. You must communicate some basic information to your users including who you are, how to opt-out, how to get more information and how often users should expect to hear from you.

We've incorporated some current best practices. We capture information about each user's consent to receive messages and document and enforce opt-outs. Our built-in design includes a checkbox so you can capture a user's explicit opt-in. We've included sample disclaimer language.

We've also given you a lot of freedom for customizing the your content and user experience. As with email, your ability to deliver text messages will reflect your own behavior. We encourage you to keep the intent of the texting regulatory framework in mind as you design and implement your texting program.

Beta¶

If you are participating in our texting beta, there are a few things to note.

You can find your outbound number on the CONFIG screen under Integrations.

If you're importing text subscribers, you'll need to create a fake email for each row (unless you know the user's email). Emails must be unique so we suggest doing something that's easy to track like 'sms1@example.com' for row 1, sms2 for row 2, etc. You'll need to track the highest number used so you can start with that number +1 for your next import. We'll auto-generate these fake emails for you in an upcoming release.

Take care not to disable required autoresponders. We ship with some pre-configured autoresponders for common keywords like “STOP”, “START”, “CONFIRM”, “HELP”, etc. If you change these keywords or disable the autoresponders, your users may not receive important responses, and your texting reputation may be impacted.

Users can sign up for texting by acting on a page, but they can't manage their own texting subscriptions, such as changing lists or unsubscribing, through a page.

The TCPA states that “automated texts can only be sent between 8 a.m.- 9 p.m. in the recipients' time zone." Often you won't have location data for your texting subscribers so it's safest to send between 11 am and 9 pm Eastern. However, here's nothing to stop you from texting outside these hours.

As noted below, an email can only have one associated subscribed mobile phone number at a time and a phone number can be textable (subscribed) for only one email at a time. A single broadcast will only be delivered once to a given phone number. But there are minimal other guards against sending multiple messages (say, on a single day) to a given user.

Texting does not yet support many of the advanced features you know from the mailer, like recurring mailings, merge files, merge queries and A/B testing. We're also in the process of adding texting reports. Please help inform our priorities by letting us know about your desired use cases!

Finally, keep those support tickets coming. We want to know if something isn't working. We also want to know if something is surprising or if you've got ideas for improvements. Thank you for your help!

Subscribe through Page Action¶

You can configure the user form of any ActionKit page to allow users to subscribe to text messages.

From the Edit Content screen of the page, in the User form fields section, add the Mobile Phone field and check SMS Opt-in.

This adds a checkbox to your page under the mobile phone field, which users must check to subscribe. If you select "Single Opt-In:" users are immediately subscribed. We recommend sending a confirmation message welcoming the user to your list.

If you do not check "Single Opt-In:", the user will receive a text message asking them to confirm their subscription. The user's texting subscription status will be set to 'pending' and they will not receive text messages until their subscription has been confirmed.

Fill in the “Label” and “Notice” fields, which are displayed to the user. The language of these fields must make it explicit that the user is signing up to recieve text messages.

Although many people have mobile service plans that cover unlimited text messages, some people still pay a service for each text message sent or received, or for each megabyte of data traffic. When enrolling new text subscribers you should notify them of this possibility using language such as "message and data rates may apply."

If you are building your own forms outside ActionKit, you will need to include the following fields for text message subscriptions:

Required:

• texting_fieldname -- a checkbox input whose value is the name of a phone input field (like "phone" or "mobile_phone"), with the opt-in language
• phone (or mobile_phone) -- the input to collect the phone number

Optional:

• texting_require_opt_in -- as a hidden input, this causes a confirmation text to be sent to the user. Their subscription will be "pending", and they must affirmatively reply to the confirmation text in order to be subscribed and receive further messages. If this input is absent, empty, or "0", the subscriber will receive the "welcome" message with information on how to opt-out, and will be subscribed immediately.
• texting_skip_confirmation -- If present, don't send a confirmation text. Note that unless the user is already confirmed, they will not receive information on how to opt in, and will never be reachable.

Subscribe through Import¶

You can add subscribers to your text lists through an import page by including the header 'texting_address' where you'll provideg the user's mobile number. Mobile numbers should begin with the country code and area code and contain no punctuation, such as '12025551212'.

Import pages require an email address for new users, or a user_id or akid for existing users. See the Beta section above for tips on creating fake email addresses.

Imported mobile numbers will be added to your default texting list. If you would like to add the users to a different list, include a column with the header 'texting_list'.

Imported text subscribers are subscribed immediately, and do not receive a confirmation message.

You can add a column "texting_skip_confirmation=0" to ensure that the "welcome" message is sent to new subscribers. If you import new subscribers in off hours, we don't recommend prompting the welcome message. In that case, you can create a broadcast, target it to users who took action on the import page and schedule it for a reasonable time. A broadcast message also makes mor sense if you're moving subscribers from another platform since it's best practice to send a message notifying these subscribers that the number you'll be texting from has changed.

If you would like imported text message subscribers to affirmatively opt-in before they are subscribed, add the column "texting_require_opt_in" to your upload with a value of "1" on each row. Once uploaded, the user's texting subscription status will be set to 'pending'. They will receive a text message asking them to confirm their subscription and they cannot receive text messages until they have done so.

Compose¶

From the texting dashboard, “Create New Draft” will take you to a compose screen where you can edit your broadcast message. You can also set internal notes, tags, a landing page, and custom fields.

As with an email message, a text message can include code to personalize the message for each recipient. Snippets are provided for commonly used substitutions.

Hello {{ user.first_name|default:"Friend"|title }}!

To use the snippets for "Landing Pages", "Suggested Ask" under "Donations", and "Page Targets" snippets you need to select the relevant page from the drop down so ActionKit knows where to find the related information.

There is no “visual” HTML editor since text messages do not support HTML tags. However, most messaging apps will link URLs in text messages.

As with mailings, ActionKit will generate a short link for all URLs in text messages. Clicks and actions from a link are recorded in the database.

Notes and tags are useful for categorizing your broadcasts so you can more easily find and compare them later.

Preview shows a preview of the text content, and you can specify the user_id or email of a user for whom to see a preview.

You'll also see an estimated segment count for the user previewed. The actual segment count for the message each user receives is determined by the final number of characters included. For example, a user with a long first name might require two segments for a message with the intro shown above.

Target¶

From the target screen, you can specify the audience for your broadcast, filtering or excluding users by their geographic location, lists, groups, past actions, donor status and more. You can also set a limit and order.

Texting targeting works like the ActionKit mailer, and the underlying mechanisms are the same. Read more about how our targeting system works at Target.

Proof and Send¶

The proof and send screen shows a summary of the content and targeting you have specified for a broadcast and a count of the targeted audience who will receive it.

Use the proofs form to send yourself proofs of the message and verify that it comes through as expected. You must first subscribe the phone number you'd like to receive proofs at. You can do this from your user record.

Finally, when you’re ready, you can send the message, or schedule it for later. A table shows a breakdown of the audience by time zone so you can check to be sure no one will receive it too late or too early. Subscribers with no location info are included in the Eastern Time count.

After-Action Text Messages¶

You can configure text messages that will be automatically sent to texting subscribers who take action on specific pages. These are similar to confirmation emails except you create them from the Text Tab and select the page or pages to associate them with.

After-action messages are only sent to texting subscribers.

Automatic responses¶

An auto-response is a preconfigured message that is sent in response to an incoming message sent by a user. Auto-responses are based on triggers that you define.

For example, if a user sends an incoming message containing the word STOP, you might send a message that says "You have been unsubscribed."

We ship with some pre-configured autoresponders for common keywords. You can edit the messages but you shouldn't disable these.

You are required to honor subscriber opt-outs via text. If a subscriber texts STOP, or equivalent normal language requests like end, unsubscribe, cancel or quit, they should receive one final message from you confirming the unsubscribe, then be removed from your texting list. Users can resubscribe by explicitly opting back in.

Similarly, if a user sends an incoming message containing the word HELP, your auto-responder should include the organization name and opt-out instructions, "You are receiving action updates from [Organization]. Send STOP to cancel." You may also want to include where the subscriber can get more information.

In addition to sending a message to the user, you can configure the auto-response to subscribe, confirm, or unsubscribe the user from texting lists.

Confirmation Messages¶

Your instance will have confirmation messages for four specific events. You should customize these before you launch your texting program. The triggers are:

• "Welcome" - New subscribers should receive a welcome message that includes who you are, how to opt-out, how to get more information and how often users should expect to hear from you. You can customize the language but you must include the same content as in the sample message.
• "Opt-in Confirmation (Changed Number)" - A user who is subscribed to your text list with an associated mobile number and email address signs up with a different phone number. This message should confirm that the user intended to subscribe at the new phone number. The old number will be unsubscribed.
• "Opt-in Confirmation (Replacing Other User)" - A user who is subscribed to one of your text lists with an associated mobile number and email address signs up with a different email address. This message should confirm that the phone number should be associated with the new email address.
• "Opt-in Confirmation" -- A user signs up for your texting list on a page that requires double opt-in or is added from the Users Tab. This message asks the user to text "start" to confirm they want to receive your text messages. The user's status is set to "Pending" and they can't be texted until they confirm.

Incoming Text Messages¶

While ActionKit only sends email and never receives it, in the case of text messages ActionKit can also receive incoming messages from users that are sent to your originating numbers. We provide a searchable log of all incoming messages and how they were handled by the system.

When the incoming message generates an automatic response, the status shows "Handled". You can view the content of any incoming message. If you wish to follow up on incoming messages that don't have an automatic response you can generate a new broadcast targeted to the individual user.

Texting Lists¶

As with mailings, users need to be subscribed to a list to be available for inclusion on the Targeting screen. A user cannot be subscribed without belonging to at least one text list.

Every client with texting enabled starts with one texting list, called "Main SMS List". From the "Texting Lists" link under "Sending Options" you can rename this list and add or hide additional lists.

You can also change your default list from this screen. The default is the list new subscribers will be added to when subscribing through a page action or an import (unless you specify an alternative in your CSV).

Blocklist¶

You can add numbers to your Blocklist to ensure that they cannot receive text messages from you, even if they opt-in.

From the link you can add, edit or delete numbers on the blocklist.

Tags¶

Tags can be used to categorize broadcast texts for internal tracking. The tag list is shared across pages, mailings and texts.

Custom Text Fields¶

Custom text fields can be used to track meta data associated with texts. For example, you might create a custom text field called "Type" to categorize the ask in each broadcast so can later compare performance between like broadcasts (e.g. comparing fundraising texts with each other).

You could also use these fields to create some workflow shortcuts, even though texts don't support sophisticated templating like mailings. For example, you could create a simple draft broadcast for use as a starting point:

Hi {{user.first_name}}! {{custom_fields.ask_text}} {{custom_fields.ask_url}} This message is from FunOrg. HELP for info, STOP to end.

Other staff could copy this draft and type the ask and url into the custom text fields on the compose screen without touching the message body, eliminating a place where errors or typos could be introduced.

Individual Text Report¶

From the "Sent Broadcasts" view click on the a broadcast to view a summary report showing Clicks, Actions and New Users attributed to this broadcast.

Compare Text Messages¶

You can compare click and action stats between multiple broadcasts from this screen.

Query Builder¶

There are two query types within the Query Builder that are specific to texting. The Text Messages query type enables you to create reports about text broadcasts, similar to the Mailings query type. To create reports about your texting subscriptions, use the Texting Lists query type, which is the equivalent of the Mailing Lists query type.

In addition, the Users query type has display/ filter options for texting lists and subscription status.

Originators¶

In order to send and receive text messages, you must have a texting-capable phone number registered with the gateway service; in the jargon of text messaging, these texting-capable phone numbers are known as "originators."

While any number associated with a mobile phone can be used to send and receive text messages, additional work is required to obtain a phone number that is capable of sending messages using a gateway service.

Several different types of phone numbers may be used:

• Short codes are four-, five-, or six-digit numbers that are used only for sending and receiving text messages.
• Text-capable 800 numbers are standard 800-style numbers (beginning with prefixes such as 800, 888, 877, 866 and so forth) which are registered for use with a messaging gateway.
• Ten-digit long codes (10DLC) are regular-style phone numbers which are registered for use with a messaging gateway

Texting Spam and Trust Metrics¶

Like email, text mesaging is subject to spamming efforts by bad actors, and anti-spam measures deployed by carrier networks to limit it.

In order to send messages through a gatway service, the originator phone numbers that will be used must be approved for application-to-person messaging (A2P).

Obtaining approved A2P originator numbers can take a few weeks, and require submitting a "campaign brief" that describes your organization and how you intend to use text messaging to communicate with your users.

Based on this information, your originating number will be given a trust score that also governs how many outbound text messages you may send in a given period of time. A large established organzation with a previous track record of text messaging campaigns might receive a trust score that allows them to send over a hundred thousand messages per hour, while a new organization just starting out might be limited to a few thousand messages per hour.

Gateway Service¶

To connect the web-centric world of ActionKit to the telephony-centric world of mobile carrier networks used by text messages, we rely on a service known as a "gateway."

The web-to-text gateway service used by the current version of the texting tool is provided by a vendor named OpenMarket. ActionKit manages the relationship and fees associated with this service, but clients may need to interact with OpenMarket during the process of setting up texting capabilities for their instance.