10DLC Campaign Delays and Programmatic Toll-Free Onboarding

10DLC Campaign Delays and Programmatic Toll-Free Onboarding

It's crunch time! With the August 31st deadline looming for registering Application to Person messaging campaigns, businesses are finding themselves in a sticky situation. Messages sent from unregistered A2P 10DLC numbers will be blocked, returning either the 30034 or 30035 error responses, which indicates that the message is from an unregistered number.

But don't fret! In this post, I’ll introduce you to a script which is designed to mitigate 10DLC campaign registration delays, avoid blocked SMS traffic, and offers an alternative or temporary solution if you are facing 10DLC verification queues by swapping 10 digit long codes with compliant toll-free numbers.

The Solution: Toll-Free Numbers

Businesses unable to complete their campaign registration on time are able to replace their 10DLC numbers with toll-free numbers leveraging an automated solution. Toll-free numbers are a flexible sender type in the US and Canada, available for voice and messaging, and are capable of sending high volume SMS and MMS. Because they can be used across use cases and communication channels, they provide businesses with a singular number for all communication needs, creating a brand identity.

Automated solution: the script

This script is designed to:

• Iterate through parent and subaccounts: This means that every account linked to your main account is evaluated (unless they are explicitly excluded).
• Identify problematic messaging services and numbers: If desired, the script spots messaging services with at least one 10DLC number that has sent messages in the US within the last 7 days and has encountered 30034 or 30035 error responses (thereby avoiding swapping unused or non-impacted numbers).
• Select existing available toll-free numbers or purchase new ones: If you have available toll-free numbers, these are chosen first. If not, new numbers are purchased via Twilio's Phone Number API.
• Swap 10DLC numbers with new toll free numbers on the Messaging Service: 10DLC numbers will be removed from the service but will remain on the account. The new toll free number will then be added to the messaging service.
• Submit for toll-free verification using API: If a pending campaign exists, the script will attempt to gather necessary information to submit for toll-free verification from 10DLC brand and campaign records. If there are no campaign details to fetch, the number will be in restricted status until a verification request is sent. Please review Toll Free Verification limits for each phase in the process.
• Option to skip accounts: A CSV exclusion list can be passed to the script, allowing certain accounts you designate to be left untouched.

Considerations

Before continuing through this guide, please ensure you are aware of these important considerations:

• The use of this script assumes you're already using Messaging Services in your accounts.
• As a prerequisite, ISVs must have a Primary Customer Profile setup and your Business Type set as an ISV. See: Prerequisites and Best Practices for ISV's Using Toll Free Numbers.
• As a reminder, ISVs must always submit the end business's information. This script will attempt to retrieve this via the current 10DLC Brand and Secondary Customer Profile data, however it is your responsibility to ensure its accuracy.  See: Toll Free Verifications for ISV's
• Verification may be rejected if the existing campaign has inaccurate data. Incomplete or inaccurate data in the existing brand or campaign records could lead to verification rejection for the Toll-Free number, resulting in a resubmission or outright rejection of the verification request.
• If no existing campaign data is available on the Messaging Service, the toll free number assigned to it will not be submitted for verification and will remain in a “restricted” state. You will need to submit for verification by other means, including via a support ticket, through the console, or via an API call. See limits here for more information on the different stages of verification and their caps until the number is fully verified.
• If you want to include shortened URLs in your messages, we recommend using a dedicated short domain. Public URL shorteners are not allowed. For details, see How can I send shortened URLs (links) in my messages?
• Toll free numbers are selected at random, and there is no logic built into the script to prefer certain numbers.
• There's no cap on the number of toll-free numbers that can be bought, unless you explicitly state a limit in the dialog. 10DLC’s are replaced on a one for one basis on each Messaging Service. Please note that toll free verification has a limit of 5 numbers for a single end business.  Any more than 5 per business will result in a rejection without further justification.
• Your original 10 digit long code numbers remain on your account, however it will be unassigned to any messaging service.
• You need your parent account SID and auth token to process and iterate through the subaccounts.
• We highly recommend starting with a small number of subaccounts using the exclusion list or limiting the number of toll free numbers to purchase to validate it works well in your environment before proceeding to the full list.
• If your application is currently calling the Messaging Services API using the phone number as a “from” field instead of the”messagingServiceSid”, you will need to adjust your code to use the TFN instead of the original 10DLC number.

Required JavaScript packages

Prompted Inputs

Upon execution, the script prompts you to:

• Decide whether you would like to include the count of error codes 30034 or 30035 within the past 7 days when selecting numbers to replace.
• Choose whether you want to replace all 10 digit numbers without a successful campaign, or just those in a pending status. (choosing “no” will avoid having toll free numbers that remain in a restricted status due to no verification as this script will not send a verification request on those numbers with failed or no campaign at all)
• Determine the maximum quantity of toll-free numbers to purchase.
• Reference a CSV exclusion file with account SIDs to avoid.
• Input OptInType, UseCaseCategory, OptInImageUrls, and monthlyMessageVolume for toll-free verification if applicable. (These will be the same for all TFN verification submissions in the script so be sure that they are relevant across all verified phone numbers)

Retrieve the application from Github

Setup Instructions

Follow these steps to set up and run the toll-free number automation script:

1. Prerequisites

• Node.js: Ensure you have Node.js and github installed. You can check by running:

2. Clone the Repository

Clone the repository to your local machine. The repository is located here.

3. Install Dependencies

Once inside the project directory, install the necessary packages:

4. Configuration

Environment Variables: Rename the .env.example file (if it exists) to .env and update the variables with your values, especially your parent account SID and Auth Token.

You can find your Account SID and Auth Token inside the Twilio Console.

(Optional) CSV Exclusion File

If you're planning to exclude certain accounts, prepare a .csv file with the account SIDs you want to omit.  The .csv is simply a list of each subaccount you wish to exclude from the execution.  You may want to consider starting with a few of your subaccounts to begin with and validate the script before moving to the entire list.

Example:

ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1
ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2
ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3
ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX4

5. Running the Script

With everything set up, execute the script using:

Here’s an example runthrough of the script. Replace the responses with the proper settings for your project.

Additional Resources

For more in-depth understanding and information, refer to:

• API Onboarding for Toll-Free
• US A2P Campaign Resource
• Twilio's Messaging Compliance API for Toll-Free Verification
• Event Streams Setup and Notifications for A2P Brands and Campaigns
• Limits on Toll Free in Different Stages of Verification

Possible Future Enhancements

The possibilities to expand the script are endless! While you might put the script into effect while you wait for 10DLC registration, future updates could incorporate:

• A feedback loop using event streams to switch back to 10DLCs.
• A user-friendly web front-end for manual number swapping.
• A feature to store updated numbers and toll-free verification data.

In this era of swift digital communications, it's vital to stay compliant and ensure business continuity. Toll-free numbers as an alternative to 10 digit long codes can help ensure that. Let's keep the messages flowing!

Giles Everist is a Solutions Engineer at Twilio. He lives in Denver, CO and enjoys working with customers and solving business problems - besides golfing and spending time with his family. He can be reached at geverist [at] twilio.com