Troubleshooting and rectifying A2P Campaigns

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:

Expand image

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 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 can be either edited or deleted using the respective blue or red links to the right of "Campaign Details".

If you click on the blue Edit Campaign link, you will be taken to the following modal:

Expand image

As we see, the modal begins with a banner confirming that this Campaign was failed upon review, and inviting you to fix whatever issues were flagged in the previous screen. Below this you will see text entry boxes corresponding to most of the text-entry fields in the original Campaign submission flow: Campaign description, Sample messages (you'll see that there are boxes for up to five different sample messages, but only the first two are required), then Message contents checkboxes to indicate whether any of your messages will contain embedded links, phone numbers, content related to direct lending or other loan arrangements, or any age-gated content; and finally a box for a description of the opt-in process (how end users give their consent to receiving text messages). All of these will be pre-populated with the information entered in the original Campaign submission. In our example, we have two things to fix here: first, the Campaign Description needs to be more detailed; second, the two sample messages need to be rewritten so they actually reflect the designated purpose of the Campaign: sending marketing messages about sales and offers (as opposed to indicating a successful opt-out, which is an entirely different use case).

Whatever changes you need to make to address your own failure_reason(s), once you have rectified the necessary information, click the blue Update button and your Campaign will be resubmitted for approval. This kicks off a new Campaign vetting process, involving the same time and labor on the part of our A2P ecosystem partners as an original Campaign submission, so it's not feasible to allow an indefinite number of free resubmissions. At present, Twilio allows three free resubmissions of the same Campaign. The number of allowed resubmissions remaining is indicated to the right of the Update button.

As indicated above, there are two scenarios in which a failed Campaign cannot be edited but must instead be deleted and recreated (ie a new Campaign submitted from scratch). The first involves a Campaign in which the wrong use case was chosen from the dropdown. If a mismatch has been flagged between your indicated use case and your use case description and/or sample messages, often this means that the latter should be edited to match the chosen use case; but it might instead mean that the latter does accurately represent the intent of the Campaign but you need to indicate a different use case to match them. The other scenario is when the failure stems not from the Campaign itself but from some aspect of the associated Brand.

In either of these cases, rather than the blue Edit Campaign link, you would use the red Delete Campaign link next to it in the main Campaign details screen. This will launch a confirmation modal; this Delete Campaign link is active for APPROVED Campaigns as well, and you definitely do not want to delete an approved Campaign unless you have very good reason to do so. Also NOTE: since you will want to use either most or all of the original Campaign details in the new submission, it might be a good idea to duplicate the tab with the original Campaign details screen, so that you can refer back to these Campaign details when you recreate the Campaign.

Once the FAILED Campaign has been deleted, you can then go back to the Brand for which you submitted this Campaign (you can find this via Messaging > Regulatory Compliance > Brands in the left navigation, which will allow you to click on the appropriate Brand and launch the Brand details page). If you just need to resubmit the Campaign with a new use case indicated, use the blue Register New Campaign button in the Brand details screen, which will launch a new Campaign creation workflow and allow you to enter whatever original and new Campaign information is appropriate.

On the other hand, if the Campaign's failure reason lies with the Brand information itself (which ultimately always means some aspect of the Brand's underlying business profile or trust bundle), you will need to refer to Section 2 above for how to remediate Brand issues. But the Campaign deletion still needs to happen first; a Brand cannot be edited if it has a Campaign associated with it. Once the Brand has been resubmitted, then on the Brand details screen you can use the Register New Campaign button to launch the new Campaign creation workflow. In this case it's likely that all of the original Campaign detail information can be used as-is.

During the onboarding process, you created a UsAppToPerson resource which represents the A2P 10DLC Campaign.

You can fetch a UsAppToPerson resource to check the campaign_status.

Sole-Proprietor Campaigns tend to be approved or rejected quickly, while Standard Campaigns must go through several distinct layers of vetting and this process can take up to several weeks.

