ISV A2P 10DLC Standard and Low-Volume Standard Registration: API Walkthrough
Please rate limit all API requests for Brand and Campaign registration to 1 request per second.
The process for registering for a Low Volume Standard Brand is the same as registering for a regular Standard Brand, with the only exception that Low Volume Standard Brands must skip secondary vetting when creating an A2P Brand (skip_automatic_sec_vet
should be True when you create an A2P Brand). For more on Standard vs Low-Volume Standard see Section 3 below.
Purpose of this Guide
- intended for ISVs
- registering secondary clients
- for Standard or Low-Volume Standard A2P Brands and Campaigns
- using Twilio's API tools
This guide is a step-by-step walkthrough of the various API calls that an ISV will make to register their secondary customers for A2P 10DLC capabilities using Twilio APIs. This guide is intended for ISVs only--that is, businesses that resell Twilio messaging services to their own customers (who from Twilio's perspective are known as secondary customers). For example, if you are a software company providing a platform for your customers to send sms messages on their own behalf, powered by Twilio's messaging services, you are an ISV.
If you instead need to register for A2P 10DLC capabilities to send sms messages exclusively on your own behalf, you are a direct customer, and would not typically use the following API calls for A2P registration. Instead, you would use the Twilio Console tool for registration, and would follow this guide if you are registering as a Standard or Low-Volume Standard Brand, or this guide if you are registering as a Sole Proprietor Brand.
Please note that Standard and Low-Volume Standard Brands must have an EIN or other national Tax ID in order to register, while Sole Proprietor Brands cannot have such a Tax ID (and must also be headquartered in the U.S. or Canada).
In this guide you will be registering your secondary customers' brands as either Standard or Low-Volume Standard Brands (see Section 3 below for the difference between the two). If you instead need to register your secondary customers for Sole Proprietor Brands, please see this guide instead.
While our A2P registration Console tool is intended primarily for use by direct customers, and the API calls covered in this guide are intended for use by ISVs, the Console can also be used for ISVs to register their secondary customers, though this is necessarily a one-at-a-time process (while the API calls can be used for batch-submission processes, or as the back-end for your own customer self-service registration websites). As an ISV, you might consider using the Console tool to register one or two of your secondary customer brands simply as a way to familiarize yourself with the basic steps in the registration process and the inputs required at each step, before using this document's API sequence for your other customers. From the standpoint of Twilio and A2P ecosystem partners, registrations are identical whether they originate in the Console or API calls. The Console can also be a convenient way to check on the status of particular Brand and Campaign registrations.
You will be working with two different APIs to cover the three main steps of this registration process:
- Customer Profile and Trust Bundle registration -- Trust Hub API
- Brand registration -- Messaging API
- Campaign creation -- Messaging API
If you haven't already done so, be sure you're using the latest version of the Twilio Helper Libraries to perform the API calls in this walkthrough.
Prerequisite: Create a Trust Hub Profile for your Company (ISV)
What does this do? Creates a Trust Hub profile for your business (the ISV).
Which API? This can only be done via the Trust Hub UI in the Twilio Console.
Before proceeding with the onboarding process for your clients, all ISVs must have a primary customer profile in an APPROVED state. You can do this in the Trust Hub, located in the Twilio Console. In order to register secondary profiles, the primary customer profile needs to have “ISV Reseller or Partner” selected as your Business Identity.
NOTE: To get the highest possible messaging limits, please create your customer's profile with details that exactly match those in their US EIN listing (or that of their relevant national Tax ID if their business is located outside the U.S.). If there are any differences – for example, in the business name or address – their messaging limits will be lower. Please have your customer verify these details via their W2 form or equivalent national tax record.
Tip: Copy the Primary Customer Profile's bundle SID (BUxxx) from Customer Profile Details page to be used in a later step; see https://console.twilio.com/us1/account/trust-hub/customer-profiles > View profile details button
1. Create secondary customer profile(s) and attach required information
Before you go through the process described in this step, be aware that the secondary customer profile you are creating here can be used as well for three Twilio Voice products: SHAKEN/STIR Trusted Calling, Branded Calls, and CNAM Registration. See the Trust Hub console for details on each of these products. If your secondary client is already using any of these Voice products, this means that a customer profile identical to the one you are about to create has already been created for that customer and accepted by Twilio. Rather than creating a new one, then, you should go to the Trust Hub Console (Trust Hub > Customer Profiles), and beneath your own primary ISV business profile you will see a list of all your existing secondary customer profiles. Select the SCP corresponding to the customer you are now registering for A2P messaging, if you find it listed there, and click on its Bundle SID to inspect its details to ensure that they are still correct for this client. If so, copy the Bundle SID of that profile (begins with 'BU'). You can then skip the entirety of Step 1 of the present walkthrough, and start at the beginning of Step 2 below (there you're creating a Trust Product for that client, and the Trust Product will be specific to A2P vs the Voice products). The profile Bundle SID that you just copied will become the trust_product_sid
that you use in Step 2.5.
Conversely, if you have not yet used any of these three Voice products with this secondary client, but plan to do so in the future, bear in mind that the Customer Profile you are creating in Step 1 below can itself be reused for SHAKEN/STIR, Branded Calls and/or CNAM Registration.
In your requests throughout this walkthrough, you should be using the Twilio Account SID (and corresponding Auth Token) where you plan to use the Brand you are registering for. For example, if you use subaccounts to separate your customers' usage, use the Twilio Account SID corresponding to the subaccount for the customer you are registering.
Note: For all information entered as part of this registration process, please note that The Campaign Registry (TCR) supports all “utf8mb4” supported characters. Please see the list for all Unicode 15.0 supported scripts and characters here: https://www.unicode.org/charts/
What does this do? Creates Trust Hub profiles for each of your clients
Which API? Trust Hub API
Once you have an approved primary customer profile for your own ISV business entity, create a secondary customer profile for each of your clients. Depending on your Twilio account architecture, you may need to create the Secondary Customer Profile (SCP) at the Twilio subaccount or account level.
The following will guide you through the necessary steps to create a (single) secondary customer profile. If you have multiple secondary customers to register, you must follow the following process separately for each customer.
NOTE: For purposes of A2P registration, your ultimate objective in Sections 1-3 of this guide is to register an A2P Brand for your secondary customer. This Brand creation itself happens in Part 3. However, the success or failure of this Brand registration (and, if successful, the Trust Score which will determine allowable messaging throughput) depends to a very large extent on information you will enter in this first profile-creation step, and specifically on the information detailed in Parts 1.2 through 1.6 below. Please attend carefully to the instructions and guidance offered in these steps, to maximize your chances of successful Brand registration with the highest possible Trust Score.
Conversely, if your Brand registration does fail, or results in a lower Trust Score than you feel is warranted, it is generally this customer profile information that will need to be rectified. In other words, some information in the customer profile you are creating in this step would need to be updated (as well as the Trust Product you will create in Step 2), before the Brand itself can be resubmitted.
1.1 Fetch the Secondary Customer Profile Policy
This step requires you to use a hard-coded PolicySID: RNdfbf3fae0e1107f8aded0e7cead80bf5
. As the Trust Hub is built to support multiple use cases, the PolicySID is the object that Twilio uses to store the various policies and regulations for that specific trust product. You will see this reappear later on for A2P 10DLC regulations.
1.2 Create an empty secondary customer profile bundle
In this step, you are populating the information for a customer profile, similar to what you did when you filled in your own Primary Customer Profile in the Twilio Console.
Secondary Customer Profiles can live at either the parent or subaccount levels. If you are creating these within a subaccount, the AccountSID and AuthToken that you use in the following requests should be that of the Subaccount.
This API call to the customer_profiles
endpoint involves the following parameters:
Parameter | Details |
policy_sid |
The static Trust Hub policy identifier for secondary customer profiles for A2P purposes. The hard-coded value is RNdfbf3fae0e1107f8aded0e7cead80bf5 and you use this value for every Secondary Customer Profile Bundle you create. |
friendly_name |
A string representing your customer's business name. This is an internal name meant for you to identify this particular customer profile Bundle for your customer. |
email |
A string representing your customer's email address. This must be a valid email address and will be verified by TCR. |
status_callback (optional) |
Provides a status callback URL. If provided, all status callbacks with bundle information in this and following steps will be sent to the provided URL. |
1.3 Create end-user object of type: customer_profile_business_information
This step provides Trust Hub with necessary information about the customer/business that is represented by the secondary customer profile.
If your customer is a US entity with an EIN, use this EIN to register their customer profile. Do not use a DUNS number. If your customer is a non-US based entity, you should use the Tax ID with which they are registered with their national tax authority (Refer to the business_registration_identifier
list in the table below for some specific international Tax IDs).
Only the Parent Business Profile should be marked as isv_reseller_or_partner
in most scenarios, so please pass direct_customer
for the business_identity
field in this step for Secondary Customer Profile registrations
In this step, you will make a create
call to the end_user
endpoint of the Trust Hub API.
- You will pass in a
type
parameter of"customer_profile_business_information",
to indicate the operation you are performing in this particular step. - The
friendly_name
parameter allows you to name the object you are creating here, to associate it with the secondary brand. For internal use only. - As shown in the code snippet, all of the specific business information is passed in within the
attributes
parameter, as an object. The following table specifies each attribute relevant to this use case, and provides all possible valid values for each attribute. Please refer to the language-specific code snippets for the appropriate syntax/formatting of the attributes object in each language.
Note: Because this will be a Standard or Low-Volume-Standard registration, "Sole Proprietorship" is not a valid value for business_type
in this case. If your secondary customer is a U.S.-based LLC of a type considered "Sole Proprietorship" by the IRS, The Campaign Registry still views this customer as eligible only for a Standard or Low-Volume Standard Brand because, as an LLC, that customer uses an EIN for tax purposes. In this case you would specify Limited Liability Corporation
as the business_type
.
For business_industry
, please choose the industry that most closely resembles the business in question.
Attribute | Valid values |
business_name |
|
website_url |
This is the website of the business entity whose brand you are registering. If you are an ISV, this is the website of the secondary customer's brand, NOT the website of your own business. This website must be functional, and it must bear some obvious relationship with the business name you have entered above.
|
business_type |
|
business_industry |
|
business_registration_identifier |
|
business_identity |
Note: The |
business_regions_of_operation |
|
business_registration_number |
The value here depends on which US EIN: [xx-xxxxxxx] (NUMERICAL) US DUNS: [xx-xxx-xxxx] (NUMERICAL) CA CBN: [xxxxxxxxx] (NUMERICAL) |
1.4 Create end-user of type: authorized_representative_1
This step provides required information about an authorized business representative (one authorized point of contact is required) for the secondary customer profile.
You should use a point of contact from the end business (secondary client) representing this brand, not from your own business. At this time, Twilio or The Campaign Registry does not use this contact information to reach out to the end business. If in the future the industry requirements change and there becomes a need for the ecosystem to reach out to this contact information for verification, there may be a change in this policy.
This step makes another create
call to the end_users
API endpoint, but this time the type
parameter has the value of "authorized_representative_1." The friendly_name
attribute might be something like "auth_rep_1". As in the previous step, the actual information on this point of contact is passed in via the attributes
parameter, as an object. The following table lists the attributes and valid values:
Attribute | Valid values |
business_title |
Represents the exact job title of the contact, and is free form. |
job_position |
Director GM VP CEO CFO General Counsel Other |
last_name |
Exact last name of the contact |
phone_number |
Valid phone number for this contact |
first_name |
Exact first name of this contact |
email |
Valid email for this contact |
1.5 Create end-user of type: authorized_representative_2 (optional)
This step provides optional information about a second authorized business representative for the secondary customer profile. This is another create
call to end_users
, with a type
of "authorized_representative_2". If you do choose to list a second authorized representative, please use the same attribute fields listed for 1.4 above, with the values adjusted accordingly.
1.6 Create supporting document: customer_profile_address
This step creates an object representing your customer’s address information if you don’t already have one for the customer. Alternatively, if you already have an address, skip to the next code block, where you can create a customer document (when you have a valid AddressSID).
The following table lists all parameters for this API call and their valid values:
Parameter | Valid values |
customer_name |
The full name to associate with the new address |
street |
The number and street address of the new address |
city |
The city of the new address |
region |
Any correct two-letter abbreviation for a US state, for example: |
postal_code |
The postal code of the new address |
iso_country |
The ISO country code of the new address |
friendly_name (optional) |
A descriptive string that you create to describe the new address. It can be up to 64 characters long. |
emergency_enabled (optional) |
Whether to enable emergency calling on the new address. Can be: `true` or `false`. Default is 'false'. |
auto_correct_address (optional) |
Whether we should automatically correct the address. Can be: `true` or `false` and the default is `true`. If empty or `true`, we will correct the address you provide if necessary. If `false`, we won't alter the address you provide. |
street_secondary (optional) |
Additional address information, if necessary (e.g. "Suite" or "Attention") |
1.6.1 Create customer document (when you have a valid AddressSID)
In this step you will make a call to the supporting_document
API endpoint, with a type
parameter value of "customer_profile_address".
- The
friendly_name
parameter value should remind you of the relevant customer profile, e.g. "acme" in our example. - As shown in the code snippet, the
attributes
parameter value in this case contains a single name/value pair:address_sids:
, and then a valid AddressSID that you either derived (as the SID output parameter) from the previous call in 1.6, or had already from some earlier customer_profile_address creation with the same address data. In either case, this AddressSID will associate that set of address data, enumerated in step 1.6, with the secondary customer profile you are creating in this general step.
Note: The creation of a secondary customer profile does not depend on the status
of a supporting document. The status
field of the JSON response in this step can be disregarded.
1.7 Assign end-users, supporting document, and primary customer profile to the empty secondary customer profile that you created
Using the SIDs you've gotten in the json response from each of the steps above, you will now attach them all to the secondary customer profile. This will entail four (or five, if you've chosen to specify a second authorized_representative) separate create
calls to the customer_profiles
endpoint. In each case the customer_profiles
value is the SID of the empty secondary profile itself, which was the first entity created in this general step, and the object_sid
is the relevant SID returned from the API calls for items 1-4 below (or rather 1-3, whereas in #4 the SID comes from the primary customer profile under which this SCP is being created). Again, the code snippet below represents an example of only one of these four (or potentially five) calls:
- authorized_representative_1 and optionally authorized_representative_2
- supporting document (address)
- customer_profile_business_information
- primary_customer_profile
1.8 Run evaluation on secondary customer profile
By running an evaluation, you check that you’ve provided all the required Secondary Customer Profile information. The evaluation also flags issues with the data before you submit it to Twilio’s Trust Hub. If there are no errors, you will get a status of "compliant", otherwise it will fail and error codes will be surfaced to you.
This call to the customer_profile_evaluation
API endpoint takes two parameters:
Parameter | Valid values |
customer_profile_sid |
The SID of the secondary customer profile you created above |
policy_sid |
The hard-coded policy SID associated with the creation of a secondary customer profile: RNdfbf3fae0e1107f8aded0e7cead80bf5 |
1.9 Submit the secondary customer profile for review
This will submit the secondary customer profile, including all of the bundled information, to Twilio Trust Hub for review. You can proceed to the next steps without an approved secondary customer profile.
This submission is accomplished by way of an update
call to the customer_profile
API endpoint, for which you called the create
method in step 1.2 above. Here are the required and optional parameters for this particular step:
Parameter | Valid values |
sid |
The SID of the secondary customer profile you created above |
status |
Other than specifying the profile SID itself, the one required action for this step is to change the status of this profile to a value of pending_review . The result of this API call will update the profile's status to in-review (which you should see in the response to your API request), at which point you should move on to the next step in this walkthrough. |
status_callback (optional) |
If you did not provide a status_callback URL in step 1.2, you can provide one here. If you've provided one already, a value entered here will overwrite the existing value. See the Bundles Resource documentation for details on Twilio's request to your webhook. |
friendly_name (optional) |
As friendly_name was a required parameter in step 1.2, you should only use this parameter in the current call if you wish to update the friendly_name |
email (optional) |
This was a required field in step 1.2, so you should only use this parameter if you wish to change the email address you entered previously. |
You do not need to wait for this Secondary Customer Profile to have a status of approved
before moving on to Brand submission in step 3. Brand submission will retroactively modify your Secondary Customer Profile’s status.
2. Create an A2P Trust Product
What does this do? Creates an A2P Profile (a bundle of information) that you will submit with your Customer Profile to the Campaign Registry
Which API? The Trust Hub API
Once your Secondary Customer Profile from the previous step is in_review
, you can create a new Standard A2P Trust Bundle for your customer, which you will then use to complete a Standard or Low-Volume Standard Brand. The steps in this section are similar to the ones you completed in Section 1, but you will provide different information about your customer here. These steps are required before this new profile can be submitted to The Campaign Registry (TCR) for approval.
2.1 Fetch A2P Profile Policy
Fetch the policy details for A2P Messaging.
This is a fetch/GET
call to the policies
endpoint of the Trust Hub API. The one required pameter is sid,
which will be the hardcoded Regulation SID RNb0d4771c2c98518d916a3d4cd70a8f8b
See the code snippet below:
2.2 Create an empty A2P Trust Bundle
This Standard A2P Trust Bundle contains additional information about your customer (from the profile you created above) and their Brand. You fill out some of the fields now, and attach more information to this Bundle in later steps. You will submit this Bundle for review in the last step of Section 2 of this walkthrough.
These are the parameters for the API request to create a Standard secondary client A2P Trust Bundle (this is a create
call to the trust_products
API endpoint):
Parameter | Valid Values |
friendly_name |
A string representing your customer's business name. This is an internal name for you to identify this Bundle for your customer. Can be the same as the friendly_name you set up for the secondary customer profile in steps above. |
email |
A string representing your customer's email address |
policy_sid |
The static A2P Messaging TrustHub Policy identifier. The hard-coded value is RNb0d4771c2c98518d916a3d4cd70a8f8b . |
status_callback (optional) |
The URL at which you would like to receive status update webhook requests for this Trust Bundle. |
2.3.1 Create an end user of type us_a2p_messaging_profile_information (public companies)
This step is similar to step 1.3 above, in that you are once again making a create
call to the end_user
endpoint. But this time:
1) for the type
parameter you are passing in a value of us_a2p_messaging_profile_information
2) for the friendly_name
parameter you would want a name that references this step, such as "A2P for acme-inc" (OR "A2P for nonprofit-acme-inc" or "A2P for government-acme-inc", see next)
3) in the attributes
parameter you are once again passing in an object of name/value pairs, but this time it's a smaller and different list of values. Also, importantly, the essential attribute company_type
will differ, depending on what type of client company you are registering. There will be more or fewer accompanying attributes depending on this type. Accordingly, we have provided four different code snippets, corresponding to the typical registrations for public companies (immediately below), private companies (2.3.2 below), nonprofit entities (2.3.3), and governmental entities (2.3.4).
NOTE that the general use case for this document is the creation of Standard or Low-Volume Standard Brands and Campaigns. Thus the company_type
of Sole Proprietor
is not valid for this use case, as that would be the type appropriate for a Sole Proprietor brand registration.
Because this first example call is for a public (for-profit) company, in addition to specifying a company_type
attribute of public
, you will also specify the stock_exchange
on which that company's stock is listed, as well as its stock_ticker
symbol. These latter attributes would not apply to the three organization types addressed in the examples that follow.
2.3.2 Create an end user of type us_a2p_messaging_profile_information (private companies)
This is the variant of step 2.3 that will apply to private companies (i.e., not publicly-traded) that are still formally corporations AND have EINs. If your secondary client does not have an EIN, and does business in the US, they probably qualify for a Sole-Proprietor Brand and should be registered as such.
Note that because this case pertains to a private company, within the attributes
parameter of this call, company_type is set to private
, and there is no stock-exchange information as in 2.3.1 above.
2.3.3 Create an end user of type us_a2p_messaging_profile_information (nonprofit)
This variant of step 2.3 pertains to non-profit organizations. Creating a brand with a company_type
of non_profit
(as shown here) is essential to unlocking campaign special use cases reserved for particular types of nonprofits. For instance, 501(c)(3)s can only unlock the Charity special use case if their brand is created with a non-profit company type here — this triggers TCR to verify the brand's 501(c)(3) status and, upon success, marks them as qualified for this use case.
2.3.4 Create an end user of type us_a2p_messaging_profile_information (government)
This final variant of step 2.3 pertains to governmental organizations or agencies. Creating a brand with a company_type
of government
(as shown here) is essential to unlocking increased messaging throughput reserved for government agencies. Creating a brand with the government company type here triggers TCR to verify the brand's status as a government entity and, upon success, qualifies the brand for increased throughput (T-Mobile: Unlimited daily cap, AT&T: TBD MPS).
2.4 Assign the end user to the A2P Trust Bundle
In this step, you will associate the end user object you just created in step 2.3 with the A2P Trust Bundle you created in step 2.2. In this create
call to the trust_products_entity_assignments
endpoint, the Path
or trust_product_sid
is the SID returned in step 2.2 (it will begin with "BU"), and the object_sid
parameter is the SID (beginning with "IT") that was returned in step 2.3.1, 2.3.2, 2.3.3 or 2.3.4, depending on the company_type
of the Brand you're creating.
2.5 Assign secondary customer profile bundle to A2P trust bundle
This step ties your A2P trust bundle back to the secondary customer profile you created in step 1 above. This is another create
call to the trust_products_entity_assignments
endpoint. The Path
or trust_product_sid
is once again the SID returned in step 2.2 (it will begin with "BU"), and the object_sid
parameter in this case is the SID for the secondary client profile you created in step 1 above.
2.6 Run evaluation on A2P Trust Product
By running an evaluation, you check that all the necessary A2P Bundle information has been added. If there are no errors, you will get a status of compliant
. If there are errors, the evaluation will fail and error codes will be surfaced to you.
In this create
call to the trust_products_evaluations
endpoint, the trust_product_sid
is the same one you used in 2.4 and 2.5 (begins with "BU"), while policy_sid
is the hardcoded policy SID from step 2.1: RNb0d4771c2c98518d916a3d4cd70a8f8b
The status
parameter in the response to this call will either be compliant
or noncompliant.
2.7 Submit A2P Trust Bundle for review
This is an update call to the trust_products
endpoint, with the following possible parameters:
Parameter | Valid values |
sid |
The SID of the Trust Bundle you have created above |
status |
Other than specifying the Trust Bundle SID itself, the one required action for this step is to change the status of this Trust Bundle to a value of pending_review . This will trigger the automated validation by our system. |
status_callback (optional) |
If you did not provide a status_callback URL in step 2.2 you can provide one here. If you've provided one already, a value entered here will overwrite the existing value. See the Bundles Resource documentation for details on Twilio's request to your webhook. |
friendly_name (optional) |
As friendly_name was a required parameter in step 2.2, you should only use this parameter in the current call if you wish to update the friendly_name |
email (optional) |
As this was a required field in step 2.2, you should only use this parameter if you wish to change the email address you entered previously. |
You do not need to wait for this A2P Trust Bundle to be approved
before moving on to Brand submission in step 3. Brand submission will retroactively modify your A2P Trust Bundle's status.
3. Create an A2P Brand
What does this do? Submits the combined package of your A2P Messaging Profile and Customer Profile to the Campaign Registry (TCR) in order to get the A2P Brand registered. TCR is the 3rd-party body that must approve the provided information in both profiles in order for your Brand registration to be registered successfully.
Which API? The Messaging API
Note: The most important decision during this Brand-creation step is whether you want to register as a Standard or Low-Volume Standard Brand. The latter creation step is identical to the former except that Secondary Vetting is skipped, by setting the parameter skip_automatic_set_vet
to true
in the following call, so that the Brand being submitted for registration will only go through primary vetting and skip secondary vetting. This reduces Brand registration cost; however, please note that daily message caps and throughput may be significantly lower for Brands registered without Secondary Vetting (hence the name "Low Volume Standard").
For more details on the approach you should choose, see our support article Secondary Vetting for A2P 10DLC.
Low Volume Standard Brands will by default receive the following throughput and messaging limits:
Brand is a Russell 3000 index company? | T-Mobile daily message limit (SMS segments + MMS) | Message throughput tier – Declared use case | Message throughput tier – Mixed/Marketing use case | Message throughput tier - Low volume mixed use case |
---|---|---|---|---|
Yes | 200,000 | 75 MPS per major US carrier | 75 MPS per major US carrier | 1.25 MPS per major US carrier |
No | 2,000 | 4 MPS per major US carrier | 4 MPS per major US carrier | 1.25 MPS per major US carrier |
If you’ve registered a Low Volume Standard brand, and later wish to go through Secondary Vetting and receive higher throughput and messaging limits, please contact Twilio support. The Campaign Registry (TCR) charges $40 for Secondary Vetting, and this fee will be passed onto you.
For more information, please see our support article on Secondary Vetting for A2P 10DLC.
Note for 527 Political Organizations: ISVs registering 527 Political customers should in all cases pass skip_automatic_sec_vet
as true
when creating an A2P Brand. Secondary vetting is not required as A2P messaging limits are determined by your status as a 527 organization.
The same applies to political organizations with a Campaign Verify token as well; they should disable automated Secondary Vetting. Political organization brands will receive increased throughput when a valid Campaign Verify token is uploaded at the brand registration step. See the step below, Import Campaign verify token to an existing brand, for more information.
Note for Government entities and Non-profits: Brand registrations for non-profit and government entities should not skip automatic secondary vetting with the exception of 527 Political customers as described above. Except for 527s, secondary vetting is required to trigger automatic verification of nonprofit or government entity status by TCR and to successfully apply this status to the brand.
Brand registration entails a create
call to the brand_registrations
endpoint of the Messaging API. Here are the required and optional parameters for this call in the present use case:
Parameter | Valid values |
customer_profile_bundle_sid |
The SID associated with the customer profile you created in step 1.2 |
a2p_profile_bundle_sid |
The SID associated with the A2P Profile Bundle you created in step 2.2 |
skip_automatic_sec_vet (optional) |
Boolean. While this parameter is technically optional, as explained above, it is required if you are electing to create a Low-Volume Standard Brand, or have any other reason (such as 527 political organizations) to skip secondary vetting. In this case it must be set to true . Otherwise it can be set to false , or can be omitted and the value will default to false . |
In the code snippet that follows, the skip_automatic_sec_vet parameter has been set to true. If your brand does need secondary vetting, set this to false or omit the parameter.
Submitting the A2P Brand triggers a billable event. By default your account will be charged $4 registration + $40 to include automated secondary vetting, unless your account currently has any vetting waivers in place or you have explicitly set skip_automatic_sec_vet
to true
.
Please take caution when making this API request. For more information on automated secondary vetting and associated fees, please review this support article.
A2P Brand Registration can take up to several days in some cases. If your brand isin the "IN_REVIEW" state for more than two days, please reach out to Twilio's support team.
3.0.1 Using Fetch to check brand registration status
You can do a fetch
call on this same brand_registrations
endpoint to check the current status of your Brand registration, at any point after the creation step.
NOTE: it is now possible to set up and subscribe to Brand status Event Streams, so that an event message will be sent to a specified webhook url when the new Brand has been successfully registered or has failed registration. Please see this guide for setting up the necessary Event Streams sinks and event subscriptions, and for information on reading each event message payload.
As the code snippet below illustrates, the call itself requires only a path/sid
to be specified, which is the Brand SID returned from the Brand creation call above. The parameters in the return json will be identical to those returned with the initial creation call, but some of the values will likely be different at a later point in time, as the status of your new Brand changes. Here are the relevant response parameters with various values and other information:
Parameter | Possible values and behavior |
status |
|
tcr_id |
|
brand_score |
|
failure_reason |
|
russell_3000 |
|
tax_exempt_status |
Identifies the tax-exempt 501c status for a non-profit Brand. If you are not tax-exempt, your
|
skip_automatic_sec_vet |
|
identity_status |
|
government_entity |
|
The brand_feedback
field is returned in the response of Creating/Fetching an A2P Brand. This field contains a list of Feedback IDs, where each ID corresponds to a recommendation on how you can improve your brand score. You will receive a list of feedback IDs on your brand registration, if any. Along with the list of feedback IDs, you will receive descriptive recommendations for ways to fix your brand registration.
Below are a list of possible feedback IDs that can be returned and corresponding recommendations for fixing the brand information:
Feedback ID | Recommendations |
TAX_ID |
|
STOCK_SYMBOL |
|
GOVERNMENT_ENTITY |
|
NONPROFIT |
|
More than one feedback ID may be returned at a time. To understand and rectify specific Brand feedback, please see our Guide to Troubleshooting A2P Brands and Campaigns.
You can also read more in A2P 10DLC Brand Approval Best Practices.
3.1 Update an A2P Brand
You may perform a brand update a maximum of three times at no additional charge. Once you have reached this limit, reach out to Twilio Support for additional assistance.
If you attempt a brand update more than three times, you will receive a 400 API response and a 21724 error code.
While Twilio will continue to allow brand updates, these may incur a fee at some point in the future, as each brand resubmission entails a charge by our A2P ecosystem partners.
What does this do? This step allows you to edit the A2P brand you've created if you have received a FAILED
brand status and the tcr_id
is not null. You will use the brand's SID (starting with BN
) to make this update call.
First, review the error message from the brand_feedback
and feedback_reason
parameters. You can use Fetch (shown above, 3.0.1) to check the feedback on your brand registration, once this becomes available. Next, you will need to perform the necessary updates using the relevant Trust Hub API endpoints. For example, you may need to update the associated customer profile or update the information attached to the listed end-user.
Once you have finished any necessary updates to your Profile and/or Trust Bundle , use this update
method of the brand_registrations
endpoint to update the brand’s registration. As the following snippet indicates, the only necessary input parameter for this update call is the Brand SID (path
or sid)
itself. The return json will contain the same parameters you've seen in the create and fetch calls above. Remember that your newly-updated information will in many cases require manual re-verification, so allow some time for this before checking Brand Registration status again.
As an alternative to this API call, you may review your brand feedback and update your brand via the Trust Hub UI in the Twilio Console. If you are registering many secondary brands and only some have failed, and potentially for different reasons, you might find it easier to keep track of your update work via the Console.
3.2 Import Campaign verify token to an existing brand (527 Political Organizations)
Prerequisites
If you are registering a 527 political organization, we highly recommend that you review "Registration for 527 Political Organizations" in the ISV Onboarding guide for an overview of the Campaign Verify registration process and Campaign Verify tokens before completing this step.
Note: A 527 organization that does not register with Campaign Verify and provide a token during 10DLC registration will be allowed to register with standard use cases, but will receive the lowest tier of A2P messaging limits and will not qualify for the Political Special Use Case. In addition, you may be subject to penalties from carriers if political messaging traffic is incorrectly registered with standard use cases. You must import your Campaign Verify token during the Brand Creation step.
Register with Campaign Verify to submit information about your political organization and verify your identity as an authorized person associated with the organization. You will receive a Campaign Verify token (vetting_id
) which you will need for the following API call. ISVs that are sending messages on behalf of 527 organizations must collect Campaign Verify tokens from their customers and provide them during the A2P brand registration steps as described below.
A2P brands with a Campaign Verify token successfully attached will only qualify for the Political special use case — all standard use cases will be disabled for this brand. This is both so that political organizations can take advantage of increased messaging limits associated with the Political campaign use case, and so that all messages from 527s are correctly categorized as political traffic.
What does this do? This create
call to the brand_vettings
endpoint attaches a Campaign Verify token to an existing A2P Brand to prove its status as a 527 Organization. This will unlock the ability to register with the Political Special Use Case and receive increased A2P messaging limits from carriers. You will need to pass your vetting_id
in the body of this request to associate it with your A2P Brand and assert your brand status as a verified 527 Political Organization within the carrier ecosystem.
Parameter |
Details |
|
The SID of the A2P Brand for which you are importing a Campaign Verify ID. This Brand must have been created with the "Nonprofit" company type to import a Campaign Verify token. |
|
The third-party provider that has conducted the vetting. Set to "campaign-verify" for Campaign Verify tokens. |
|
The unique identifier of the vetting from the third-party provider. Set this to your Campaign Verify token string. |
3.3 Fetch all external vetting records (527 Political Organizations)
What does this do? This call (list
or read
, depending on the library) to the brand_vettings
endpoint fetches a list of all vetting records attached to a brand_sid
. Each object inside of the response array contains a vetting_sid
and its associated vetting_id
. Returns all external vetting records applied to the brand for Campaign Verify.
Vetting import attempts are asynchronously performed. You can monitor the status of the import vetting attempt using the vetting_status
parameter.
The statuses for external vetting records are:
IN_PROGRESS
: The attempt to import the vetting record is in progress.SUCCESS
: The vetting record has been successfully applied to the brand.FAILED
: The attempt to apply a vetting record to the brand failed.
Parameter |
Details |
|
The SID of the A2P Brand for which you are fetching vettings. |
|
Set to "campaign-verify" to limit the vetting results to only Campaign Verify token. |
For 527 Political Organizations, ensure that the status of the vetting record is SUCCESS
to confirm that the Campaign Verify token has been successfully applied to the brand before moving on to campaign registration. This will unlock the Political special use case and apply increased messaging limits from carriers.
3.4 Fetch a single external vetting record (527 Political Organizations)
What does this do? This call to the brand_vettings
endpoint fetches an individual vetting record using a vetting_sid
. This call is very much like the previous one (step 3.3 above) except that, since a single vetting_sid is associated with only a single vetting record, just that specified record will be returned. A possible use of this call would be to determine, for example, if the status of a particular vetting record returned in 3.3 had changed, e.g. from IN_PROGRESS to SUCCESS.
Vetting import attempts are asynchronously performed. You can monitor the status of the import vetting attempt using the vetting_status
parameter.
The statuses for external vetting records are:
IN_PROGRESS
: The attempt to import the vetting record is in progress.SUCCESS
: The vetting record has been successfully applied to the brand.FAILED
: The attempt to apply a vetting record to the brand failed.
Parameter |
Details |
|
The SID of the A2P Brand for which you are fetching vettings. |
|
The Twilio SID of the third-party vetting record. |
4. Create or Choose a Messaging Service
What does this do? Creates a new Twilio Messaging Service for A2P Messaging, or designates an existing Messaging Service to use in the new Campaign.
Which API? The Messaging API
At the beginning of this document, we said that the three main steps involved in new Standard and LVS Brand registration were:
- Trust Hub registration
- Brand registration
- Campaign use case creation
You have now accomplished the first two of these major steps (Trust Hub registration itself had two parts: the new Standard Customer Profile and the new Trust Bundle). Here you are moving on to the final step, but it too has several pieces. Before you define the actual Campaign use case and other features, in step 5 below, you will first need to either create a new A2P Messaging Service that you will then associate with that new Campaign, or select an existing Messaging Service that you will designate for reuse in the new Campaign (either option will provide the Messaging Service SID that you will use in step 5).
If you are considering reuse of an existing Messaging Service in the new Campaign, be aware that any Messaging Service can only be associated with one Campaign (and Brand) registration at a time. If you attempt to register a new Campaign in step 5 below and designate an existing Messaging Service that is currently associated with a different Campaign, the new Campaign registration step will fail.
If you need to programmatically delete an existing Campaign associated with a given Messaging Service, in order to free up that MS for reuse in a new Campaign, step 5.4 below indicates how to do this.
4.1 Create a new Messaging Service
New Messaging Services are created via a create
call to the services
endpoint of the Messaging API. This call, with all of its possible parameters, is detailed in the Messaging API documentation. Please consult this document before creating a new Messaging Service via the API.
Note that this call has only one required parameter, friendly_name
, but there are many optional parameters. The code snippet below specifies two of these optional parameters in addition to friendly_name
: inbound_request_url
and fallback_url
. To configure your Messaging Service to ensure you receive inbound messages, you would need to configure a webhook url using the inbound_request_url
parameter. You may also want to configure a fallback webhook url (fallback_url
) in case the primary handler fails.
The sid
attribute in the json return from this call will be the messaging_services_sid
to be used in section 5 below.
4.2 Fetch a Pre-existing Messaging Service
As noted above, rather than create a new Messaging Service for this new Brand and Campaign, you may use a pre-existing Messaging Service if you have one that is currently not associated with a campaign, and is appropriate to use for this new one. The API call below is a fetch
call to the services
endpoint, using the SID of your existing Messaging Service. This call would be useful to inspect all of the attributes currently associated with a given Messaging Service.
5. Create an A2P Campaign
What does this do? Creates a required campaign for sending A2P messages around a given use case
Which API? The Messaging API
5.1 Fetch possible A2P campaign use cases
Before you can create your new Campaign, you will need to determine which use case you'd like to specify for it (for a list of all campaign use case types, please see our support article on use case types for A2P 10LC registration). Only one use case can be specified per Campaign. The type of use case that you select greatly impacts the pricing and throughput available to you. Moreover, only a certain subset of all possible use cases are valid for any particular Brand type (e.g. for-profit corporation, non-profit organization, government agency). Thus, the purpose of the API call in this step is to determine what this valid subset is for your brand type, and in this set of valid use cases be able to see which of them, for example, require a post-approval step by your carrier.
NOTE: If OTP (One-Time Password) or any other form of 2-Factor Authentication is your only use case for SMS messaging with 10DLC numbers in the U.S., you should investigate Twilio's Verify service to see if this is a better option. With Verify you do not need to worry about A2P registration or any other aspect of sender provisioning.
As the code sample below indicates, this will be a fetch
call to the us_app_to_person_usecases
endpoint of the Messaging API. In this call you will specify the messaging_service_sid
, which is the SID of the Messaging Service you either created or selected for reuse in step 4 above (this SID will begin with "MG"). You will also specify the brand_registration_sid
, which is the SID returned when you created your new Brand in step 3 (this SID begins with "BN").
As an ISV, you will be able to see which Campaign use cases require post-approval using the API call in this step. If the new parameter post_approval_required
is set to true
, the use case requires an additional carrier review.
If you’re a 501(c)(3), we recommend you register using the Charity/501(c)(3) Nonprofit special use case. For more information, please see Registering Campaign Use Cases for Nonprofits.
If you have registered a Low-Volume Standard Brand in the steps above, it is recommended that you use Low-Volume Mixed use case for registering your Campaigns
5.2 Create A2P Campaign
When you create a Campaign, beyond specifying the use case and the Messaging Service to use, you will need to indicate how end users opt-in and give consent to receive messages from this Campaign; you will also need to provide details about how end users can opt-out and receive help, and provide some additional information. For the full set of parameters see the table below.
Top reasons for Campaign rejection, and how to avoid them:
- missing or unclear message flow (Call to Action) information: the Message Flow describes the process by which end users opt-in to receiving your Campaign's SMS messages. This process must be clearly described and verifiable. If users opt-in through a business website, either provide a direct url to the opt-in form or, if this is not publicly accessible, provide a url to a hosted screenshot of the relevant page (as well as pages showing privacy policies and other information specified below). The url must clearly align with the Brand name provided in the Business Profile in Step 1 above. If Opt-in is done via a paper form, provide a url to a hosted image of this form. If Opt-in is done verbally, provide a script for the solicitation of this opt-in.
- TCR cannot verify business website: in the Business Profile creation step, you are asked to provide a public url to the website of the Brand being registered. This url must be functional, it must match in some obvious way the Business Name provided, and the url provided in Step 5.2 below for opt-in (if applicable) and any links included in sample messages. If you are an ISV registering secondary customers, the website provided in this registration must be that of the secondary customer's brand, NOT the ISV as.a business entity.
- misalignment between Campaign description, use case, Message flow, sample messages, and/or Brand name: it must be clear and obvious why a particular set of sample messages serves the purposes of a particular Campaign, and why that Campaign serves the purposes of the Brand for which it is registered.
Please see A2P 10DLC Campaign Approval Best Practices to ensure your Campaigns meet all requirements.
If your A2P Brand registration has failed or is not yet approved, you will receive an error when making this API call. Please ensure that your brand registration status is APPROVED
before continuing with this step.
Most Twilio customers use Twilio's default or advanced opt-out features. If you use default or advanced opt-out, Twilio will automatically complete your Campaign's opt-out and help parameters with Twilio's default values or your customized advanced opt-out and help values.
Creating a Campaign involves a create
call to the us_app_to_person
endpoint of the Messaging API. There are a total of eight required parameters for this call, and six optional parameters, depending on how much you'd like to explicitly manage opt-in/opt-out mechanisms and help information. Below you will find two different example calls, with the second making more use of these optional parameters.
Parameter | Description |
messaging_service_sid |
The SID (begins with "MG") of the Messaging Service you either created or chose for reuse in step 4. |
brand_registration_sid |
The SID of the Brand you created in step 3 above. It will begin with "BN". |
description |
This should be a fairly detailed description of what purpose this campaign serves. The description should provide an explanation of who the sender is, who the recipient is, and why messages are being sent to the intended recipient. Min length: 40 characters. Max length: 4096 characters. This description must align with the use_case you specify below. and should be descriptive enough to pass manual reviews. Example: "This Campaign will send weekly marketing messages about sales and offers from Acme Sandwich Company to end customers who have opted in" NOTE: If you are a financial institution engaged in direct, first-party lending to your customers, please indicate "Direct Lending" in the Campaign description so that our review team can properly set this attribute before submitting the registration to TCR. Please indicate this even if your Campaign use case is not directly related to your offer of lending services (e.g. OTP). |
message_flow |
Required for all Campaigns. Details around how a consumer opts-in to their campaign, therefore giving consent to receive their messages. If multiple opt-in methods can be used for the same campaign, they must all be listed. 40 character minimum. 2048 character maximum.
If a website is used for opting in, provide a link to the website. The website needs to have a privacy policy and terms of service. Privacy policies also need to include a statement of non-sharing for mobile numbers, message frequency, and "message and data rates may apply" disclosure. You need to provide a link to the policy. If this opt-in mechanism and other required information is not publicly accessible at the business website url you have provided, please provide a url with hosted screenshots of the relevant pages. Understanding the opt-in mechanism is critical to the acceptance of the Campaign by TCR. Example: "End users opt-in by visiting www.acmesandwich.com and adding their phone number. They then check a box agreeing to receive text messages from Acme Sandwiches. Additionally, end users can also opt-in by texting START to (111) 222-3333 to opt in. Term and Conditions at www.acmesandwich.com/tc. Privacy Policy at www.acmesandwich.com/privacy" |
message_samples |
An array of sample message strings, min two and max five. Min length for each sample: 20 chars. Max length for each sample: 1024 chars. Give concrete examples of messages you would send in this Campaign. Sample messages must be clearly aligned with the Campaign description given above and use_case given below. In each message, be sure to identify your Brand by name and/or website. Also, indicate with brackets [] any content that will be conditionalized. Example: "This is a message from the Acme Sandwich Company. Your order for [sandwich type, other item] will be delivered by [time] on [date]. If you have questions or would like to change your order schedule, please call 333-444-1212. If you would like to opt out of future notifications like this, text STOP in reply to this message." |
us_app_to_person_usecase |
This must be a valid use case from the list provided to you in step 5.1, e.g. "MARKETING". Make sure your string exactly matches the one from step 5.1, and that it is also aligned with your Campaign description and sample messages above. |
has_embedded_links |
Boolean. Indicates that this SMS campaign will send messages that contain url links. Best practice would be to include such links in your sample messages, so that any such links can be verified. |
has_embedded_phone |
Boolean. Indicates that this SMS campaign will send messages that contain phone numbers. Again, best practice would be to include any such phone number in your sample messages, so that the number(s) can be verified. |
opt_in_message (optional) |
If end users can text in a keyword to start receiving messages from this campaign, the auto-reply messages sent to the end users must be provided here. The opt-in response should include the Brand name, confirmation of opt-in enrollment to a recurring message campaign, how to get help, and clear description of how to opt-out. This field is required IF end users can text in a keyword to start receiving messages from this campaign. 20 character minimum. 320 character maximum |
opt_out_message (optional) |
Upon receiving the opt-out keywords from the end users, Twilio customers are expected to send back an auto-generated response, which must provide acknowledgment of the opt-out request and confirmation that no further messages will be sent. It is also recommended that these opt-out messages include the brand name. This field is required IF you are managing opt out keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). 20 character minimum. 320 character maximum (this field is required if you are managing the opt-outs by yourself). |
help_message (optional) |
When customers receive the help keywords from their end users, Twilio customers are expected to send back an auto-generated response; this may include the brand name and additional support contact information. This field is required IF you are managing help keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). 20 character minimum. 320 character maximum (this field is required if you are managing the opt-outs by yourself). |
opt_in_keywords (optional) |
If end users can text in a keyword to start receiving messages from this campaign, those keywords must be provided, in a comma-delimited list if more than one. This field is required if end users can text in a keyword to start receiving messages from this campaign. 255 character maximum. |
opt_out_keywords (optional) |
End users should be able to text in a keyword to stop receiving messages from this campaign. Those keywords must be provided here, if you are managing opt out keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Values must be alphanumeric. 255 character maximum (this field is required if you are managing the opt-outs by yourself). |
help_keywords (optional) |
End users should be able to text in a keyword to receive help. Those keywords must be provided as part of the campaign registration request, IF you are managing help keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Values must be alphanumeric. 255 character maximum (this field is required if you are managing the opt-outs by yourself). |
Please note that the path
used in this Campaign creation call is the Messaging Service SID,
e.g. in Python, client.messaging.v1.services('MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
, prior to any of the actual input parameters. This is a reminder that Campaigns are built around a pre-existing Messaging Service, which is why you either created one or selected a pre-existing one in Step 4 above. Campaigns cannot be created except in association with a Messaging Service.
By the same token, once a Campaign has been created, deleting its associated Messaging Service (either via API call or via the Console) will necessarily mean deleting the Campaign itself. This would be especially undesirable, in most cases, once a Campaign has been VERIFIED (approved), as the Campaign approval process would need to be re-initiated from scratch.
Note finally that the Campaign itself can be deleted, if necessary, without deleting the Messaging Service; this is addressed in Section 5.4 below.
You can can create up to five Campaigns per Brand, unless a clear and valid business reason is provided for exceeding this limit.
The first code example below demonstrates how you could create a campaign if you are using Twilio's default or advanced opt-out. The opt-out and help parameters are not required, because Twilio will automatically complete those.
Twilio customers who do not use default or advanced opt-out will need to provide opt-out and help keywords and messages.
Customers managing their own opt-out will need to provide additional opt-out and help information when registering a Campaign, as demonstrated in this second sample call.
5.3 Check your Campaign registration status
NOTE: it is now possible to set up and subscribe to Campaign status Event Streams, so that an event message will be sent to a specified webhook url when the new Campaign has been approved or has been rejected. Please see this guide for setting up the necessary Event Streams sinks and event subscriptions, and for information on reading each event message payload. In the event of a Campaign rejection, you will then need to perform the fetch
call described below in order to learn details about the failure reason(s).
Just as you did when you submitted your new Brand for review in Step 3, after you've submitted your new Campaign you can check on the status of its approval process using a fetch
call to the same us_app_to_person
endpoint that you used to create the Campaign. This will be particularly useful for a Campaign with a use case that requires post-approval (i.e., an additional approval step by your mobile carrier).
This fetch call requires two parameters: the messaging_service_sid
(i.e., the SID of the Messaging Service you're using in this Campaign), and a hardcoded compliance type of QE2c6890da8086d771620e9b13fadeba0b
(see code sample below for how these are used in your code library of choice).
In this call's json response, the attribute campaign_id
is a seven-character string that will have been added to the new Campaign record by the Campaign Registry (TCR). But in this response, you would be looking in particular at the campaign_status
attribute. The possible statuses for campaigns will vary depending on what stage the Campaign is at in the review process. A newly-created Campaign that has yet to be considered by TCR will be PENDING, assuming that the Twilio API itself has accepted it (i.e., all the data is basically conforming); otherwise it will be FAILED. Once TCR has begun its own review process on a successfully-submitted Campaign, the Campaign will be IN_PROGRESS until that review has finished. At that point the campaign_status
will be either VERIFIED (approved) or FAILED (rejected). In certain rare case the status may instead be SUSPENDED; if your Campaign has a Suspended status please see this section of our Troubleshooting Guide.
If campaign_status
is FAILED, the response will contain an “errors” attribute with the information on why the registration failed (but please note that this is only the case for Campaigns submitted since May 31, when this feature was implemented; for previous Campaigns the errors[] attribute will be empty). The populated errors[] attribute is particularly helpful if the campaign registration failed during Twilio’s internal review or External campaign review by our partners.
If your Campaign is marked as FAILED, please see our Guide to Troubleshooting A2P Brands and Campaigns to understand Campaign error messages and how to rectify these
5.4 DELETE an A2P Campaign (Optional)
If you need to unregister or delete a campaign, you can make the following delete
request to the Messaging Service us_app_to_person
endpoint. Again, here you will specify the compliance type QE2c6890da8086d771620e9b13fadeba0b
in your request.
After your API request is accepted, please allow a few seconds for deletion to be finalized in our system.
As noted in section 4 above, one of the reasons you might want to delete an existing Campaign would be to reuse the Messaging Service associated with that Campaign for a new Campaign. If you are doing this programmatically, we recommend implementing a 5-second delay between removing the existing Campaign and creating a new one using the same Messaging Service, so that your Campaign creation does not fail.
6. Ensure that a Twilio 10DLC phone number is associated with your new Campaign
Once your Business Profile, Brand, and Campaign have been registered and verified, the final step before you can begin using the new Messaging Campaign is to ensure that the Twilio 10DLC phone number or numbers you use to send messages to the US are associated with the new Campaign’s Messaging Service as the Sender. To do this via the API:
- See this part of the PhoneNumber Resource guide for the API call to associate a given phone number (by
phone_number_sid
) with the new Messaging Service (bymessaging_service_sid
) you’ve created for the new A2P Campaign. - You can subsequently use a GET call on that same
phone_numbers
endpoint as in (2) above to confirm that the phone number is associated with this Messaging Service (see this part of the same PhoneNumberResource guide).
If you do not currently have any Twilio 10DLC phone numbers you’d like to use with the new Messaging Service, you can select and buy one either via the Twilio Console or via API – see this guide for details on both.
NOTE: Whether or not you choose to reuse existing Twilio phone numbers in the context of this particular Campaign registration, please be aware that any Twilio 10DLC numbers you currently have, and that you wish to continue using for SMS messaging within the U.S., must be registered as senders for A2P Messaging Services (ie officially associated with some officially registered A2P Campaign) as of the Summer of 2023.
Congratulations! 🎉 You now have a registered Standard or Low-Volume Standard Campaign!
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.