Menu

Expand
Rate this page:

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:

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
post sid<MG> Not PII

The SID of the Messaging Service to create the resources from.

brand_registration_sid
Required
post sid<BN> Not PII

A2P Brand Registration SID

description
Required
post string Not PII

A short description of what this SMS campaign does.

message_samples
Required
post string[] Not PII

Message samples, at least 2 and up to 5 sample messages, <=1024 chars each.

us_app_to_person_usecase
Required
post string Not PII

A2P Campaign Use Case. Examples: [ 2FA, EMERGENCY, MARKETING..]

has_embedded_links
Required
post boolean Not PII

Indicates that this SMS campaign will send messages that contain links.

has_embedded_phone
Required
post boolean Not PII

Indicates that this SMS campaign will send messages that contain phone numbers.

message_flow
Optional
post string Not PII

Description of how end users opt-in to the SMS campaign, therefore giving consent to receive messages.

opt_in_message
Optional
post string Not PII

The message that will be sent to the user when they opt in to the SMS campaign.

opt_out_message
Optional
post string Not PII

The message that will be sent to the user when they opt out of the SMS campaign.

help_message
Optional
post string Not PII

The message that will be sent to the user when they request help for the SMS campaign.

opt_in_keywords
Optional
post string[] Not PII

The keywords that will be used to opt in to the SMS campaign.

opt_out_keywords
Optional
post string[] Not PII

The keywords that will be used to opt out of the SMS campaign.

help_keywords
Optional
post string[] Not PII

The keywords that will be used to request help for the SMS campaign.

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:

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.

              Rate this page:

              Need some help?

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

                    
                    
                    

                    Thank you for your feedback!

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

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

                    Thanks for your feedback!

                    Refer us and get $10 in 3 simple steps!

                    Step 1

                    Get link

                    Get a free personal referral link here

                    Step 2

                    Give $10

                    Your user signs up and upgrade using link

                    Step 3

                    Get $10

                    1,250 free SMSes
                    OR 1,000 free voice mins
                    OR 12,000 chats
                    OR more