A2P 10DLC - Use Externally Registered Campaigns

This section covers the steps you need to follow to associate an external Campaign with a Messaging Service. Optionally, you can reference this sequence diagram for a more technical look at the required steps.

1. Create a Twilio Messaging Service via the Console or via API. Do not specify the Messaging Service's Usecase parameter. Twilio will assign the default value undeclared for the Messaging Service, which is appropriate for external Campaigns regardless of what Use Case they are registered with in TCR.

2. Add phone numbers to the Messaging Service's Sender Pool via API or the Console at any point in the process. For detailed instructions on how to do this, see the Managing a Messaging Service Sender Pool Help Center article. Sole Proprietor Campaigns are limited to one phone number.

3. Share the Campaign with Twilio as the Direct Connect Aggregator (DCA) using the TCR web portal or TCR API. A DCA is a company that provides direct connectivity to mobile carrier gateways for the purpose of delivering SMS messages.

4. Twilio reviews the Campaign.

If the Campaign fails this review: Twilio will reject the Campaign sharing request. You will receive a CAMPAIGN_SHARE_DELETE event to the webhook endpoint you provided to TCR containing rejection feedback. You can update the Campaign based on the feedback and repeat step #3 above.

5. When the Campaign passes Twilio's compliance review and is accepted, you will receive a CAMPAIGN_SHARE_ACCEPT event to the webhook endpoint you provided to TCR. You cannot continue to the next step until this happens.

6. Associate the Campaign with a Messaging Service with this API call.

7. Twilio performs any carrier-specific Campaign configuration and elects any required secondary DCAs for the Campaign. Secondary DCAs must conduct reviews before the Campaign can be fully operational.

If the secondary DCAs reject the Campaign: You will receive a CAMPAIGN_SHARE_DELETE event to the webhook endpoint you provided to TCR containing rejection feedback from the secondary DCA. First, you will need to delete the Campaign association from Twilio. Then, you can update the Campaign based on the feedback and start again at step #3 above. Twilio will bill the $15 vetting fee for each review conducted by the secondary DCA. Note that TCR Nudge (APPEAL_REJECTION, REVIEW) functionality is unsupported by Twilio at this time. If you wish to appeal a secondary DCA rejection, contact support at 10dlc-onboarding@twilio.com.

8. When the Campaign is approved by all parties, all numbers in the Messaging Service's Sender Pool are associated with the Campaign, including numbers added later.

9. Start sending! Twilio will bill and rate limit messages according to the TCR Campaign Class.

This call kicks off the process of Twilio associating an external Campaign with a Messaging Service. To check if the association process is complete and your Campaign is ready to send messages, use the Get Campaign Details API call below and verify that the campaign_status is VERIFIED in the JSON response.

Rate limit: One request per five seconds. Failures resulting from exceeding this limit are asynchronous and the Campaign moves to a failed status after all retries are exhausted. To proceed, you must delete the Campaign association from Twilio and reshare the Campaign with Twilio from TCR.

campaignId parameter: This is TCR's unique identifier of your Campaign. It is a seven character alphanumeric string that starts with C.

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 createExternalCampaign() {
11
  const externalCampaign = await client.messaging.v1.externalCampaign.create({
12
    campaignId: "CRMTK1Z",
13
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14
  });
15

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

19
createExternalCampaign();

1
{
2
  "sid": "QE2c6890da8086d771620e9b13fadeba0b",
3
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4
  "campaign_id": "CRMTK1Z",
5
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "date_created": "2021-03-21T21:31:00Z"
7
}

This call returns the details of a specific Campaign. You can use it to check the status of a Campaign that you have associated with a Messaging Service. A campaign_status of VERIFIED means you are ready to start sending messages. Twilio bills messages and rate limits them according to the TCR Campaign Class.

The Sid parameter value should be QE2c6890da8086d771620e9b13fadeba0b for all A2P 10DLC Campaigns and Messaging Services. It is the US A2P Compliance resource identifier.

See this endpoint's full API Reference for more information.

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("QE2c6890da8086d771620e9b13fadeba0b")
14
    .fetch();
15

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

19
fetchUsAppToPerson();

1
{
2
  "sid": "QE2c6890da8086d771620e9b13fadeba0b",
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
}

This API call deletes an external Campaign association to a Messaging Service. After an association is deleted, you can re-associate a different Campaign with the same Messaging Service or associate the same Campaign with different Messaging Service.

When this call is successfully made, it takes a few seconds to finalize deletion in the Twilio system. To account for this, you can implement a five second delay between removing a Campaign and creating a new association with the same Campaign or the same Messaging Service.

See this endpoint's full API Reference for more information.

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 deleteUsAppToPerson() {
11
  await client.messaging.v1
12
    .services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .usAppToPerson("QE2c6890da8086d771620e9b13fadeba0b")
14
    .remove();
15
}
16

17
deleteUsAppToPerson();

Twilio now supports the migration of Campaigns approved by all carriers via TCR from other messaging API providers, without requiring re-registration.

When a Campaign is shared with Twilio through Connectivity Partner (CNP) Migration, a secondary CNP chain is created in the background, ensuring minimal service disruptions. Once all necessary approvals are received, this secondary chain transitions to the primary chain. Each migrated Campaign incurs a fee of $8.

Number migration can occur before or after Campaign migration. For optimal results, complete number porting first and ensure SMS traffic is available on Twilio for the ported number before initiating Campaign migration.

Refer to the TCR documentation for details on initiating a CNP migration request to Twilio's DCA. After the Campaign is accepted by Twilio, use the following endpoint to associate it with a Twilio Messaging Service:

CnpMigration parameter: This optional parameter, when set to True, indicates the Campaign was shared through CNP migration.

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 createExternalCampaign() {
11
  const externalCampaign = await client.messaging.v1.externalCampaign.create({
12
    campaignId: "CRMTK1Z",
13
    cnpMigration: false,
14
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
15
  });
16

17
  console.log(externalCampaign.sid);
18
}
19

20
createExternalCampaign();

1
{
2
  "sid": "QE2c6890da8086d771620e9b13fadeba0b",
3
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4
  "campaign_id": "CRMTK1Z",
5
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "date_created": "2021-03-21T21:31:00Z"
7
}