Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Externally Registered Campaigns API


(information)

Info

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?(link takes you to an external page)

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

understanding-a2p-10dlc page anchor

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.

Associating Campaigns with Messaging Services

associating-campaigns-with-messaging-services page anchor

Below are the general steps that you/Twilio will perform in order to associate your Campaigns with Messaging Services. Additionally, this sequence diagram(link takes you to an external page) 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)(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 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.

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.


The following calls are all made using the Messaging API

1. Create a Messaging Service

1-create-a-messaging-service page anchor

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

create-a-messaging-service page anchor
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
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messaging.v1.services
_10
.create({friendlyName: 'My Service'})
_10
.then(service => console.log(service.sid));

Output

_33
{
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"date_created": "2015-07-30T20:12:31Z",
_33
"date_updated": "2015-07-30T20:12:33Z",
_33
"friendly_name": "My Service",
_33
"inbound_request_url": "https://www.example.com/",
_33
"inbound_method": "POST",
_33
"fallback_url": "https://www.example.com",
_33
"fallback_method": "GET",
_33
"status_callback": "https://www.example.com",
_33
"sticky_sender": true,
_33
"smart_encoding": false,
_33
"mms_converter": true,
_33
"fallback_to_long_code": true,
_33
"scan_message_content": "inherit",
_33
"area_code_geomatch": true,
_33
"validity_period": 600,
_33
"synchronous_validation": true,
_33
"usecase": "marketing",
_33
"us_app_to_person_registered": false,
_33
"use_inbound_webhook_on_number": true,
_33
"links": {
_33
"phone_numbers": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers",
_33
"short_codes": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ShortCodes",
_33
"alpha_senders": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AlphaSenders",
_33
"messages": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages",
_33
"us_app_to_person": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Compliance/Usa2p",
_33
"us_app_to_person_usecases": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Compliance/Usa2p/Usecases",
_33
"channel_senders": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ChannelSenders"
_33
},
_33
"url": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_33
}

2. Associate the pre-registered A2P campaign with the Messaging Service

2-associate-the-pre-registered-a2p-campaign-with-the-messaging-service page anchor

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

associate-the-pre-registered-a2p-campaign-with-the-messaging-service page anchor
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
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.messaging.v1.externalCampaign
_13
.create({
_13
campaignId: 'CRMTK1Z',
_13
messagingServiceSid: 'MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
_13
})
_13
.then(external_campaign => console.log(external_campaign.sid));

Output

_10
{
_10
"sid": "QE2c6890da8086d771620e9b13fadeba0b",
_10
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"campaign_id": "CRMTK1Z",
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"date_created": "2021-03-21T21:31:00Z"
_10
}

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.

(information)

Info

Note: The QE SID is the same string for any messaging service or 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
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.messaging.v1.services('MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.usAppToPerson('QE2c6890da8086d771620e9b13fadeba0b')
_11
.fetch()
_11
.then(us_app_to_person => console.log(us_app_to_person.sid));

Output

_47
{
_47
"sid": "QE2c6890da8086d771620e9b13fadeba0b",
_47
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_47
"brand_registration_sid": "BNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_47
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_47
"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.",
_47
"opt_in_keywords": [
_47
"START"
_47
],
_47
"opt_out_keywords": [
_47
"STOP"
_47
],
_47
"help_keywords": [
_47
"HELP"
_47
],
_47
"date_created": "2021-02-18T14:48:52Z",
_47
"date_updated": "2021-02-18T14:48:52Z",
_47
"url": "https://messaging.twilio.com/v1/Services/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Compliance/Usa2p/QE2c6890da8086d771620e9b13fadeba0b",
_47
"mock": false,
_47
"errors": []
_47
}

4. Delete A2P Campaign Assocation

4-delete-a2p-campaign-assocation page anchor

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.

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
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messaging.v1.services('MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.usAppToPerson('QE2c6890da8086d771620e9b13fadeba0b')
_10
.remove();

Frequently Asked Questions

frequently-asked-questions page anchor

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?(link takes you to an external page)

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)

Rate this page: