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 keyword responders. We ship with some pre-configured keyword responders for common keywords like “STOP”, “START”, “CONFIRM”, “HELP”, etc. If you change these keywords or disable the keyword responders, 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 subscription, such as 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 Texting 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 list 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 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.

If you want to send media like images, video, or audio with your message, select "MMS" instead of "SMS" as the Send Type. This will reveal an input where you can enter the URL of the media file you'd like to send. The preview should update accordingly.

Note that the URL for the media file must be publicly accessible, and have a correct Content-Type header for its type. Media uploaded via the Media Library should meet these requirements. Also, the media size should be no larger than 600kB, and any associated text should be less than 1600 characters.

Target¶

From the target screen, you can specify the audience for your broadcast, filtering or excluding users by their geographic location, 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.

The Respect Recipient Local Time option is checked by default. With this option on, recipients who would receive a text outside of normal hours (8am-9pm) in their local timezone will be skipped instead of sent a message. These will appear as failed sends on the Broadcast report screen and can be targeted for a subsequent message by copying the Broadcast. Users with an unknown timezone will be contacted only if they would receive a message at a time that's valid anywhere in the Continental United States (Eastern-Pacific times).

Unchecking the box removes this safety: a warning will be shown on the Proof and Send page, but messages will go out to all targeted recipients when the Broadcast is sent regardless of what time it is.

Confirmation Messages¶

Confirmation messages are built-in automatic replies, required for all texting programs. It is important to customize these before you launch your texting program.

Confirmation messages differ from Keyword Responses in that the former are not triggered by anything sent by the user. Confirmation messages are triggered based on changes to a user's subscription status.

The four confirmation triggers are as follows:

• "Welcome" – This is usually the first message users see after they subscribe (for example, by texting the keyword "SUBSCRIBE"). 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" -- 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.
• "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 your text list 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.
• "Nonsubscriber Reply" - If a NON-subscriber sends a message other than "Subscribe", this message will be sent back to them in reply. This message should identify the list/organization, and advise them to reply "Subscribe" if they would like to join.

Automatic Keyword-based Responses¶

Unlike with email messages, Actionkit both sends AND receives text messages.

A "Keyword Response" is a preconfigured message that is sent in response to an incoming message received from a user. Keyword responses are based on custom triggers, called "keywords", that you define. You can use these keyword responses to provide additional general information to users, or to support specific campaigns.

For example:

• User texts "ABOUT" or "HISTORY": Respond with details about your org, and maybe a link to a more expansive page.
• User texts "EVENTS": Respond with a list of upcoming events
• User texts "DONATE": Respond with a link to a donation page

In addition to responding with a message, Keyword Responses may also change the user's subscription status. On the edit screen for Keyword Response messages, under the "Actions" heading, you may select "Subscribe", "Unsubscribe", or "No Change" for each keyword response.

Required Keywords

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

There are some keywords which must be configured to always unsubscribe a user. These keywords are: "STOP", "CANCEL", and "UNSUBSCRIBE".

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

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

After-Action Text Messages¶

You can configure text messages that will be automatically sent to texting subscribers who take action on specific pages. These "Confirmation Text" messages are similar in function to after-action confirmation email messages.

However, unlike confirmation emails, the message text is reusable, and created via the "After-Action Text Messages" admin. To get to this admin page, click on the "Texts" tab, expand "Transactional Messages", and click on "After-Action Messages"

After-action messages are only sent to texting subscribers.

Incoming Text Messages¶

Unlike with email messages, Actionkit both sends AND receives text messages. You can view all incoming text messages by going to the "Incoming Messages" admin. To get to this admin page, click on the "Texts" tab, expand "Transactional Messages", and click on "Incoming Messages".

From this admin screen you can search, filter, and sort all text messages received by users.

The "Status" column on this page tells you how Actionkit responded to the message, if it was able to respond. Common status types:

• Handled: Actionkit automatically responded using one of the Keyword-based Responses
• No Handler: No Keyword-based response matched the incoming text, and no automatic response was made
• No Matching Subscriber: A text message was received from an unknown phone number, and no Keyword-based response was possible

If you wish to manually follow up on incoming messages (typically one for which there was no automatic response), clicking on the subscriber's name will take you to the User admin texting page. From this page, a response can be sent to the user by an admin. These responses can be selected from the list of Keyword-based Responses, OR they may be written by hand. (Note that these admin reply messages may only be sent to users who have subscribed from a known text phone number.)

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¶

In the query builder, the Text Messages query type enables you to create reports about text broadcasts, similar to the Mailings query type.

In addition, the Users query type has display/ filter options for texting 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.