Note: This is a preview of an endpoint that can be made available to you for the purposes of assigning campaigns that you have registered directly with The Campaign Registry (TCR) to phone numbers you own at Twilio, via the Messaging Service. We are still actively working on these APIs and expect to be making updates to them. This API document should be used to help your team scope the amount of integration work to be done.
The Externally Registered Campaigns API allows you to jump straight to associating a previously registered campaign use case and associate it with a Twilio Messaging Service, skipping all of the Brand registration steps (since you have already registered your brand with The Campaign Registry).
Understanding A2P 10DLC
It is useful to first understand Twilio's overall model for A2P 10DLC and how this aligns with common customer architectures. The following diagram shows the relationship between Twilio's Trust Hub, Twilio's Messaging Services, and where The Campaign Registrys' (TCR) concepts of Brand and Campaign fit into Twilio's foundational concepts:
Associating Campaigns with Messaging Services
Below are the general steps that you/Twilio will perform in order to associate your Campaigns with Messaging Services. Additionally, this sequence diagram highlights the required steps for onboarding TCR registered campaigns:
Create a Twilio Messaging Service via API/Console.
Assign phone numbers to the Messaging Service's Sender Pool via API/Console. Phone numbers can be added to a Messaging Service before or after Campaign association.
Via TCR APIs, share the campaign with Twilio as the Direct Connect Aggregator (DCA).
Twilio, as the DCA, reviews the campaign for compliance.
If the campaign data fails the review criterion
, Twilio will reject the campaign sharing request. You will receive a CAMPAIGN_SHARE_DELETE webhook from TCR. You can update the information on the campaign based on the feedback in that webhook and re-share the campaign for re-review.
Once a campaign is accepted, you will receive a CAMPAIGN_SHARE_ACCEPT webhook from TCR. You will not be able to move past this step until the campaign is accepted.
You assign a CampaignID to the Messaging Service that you created using the Externally Registered Campaigns API. Twilio obtains campaign metadata regarding rate limits and daily messaging caps.
Twilio will perform any carrier-specific campaign configuration and elect any required secondary DCAs for this campaign. Secondary DCAs will conduct campaign reviews before the campaign becomes fully operational.
If the secondary DCAs reject the campaign
, you will receive a CAMPAIGN_SHARE_DELETE specifying that the DCA2 has rejected the campaign with a reason. You will need to delete the A2P campaign with Twilio through API/Console and unshare the campaign with Twilio via TCR APIs. You will need to update the campaign based on the feedback and via TCR APIs, share the campaign with Twilio as the Direct Connect Aggregator (DCA) [Step 3]. Twilio will bill the $15 vetting fee for each review conducted by the secondary DCA.
Note
:
TCR Nudge (APPEAL_REJECTION, REVIEW)
functionality is unsupported by Twilio at this time. If you wish to appeal a secondary DCA rejection, contact support by
10dlc-onboarding@twilio.com
.
Once the campaign is approved by all parties in the chain, Twilio ensures every phone number in the Messaging Service's Sender Pool is associated with the CampaignID attached to the Messaging Service. All future numbers added to the Messaging Service will also be associated with the campaign. (Note: Sole Proprietor campaigns are limited to 1 number)
Twilio will bill messages and rate limit them according to the Campaign Class.
Deleting Campaigns
If you want to delete the campaign, you have two options:
Delete the Messaging Service resource
: If you delete the Messaging Service resource, Twilio ensures that the associated campaign object is deleted. The phone numbers are disassociated and revert back to being unregistered for A2P capabilities.
Delete only the Campaign
: If you want to delete only the Campaign, but leave the Messaging Service intact, you can make a request to the A2P endpoint on the Messaging Service to delete only the associated campaign. Twilio will ensure that the phone numbers are disassociated from the campaign, but stay in the Messaging Service's Sender Pool.
If you add/delete phone numbers to the Messaging service, Twilio will perform the necessary registration/deregistration steps with the carriers and other ecosystem service providers.
API Reference
The following calls are all made using the Messaging API
1. Create a Messaging Service
Please note: Do not specify the "usecase" field in request. Twilio will assign a default "undeclared" usecase for the Messaging Service. All existing Messaging Services will have their "usecase" set to "undeclared". For the Externally Registered Campaigns API the "usecase" field will remain undeclared, no matter what is specified with the TCR.
Create a Messaging Service
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
2. Associate the pre-registered A2P campaign with the Messaging Service
This step associates the A2P Campaign, which was already registered with TCR, with the Twilio Messaging Service that you just created. From here, Twilio asynchronously retrieves the Campaign information from TCR and updates the A2P ecosystem with Campaign information for all the 10DLC that are part of the Messaging Service's Sender Pool.
(warning)
Warning
Kindly rate limit usage of this API for mapping one campaign to one messaging service to a rate limit of once every 5 seconds. Failures from hitting rate limits will be asynchronous and the campaign will move to a failed status after all retries are exhausted. The path forward will then be deleting and re-initiating the API request. This rate limit is so that we are able to accommodate the additional load when sending API requests to TCR, since we are rate limited to TCR.
(warning)
Warning
As noted above, this association of an Externally Registered Campaign with a Twilio Messaging Service is asynchronous, involving several potential steps on Twilio's part, before your Campaign is ready to send messages. For this reason, do NOT expect this association to be enabled immediately upon making the API call indicated with the following code sample.
In order to determine that your Externally Registered Campaign is in fact ready to begin sending A2P messages via your designated Twilio Messaging Service, you must make the Get/Fetch call indicated in Step 3 below and see a campaign_status of VERIFIED in the json response. Only at that point can you begin sending messages via this Campaign.
Associate the pre-registered A2P campaign with the Messaging Service
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
This shows you how to get the details of a campaign that you have imported using the compliance typeQE2c6890da8086d771620e9b13fadeba0b. Once the Campaign status is VERIFIED, you may begin sending A2P messages with this Campaign. At that point, Twilio will bill messages and rate limit them according to the Campaign Class.
(information)
Info
Note: The QE SID is the same string for any messaging service or campaign.
Get A2P campaign
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
"description": "Send marketing messages about sales to opted in customers.",
_47
"message_samples": [
_47
"EXPRESS: Denim Days Event is ON",
_47
"LAST CHANCE: Book your next flight for just 1 (ONE) EUR"
_47
],
_47
"us_app_to_person_usecase": "MARKETING",
_47
"has_embedded_links": true,
_47
"has_embedded_phone": false,
_47
"subscriber_opt_in": true,
_47
"age_gated": false,
_47
"direct_lending": false,
_47
"campaign_status": "PENDING",
_47
"campaign_id": "CFOOBAR",
_47
"is_externally_registered": false,
_47
"rate_limits": {
_47
"att": {
_47
"mps": 600,
_47
"msg_class": "A"
_47
},
_47
"tmobile": {
_47
"brand_tier": "TOP"
_47
}
_47
},
_47
"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.",
_47
"opt_in_message": "Acme Corporation: You are now opted-in. For help, reply HELP. To opt-out, reply STOP",
_47
"opt_out_message": "You have successfully been unsubscribed from Acme Corporation. You will not receive any more messages from this number.",
_47
"help_message": "Acme Corporation: Please visit www.example.com to get support. To opt-out, reply STOP.",
Please note: this deletion operation will only remove the Externally Registered Campaign association with Twilio. This does not delete the Campaign from The Campaign Registry. If you wish to remove your externally-registered Campaign from TCR, you must do that directly in the TCR web portal or API.
After a Campaign association is deleted, you may then re-associate a different Campaign with the same Messaging Service, or associate the same Campaign with another Messaging Service on Twilio.
After your API request is accepted, please allow a few seconds for deletion to be finaized in our system. If you are programmatically deleting and re-associating Campaigns, we recommend implementing a 5-second delay between removing a Campaign and creating a new association with the same Campaign or the same Messaging Service.
Delete A2P Campaign
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure