Campaign Registration API Overview and Changes
Part of the process of registering for US A2P 10DLC capabilities requires creating a Messaging Campaign, which indicates your messaging use case (for example, sending account notifications or conducting marketing).
The Campaign Registry (TCR) is a central hub for A2P 10DLC messaging campaigns. Twilio provides you the ability to register your Messaging Campaigns with Twilio's APIs, which will then integrate with TCR directly to facilitate the registration process.
Starting November 17th, 2022, TCR is introducing changes to their Campaign registration APIs. They will start requiring additional fields to be submitted and enforcing length requirements on certain existing fields.
This document provides:
- A list of all the available parameters for creating a Campaign via the Twilio API
- A list of new parameters that have been added to fulfill the November 17, 2022 changed requirements
- A list of existing parameters that will have character limit changes starting on November 17, 2022
- Create Campaign API request examples
- Error cases and error codes that the Campaign API can return
You can learn more about Messaging Campaigns in this support article.
Create Campaign API Parameters
Below are the names and descriptions of all the parameters you can pass when creating a Campaign via Twilio's API. Note that fields that are required for all customers are indicated below.
For the new fields that have been added for the November 17 API changes, requirements will vary based on how customers can opt out of your messaging services. See the new parameters section for more information.
The new parameters added for the November 17th TCR requirements are available in the newest versions of the Twilio Helper Libraries.
Note that if you start passing in the new parameters prior to the November 17, 2022, Twilio's API will ignore them. Starting November 17, Twilio will begin accepting the new parameters and enforcing the new TCR requirements.
| Parameters in REST API format | |
|---|---|
messaging_service_sid
Path
|
The SID of the Messaging Service to create the resources from. |
brand_registration_sid
Required
|
A2P Brand Registration SID |
description
Required
|
A short description of what this SMS campaign does. Min length: 40 characters. Max length: 4096 characters. |
message_flow
Required
|
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. |
message_samples
Required
|
Message samples, at least 1 and up to 5 sample messages (at least 2 for sole proprietor), >=20 chars, <=1024 chars each. |
us_app_to_person_usecase
Required
|
A2P Campaign Use Case. Examples: [ 2FA, EMERGENCY, MARKETING..] |
has_embedded_links
Required
|
Indicates that this SMS campaign will send messages that contain links. |
has_embedded_phone
Required
|
Indicates that this SMS campaign will send messages that contain phone numbers. |
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. 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 managing opt out keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). 20 character minimum. 320 character maximum. |
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 managing help keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). 20 character minimum. 320 character maximum. |
opt_in_keywords
Optional
|
If end users can text in a keyword to start receiving messages from this campaign, those keywords must be provided. This field is required if end users can text in a keyword to start receiving messages from this campaign. Values must be alphanumeric. 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. This field is required if managing opt out keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Values must be alphanumeric. 255 character maximum. |
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. This field is required if managing help keywords yourself (i.e. not using Twilio's Default or Advanced Opt Out features). Values must be alphanumeric. 255 character maximum. |
New parameters added to the Campaigns API
These new parameters will be ignored by the API until the TCR Campaign requirements go into effect on November 17, 2022. You can include them in your API requests before November 17, but they will not have an impact on your Campaigns.
The following table describes the new parameters added to the Campaign API in November 2022. Note that there are different requirements for including certain parameters in the API request depending on how you manage opt-out and help keywords for your messaging services.
The majority of Twilio customers use Twilio’s default opt-out features or Advanced Opt-out to manage their opt-out and help keywords and messages and therefore do not need to include opt-out and help message information when creating a Campaign.
If you are managing your own opt-out and help keywords, you should consider switching to Twilio’s opt-out features to simplify your A2P 10DLC campaign registration process and standardize how you comply with global compliance requirements. If you choose not to make this switch, you will be required to include your opt-out and help values.
You can verify your Messaging Service's opt-out settings in the Twilio Console:
- Navigate to Messaging Services in the Twilio Console
- Click on the desired Messaging Service
- Click the Opt-Out Management tab in the left-hand side bar
For additional details and best practice examples around these attributes, please reference the CTIA guidelines. For additional FAQ, please reference the Twilio Support article on Changes to the A2P 10DLC Campaign Creation Process.
| Field | Required for customers using Twilio's Default or Advanced Opt-out? | Required for customers managing help and opt-out themselves? | Best Practice Example |
|---|---|---|---|
| MessageFlow | Yes | Yes | 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. |
| OptInKeywords | Only required if end users can text in a keyword to start receiving messages from this campaign. | Only required if end users can text in a keyword to start receiving messages from this campaign | Start |
| OptInMessage | Only required if end users can text in a keyword to start receiving messages from this campaign | Only required if end users can text in a keyword to start receiving messages from this campaign | Acme Corporation: You are now opted-in. For help, reply HELP. To opt-out, reply STOP |
| OptOutKeywords | No | Yes | Stop |
| OptOutMessage | No | Yes | You have successfully been unsubscribed from Acme Corporation. You will not receive any more messages from this number. |
| HelpKeywords | No | Yes | Help |
| HelpMessage | No | Yes | Acme Corporation: Please visit www.example.com to get support. To opt-out, reply STOP. |
If you are using Twilio's default or advanced opt-out features, the API will ignore any values you pass for the OptOut and Help parameters. Twilio will use the default opt out and help values (if using the default) or custom values you've enabled for your Messaging Service (if using advanced opt-out).
Changes to existing parameters
The following fields were already required prior to these November 17 changes. However, they have updated requirements:
- Description: The new minimum length is 40 characters. The maximum length is 4096 characters.
- MessageSamples: The new minimum length is 20 characters. The maximum length is 1024 characters. Additionally, only one sample is required, except for sole properietor, mixed, and marketing use cases, which require at least two samples.
Create Campaign API Examples
Example 1: All the parameters are present and length validation passes
This example demonstrates how you could pass all parameters to create a Campaign. Passing all of these parameters is required for customers managing their own opt-out and help.
If you are using Twilio's default or advanced opt-out, you should not include the Opt-Out and Help parameters to your request. If you do include them, the API will overwrite those passed-in values with either Twilio's default opt-out/help messages, or with your customized opt-out/help messages (for advanced opt-out users).
If you are using default opt-out and pass OptOut or Help parameters in the Create Campaign request, those fields will be overwritten with Twilio's default opt-out and help text.
If you are using advanced opt-out and pass OptOut or Help parameters in the Create Campaign request, those fields will be overwritten wtih the custom reply messages and keywords you have configured for your Messaging Service.
Example 2: Omit OptOut/Help parameters and use default values
This example demonstrates how you could omit OptOut and help parameters to create a Campaign. This is only available for customers using default or advanced opt-out. If you are managing opt-out yourself, you must submit these parameters, as in Example 1 above.
In this example, the API request is from the perspective of a default opt-out customer. Note that in the example response, the API has included Twilio's default opt-out and help messaging and keywords when creating the campaign.
Error cases and error codes
The Campaigns API can return a 400 response containing the following error codes if your API request is not correct:
- 21727: Missing required parameter(s)
- This only applies when at least one of the new fields is missing
- If the only fields missing are the fields that already existed prior to the November 17, 2022 changes, the request will be rejected synchronously with a status code 400, but no error code will be returned. In the future, Twilio may consolidate these campaign registration error cases due to missing fields into the 21727 error code.
- 21728: Length requirement not satisfied
If your API request fails with either of these error codes, your Campaign will not be created. You will need to fix the error and resubmit the request.
Get help with A2P 10DLC
Need help building or registering your A2P 10DLC application? Learn more about Twilio Professional Services for A2P 10DLC.
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.
