Skip to contentSkip to navigationSkip to topbar
On this page

A2P 10DLC - Use Externally Registered Campaigns


(information)

Info

Please contact your Twilio Account Executive (AE) to request access to this feature.

This guide explains the process of associating an external Campaign that was directly registered with The Campaign Registry (TCR) with a Twilio Messaging Service. Doing this allows you to skip the Customer Profile creation and Brand registration steps of Twilio A2P 10DLC onboarding.

Twilio does not recommend using external Campaigns in most cases, and TCR only allows direct registration from ISVs. See the Can I go directly to The Campaign Registry for US A2P 10DLC registration?(link takes you to an external page) Help Center article for more information on external Campaigns and their limitations.


Steps to associate external Campaigns with Messaging Services

steps-to-associate-external-campaigns-with-messaging-services page anchor

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(link takes you to an external page) for a more technical look at the required steps.

  1. Create a Twilio Messaging Service via the Console(link takes you to an external page) 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(link takes you to an external page) 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(link takes you to an external page) . 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.

  1. 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.
  2. Associate the Campaign with a Messaging Service with this API call .
  3. 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)(link takes you to an external page) functionality is unsupported by Twilio at this time. If you wish to appeal a secondary DCA rejection, contact support at 10dlc-onboarding@twilio.com.

  1. 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.
  2. Start sending! Twilio will bill and rate limit messages according to the TCR Campaign Class.

Associate an external Campaign with a Messaging Service

associate-an-external-campaign-with-a-messaging-service page anchor
(information)

Info

This endpoint is private, contact your Twilio Account Executive (AE) to request access.

(warning)

Warning

This API call can take some time to complete, use the Get Campaign details endpoint to confirm the Campaign is verified before sending messages.

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.

Associate an external Campaign with a Messaging ServiceLink to code sample: Associate an external Campaign with a Messaging Service
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();

Output

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();

Output

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
}

Delete an external Campaign association

delete-an-external-campaign-association page anchor
(warning)

Warning

This request does not delete the Campaign from TCR. That must be done directly via the TCR web portal or TCR API(link takes you to an external page).

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();
Get help with A2P 10DLC

Need help building or registering your A2P 10DLC application? Learn more about Twilio Professional Services for A2P 10DLC.

Get help(link takes you to an external page)

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.