On this page

Using Proxy with Flex A2P SMS

(error)

Proxy Public Beta is not available to new customers

Proxy Public Beta is currently closed for new customers. Please consider using Twilio Conversations and Programmable Voice directly if you are building your masking application.

Note that this does not have any impact on Twilio Flex customers.

(warning)

Public Beta for customers already using Proxy

Twilio's Proxy API is currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.

Public Beta products are not covered by a Twilio SLA.

(information)

Info

This guide is for Flex UI 1.x and channels that use Programmable Chat and Proxy. If you are using Flex UI 2.x or you are starting out, we recommend that you build with Flex Conversations.

If your contact center is sending SMS traffic in the United States, you're likely sending Application-to-Person SMS. As your contact center goes into production and scales its outbound traffic, you might notice that carriers are filtering some of your messages as potential spam. When your contact center gets to this point—or if you plan to send a high volume of outbound messages—it means that you'll need to:

Register your SMS traffic with US carriers and
Configure your contact center's messaging orchestration to use that registration.

This helps show that your messaging traffic is relevant to your customers and prevents it from being filtered by the US carrier network.

(information)

Info

Carrier filtering is more of an art than a science. Work with your Twilio team to discuss your traffic and come up with a strategy for scaling your traffic. If you're just testing your contact center, however, you shouldn't have any issues. Feel free to return to this document when you're in production!

Key Concepts for A2P-10DLC in Flex

Phone Numbers/10DLC: A phone number in the US is also sometimes called a 10-digit long code (10DLC). If you plan to send traffic to your customers in the US, you'll need to register that Application-to-Person (A2P) traffic with the US Carriers.

Messaging Services: A messaging service is a software layer for Programmable SMS that contains a link to your A2P registration. It contains a pool of phone numbers that will all behave according to the messaging service's configuration.

Twilio Proxy: Twilio Proxy is another software product that your Flex Contact Center uses to orchestrate inbound messages and connect them to unique chat channels.

Register for an Application-to-Person use case

Your first step will be to register for an A2P use case. You can learn more about how to register and what you'll need for registration in the Direct Brand Onboarding documentation.

Associate your Phone Numbers with your A2P Registration

Typically, Flex messaging orchestration sends inbound messages directly to a software layer called Proxy, as described in the Flex Messaging overview. With A2P-10DLC, however, you first need to associate your phone numbers with your registration from the first step. You can do this using another handy piece of messaging software called a Messaging Service. The messaging service will associate your number with your A2P registration before sending traffic to your normal Flex messaging orchestration.

Create a Messaging Service via the Twilio Console

You'll need to navigate to the Messaging Services section of the Twilio Console to create a new messaging service. This will take you through four main steps:

In Step 1, choose a Friendly Name and use case that feels appropriate for you.
Add in any phone numbers that you want to use for messaging. This could be one phone number or many.

Set your integration to Defer to Sender Webhook - this means that your phone number will keep using Flex messaging orchestration configuration, instead of using any of the messaging service logic. This step is the most important!
Click Complete Messaging Service Setup to finish setting up your new Messaging Service.
Optionally try the Send an SMS with a Messaging Service option to confirm your newly created Messaging Service is working. For more guidance, see the Messaging Service docs.

Create a Messaging Service via API

You can also create and update a Messaging Service via the API. In this method, make sure that you have the useInboundWebhookOnNumber property set to True.

Set useInboundWebhookOnNumber to True

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateService() {
11  const service = await client.messaging.v1
12    .services("MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .update({ useInboundWebhookOnNumber: true });
14
15  console.log(service.sid);
16}
17
18updateService();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "friendly_name": "My Service!",
4  "sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "date_created": "2015-07-30T20:12:31Z",
6  "date_updated": "2015-07-30T20:12:33Z",
7  "sticky_sender": false,
8  "mms_converter": true,
9  "smart_encoding": false,
10  "fallback_to_long_code": true,
11  "scan_message_content": "inherit",
12  "synchronous_validation": true,
13  "area_code_geomatch": true,
14  "validity_period": 600,
15  "inbound_request_url": "https://www.example.com",
16  "inbound_method": "POST",
17  "fallback_url": null,
18  "fallback_method": "POST",
19  "status_callback": "https://www.example.com",
20  "usecase": "marketing",
21  "us_app_to_person_registered": false,
22  "use_inbound_webhook_on_number": true,
23  "sending_windows": [],
24  "links": {
25    "phone_numbers": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers",
26    "short_codes": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ShortCodes",
27    "alpha_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AlphaSenders",
28    "messages": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
29    "us_app_to_person": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p",
30    "us_app_to_person_usecases": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p/Usecases",
31    "channel_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelSenders"
32  },
33  "url": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
34}

Next Steps

Check out the A2P-10DLC support article for further information about A2P 10DLC, Application-to-Person messaging, and additional steps you may need to take to allow your SMS traffic in the US
Are you looking to register your customers' numbers for A2P traffic? Learn more about A2P 10DLC for ISVs
If you're looking to run Flex UI 2.x with Flex Conversations, please refer to the Conversations A2P Guide