Troubleshooting A2P 10DLC registrations

To register in the US 10DLC ecosystem, customers must register a Brand for their business entity and then register an A2P messaging Campaign, for that Brand, built around a specific use case. This process can fail both at the Brand- and Campaign-approval stages. Brand registrations typically fail if the business-identifying information is incomplete, improperly formatted or doesn't match existing records. Campaigns tend to fail when the description of the proposed Campaign purpose, use-case, workflow, opt-in and opt-out methods is incomplete or inadequate, or if the substance of the proposed Campaign is deemed to violate TCR policies.

Finally, after a Campaign has been successfully registered for A2P, each of the phone numbers present in (or subsequently added to) the Messaging Service associated with that Campaign must themselves be registered by the A2P ecosystem partners. This process is initiated once the Campaign has been approved, but is not instantaneous and in some instances can be delayed or can fail.

The present document will explore troubleshooting Brand and Campaign issues and, where necessary, resubmitting both Brands and Campaigns that have been rejected. Finally, we will see how customers can check the current A2P registration status of all phone numbers owned by their account.

1. Troubleshooting Brand registration failures

This document walks through the process of registering a Standard or Low-Volume Standard Brand and Campaign via our APIs. In Step 3 of that document you have created the new Brand, and in Step 3.01 you call fetch on that Brand to determine its current STATUS, as indicated in the brand_status return parameter. The possible statuses of the Brand you've created are as follows:

• "PENDING": your Brand registration has not yet been completed. Most Brand registrations complete within a few minutes, but a few registrations take more than seven days.
• "IN_REVIEW": your Brand registration has not yet been completed; your Brand information is under manual third-party review. Such a manual review takes seven business days or more. There is no action required from your side.
• "APPROVED": your Brand registration was completed and verified. You can now register your campaigns. Please note, however, that a Brand with APPROVED status might still have brand_feedback information which could be used to improve your Trust Score. Please see immediately below for details.
• "FAILED": your Brand registration's information couldn't be verified. Please review the brand_feedback or failure_reason fields to understand more about this failure.
• "SUSPENDED": your Brand is deemed to have potentially violated one or more rules for Brand registration established by the A2P ecosystem partners. This status will require Twilio Support assistance to address. Please see Section 1.1 below for details.

The brand_feedback field contains a list of Feedback IDs, where each ID corresponds to a recommendation on how you can improve your brand score. You will receive a list of feedback IDs on your brand registration, if any is determined necessary. Along with the list of feedback IDs, you will receive descriptive recommendations for ways to fix your brand registration.

Below are a list of possible feedback IDs that can be returned and corresponding recommendations for fixing the brand information (note that these particular feedback IDs pertain only to Standard and Low-Volume Standard Brands, as Sole Proprietor Brands cannot have e.g. Tax IDs or stock symbols):

More than one feedback ID may be returned at a time. Once you have received feedback on your brand registration, you can contact Twilio support with the appropriate corrected information to update your brand.

You can read more in A2P 10DLC Brand Approval Best Practices.

As noted above, unlike brand_feedback, the failure_reason return parameter will only be populated in the case of a FAILED brand registration (while brand_feedback may appear for both FAILED Brands and low-scoring APPROVED brands). There are many potential values for failure_reason, but in each case you will see a description of the failure reason and a suggestion for resolution. Here follow some examples from failed Sole Proprietor Campaigns:

—"Unable to fetch A2P Bundle Details, please check if the correct bundle sid was provided for registration and the bundle is compliant." -> Check Bundle Details and retry

—"Unable to fetch Customer Profile Bundle details, please check if the correct bundle sid was provided for registration and the bundle is compliant." -> Check Bundle Details and retry