If the UsAppToPerson resource's campaign_status is IN_PROGRESS, the vetting process is not yet complete. Once the process complete, the campaign_status is 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).

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function fetchUsAppToPerson() {
11
  const usAppToPerson = await client.messaging.v1
12
    .services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .usAppToPerson("QEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
    .fetch();
15

16
  console.log(usAppToPerson.sid);
17
}
18

19
fetchUsAppToPerson();

1
{
2
  "sid": "QEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "brand_registration_sid": "BNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6
  "description": "Send marketing messages about sales to opted in customers.",
7
  "message_samples": [
8
    "EXPRESS: Denim Days Event is ON",
9
    "LAST CHANCE: Book your next flight for just 1 (ONE) EUR"
10
  ],
11
  "us_app_to_person_usecase": "MARKETING",
12
  "has_embedded_links": true,
13
  "has_embedded_phone": false,
14
  "subscriber_opt_in": true,
15
  "age_gated": false,
16
  "direct_lending": false,
17
  "campaign_status": "PENDING",
18
  "campaign_id": "CFOOBAR",
19
  "is_externally_registered": false,
20
  "rate_limits": {
21
    "att": {
22
      "mps": 600,
23
      "msg_class": "A"
24
    },
25
    "tmobile": {
26
      "brand_tier": "TOP"
27
    }
28
  },
29
  "message_flow": "End users opt-in by visiting www.example.com and adding their phone number. They then check a box agreeing to receive text messages from Example Brand. Additionally, end users can also opt-in by texting START to (111) 222-3333 to opt in.",
30
  "opt_in_message": "Acme Corporation: You are now opted-in. For help, reply HELP. To opt-out, reply STOP",
31
  "opt_out_message": "You have successfully been unsubscribed from Acme Corporation. You will not receive any more messages from this number.",
32
  "help_message": "Acme Corporation: Please visit www.example.com to get support. To opt-out, reply STOP.",
33
  "opt_in_keywords": [
34
    "START"
35
  ],
36
  "opt_out_keywords": [
37
    "STOP"
38
  ],
39
  "help_keywords": [
40
    "HELP"
41
  ],
42
  "date_created": "2021-02-18T14:48:52Z",
43
  "date_updated": "2021-02-18T14:48:52Z",
44
  "url": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p/QE2c6890da8086d771620e9b13fadeba0b",
45
  "mock": false,
46
  "errors": []
47
}

If the campaign_status is FAILED, the errors property is populated with information, as shown in the sample below.

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

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

1
"errors": [
2
    {
3
      "url": "https://www.twilio.com/docs/api/errors/30886",
4
      "fields": [
5
        "USE_CASE_DESCRIPTION"
6
      ],
7
      "error_code": 30886,
8
      "description": "The campaign submission has been reviewed and it was rejected because of invalid campaign description."
9
    },
10
    {
11
      "url": "https://www.twilio.com/docs/api/errors/30892",
12
      "fields": [
13
        "SAMPLE_MESSAGE_1"
14
      ],
15
      "error_code": 30892,
16
      "description": "The campaign submission has been reviewed and it was rejected because of URL shortener in the sample message."
17
    },
18
    {
19
      "url": "https://www.twilio.com/docs/api/errors/30893",
20
      "fields": [
21
        "SAMPLE_MESSAGE_2"
22
      ],
23
      "error_code": 30893,
24
      "description": "The campaign submission has been reviewed and it was rejected because of invalid sample message content."
25
    }
26
]

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 either deleted and recreated or edited in place. As with failed Campaigns remediated via the Console, in using the API the delete/recreate route is more cumbersome than an edit-in-place, and should be used only in the two scenarios where an in-place edit is not possible: ie, either the Campaign's designated use case (not use case description) is incorrect, or the failure reason actually pertains to the associated Brand rather than any detail of the Campaign itself, in which case the Campaign must be deleted, then the Brand must be rectified as detailed in Section 2 above, and then the Campaign recreated. To delete a Campaign, you delete the UsAppToPerson resource.

First, however, we need to consider some examples of the second category of Campaign failure error, which cannot be remedied (through either an edit or a delete/recreate) 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.

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. Check your email or the Twilio Support Center. If you don't see anything, 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 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

A feature to edit (UPDATE) a Campaign in place via the API is now available for customers participating in the beta program for this feature (the current document applies only to customers participating in this program).

Section 4.2 below defines a whole list of input parameters that are either required or optional for the A2P Campaign CREATE API call (including 3 optional parameters newly available for this beta release). For the new UPDATE API call there are a total of seven required parameters, which are a subset of the parameters available for the CREATE call. The following table lists and describes each of these required parameters.

It is important to understand that all seven parameters are required, for any and every UPDATE call, even if you only need to modify information in one or more of these fields. For example, a customer might only need to update the message_flow parameter, because TCR had initially failed the Campaign submission on the grounds that the message flow was not clearly explained. In this case the text value of the message_flow parameter would need to be changed to satisfy TCR, but the other six fields listed below would also need to be included in the update call, even though their values could (and should) be unchanged from the original CREATE call. Similarly, if the Campaign failed because the associated Brand was involved in direct lending, but the direct_lending Boolean parameter had not been set to True, in the UPDATE call this Boolean would need to be changed to True, but the other six parameters would still need to present in the call even if all their values were (and presumably should be) unchanged.

Another feature of this Campaign Update call that must be understood is that, while this call is primarily intended to rectify a failed Campaign (i.e. one where TCR refused registration owing to some of the information provided in the Create call), this update can also be used on a Campaign that has been successfully approved and registered by TCR. The customer might wish to do this if, for example, the message_flow, Campaign description or sample_messages had changed sufficiently that it was useful to update the Campaign registration accordingly. However, in the case of updating an approved and registered Campaign, while all seven listed fields are still required, it is NOT permissible to alter the values of any of the four Boolean flags (has_embedded links, has_phone, direct_lending or age_gated). The Boolean parameters must have the same values that they did on the initial Campaign CREATE call and/or a pre-TCR-approval UPDATE call (when they still CAN be changed), otherwise the Update call will error. All of this will be noted in the table below.
Finally, it should be reiterated that any parameters included in the original Campaign CREATE call, but not specifically mentioned in the table below, cannot be edited under any circumstances through the new UPDATE call, either before or after TCR registration. If the customer wished for any reason to change any of these disallowed fields (for example Opt-in, Opt-Out or Help information, the use_case of the Campaign, or the path parameters messaging-services-sid and brand-registration-sid), the Campaign would need to be deleted and then recreated in Section 3.3 above.

Following this table you will find a sample update call.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateUsAppToPerson() {
11
  const usAppToPerson = await client.messaging.v1
12
    .services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .usAppToPerson("QEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
14
    .update({
15
      ageGated: false,
16
      description: "Send marketing messages about sales and offers.",
17
      directLending: false,
18
      hasEmbeddedLinks: true,
19
      hasEmbeddedPhone: true,
20
      messageFlow:
21
        "End users opt-in by visiting www.acme.com, creating a new user account, consenting to receive marketing messages via text, and providing a valid mobile phone number.",
22
      messageSamples: ["Message Sample 1", "Message Sample 2"],
23
    });
24

25
  console.log(usAppToPerson.sid);
26
}
27

28
updateUsAppToPerson();

1
{
2
  "sid": "QEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "brand_registration_sid": "BNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6
  "description": "Send marketing messages about sales and offers.",
7
  "message_samples": [
8
    "EXPRESS: Denim Days Event is ON",
9
    "LAST CHANCE: Book your next flight for just 1 (ONE) EUR"
10
  ],
11
  "us_app_to_person_usecase": "MARKETING",
12
  "has_embedded_links": true,
13
  "has_embedded_phone": true,
14
  "campaign_status": "PENDING",
15
  "campaign_id": "CFOOBAR",
16
  "is_externally_registered": false,
17
  "rate_limits": {
18
    "att": {
19
      "mps": 600,
20
      "msg_class": "A"
21
    },
22
    "tmobile": {
23
      "brand_tier": "TOP"
24
    }
25
  },
26
  "subscriber_opt_in": false,
27
  "age_gated": false,
28
  "direct_lending": false,
29
  "date_created": "2021-02-18T14:48:52Z",
30
  "date_updated": "2021-02-18T14:48:52Z",
31
  "url": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p/QE2c6890da8086d771620e9b13fadeba0b",
32
  "message_flow": "End users opt-in by visiting www.acme.com, creating a new user account, consenting to receive marketing messages via text, and providing a valid mobile phone number.",
33
  "opt_in_message": "Acme Corporation: You are now opted-in. For help, reply HELP. To opt-out, reply STOP",
34
  "opt_out_message": "You have successfully been unsubscribed from Acme Corporation. You will not receive any more messages from this number.",
35
  "opt_in_keywords": [
36
    "START"
37
  ],
38
  "opt_out_keywords": [
39
    "STOP"
40
  ],
41
  "help_keywords": [
42
    "HELP"
43
  ],
44
  "help_message": "Acme Corporation: Please visit www.example.com to get support. To opt-out, reply STOP.",
45
  "mock": false,
46
  "errors": []
47
}

This section lays out the full set of parameters available for the beta version of the request that creates a UsAppToPerson resource.

Most Twilio customers use Twilio's default or advanced opt-out features. If you use default or advanced opt-out, Twilio will automatically complete your Campaign's opt-out and help parameters with Twilio's default values or your customized advanced opt-out and help values.

Creating a Campaign involves a create call to the us_app_to_person endpoint of the Messaging API. There are a total of eight required parameters for this call, and nine optional parameters (including three added as part of the Campaign edit beta release), depending on how much you'd like to explicitly manage opt-in/opt-out mechanisms and help information.