Thursday, 24 August, 2023 UTC
Summary
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! There’s a workaround that can tide you over while you await your campaign's approval, or simply use these new valuable numbers moving forward. 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 to the more strict carrier requirements around sending SMS over long codes on their networks by swapping unregistered 10 digit long codes with toll-free numbers.
The Solution: Toll-Free Numbers For businesses unable to complete their campaign registration on time, current policies permit sending messages using toll-free numbers even if they are in a pending status. By swapping your unregistered 10-digit long code with a toll-free number, you can bypass these blocking issues.
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: 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 unregistered 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 service.
- Submit for toll-free verification using API: If a pending or failed 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.
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.
- Verification might be rejected if the existing campaign has inaccurate data. Incomplete or inaccurate data in the existing campaign could lead to verification rejection for the Toll-Free number.
- If no existing campaign data is available on the messaging service the toll free number assigned to it will not submit for verification and will remain in a restricted state. See limits here for more information on the different stages of verification and their caps.
- 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.
- Your original 10dlc number remains on your account.
- You need your parent account SID and auth token to process and iterate through the subaccounts.
Required JavaScript packages
require('dotenv').config(); require('twilio'); require('moment'); require('readline'); require('fs'); Prompted Inputs
Upon execution, the script prompts you to:
- Determine the quantity of toll-free numbers for purchase.
- Reference a CSV exclusion file with account SIDs to avoid.
- Input
OptInType,UseCaseCategory,OptInImageUrls, andmonthlyMessageVolumefor toll-free verification if applicable.
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 installed. You can check by running the following commands in a terminal:
node -v git --version 2. Clone the Repository
Clone the repository to your local machine, and change directory into it. The repository is located here.
git clone https://github.com/geverist/10dlc2tollfree.git cd 10dlc2tollfree/ 3. Install Dependencies
Once inside the project directory, install the necessary packages:
npm install 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.
TWILIO_ACCOUNT_SID=your_account_sid TWILIO_AUTH_TOKEN=your_auth_token (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 ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX45. Running the Script
With everything set up, execute the script using:
node migrate2tollfree.js Here’s an example runthrough of the script. Replace the responses with the proper settings for your project:
What is the maximum number of toll-free numbers you are willing to purchase? (Enter "unlimited" for no limit): unlimited Would you like to include an exclusion .csv for account SID's? (Enter path to CSV or "no" for none): exclusions.csv Enter your Monthly Expected Message Volume for Toll Free Verification (10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000, 10000000+): 10 Select your OptInType (VERBAL, WEB_FORM, PAPER_FORM, VIA_TEXT, MOBILE_QR_CODE): VERBAL Select your UseCaseCategory (TWO_FACTOR_AUTHENTICATION, ACCOUNT_NOTIFICATIONS, CUSTOMER_CARE, CHARITY_NONPROFIT, DELIVERY_NOTIFICATIONS, FRAUD_ALERT_MESSAGING, EVENTS, HIGHER_EDUCATION, K12, MARKETING, POLLING_AND_VOTING_NON_POLITICAL, POLITICAL_ELECTION_CAMPAIGNS, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT): MARKETING Please enter your OptInImageUrls (must be a valid URL): https://www.test.com/optin.jpg Processing subaccount SID: ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Messaging Service SID: MG192e1869c199a4d0a383a45da7c73905 No campaigns associated with messaging service MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX No long code numbers associated with the messaging service MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 10dlc2tollfree$ 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
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 once approved.
- 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. This toll-free workaround ensures just 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