Need help building or registering your A2P 10DLC application? Learn more about Twilio Professional Services for A2P 10DLC.
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? Help Center article for more information on external Campaigns and their limitations.
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.
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.
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.
CAMPAIGN_SHARE_ACCEPT
event to the webhook endpoint you provided to TCR. You cannot continue to the next step until this happens.
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.
This endpoint is private, contact your Twilio Account Executive (AE) to request access.
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
.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createExternalCampaign() {11const externalCampaign = await client.messaging.v1.externalCampaign.create({12campaignId: "CRMTK1Z",13messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14});1516console.log(externalCampaign.sid);17}1819createExternalCampaign();
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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchUsAppToPerson() {11const usAppToPerson = await client.messaging.v112.services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.usAppToPerson("QE2c6890da8086d771620e9b13fadeba0b")14.fetch();1516console.log(usAppToPerson.sid);17}1819fetchUsAppToPerson();
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 request does not delete the Campaign from TCR. That must be done directly via the TCR web portal or TCR API.
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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteUsAppToPerson() {11await client.messaging.v112.services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.usAppToPerson("QE2c6890da8086d771620e9b13fadeba0b")14.remove();15}1617deleteUsAppToPerson();
Need help building or registering your A2P 10DLC application? Learn more about Twilio Professional Services for A2P 10DLC.