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.
For more information on what this means, limitations, and reasons why Twilio does not recommend this path see Can I go directly to The Campaign Registry for US A2P 10DLC registration?
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).
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:
Below are the general steps that you/Twilio will perform in order to associate your Campaigns with Messaging Services:
- You create a Twilio Messaging Service via API/Console
- You assign phone numbers to the Messaging Service's Sender Pool via API/Console
- You, via TCR APIs, share the campaign with Twilio as the Direct Connect Aggregator (DCA).
- Twilio, as the DCA, accepts the shared capaign and obtains campaign metadata regarding rate limits and daily messaging caps.
- You assign a CampaignID to the Messaging Service that you created using the new Externally Registered Campaigns API.
- Twilio ensures every phone number in the Messaging Service's Sender Pool is associated with the CampaignID attached to the Messaging Service.
- Twilio willo bill messages and rate limit them according to the Campaign Class.
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.
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.
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.
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.
This shows you how to get the details of a campaign that you have imported using the compliance type
QE2c6890da8086d771620e9b13fadeba0b. Once the Campaign status is
VERIFIED, Twilio bills messages and rate limits them according to the Campaign Class.
For frequently asked questions on the externally registered campaigns API, please see Can I go directly to The Campaign Registry for US A2P 10DLC registration?