Menu

Expand
Rate this page:

Externally Registered Campaigns API

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).

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:

a2p-campaign-use-cases.png

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:

  1. Create a Twilio Messaging Service via API/Console.
  2. 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.
  3. Via TCR APIs, share the campaign with Twilio as the Direct Connect Aggregator (DCA).
  4. Twilio, as the DCA, reviews the campaign for compliance.
    1. 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.
  5. 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.
  6. 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.
  7. 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.
    1. 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.
  8. 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)
  9. 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:

  1. 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.
  2. 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.

Loading Code Sample...
        
        

        Create a Messaging Service

        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.

        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.

        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.

        Loading Code Sample...
              
              

              Associate the pre-registered A2P campaign with the Messaging Service

              3. Get A2P Campaign

              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, 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.

              Note: The QE SID is the same string for any messaging service or campaign.

              Loading Code Sample...
                    
                    

                    Get A2P campaign

                    4. Delete A2P Campaign Assocation

                    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.

                    Loading Code Sample...
                          
                          

                          Delete A2P Campaign

                          Frequently Asked Questions

                          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?

                          Get help with A2P 10DLC

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

                          Rate this page:

                          Need some help?

                          We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                          Loading Code Sample...
                                
                                
                                

                                Thank you for your feedback!

                                Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                Sending your feedback...
                                🎉 Thank you for your feedback!
                                Something went wrong. Please try again.

                                Thanks for your feedback!

                                thanks-feedback-gif