—"Unable to register Brand with The Campaign Registry" -> review the registration requirements defined at the beginning of this document and ensure that your registration information is complete and meets the requirements (for additional information please see https://support.twilio.com/hc/en-us/articles/14488596590491-Why-did-my-Sole-Proprietor-Brand-Registration-Fail-.) Please verify that the supplied information is accurate and well-formed before contacting Twilio Support

1.1 Brands with SUSPENDED status, and related Campaign suspensions

If you have a suspended brand, it means the brand may have violated one or more of the following rules, causing Carriers / other ecosystem partners to suspend it:

• Campaign-to-traffic mismatch: In-market traffic does not match with the campaign registered
• Spam: including but not limited to any kind of unwanted or unsolicited messaging
• Controlled substance: including but not limited to messaging pertaining to controlled substances
• Phishing Messages: including but not limited to messaging designed to gain access to information through deceptive means
• (Excessive) Complaints: including but not limited to unacceptable volumes of consumer complaints
• Illicit Content: including but not limited to messages relating to illegal activity
• Fraudulent Messages: including but not limited to counterfeit/fraudulent goods or activities
• Affiliate Marketing: including but not limited to sharing of opt-ins to affiliate companies
• Promotional Gambling or the act of betting: including but not limited to the act of gambling or promoting gambling
• Lack of Age gate: No age gate mechanism for messaging campaigns that require it
• Illegal Sweepstakes: including but not limited to sweepstakes that do not follow required laws
• Other violations not listed above

The Twilio team should be reaching out to you to provide guidance on how to fix the suspended Brand. Please check your email or the Twilio Support Center. If you don’t see anything, please raise a ticket.

While your brand is suspended, you will experience the following restrictions:

1. It is VERY important that you do not attempt to send similar messages via another existing or new Brand or Campaign. This could result in a serious violation and may result in termination / suspension of your account with Twilio.
2. Suspended Brands face the following restrictions
1. Suspended Brands cannot be updated or used to register any new Campaigns. You will receive an error code 21731 if you try to do this.
2. Suspended brands with active Campaigns may not be deleted via self-service. Suspended brands with no campaigns may be deleted via self-service.
3. Your ability to create new Brands using the same tax ID may be restricted.
3. All campaigns associated with suspended brands will be suspended. Suspended Campaigns face the following restrictions
1. Suspended campaigns cannot cannot be used to send messages. You will receive an error code 30033 if you try to do this
2. Suspended campaigns cannot be deleted via self-service and you may not add / remove the numbers. You will receive an error code 21729 if you try to do this.
4. Before you resolve the suspensions, you’re responsible for the monthly registration fees associated with suspended campaigns as well as the monthly fees associated with the numbers that are in the campaigns.
5. It is also possible that you won’t be able to resolve the suspensions if the ecosystem has determined your use case is not fit for A2P 10DLC. If this is the case, after 60 days of being suspended, you may request the Twilio Support team to delete your suspended brands and campaigns. But you may be required to release all the associated phone numbers at the same time. In the future, we plan on deleting unresolved suspended brands and campaigns automatically after a certain period of time

2. Resubmitting Standard/LVS Brands

Twilio supports resubmission of Brands in the unverified (or FAILED) state up to three times for free using either the Twilio Console or the Twilio Trust Hub API.

Using the Console

When a Brand registration fails within the Console, here’s what you can expect to see in your process to resubmit the Brand with correct information. Of course failure reasons can be various; this one happens to be a mismatch between the name associated with the provided business registration number (Tax ID/EIN) in publicly-available tax information, and the legal name you've provided for the Brand itself:

When submitted using the Twilio Console, Brands will show descriptive error messages. From here, you can click "Edit customer profile" to begin the process of editing and correcting your Brand information. Note that you are not editing the Brand submission as such; that can only be deleted and resubmitted when you are using the Console. But the information that needs to be rectified is actually in the Customer Profile you submitted before the Brand creation step, and the Customer Profile can be edited via the blue button, as indicated.

After you have edited the Customer Profile to your satisfaction, and resubmitted this for approval, you'll go to Messaging > Regulatory Compliance > Brands in the left navigation and find the Brand that failed. Any Brand that you see in this list can be deleted, so be sure that you're deleting the correct one (this is one reason why its always a good idea to create Brands and other such entities with meaningful 'friendly names'). You will find the red Delete link in the dropdown when you click the three dots to the far right of the row with the Brand in question:

Once you've deleted this Brand, you can go back to the Onboarding page under Regulatory Compliance, and if you're not already in the correct profile use the Switch Customer Profile link on the right to select the Profile you just edited. This should immediately take you to the Submit Brand page, allowing you to submit a new Brand with the rectified profile information.

Updating an A2P Brand Using the API

What does this do? This step allows you to edit the A2P brand you've created if you have received a FAILED brand status and the tcr_id is not null. You will use the brand's SID (starting with BN) to make this update call.

NOTE: In contrast to the Console, where it's necessary to delete and recreate a failed Brand, through the API it is possible to call an update on an existing (failed) Brand submission, as shown in the code snippet below. However, as with the Console, it is the information you submitted in the Customer Profile or Trust Bundle associated with that Brand that actually needs to be rectified; otherwise the Brand submission will simply fail again for the same reason.

First, review the error message from the brand_feedback and/or feedback_reason parameters that you've retrieved in the Brand fetch step noted above. Where it's necessary to update information, you will need to perform the necessary updates using the relevant Trust Hub API endpoints as detailed in Steps 1 (Customer Profile submission) and 2 (Trust Bundle submission) of the API walkthrough documents. For example, you may need to update the associated customer profile or update the information attached to the listed end-user.

Once you have finished any necessary updates to your Profile and/or Trust Bundle , use the update method of the brand_registrations endpoint to update the brand’s registration. As the following snippet indicates, the only necessary input parameter for this update call itself is the Brand SID (path or sid). The return json will contain the same parameters you've seen in the create and fetch calls for the Brand. Remember that your newly-updated information will in many cases require manual re-verification, so allow some time for this before checking Brand Registration status again.

3. Troubleshooting and rectifying A2P Campaigns

Currently it is not possible to edit a submitted and failed campaign, either in the Console or via the API. Failed Campaigns must instead be deleted and recreated for submission, with an effort made to rectify whatever issue was surfaced by the error messaging. Again, please note that the issue causing rejection may lie within the submitted Campaign itself (e.g. insufficient or unclear information about the campaign purpose, use case, sample messages, opt-in/out mechanism, etc), but it may also lie with the associated Brand and its underlying Business Profile and/or Trust Product information. In the latter case, you would first need to delete and resubmit the former entities (see Step 2 above) and then delete and resubmit the Campaign itself.

3.1 Troubleshooting and rectifying Campaigns via Console

Campaign vetting can take several weeks or longer. And because Campaigns can be rejected by TCR for a wide variety of reasons, if you are an ISV registering multiple secondary customer Campaigns, you may find these approved at different times, or you may find that some are approved and others are rejected (FAILED). For this reason, both ISVs and direct customers sometimes find it easier to track the status of Campaigns via the Console, whether they were originally submitted via Console or via API. Going to Messaging > Regulatory Compliance > Campaigns will show a list of all your Campaign submissions, with a status indicated for each. If you click on the name or Campaign SID of a FAILED Campaign, you will see a Campaign Details page with something like the following:

In this case, if you look at the Campaign Information panel (you may need to zoom in on this screenshot), you'll see that two separate failure reasons are indicated. One is that the Campaign description was found too be invalid, probably because it was simply not detailed enough. The second failure reason concerns the content of the first Sample message. This would be a reasonable opt-out message, but it is not an appropriate sample message for a Campaign whose basic use case is Marketing.

Whatever the specifics of the failure reason or reasons, notice that this Campaign submission cannot be edited here (that link is currently disabled); it can only be deleted, via the red Delete Campaign link to the right of the Campaign name.

Once the FAILED Campaign has been deleted, you can go back to the Brand for which you submitted this Campaign (if you're not taken their directly by the Console, you can find it via Messaging > Regulatory Compliance > Brands in the left navigation) and recreate the Campaign for resubmission. Note, however, that your remedial action here depends very much on the specifics of the Failure Reason. Often Campaigns can fail because the rationale for the campaign, message flow, opt-in/opt-out, sample messages or other elements are unclear or inadequate per TCR's guidelines (as in our example screenshot above). These would then need to rectified in the new Campaign submission. However, Campaigns can also fail because the submitted Campaign information is simply mismatched with some aspect of the associated Brand, or it could even be that the Brand or Profile itself is internally inconsistent, as for example a Profile that's been created as Sole-Proprietor but where the business entity in fact has an EIN. Issues such as these would need to be rectified in the Profile or Trust Bundle (see Part 2 above), before the failed Campaign could be successfully resubmitted.

3.2 Troubleshooting and resubmitting Campaigns via API

In Step 5 of the guide to registering Standard/Low-Volume Standard Brands via API as well as the guide to registering Sole Proprietor Brands, you created a new messaging Campaign to go with your new A2P Brand. In the Sole Proprietor guide, Step 5.1 directs you to do a fetch call on the newly-created Campaign to check its status. In the Standard/LVS guide, Step 5.3 directs you to make this same call. It's important to remember that, like new A2P Brand registration, new Campaign verification is never an instantaneous process. Sole-Proprietor Campaigns tend to be approved (or rejected) most quickly, while Standard Campaigns must go through several distinct layers of vetting and this process can take up to several weeks. If your fetch call to the new Campaign returns a campaign_status of IN_PROGRESS, this vetting process is not yet complete. Once the process IS complete, your fetch call will return a campaign_status of either VERIFIED or FAILED (or in some rare cases SUSPENDED; on Suspended Campaigns see section 3.2.1 below)

A code sample for this fetch call follows. This call requires two parameters: the messaging_service_sid (i.e., the SID of the Messaging Service you're using in this Campaign), and a hardcoded compliance type of QE2c6890da8086d771620e9b13fadeba0b (see code sample for how these are used in your code library of choice).

If you do receive a campaign_status of FAILED, the errors[] object in the call's json return will not be empty (as it will for Campaigns in a non-failed state, and as shown in the code sample return) but will instead be populated with information. (However, please note that this is only the case for Campaigns submitted since May 31, when this feature was implemented; for previously-submitted Campaigns the errors[] attribute will be empty on failed Campaigns as well as those in other states). The format of the populated errors[] object is illustrated below:

"errors": [
{
"error_code": 30897,
"fields": [ "MESSAGE_FLOW" ],
"url": "https://www.twilio.com/docs/api/errors/30897",
"description": "The campaign submission has been reviewed and it was rejected due to Disallowed Content."
}
]

For a FAILED Campaign, there will always be at least one such error listed, but there could be multiple errors, each detailed in the same format. Each error will have a distinct error_code, which you will find enumerated in this support article: https://support.twilio.com/hc/en-us/articles/15778026827291-Why-Was-My-A2P-10DLC-Campaign-Registration-Rejected-. The description field in this error format corresponds roughly to the Rejection Category associated with that error code in the support article, and the url of the error will lead to a more detailed explanation of that failure reason and the steps to remedy it, if any. Below is an example of an error[] return showing multiple errors:

"errors": [
    {
      "url": "https://www.twilio.com/docs/api/errors/30886",
      "fields": [
        "USE_CASE_DESCRIPTION"
      ],
      "error_code": 30886,
      "description": "The campaign submission has been reviewed and it was rejected because of invalid campaign description."
    },
    {
      "url": "https://www.twilio.com/docs/api/errors/30892",
      "fields": [
        "SAMPLE_MESSAGE_1"
      ],
      "error_code": 30892,
      "description": "The campaign submission has been reviewed and it was rejected because of URL shortener in the sample message."
    },
    {
      "url": "https://www.twilio.com/docs/api/errors/30893",
      "fields": [
        "SAMPLE_MESSAGE_2"
      ],
      "error_code": 30893,
      "description": "The campaign submission has been reviewed and it was rejected because of invalid sample message content."
    },
     .......

It's important to note that there are two categories of errors laid out in the linked support article, and only the first type of error can be remedied. For example, error code 30893 maps to a Rejection Category of “Invalid Sample Message Use Case” with the following Rejection Reason: “Sample messages are either not provided, unclear, or content does not match the campaign use case.” This is one of 12 rejection reasons that can be remedied, i.e. the information supplied in the original Campaign submission can be corrected, as follows:

Verify that sample messages are accurate and detailed. Sample messages should reflect actual messages to be sent under campaign and indicate templated fields with brackets. At least one of the sample messages needs to include your business name. Use case and campaign description need to match campaign description.

In the case of an error like 30893, then, such a Campaign could be deleted (examples of this delete call can be found in Part 5.2 of the Guide for Sole Proprietor API registrations and in Part 5.4 of the Guide for Standard/LVS registrations), and the Campaign submission could then be recreated with appropriately revised sample messages and/or whatever other changes have been suggested.

However, let’s consider some examples of the second category of Campaign failure error, which cannot be remedied simply by improving the submission detail:

The 30883 error code represents a Content Violation, which means that your proposed Campaign has been deemed to deal with content that is prohibited under the terms of A2P Campaign registration, such as sexual references, hate speech, or references to alcohol, firearms, tobacco products or marijuana. As shown here, the Rejection Category and Reason will specify the content reference that is deemed to be in violation. In addition to Content Violations, your Campaign use case could be disallowed because it is deemed to represent a high risk for a spam/phishing attack (30884), other potentially fraudulent activity (30885), violation of Twilio’s general Terms & Conditions (30882), or several other reasons enumerated in the Support article, including the use of the same EIN for too many Brand registrations (By default, a single EIN/Tax ID can only be used in a maximum of 50 different Brands; any brands beyond this limit using the same EIN are invalid, and therefore their associated Campaign(s) will be rejected even if the Campaign submission itself is entirely valid otherwise).

As the support article notes, customers who disagree with a Campaign rejection for such a non-resubmittable reason may submit an appeal to the Twilio support desk; but outside of this route, there is no remedy for this kind of Campaign rejection except to materially change the nature or content of the proposed Campaign, or in some cases the associated Brand.

3.2.1 Individual Campaign Suspensions

It is possible for a Campaign to be suspended on its own, but it’s also possible for a Campaign to be suspended because the Brand it’s associated with is suspended. You can check the Brand status to understand which case it is. If it’s a Brand suspension situation, go to Section 1.1 above to check out what it means for you. If your Brand is still in an Approved state but your Campaign is suspended, keep reading.

If you have a suspended campaign, it means the campaign may have violated one or more of the following rules, causing Carriers / ecosystem partners to suspend it:

• Campaign-to-traffic mismatch: In-market traffic does not match with the campaign registered
• Spam: including but not limited to any kind of unwanted or unsolicited messaging
• Controlled substance: including but not limited to messaging pertaining to controlled substances
• Phishing Messages: including but not limited to messaging designed to gain access to information through deceptive means
• (Excessive) Complaints: including but not limited to unacceptable volumes of consumer complaints
• Illicit Content: including but not limited to messages relating to illegal activity
• Fraudulent Messages: including but not limited to counterfeit/fraudulent goods or activities
• Affiliate Marketing: including but not limited to sharing of opt-ins to affiliate companies
• Promotional Gambling or the act of betting: including but not limited to the act of gambling or promoting gambling
• Lack of Age gate: No age gate mechanism for messaging campaigns that require it
• Illegal Sweepstakes: including but not limited to sweepstakes that do not follow required laws
• Other violations not listed above

The Twilio team should be reaching out to you to provide guidance on how to fix the suspended campaign. Please check your email or the Twilio Support Center. If you don’t see anything, please raise a ticket.

While your campaign is suspended, you will experience the following restrictions:

1. It is VERY important that you do not attempt to send similar messages via another existing or new Campaign. This could result in a serious violation and may result in termination / suspension of your account with Twilio.
2. Suspended Campaigns face the following restrictions
1. Suspended campaigns cannot cannot be used to send messages. You will receive an error code 30033 if you try to do this
2. Suspended campaigns cannot be deleted via self-service and you may not add / remove the numbers. You will receive an error code 21729 if you try to do this.
3. Before you resolve the suspensions, you’re responsible for the monthly registration fees associated with suspended campaigns as well as the monthly fees associated with the numbers that are in the campaigns.
4. It is also possible that you won’t be able to resolve the suspensions if the ecosystem has determined your use case is not fit for A2P 10DLC. If this is the case, after 60 days of being suspended, you may request the Twilio Support team to delete your suspended campaigns. But you may be required to release all the associated phone numbers at the same time. In the future, we plan on deleting unresolved suspended campaigns automatically after a certain period of time

4. Troubleshooting Phone Number Registrations

It’s important to understand that even after a given A2P Campaign has been approved by TCR, individual phone numbers in the Messaging Service associated with that Campaign must then be approved by the respective US carriers. This is itself an asynchronous process. Accordingly, Twilio offers a Console tool that allows you to check the current A2P registration status of all phone numbers owned by a given account (or subaccount). Phone numbers will be listed in a downloadable .csv report, indicating the A2P registration status of each number, and its associated Campaign SID and Messaging Service SID.

This .csv report will be formatted as in the following example:

In this example report, the phone numbers shown are all associated with A2P Campaigns; numbers in your account with no such association would have a blank CampaignSID field, and their status would be UNREGISTERED. In this example, all of these numbers have a status of either PENDING_REGISTRATION or FAILURE. The full list of possible statuses follows, together with a description and potential remediation:

• UNREGISTERED: This number has not been associated with a verified campaign. Register the 10DLC number by adding it to a Messaging Service associated with a verified A2P campaign. Note that for numbers added to a Messaging Service, the MessagingServiceSid value will not display in the report until the MS has been associated with a Campaign and that Campaign has been successfully A2P-registered. Additionally, please note that Sole Proprietor Campaigns can only have one registered 10DLC. Additional 10DLC numbers in that Messaging Service will be in the “Unregistered” status.
• PENDING_REGISTRATION: Twilio has received your request to register this number, but has not completed the necessary configurations with ecosystem partners. There’s no further action required from you. Please note that it is normal for number registration to take several days depending on the amount of number registration requests we receive. You may check back at this report later to see if your number has the status of REGISTERED.
• REGISTERED: Your number is registered and ready to be used to send messages to the US
• PENDING_DEREGISTRATION: Twilio has received your request to de-register this number, but has not completed the necessary configurations with ecosystem partners. If you’ve recently tried to move a number from one Campaign to another, you may see your number status changing in the sequence of Registered - Pending De-registration - Unregistered - Registered. There is no further action required from you. Please note that it is normal for number deregistration to take several days depending on the amount of number registration requests we receive. You may check back at this report later to see if your number has been successfully registered.
• FAILURE: An unexpected error has occurred on your number. Reach out to Twilio support after logging into console at https://www.twilio.com/console/support/tickets/create

To download this CSV report, go to Phone Numbers in the Twilio Console, then Manage > Active Numbers. In the second banner on the Active Numbers page, you’ll find a link to “Request CSV Report” as indicated below:

This link will take you to a page with the following header, allowing you to request the generation of your CSV status report:

This report can take up to 24 hours to generate, depending on your volume of numbers and accounts, but if you have only a small set of numbers it could be ready much sooner. When the report has finished generating you will receive a notification email to this effect, at the email address indicated in the box on this page (it will be the email associated with the account you are using). When you receive this email notice, return to the number registration status page (refresh if necessary) and it will display a completion banner and present a blue Download CSV report button, as shown:

Further Troubleshooting

If your status report shows numbers in an UNREGISTERED or PENDING state that you feel should be fully registered at this point, try the following:

1. If the campaign is a Standard / Special use case, and has been registered, but the phone number experiencing issues was added to that registered Messaging Service less than two weeks ago, please wait a few more days for the status to update as number registration may take some time.
2. If the campaign is a Sole Proprietor use case, these can only have one number registered for A2P, so if there were multiple numbers in the Sender pool of a preexisting MS you've selected for the New Campaign, then Twilio one number in the Messaging Service at random to register for A2P. If customers wish to specify a different number for A2P use, remove ALL numbers in the Messaging Service, and only add back the number they wish to use.