Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-register-for-a-united-states-us-sms-short-code-with-aws-end-user-messaging/

Obtaining and using SMS short codes in the United States requires a thorough understanding of the detailed application process and strict requirements set forth by mobile carriers. This comprehensive guide walks through the step-by-step procedure for registering a US SMS short code from AWS End User Messaging, which provides SMS capabilities to all AWS services.

This guide covers the process from initial creation of a support case, the short code application form with all necessary details and documentation, and the multi-stage provisioning process involving carrier review and approvals. Particular emphasis is placed on establishing compliant opt-in workflows, crafting SMS-specific terms and privacy policies, and preparing the required message templates – all of which are closely scrutinized by the carriers.

While the application process may be time-consuming, the benefits of using a short code, include:

• High throughput – They start out at 100 messages per second
• Ability to scale to thousands of messages per second
• Higher deliverability rates – Because of the increased upfront scrutiny in the registration process they have less issues with filtering and blocking. Critical use cases such as One-Time Password(OTP)/Two-Factor Authentication(2FA) are use cases that, even if you don’t need the high throughput, you may want to consider using a US short code to deliver them in the US
  • Short codes investigate issues before blocking through proactive audits, while other registered originator types such as toll-free or 10DLC block/filter first and investigate later when issues arise
• Easy for customers to remember and identify – Short codes are 5-6 digit numbers, which is easier for recipients to remember than 10+ and lends credibility and trust to your message

The US Short Code Application Process

Step 1: Create a Case in AWS Support Center

Currently short codes are only available by opening a case. The first step to register a short code is to open a short code request case in the AWS Support Center, providing detailed information about your use case and opt-in policies. A request must be opened for each country in which you want a short code. Each country has their own registration process and requirements so if you are registering for other countries besides the US having a case for each allows for much easier tracking and updating as there are communications going back and forth between you, the customer, support, and any downstream clarifications that may come back.

NOTE: If you require a HIPAA eligible Short Code for your use case please respond to the case with explicit confirmation that you require a HIPAA eligible Short Code. We will provide you a unique form for this use case

Along with attaching the correct form Support will request that you confirm that you understand the pricing, billing, and time frame of this request so make sure that you respond to the case, don’t just start on the application.

Step 2: Complete the Short Code Application

We will walk through the US Short Code application in detail below. Make sure that everything you submit is 100% correct to your knowledge, as any missing information or information that needs to be corrected extends the time it takes to receive your short code.

NOTE: Application forms are occasionally revised to clarify or add to existing information. By the time you read this post, the form that you receive might differ slightly from the form that we review in this post.

The first section of the US Short Code form contains basic information about your company.

Company Information

Most of the fields in the first section are straightforward but the key thing to make sure you have a good understanding of is, who owns the relationship with the recipients? The company that owns the opt-in data and controls the message(not just the delivery) is the company that needs to have their information submitted.

IMPORTANT: If you are a SaaS/mutli-tenant/service provider, providing SMS capabilities to YOUR customers or a business within a larger portfolio make sure that you are clear on that. It does not matter WHERE the opt-in is happening, it matters who owns the data and the clear relationship between that entity and the recipient. The company that owns that relationship is the company who’s information needs to be used.

There are a few fields in this section that people ask how they will be used:

Primary Contact name, email address, phone number

These contact details will be used during the Company vetting/validation step we will discuss later in this post. It would also be used to contact you if there is ever an audit of your short code.

Customer Care Information

The customer care contact points are required to be actively monitored.

Customer Care URL

The URL of a page where your customers can go to find information about contacting your Customer Support team.

Customer Care Email

The Carriers require you to provide an email address that customers can contact if they have questions about your short code messaging program. This address should be a shared mailbox or distribution list (such as [email protected]) rather than an individual person’s email address and must match the domain of the Company URL in the Company Information section above.

Customer Care Phone Number

Like the support email address, customers should be able to call this phone number to get support for your short code messaging program. The phone number doesn’t have to be a toll-free number, but it does have to be a US-based phone number.

Short Code Service Information

AWS Region

The AWS Region that you use AWS End User Messaging in. If you’re not sure, check with the person or team within your organization that is responsible for managing your AWS accounts.

IMPORTANT: Short codes can only be used in the region that they are requested in and cannot be moved. Short codes can be shared to other accounts via Resource Access Management but they must be in the same region. All resource billing, such as the shortcode monthly leasing fee, will still run through the managing account but the cost for SMS volume will be charged to the sending account.

Short Code Option

In the US you have the option of either a 5-6 digit random code or a “vanity” code that you can specify. These vanity codes are numeric only, take longer to procure, and come with a higher cost. You can check if your preferred vanity code is available at: https://www.usshortcodes.com/find-short-code

Short Code Use Case

Mobile Carriers need to know how you plan to use your short code, and how you will interact with users. It is very important to be clear and concise in this section. Humans are reviewing these so make sure that everything you write can be understood without any prior knowledge of your company or your use case.

Company Overview

Provide a short description of the products/services that your Company provides to its customers. This should concisely answer the question, “Who are you and what do you do?”

Service Name

A name or phrase that identifies your messages as being from you. Service names typically are a recognizable form of your company or brand name. It can be a shortened version as long as it is something that your recipients would recognize as coming from you.

• For example, if Example Corp. wants a short code for sending account-related notifications, they could use a service name like “Example Corp.” The Carriers require you to put this service name at the beginning of each message. Keep in mind that SMS has a limit of 160 characters so you do want to keep this short.
• A message might look like this:
  “Example Corp. – This is an account notification for your account #[XXXXXX].”

Message Type(s)

You can choose more than one message type but keep in mind that for each message type that you select you will need to provide examples of those types of messages later in the form and you also need to collect consent for each one. We recommend to not mix promotional and transactional type messages on a single code but at the time of publication this is acceptable by the carriers.

Message Examples

You need to provide at least ONE message example for each of the message types you chose above. Carriers will review these examples during the approval process. These are only examples and will not be the only messages you will be able to send but they should represent all of the types of messages that you plan on sending. If you need more room it is fine to add more examples. Remember you do NOT need to include every message you plan on sending, as long as you have a representative sample of all message types.

• Requirements:
  • Include your service name in every message sample
  • Ideally each message is 160 characters or less to reduce your costs. Any message over 160 characters is broken into message parts in 160 character chunks and each message part is charged. 161 characters would be two message parts
    • If your message uses only characters in the GSM 03.38 character set, also known as the GSM 7-bit alphabet, it can contain up to 160 characters. If your message contains any characters that are outside the GSM 03.38 character set, it can have up to 70 characters. When you send an SMS message, AWS End User Messaging SMS automatically determines the most efficient encoding to use. We provide a tool in the AWS console to check your messages.
    • If your messages will include variables, it’s fine to use either placeholder values or variables.
      • For example, both of the following are acceptable: “Hello John. Your one-time password is 654321” and “Hello [first_name]. Your one-time password is [otp code] .”
    • Do not use unbranded link shorteners i.e., “bit.ly/yourlink”
      • If you have to use a shortener make sure that it is branded and that there are not multiple redirects. Also make sure to provide examples of the branded shortened domain so that it is on file with the carriers
  • Include an example of all of the message types you are registering for
  • If you plan on sending in languages other than English, include those versions
  • Read them all and make sure that they are clearly a part of the message type/use case that you are registering for
• If you plan on sending Multimedia Messages(MMS) make sure you include at least one example

Multimedia message sample (MMS)

MMS capabilities must be requested at the time the short code is requested. If you intend to send MMS messages make sure you check the box and include a message example in the section above

Will you use your short code for any of the following?

Selecting “Sweepstakes or contest” or “Debt Collection” will require more documentation. For example, official sweepstakes rules and terms would be requested if that was your use case. If neither of these apply then select “N/A”

NOTE: Debt collection in particular is highly regulated. If you are a 3rd party debt collector you will not be able to get a short code.

Per-user message frequency

This is an estimate but will be used later in some of the message templates so be sure to have this correct. Will you be sending out 1 message per day? Week? Month? Programs like Two Factor Authentication(2FA) or One-Time Password (OTP) are examples of “message frequency varies” or “1 message per login”.

Carrier requirements for user sign-ups

The core requirement for communicating with SMS is explicit consent – end users must have the option to consent to receive your messages, know exactly what the program will include, and are able to opt-out or ask for help at any time. There are no exceptions to this regardless of the use case or your business type. As a reminder, Carriers make their own rules which will override things like FCC exemptions.
The Carriers pay extra attention to the information provided in the following section, so be thorough and follow the guidelines provided. An in-depth review of how to build a compliant SMS opt-in process can be found here.

How the User will opt-in

There are lots of compliant ways to capture an opt-in. Choose the option that applies to your use case. It’s fine to choose more than one option. However, you must provide mockups of the opt-in workflows for all of the options that you select. Be prepared to provide a verbal script for any opt-in processes where the user does not have the written call-to-action and SMS disclosures in front of them to read. Examples include:

• Sending a keyword to your short code
• Website or mobile app
• Over the phone/In-Person
• Paper forms
• Other – Which you will need to explain in detail. As long as you can be compliant, it should be accepted

User Experience Flow

This is one of the most comprehensive parts of the form and where many customers tend to receive a lot of feedback because there are several things that MUST be included in this section and there are no exceptions. Below you will find a list of the required components and descriptions of each. Keep in mind that these can be written or verbal opt-ins but this does not change the below requirements. Keep this concise, only detailing the opt-in process and nothing else.

• The Opt-in location must include the following:
  • Program (brand) name
  • A call-to-action phrase like “To receive SMS account notifications from [SERVICE NAME], enter your mobile number below”
  • You must expressly collect consent for each use case(s) that you detailed above. A single checkbox for all use cases will not be approved.
    • For example, If you are sending account notifications and OTP you must have two separate statements such as:
      • “To receive SMS One Time Password notifications from [SERVICE NAME], check this box and enter your mobile number below.”
      • “To receive SMS account notifications from [SERVICE NAME], check this box and enter your mobile number below.”
  • The opt-in must be “explicit” this means that any checkboxes, radio buttons, etc. must be left unchecked or at least not defaulted to SMS if you have options. If it is a verbal script then there must be a verbal consent given and you should track the date of that consent. If it is written then the recipient must sign and date the consent.
  • You must supply a secondary channel such as email. SMS must be optional and another option must be provided. This is mandated by Verizon in the US.
  • Link to a publicly accessible Terms & Conditions page
    • We will detail what needs to be included later in this guide
  • Link to a publicly accessible Privacy Policy page
    • We will detail what needs to be included later in this guide
  • Message frequency disclosure
    • Same as stated earlier in this application
  • Customer care contact information
    • Email address, phone number, Text “Help”, are all valid
  • Opt-out information
    • You must support the “Stop” keyword along with this list of keywords that can be found here
  • “Message and data rates may apply” disclosure.
    • This must be verbatim

This must be explained for each process that you checked in the “How the user will opt-in” section. If you are using a keyword and also have the ability to opt-in from your website or mobile app for example, then both of those processes need to be documented here.

If you are using a paper form or a verbal opt-in all of the required components must still be present. If verbal, components such as the Privacy Policy location must be read back to the person opting in. If written, then the full URL needs to be present. Regardless of your process you must include all of the components for you to be approved.

Opt-In Mockup

This is where you can supply screenshots if the opt-in location is online. You can also provide the verbal script or written opt-in form here as well. Make sure that the Opt-in mockup exactly matches the above requirements and that you explain the process.

Example of an online form

Terms and Conditions URL

This is the URL where your SMS-specific Terms and Conditions document resides, or where it will reside. You can also include a link to your standard Terms and Conditions page, as long as it includes a section dedicated to SMS messaging. If those terms and conditions aren’t live yet, or are not available online, you must include a copy of the Terms and Conditions along with your completed application. There are boilerplate items that MUST be included here with no exceptions, see here for more detail and below for those items:

1. {Program name}
2. {Insert program description here; this is simply a brief description of the kinds of messages users can expect to receive when they opt-in.}
3. You can cancel the SMS service at any time. Just text “STOP” to the short code. After you send the SMS message “STOP” to us, we will send you an SMS message to confirm that you have been unsubscribed. After this, you will no longer receive SMS messages from us. If you want to join again, just sign up as you did the first time and we will start sending SMS messages to you again.
4. If you are experiencing issues with the messaging program you can reply with the keyword HELP for more assistance, or you can get help directly at {support email address or toll-free number}.
5. Carriers are not liable for delayed or undelivered messages
6. As always, message and data rates may apply for any messages sent to you from us and to us from you. You will receive {message frequency}. If you have any questions about your text plan or data plan, it is best to contact your wireless provider.
7. If you have any questions regarding privacy, please read our privacy policy: {link to privacy policy}

Privacy Policy URL

Message Senders are responsible for protecting the privacy of Consumers’ information and must comply with applicable privacy law. Message Senders should maintain a privacy policy for all programs and make it accessible from the initial call-to-action. The privacy policy should be labeled clearly and privacy policy disclosures must provide up-to-date, accurate information about program details and functionality. For verbal scripts, a URL must be read off to the end-user enrolling in the SMS program, or the comprehensive terms or link to those terms must be directly included in the script.

• One of the key items Carriers look for in a Privacy Policy is the sharing of end-user information with third-parties. If your privacy policy mentions data sharing or selling to non-affiliated third parties, there is a concern that customer data will be shared with third parties for marketing purposes and your registration could be rejected at worst or delayed while you explain or update your Privacy Policy.
• Express consent is required for SMS; therefore, sharing data is prohibited. Privacy policies must specify that this data sharing excludes SMS opt-in data and consent. Privacy policies can be updated (or draft versions provided) where the practice of sharing personal data to third parties is expressly omitted from the number registration. You can include an SMS specific section within your privacy policy if your company or business model requires data sharing. This part is non-negotiable and Carriers are incredibly strict about this requirement
  • Example: “The above excludes text messaging originator opt-in data and consent; this information will not be shared with any third parties.”

Confirmation SMS / Double Opt-In

A confirmation message is the message sent when someone opts into your program. It is required you send your customers an opt-in confirmation message. It is optional, but a best practice, to include a “Double Opt-In,” such as the example below, asking the recipient to text back a confirmation to prove “humanness” and also validates your end user provided you with their correct phone number

There is one exception to the above if your use case is an OTP/2FA. In this one instance, the OTP code that you send to your recipients is considered a confirmation. You MUST however, still opt them in initially, adhering to all of the prior requirements we have detailed in the above sections.

This message must include the following in 160 characters or less:

• The service name that you specified earlier in the application
• The phrase “message and data rates may apply”
• Information about how often recipients will receive messages from you (such as “up to 30 messages per month” or “message frequency varies”)
• Information about getting help (typically, something similar to “Text HELP for more info”)
• Information about opting out (typically, something similar to “Text STOP to opt out”).

Example Message:

• “Welcome to AnyCo! Reply “YES” to confirm your subscription and get special offers once a month. Msg & data rates may apply. Text ‘STOP’ to opt out.”
  • It is best practice, but not required, to do a “double opt-in” as seen in the example where the recipient will text back “YES” to confirm that they did want to register.

HELP Response

The “Help message” is the response that is required to be sent to end-users when they text the keyword “HELP” (or similar keywords). The purpose is to provide information to the end-user related to how they can get support or opt-out of the messaging program.

• The message must include:
  • Program (brand) name OR product description
  • A method of contacting your support organization. Email addresses, websites, and phone numbers are all acceptable methods of communication. We recommend that you include two contact methods in your response (such as a phone number and a website).
• The following is an example of a HELP response that complies with the requirements of the US mobile carriers:
  • ExampleCorp Account Alerts: For help call 1-888-555-0142 or go to example.com. Msg&data rates may apply. Text STOP to cancel.

STOP Response

The “Stop message” is the response that is required to be sent to end-users when they text the keyword “STOP” (or similar keywords). End-users are required to be opted out of further messages when they text the STOP (or equivalent) keyword to your number and confirms with them that they will no longer receive messages for the program.

• The message must include:
  • Program (brand) name OR product description
  • Confirmation that no further messages will be delivered
• The following is an example of a compliant STOP response:
  • You are unsubscribed from ExampleCorp Account Alerts. No more messages will be sent. Reply HELP for help or call 1-888-555-0142.

Step 3: Submit the Application and Supporting Documents

Attach your completed application to your AWS Support case. Make sure to monitor this case daily as there can be clarifications that are needed or additional information and any delay can cause substantial delays in receiving your short code.

NOTE: Billing for short codes starts at the time the application is submitted to be reviewed, which is before the short code is registered for use. We will let you know when that review period begins.

Step 4: Documentation Pre-Review

Your documentation will be reviewed prior to submitting it to the Carriers. This does not guarantee that there will be no questions/revisions but it does make step 6 more efficient as there should be less potential questions from the Carriers. Once your documentation is considered compliant your company will be submitted for vetting.

Step 5: Vetting

This is similar to a credit check process where your data will be validated by a third-party and you will need to prove you are a member of your company through a domain validation email.

Example email for vetting

Step 6: Resolve Follow-up Issues

Respond promptly to any questions or concerns raised during the review process. Make sure to monitor this case daily as there can be clarifications that are needed or additional information and any delay can cause substantial delays in receiving your short code.

The Provisioning Process – Post Approval

After approval, Carriers begin setting up your short code on their networks. This process typically takes 6+ weeks to complete across all US carrier networks. This is a part of the overall timeline given.
Expected sequence of events for Carrier Review

1. The Carriers will review your application. We’ll answer any questions/corrections requested by the aggregator or the Carriers for your application. You may need to provide additional information.
2. The Carriers will connect the short code to their network for testing. Each carrier will approve your application and provision on their network.
3. We will send you a confirmation that your short code is ready and activated in the End User Messaging service once all Carriers finish their approval and provisioning process. This process is only as fast as the slowest carrier approval.

What happens if I don’t complete these steps or if I need to change something?

Customers sometimes ask what would happen if they didn’t implement all of the requirements that are discussed in the preceding sections. If your application for a new short code doesn’t meet these requirements, the answer is simple: the Carriers will reject your request for a short code. These carrier-imposed requirements are not optional.

If you submit an application that meets all of the carrier requirements and you are approved but your real-world production use case doesn’t meet those requirements, there could also be consequences. The Carriers periodically perform audits of short codes to ensure that they are being used in a compliant manner. You can review the process here in the CTIA Short Code Monitoring Handbook If they find that your opt-in process differs greatly from what you showed in your short code application, or your use case is different than what you registered for they could pause your short code’s ability to send messages on their networks. Remember, one advantage of using a short code compared to other originator types is that, because of the increased scrutiny for being approved, when this happens, the Carriers typically provide some time to remedy the issue, rather than just block your messages without warning.

We will alert you if there is an audit of your short code and advise you on what changes/additions need to be made in order to remain within compliance and continue sending via your short code.

What do I do if I need to make edits to my registration after it is approved?

It’s OK to make minor edits such as correcting typos, clarifying text, or using a variation of a message template that was already approved after you receive your short code. Remember it is critical that you do not deviate from the use case that you registered for, short codes are periodically audited, and deviating from the use case in your application could lead to your short code being suspended if you do not respond and comply with the requests. When in doubt, open a case and request that support reviews your change, prior to making it, to determine whether you can launch the new template/process without risking an audit.

If you need to make substantial changes to these templates after you receive the short code, you may need to submit your updated message templates to the carriers. Substantial changes could include the following:

• Changes to the brand name that appears on your messages (for example, if your company rebrands under a new name, or is acquired by another company).
• Changes to the use case (for example, if your application specified a one-time password use case, but you start sending account notifications through the same short code). This type of change might require you to re-collect consent from your customers before you start sending the new type of messages.

In these situations, you should open a case with AWS Support. We will work with the Carriers to have your short code registration information updated or depending on the change, you may need to register for another short code.

Conclusion

Obtaining and utilizing SMS short codes in the United States is a complex and highly regulated process that requires meticulous attention to detail. However, the benefits that short codes offer – such as high throughput, enhanced deliverability, and strong brand recognition – make them a valuable communication tool for businesses that need to engage customers at scale through SMS.

The key to successfully navigating the short code application and provisioning journey lies in proactively planning and preparing. By thoroughly understanding the carrier requirements upfront, companies can avoid common pitfalls and delays that often plague short code implementations. This includes thoughtfully designing compliant opt-in workflows, crafting robust terms of service and privacy policies, and developing a comprehensive set of message templates that align with approved use cases.

While the investment of time and resources may seem daunting, the long-term advantages of leveraging a short code make it a worthwhile endeavor. Short codes instill a sense of trust and familiarity with customers, allowing businesses to stand out in a crowded messaging landscape. Moreover, the rigorous vetting process ensures that only legitimate players gain access to this high-value communication channel, protecting consumers from spam and fostering a healthy ecosystem.

Ultimately, the decision to pursue a short code should be made with a clear understanding of the commitment required. However, by leveraging the guidance and best practices outlined in this comprehensive guide, companies can navigate the complexities with confidence and position themselves for success in delivering impactful, high-performing SMS campaigns that drive meaningful engagement and business outcomes.

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/a-guide-to-optimizing-sms-delivery-and-best-practices/

If you’re sending critical SMS messages to your users including one-time passwords (OTP), appointment reminders, urgent alerts, and marketing messages, you know how important reliable delivery is. SMS has become the backbone of modern business communications, and for good reason. Its ubiquitous nature and high engagement rates make it the go-to channel for reaching users globally.

But here’s the thing. As your messaging volumes grow and you rely more heavily on SMS for critical communications, you might notice that not every message gets delivered exactly as planned. And that’s normal across the entire telecommunications industry. In fact, expecting 100% delivery rates for SMS messages is like expecting every flight to arrive exactly on time. It’s simply not realistic given the inherent complexity of global telecommunications networks and systems. This isn’t unique to any particular messaging provider. It’s the nature of SMS delivery itself. Don’t worry, you’re not alone. Let’s dive into why this happens and show you how to build a rock-solid messaging strategy that works for your business.

In this post, we’ll explore what really happens when you send an SMS, share practical monitoring techniques that go beyond basic delivery receipts, and show you how to build redundancy into your messaging architecture. By the end, you’ll have the knowledge and tools to optimize your messaging operations using AWS End User Messaging.

Understanding SMS Delivery Complexities

Have you ever wondered what happens when you hit send on that crucial OTP message or important customer alert? The journey your message takes is more complex than you might think. Let’s break it down.

Your message begins its journey through a network ecosystem that involves multiple carriers, systems, and devices before reaching your end user. While this might sound daunting, AWS End User Messaging works continuously to optimize and simplify these delivery paths and maintain strong relationships within the messaging ecosystem.
So what makes SMS delivery so complex? Think of it like air travel – even with the best airlines and optimal conditions, various factors can affect whether a flight arrives exactly on time. The same is true for SMS messages.

Network infrastructure plays a crucial role. Just as flights navigate through different airspaces, your messages traverse carrier networks to reach their destination. AWS End User Messaging actively participates with SMS providers, carriers, and regulators to ensure up-to-date compliance and optimal delivery performance. However, just like air traffic control might need to redirect flights, message routing isn’t always straightforward. Network congestion, carrier maintenance (both scheduled and unplanned), country regulatory changes, and handset network availability, can occasionally affect message routing.

Carriers add another layer of complexity. Each carrier has its own set of rules and policies – think of them as different airports with their own specific regulations. They implement various filtering and anti-spam policies, handle message queuing differently, and may occasionally block messages without proactive notice if they detect suspicious patterns or unusual volumes. This is actually a good thing – it helps protect users from fraud, even though it can sometimes affect legitimate messages.

Then there’s the final destination – the end user’s device. Even if your message successfully navigates the network and carrier challenges, the recipient’s phone might be turned off, in an area with poor coverage, or simply out of storage space. It’s similar to a passenger missing their flight because their vehicle broke down on the way to the airport. Like the passenger, SMS connections may be lost due to local transportation issues at their destination.

This is why focusing solely on delivery reports doesn’t tell the whole story. For instance, you might receive a successful delivery receipt from a carrier, but the end user’s phone could be in airplane mode. Or conversely, a message might show as undelivered in carrier reports, but the user actually received it after a slight delay.

Understanding these complexities helps explain why achieving 100% delivery rates isn’t realistic. Instead of pursuing perfect delivery rates, successful messaging strategies focus on multiple factors:

• Building comprehensive monitoring systems,
• Following messaging content best practices (such as using Global System for Mobile Communications (GSM) characters,
• Maintaining appropriate message lengths,
• Following URL best practices
• Ensuring compliance with carrier requirements
• Providing alternative delivery channels.

Next we will dive deeper into some of these and explore how to set up effective monitoring practices that give you real insight into your message delivery success.

The Reality of Delivery Rates

Let’s address something important: if you’re expecting 100% delivery rates for your SMS messages, you’ll need to adjust those expectations, as this is not the reality of the industry. This is true regardless of which messaging provider you use – it’s simply the nature of how SMS works within global telecommunications networks. Even in optimal conditions, various factors can affect delivery:

• Network conditions in different countries
• Carrier policies and filtering systems
• End-user device states
• Local regulations and requirements
• Natural or infrastructure disruptions (for example: cable cuts, wildfires, tsunamis, or other environmental events)

Think of it like this: even the world’s most reliable airline can’t guarantee every flight will arrive exactly on time. Weather patterns change. Airports face congestion. Maintenance needs arise unexpectedly. SMS delivery navigates similar real-world challenges.

What matters is understanding what “good” looks like for your specific use case. Just as an 85% on-time arrival rate might be excellent for flights in winter conditions but below average in clear weather, a 95% SMS delivery rate might be excellent in one country but below average in another. This is why establishing baseline metrics for different regions and message types is so crucial.

Strategies for Reliable Delivery

Now that we understand why 100% delivery isn’t realistic, let’s talk about strategies to maximize your success rates.

The Art of the Retry

When a message doesn’t get through, having a retry strategy is crucial. But it’s not as simple as “try, try again.” You need to be thoughtful about:

• How long to wait between attempts
• How many times to retry
• When to switch to a different channel
• The cost implications of your retry strategy

Think of it like following up on an important email – you wouldn’t send the same email every 5 minutes, but you might try different approaches over time.

Important Anti-Abuse Note: Always implement reasonable limits on your retry features. This prevents both intentional and unintentional abuse of the system, ensuring fair usage and maintaining the integrity of the service for all users.

This retry strategy forms just one part of a comprehensive approach to reliable message delivery. Later in this post, we’ll explore how to build additional resilience through multi-channel messaging strategies that give you multiple paths to reach your users.

Establishing Effective Monitoring Practices

Let’s talk about what really matters: knowing if your messages are actually reaching your users. Sure, carrier delivery receipts are useful, but they’re just one piece of the puzzle. Just as airlines don’t rely solely on flight trackers to measure success, you need a more comprehensive view of your messaging performance.

So how do you get the full picture? It starts with understanding what “normal” looks like for your messaging patterns.

Getting to Know Your Baseline

Just like you know your typical website traffic patterns or customer service volume, you need to understand your typical message delivery patterns. What’s a normal delivery rate for messages to India versus messages to the United States? How do your success rates vary between weekdays and weekends? What about during peak shopping seasons?

This baseline knowledge becomes your compass – helping you quickly spot when something’s not quite right. But how do you build this understanding? This is where AWS End User Messaging Message Feedback API comes in handy.

Putting the Message Feedback API to Work

Here’s the thing about carrier delivery receipts: they can take up to 72 hours to arrive and will vary by country. That’s like waiting three days to know if your customer got their one-time password! Instead of playing this waiting game, you can use the Message Feedback API to gain real-time insights into message delivery.

Let’s say you’re sending OTP codes. When a user successfully enters their code, that’s a clear signal they received your message. With the Message Feedback API, you can record this action, marking the message as successfully delivered. Not only does this give you immediate feedback, but it also helps build a more accurate picture of your actual delivery success rates.

But what about messages that don’t get a response? After an hour without user interaction, the Message Feedback API will mark these messages as failed. This helps you maintain accurate metrics and quickly identify potential delivery issues.

Building a Complete Monitoring Strategy

Your monitoring strategy should be like a flight operations center, combining multiple data sources and ready to respond to changing conditions.

Message Feedback Data: This is your real-time insight into user interactions. Are recipients completing the actions your messages are meant to trigger? Are OTP codes being used? Are links being clicked?

CloudWatch Metrics: Set up alerts that make sense for your business. If your typical OTP conversion rate is 85%, you might want to know if it suddenly drops below 80%. Remember, these aren’t perfect numbers, and they’re not meant to be. Different messages might need different thresholds. What’s acceptable for a marketing message might not be acceptable for a security verification code. The key is understanding your normal delivery rates and monitoring for significant deviations from that baseline. See here for more information on setting up CloudWatch for End User Messaging.

User Behavior Patterns: Pay attention to how users interact with your messages. Are certain types of messages more successful than others? Do some regions consistently show different patterns? This information is gold for optimizing your messaging strategy.

The key is to look for patterns. Maybe your delivery rates dip at certain times of day, or perhaps specific types of messages have lower success rates. These patterns help you adapt and improve your messaging strategy over time.

Remember, monitoring isn’t just about catching problems. It’s about understanding your messaging ecosystem and continuously improving it. When you do spot an issue, you’ll need to know how to investigate and resolve it quickly.

Investigation and Troubleshooting Strategy

Even with the best monitoring in place, you’ll occasionally run into delivery challenges. Just as airlines have procedures for investigating flight delays, you need a systematic approach to investigate and resolve messaging issues quickly.

Spotting the Signs

Just as air traffic controllers monitor multiple indicators for potential issues, your messaging system has key indicators that signal when something needs attention; your most reliable indicators come directly from your customers’ experiences:

• A sudden drop in OTP conversion rates
• An uptick in customer complaints about missing messages
• Unusual patterns in your message feedback data
• Spikes in failed delivery attempts

Customer-driven signals are your most accurate indicators of messaging health. When these metrics change significantly, particularly in one-time password (OTP) conversion rates and customer complaints, it’s crucial to investigate the underlying causes and understand their impact on user experience.

Playing Detective

When you notice something’s off, start by narrowing down the scope. AWS End User Messaging provides detailed event data that helps you investigate delivery issues. Let’s look at what information you have at your fingertips:

Message Events contain crucial investigation data like:

• Country (isoCountryCode): Which countries are affected?
• Carrier information (carrierName): Is this specific to certain carriers?
• Timing (eventTimestamp): Are issues occurring at particular times?
• Message status and description: What’s happening with the message?
• Message type and encoding: Could content formatting be a factor?

Some of the most important things to configure in End User Messaging are Event Destinations. For an in-depth post on how to configure these read here. Here’s an example snippet of a delivery event that you might receive that helps paint the picture:

Understanding these events helps identify patterns. Maybe you recently changed your message templates, or perhaps you’re sending higher volumes than usual. These could be important clues to investigate.

When to Call in AWS Support

Time is crucial when investigating SMS issues. For ongoing problems, carriers need recent examples – ideally messages sent within the last 48 hours. This allows them to investigate current network conditions and message flows.

Even for historical issues that are no longer occurring, fresh data is still required for investigations. If you’re reporting a past problem, try to provide the most recent examples possible. Be aware that if an issue is too old, providers may be unable to conduct a root cause analysis due to log retention policies and other limitations.

The SMS ecosystem involves multiple third parties, each playing a role in message delivery. Investigating issues often requires coordinating with these various entities, which can extend the time needed to determine the root cause. In some cases, if the issue is old enough, a complete analysis may not be possible.

Prompt reporting is key. The sooner you alert us to an issue, the better chance we have of gathering relevant data and working with carriers to resolve the problem or provide meaningful insights.

If you spot significant issues and you have AWS Premium Support (a paid service that provides additional assistance), don’t hesitate to contact them. But here’s the key to getting quick results: provide comprehensive information. Remember that “my message didn’t deliver” isn’t nearly as helpful as “we’ve seen a 20% drop in OTP conversion rates for messages to Country X over the past 4 hours, affecting approximately 1,000 messages. Here are message IDs to investigate.”

What is Required by Support to Help You:

• Country having SMS issues
• Clear data showing the scope of the issue
• Multiple example message IDs and phone numbers that reflect the scale of the problem:
  • For widespread issues affecting thousands of messages, provide dozens of examples
  • For regional issues, include examples from different affected areas
  • For carrier-specific problems, include examples across affected carriers
• Dates and times for when the issue started and any patterns you’ve noticed
• Relevant message feedback data

The affected downstream carrier and our support team requires detailed information to help resolve delivery problems. A few example numbers aren’t enough if you’re seeing a widespread issue. The scale of your evidence should match the scale of the problem.

Investigating Issues Without Premium Support

Even without Premium Support, you have powerful tools at your disposal to investigate and resolve many issues:

• Leverage CloudWatch Metrics: Set up detailed alarms to catch issues early. Monitor trends in delivery rates, user engagement, and error types.
• Analyze Message Feedback Data: Use the Message Feedback API to gather real-time data on message delivery and user interactions. This can help you pinpoint where in the delivery process issues are occurring.
• Review AWS End User Messaging Documentation: Check out our Best Practices guide for proactive measures you can take.
• Use AWS Forums and Communities: Connect with other AWS users who might have encountered similar issues. Our community forums are a great place to share experiences and solutions.
• Implement Logging: Detailed application logs can be invaluable for tracking down the root cause of issues. Ensure you’re logging key events in your messaging workflow.
• Test with Simulator Numbers: Use our simulator numbers to test your messaging flows in a controlled environment, helping you isolate issues.

For particularly complex or persistent problems, Premium Support does offer additional resources and expert assistance. You can learn more about these services here: https://aws.amazon.com/premiumsupport/.

Learning from Each Investigation

Each investigation is an opportunity to improve your messaging strategy. Keep track of what you learn:

• Which monitoring alerts helped you catch the issue?
• What investigation steps were most effective?
• How could you spot similar issues faster next time?

But what if you could prevent some of these issues in the first place? That’s where building a resilient messaging strategy comes in, and that’s exactly what we’ll explore next.

Building a Resilient Messaging Strategy

Earlier, we discussed how retry logic helps handle immediate delivery challenges. Now, let’s expand our reliability toolkit with multi-channel approaches…

Just as passengers don’t have to rely on a single airline to reach a destination, you shouldn’t depend solely on SMS for critical communications. While SMS is fantastic, using just one channel is like depending on a single flight path. When that path becomes unavailable, you need alternatives.

Understanding Single Points of Failure

Here’s something crucial to consider: dedicated SMS phone numbers are provisioned through a single carrier partner in each region and country. Think of it like relying on a single airline for all your routes. If that airline experiences issues, you need alternative routes. This creates a potential single point of failure if that carrier partner experiences problems.

This makes implementing redundancy into your messaging strategy not only favorable/beneficial, but essential for business-critical communications. You can create this redundancy through:

• Using multiple channels like WhatsApp, Push notifications, or voice calls
• Implementing email notifications as a backup, failover, or just as an additional channel that handles specific types of messages
• In countries that support both dedicated numbers and sender IDs, planning to use either option if your use case allows for it
• Using phone pools to quickly adjust your sending strategy if specific originators experience problems

Remember, just as major airports maintain multiple airlines and routes to ensure reliable travel options, your messaging strategy needs multiple paths to reach your users reliably.

The Multi-Channel Advantage

Consider your messaging strategy like an international airport hub serving multiple carriers. AWS End User Messaging gives you several channels to work with:

• SMS for its universal reach
• WhatsApp for rich, interactive messages
• Push notifications for app users
• Voice calls when immediate attention is crucial
• Email as another reliable option

But it’s not just about having multiple channels – it’s about using them strategically. Pick the right channel for the message you are delivering. Not every message belongs on every channel.

Smart Failover: Your Messaging Safety Net

Imagine you’re sending a critical security alert. Here’s how a smart failover strategy might work:

1. Start with an SMS – it’s quick and widely accessible
2. If you don’t get confirmation within a few minutes, try WhatsApp
3. Still no response? Send a push notification if they have your app
4. For truly critical messages, you might even escalate to a voice call, or send via email and SMS at the same time

Putting Users in the Driver’s Seat

Just as frequent flyers have preferred airlines and routes, your users likely have preferred ways to receive messages. Some might want WhatsApp messages during the day but SMS for urgent notifications. Others might prefer push notifications while using your app but SMS for critical alerts.

Let your users choose their preferred channels, but be smart about it:

• Make preference updates simple and straightforward
• Consider message urgency when applying preferences
• Remember that preferences might vary by message type

Testing: Your Safety Check

Just as pilots run through a pre-flight checklist, regularly test your messaging setup. AWS End User Messaging makes this easier with SMS simulator numbers – a powerful tool that lets you test your messaging flows without sending messages over carrier networks.

With simulator numbers, you can:

• Test your messaging flows in a controlled environment
• Receive realistic event records
• Validate your application’s handling of SMS events
• All without incurring carrier costs(you will still pay for volume based on the country you are sending to) or affecting production traffic

Your testing strategy should include:

• Using simulator numbers to verify basic message flows
• Checking that messages render correctly across different channels (especially if you support multiple languages in your messaging)
• Confirming that your retry logic performs as designed
• Validating failover mechanisms work as expected
• Monitoring the performance of each channel

Think of simulator numbers as your messaging test lab – a controlled environment where you can experiment, validate, and fine-tune your implementation before sending to real phone numbers. You can find more details about using simulator numbers in the AWS End User Messaging documentation.

The Goal: Reliable Communication

Remember, the goal isn’t perfect delivery, but reliable communication with your users. By building redundancy into your system and offering choices, you create a robust messaging strategy that handles real-world challenges.

Just as airlines maintain multiple hubs and routes to ensure reliable service, your messaging strategy should provide dependable communication, even when individual channels face challenges.

Bringing It All Together: Your Path to Messaging Success

We’ve covered a lot of ground, so let’s wrap up with the big picture. Successful message delivery isn’t about achieving perfect numbers. It’s about building a robust system that reliably connects you with your users, even when conditions aren’t ideal.

Key Lessons to Take Away

Think of what we’ve learned as your messaging strategy toolkit:

First, we discovered why SMS delivery isn’t as straightforward as pushing a button. Just like a flight plan, your message navigates through various networks and systems before reaching its destination. Understanding these complexities helps set realistic expectations and guides better decision making.

Next, we learned that comprehensive monitoring is like having a reliable air traffic control system. It’s not just about watching flight trackers. It’s about actively monitoring passenger experiences through tools like the Message Feedback API. Remember, knowing if your passenger reached their final destination tells you more than a simple landing confirmation ever could.

We also explored how to identify and thoroughly investigate issues when they arise. Time is crucial. Those first 48 hours are golden when investigating delivery problems, and when you need help from AWS Support, detailed evidence is your best asset.

Finally, we looked at building resilience through multiple channels. Just as airlines maintain various routes to key destinations, your messaging strategy should have backup plans ready when needed.

Taking Action

Ready to improve your messaging strategy? Here are your next steps:

1. Start with Monitoring
   Review your current monitoring setup. Are you just looking at delivery receipts, or are you tracking actual user interactions? Implement the Message Feedback API to get better visibility into your real delivery success rates.
2. Set Up Smart Alerts
   Configure CloudWatch alerts that make sense for your business. Remember, different messages might need different thresholds – what’s acceptable for a marketing message likely is not acceptable for a security alert.
3. Build Your Safety Nets
   Begin implementing multi-channel capabilities. You don’t need to do everything at once. Start with one alternative channel and expand from there. Click here for a workshop on a basic failover between SMS and Email
4. Test and Learn
   Regularly test your messaging flows and monitor their performance. Use what you learn to continuously refine your strategy.

Need More Help?

We’re here to support your messaging journey. Check out these resources to dive deeper:

• AWS End User Messaging Documentation [link]
• Message Feedback API Guide [link]
• AWS End User Messaging Best Practices [link]
• AWS Premium Support [link]

The Future of Your Messaging Strategy

The messaging landscape will continue to evolve, but the fundamentals we’ve discussed will serve you well: monitor effectively, investigate thoroughly, and build in redundancy. With AWS End User Messaging, you have a partner who’s continuously working to optimize message delivery and provide the tools you need for success.

Remember, the goal isn’t perfection. It’s building a reliable communication system that your users can count on. Start implementing these practices today, and you’ll be well on your way to more effective user communications.

What’s your next step? Whether it’s implementing the Message Feedback API or designing a multi-channel strategy, the time to start is now. Your users are waiting to hear from you.

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-send-mms-using-amazon-pinpoint/

In our digital age, communication has evolved far beyond simple SMS, short for Simple Message Service. The rise of multimedia messaging has transformed the way we share information, express ourselves, and stay connected. MMS, short for Multimedia Messaging Service, is a technology that has become an integral part of our daily lives, enabling us to convey messages that go beyond the confines of plain text. MMS allows senders to transmit a variety of media, including images, videos, audio recordings, and even documents, alongside traditional text. This powerful combination has revolutionized the way we communicate, making it easier to share experiences, ideas, and emotions in a more engaging and visually compelling manner. In a world where visual content is becoming increasingly dominant, MMS has become a crucial tool for companies to communicate with their customers.

What are the differences between SMS and MMS?

MMS is similar to SMS but has some very distinct differences that enable you to send and engage with your customers in different ways.

Message length

• SMS
  • SMS can send text messages up to 160 characters as long as each character is a part of the GSM 03.38 character set. This means that if you have long links or longer form content that you need to send that these messages will be broken up into multiple message parts. This increases your cost and decreases the recipient reading experience on their device.
    • NOTE: Use the Message Part Preview tool in the console to determine how many message parts your message will be broken into
• If your SMS contains any characters that are outside of the GSM 03.38 character set, your message can only contain up to 70 characters. Depending on the language you are using this can be very limiting. Messages that are broken up into multiple message parts can quickly cause you to hit your throughput limits since each part is measured as one message, even if you are only making a single call to the API. A GSM 03.38 message with 161 characters is 2 message parts which means that your throughput is effectively cut in half.
• MMS
  • MMS can send up to 1,600 characters, regardless of the character set you use. Messages can be much larger, often up to 300 KB depending on the character set you are using. This expanded size allows you to send long form messages and not be so limited if you need to send messages in a character set outside of GSM 03.38 or just have the need to send longer messages.
  • This can reduce your cost and improve the experience for your recipients.
  • The larger message size helps you manage your throughput limitations since, a single MMS message can be sent, rather than an SMS being broken up into multiple message parts.

Message content

• SMS
  • SMS is text based only. You cannot send media or attachments.
• MMS
  • MMS can send multimedia content such as images, videos, PDF files, and audio files. This opens up many more options for how it can be used such as attaching a receipt, sending a new product launch gallery, or supporting troubleshooting with a how-to video.
  • A single MMS message can be up to 600KB in size for media files
  • Supported media file formats
    • Portable Network Graphics (PNG)
    • Joint Photographic Experts Group (JPEG)
    • Graphics Interchange Format (GIF)
    • MPEG-4 (MP4)
    • Quicktime File Format (MOV)
    • Portable Document Format (PDF)
    • Virtual Contact File (VCF)
    • More

Message delivery time

• SMS
  • SMS messages are delivered as a text-only message and are much smaller which may result in it being delivered more promptly.
• MMS
  • MMS messages may take longer to deliver dependent on the type and size of the multimedia content that is included which may increase the time to be delivered. This makes time sensitive messages such as OTP delivery more costly and potentially slower so it’s not an ideal use case for MMS.

Cost

• SMS
  • A single SMS message part is cheaper to send than MMS messages. Pricing is based on the country that is being sent to and can be seen here
• MMS
  • MMS messages often incur additional charges due to the larger file sizes and additional data usage. This includes S3 storage costs for any media being sent as well as a higher cost per message. MMS cost to the US and Canada can be seen here.

Network and device support

• SMS
  • SMS is a widely-adopted and supported protocol across all mobile networks
  • SMS is compatible with all mobile devices, even the most basic models
• MMS
  • MMS requires specific network infrastructure and compatibility between the sender’s and receiver’s devices and networks
  • MMS requires devices with multimedia capabilities, such as smartphones or feature phones with advanced messaging capabilities. Long text MMS messages sent to an MMS incapable recipient will be redirected to SMS by default

Regional availability and location

• SMS
  • SMS can be sent to the over 240 countries that we support in this table
• MMS
  • Currently Pinpoint MMS can only be sent to the US and Canada and can be used with Short Codes, Toll-Free, and 10DLC originators
  • NOTE: Currently, receiving inbound media is not supported. However, MMS is 2-way text enabled, so your recipients can send text based messages back to you, which flow through an Amazon Simple Notification Service (SNS) Topic in the exact same way that SMS messages do.

What are some examples of MMS messages?

Here are some examples of how MMS messages can be used:

• Attached video
  • “Introducing our new limited-edition product line! Check out this exclusive sneak peek video.“
• Single attached photo
  • “Caught you in the act! Here’s a fun photo from our recent in-store event. Thanks for stopping by!”
• Multiple attached photos
  • “Treat yourself to something special this weekend. Explore our latest makeup collection with this handy lookbook.”
• Attached receipt
  • “Thanks for your most recent purchase! We hope you love it! Your receipt is attached”

It’s important to note that you do not need to send all of your messages using one or the other. As an example you can use SMS for One Time Password (OTP) sends since they do not require media and generally should be a single message part in any language and use MMS to enable an eye catching marketing release with pictures or video.

How to send MMS with Amazon Pinpoint

You can use the AWS CLI or Amazon Pinpoint SMS and voice v2 API to send MMS messages to your customers. Use the send-media-message AWS CLI command to send an MMS message. There are two ways to send MMS depending on whether you are including media with your message.

How to send MMS with media

The first step to sending MMS is to make sure that you have an Origination Identity (OID) that is enabled for MMS. Amazon Pinpoint supports sending MMS to the US and Canada. Eligible MMS numbers in the US include 10DLC, toll-free, and short codes. Canadian eligible MMS numbers include long codes and short codes.

NOTE: If you procured originators for the US and Canada prior to May 2024, in some cases, existing Pinpoint SMS US and Canadian phone will be automatically updated to begin supporting MMS. To determine if your existing Amazon Pinpoint number(s) are eligible, navigate to the Amazon Pinpoint console Phone Numbers page. If MMS is listed under the “capabilities” column, you can begin using that number for MMS immediately if your number is in an active state. For these existing eligible numbers, there is no additional registration requirement as long as your use case doesn’t change. If the capability listed only shows SMS, you will need to procure a new US or Canadian phone number which will automatically include MMS.

For all newly purchased(Post May 2024) Amazon Pinpoint US and Canadian phone numbers, both SMS and MMS services will automatically be added at time of purchase, simplifying the registration process and providing the flexibility to use either messaging formats upon approval.

You can get started by navigating to the Pinpoint SMS console phone number page and selecting Request Originator. From there, simply follow the self-guided steps for purchasing and registering the phone number If you need help determining what type of OID you need consult this tutorial. Information on registering for MMS enabled OIDs can be found here:

• Toll-Free (US Only)
• 10DLC (US Only)
  • Documentation
  • Registration best practices
  • Campaign types and quotas
• Short codes (US and Canada)

Sending MMS with media included requires you to create a bucket in Simple Storage Service (S3) that your media can be accessed from. The media files have to be stored in a publicly available S3 bucket. Information on creating a bucket and uploading media objects to it can be found here:

• Create a bucket
• Uploading objects to a bucket
• Access control best practices

You will include the link to this bucket in your “sendMediaMessage” call using the “MediaUrls” attribute seen below. The supported media files formats can be found here.

The only required attributes are:

• DestinationPhoneNumber
• MessageBody
• OriginationIdentity
  • This can be either the PhoneNumber, PhoneNumberId, PhoneNumberArn, SenderId, SenderIdArn, PoolId, or PoolArn.
  • For more information on the benefits of Pools and the importance of using them for managing Opt-Out Lists click here
    • NOTE: ConfigurationSetName is not required but is best practice. The benefits of using a Configuration Set to stream events to Event Destinations are detailed here.

The CLI command below will send an MMS with the text of “Check out this Photo!” and will have a JPEG image included.

aws pinpoint-sms-voice-v2 —region 'xx-xxxx-xx' send-media-message —destination-phone-number +xxxxxxxxxxx —origination-identity +xxxxxxxxxxx —message-body 'Check out this Photo!' —media-urls 's3://s3-bucket/media_file.jpg'

If Amazon Pinpoint SMS accepts the command you will receive the MessageID. This only means the command was successfully received and not that the destination device has received the message yet.

How to send an MMS with no media

Sending an MMS with no media attached is nearly the same, you just don’t include a link to an S3 bucket in the “MediaUrls” attribute, it’s as easy as that. You might do this to reduce costs if you are sending a message with characters that are outside of the GSM 03.38 character or on a long message with more than 160 GSM 03.38 characters like the below.

The CLI command below will send the following message:

“This message will be broken up into more than 3 message parts if sent via SMS so we are going to use MMS instead to save costs. This is a great way to reduce your costs even if you are not sending any media such as a photo or video attached. Though a single MMS message costs more than a single SMS message there are times where you may want to use MMS simply because it is a cheaper way of communicating with your recipients. Since you can use SMS and MMS for different scenarios you may choose to send an OTP message with SMS and something like this message using MMS.”

aws pinpoint-sms-voice-v2 —region 'xx-xxxx-xx' send-media-message —destination-phone-number +xxxxxxxxxxx —origination-identity +xxxxxxxxxxx —message-body 'This message will be broken up into more than 3 message parts if sent via SMS so we are going to use MMS instead to save costs. This is a great way to reduce your costs even if you are not sending any media such as a photo or video attached. Though a single MMS message costs more than a single SMS message there are times where you may want to use MMS simply because it is a cheaper way of communicating with your recipients. Since you can use SMS and MMS for different scenarios you may choose to send an OTP message with SMS and something like this message using MMS.'

Conclusion

In this post you learned about the differences between SMS and MMS and how each can be used to send different types of messages. MMS is an excellent channel to communicate with your recipients to send highly engaging content that in some scenarios can reduce your cost while improving your customers’ experience. If you are sending content outside of the GSM 03.38 character set, want to send images, videos, or attachments such as receipts then MMS is definitely something you should look into.

A few resources to help you plan for your SMS program:

• Use this spreadsheet to plan for the countries you need to send to Global SMS/MMS Planning Sheet
• The V2 API for SMS and Voice has many more useful actions not possible with the V1 API so we encourage you to explore how it can further help you simplify and automate your applications.
• If you are needing to restrict your sending to only MMS supported countries read this blog or explore using a Protect Configuration
• Confirm the origination IDs you will need here
• Check out the support tiers comparison here

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-implement-self-managed-opt-outs-for-sms-with-amazon-pinpoint/

Amazon Pinpoint offers marketers and developers the ability to send SMS to over 240 countries and/or regions around the world; giving users the global reach, scalability, cost effective pricing, and high deliverability that is required to build a successful SMS program. SMS is a flexible communication channel that facilitates different business requirements, including One-Time Password (OTP), reminders, and bulk marketing to name a few. Regardless of the content that you are sending via SMS there is a requirement to manage your recipients’ opt-in/out status. Read on to learn your two options for managing opt-outs and how you can configure them. Amazon Pinpoint offers a fully managed opt-out capability and the ability to self-manage the process with your own tools.

NOTE: If you are sending to US numbers with a toll-free (TFN) number the carriers will automatically manage those numbers and are not eligible for either of these processes.

Managed Opt-Out Process
If you prefer to have Pinpoint manage your opt-out processes you can refer to our blog “How to Manage SMS Opt-Outs with Amazon Pinpoint” to learn how to configure keywords and opt-out lists.

Self-Managed Opt-Out Process
Many customers use Pinpoint’s Managed Opt-Out process to deliver their communications, but some scenarios require the ability to self-manage this process. Self-managing the opt-out process provides more granular control over customer communication preferences and allows customers to centralize those preferences within their own applications.
Common reasons for organizations to implement self-managed opt-out include but aren’t limited to:

1. Have an existing self-managed opt-out capability with a standing toolset that is already integrated with other aspects of their communication stack.
2. Need multiple options for their customers to manage the communication preferences such as a web portal, call center, and mobile application to name a few.
3. Require full control in order to implement custom logic that caters to their business needs.
4. Want to change their SMS provider to Pinpoint while not changing what they have already built within an existing application.

How to implement Self-Managed Opt-Outs with Pinpoint
Choosing to self-manage your opt-outs requires some configuration within Pinpoint and the use of other AWS services. The solution outlined in this blog will use Amazon Pinpoint in addition to the following services:

1. AWS Lambda
2. Amazon DynamoDB
3. Amazon SNS

NOTE: If you have existing services/applications that allow you to implement similar functionality as explained in this blog, you don’t have to use these services listed above.

What’s in scope?

This blog covers the following scenario:

1. SMS is being sent with Amazon Pinpoint SMS and Voice V2 API – SendTextMessage
2. You specify the Origination Identity (OID) to be used (short code, long code, 10DLC, etc) as the parameter to send the SMS to the destination phone number.

While the following scenarios can be self-managed this blog does not cover the following cases:

1. You use a phone-pool to send SMS.
2. You do not specify an OID in your call SendTextMessage call and let Amazon Pinpoint figure out and use the appropriate OID.

Keywords in scope

1. Opt-out keywords – All Opt-out keywords mentioned in this document are included in the code.
2. Opt-in keywords – This blog considers ‘JOIN’ as a valid keyword that SMS recipients can respond with to opt back in for the SMS communication.

NOTE: The code examples in this blog can be modified to add any additional custom keywords for your use case.

Assumptions/Prerequisites

1. You have the necessary permissions to configure the following services in the same AWS account and region where Amazon Pinpoint is implemented.
   a. AWS Lambda
   b. Amazon DynamoDB
   c. Amazon SNS
2. Your instance of Amazon Pinpoint has at least one OID approved and provisioned to send SMS.
   a. If you need help to determine what OID fits your use case(s) use this guide
   b. NOTE: Sender IDs do not have an ability to receive 2-way communication. If you are using Sender IDs, you still must manage opt-outs, but must do so by offering alternative ways of opting out such as a web portal, call center, and/or mobile applications.

Solution Overview

The solution proposed in this blog is fully serverless arhitecture and uses AWS managed services to eliminate a need for you to maintain and manage any of the infrastructure components.

1. Your application invokes AWS Lambda function ‘InvokeSendTextMessage’ which calls Amazon Pinpoint SMS and Voice V2 API – SendTextMessage.
2. The AWS Lambda function called ‘InvokeSendTextMessage’ performs the following tasks:
   2a. Fetches the latest item based on the descending order of the timestamp with the destination phone number and OID from Amazon DynamoDB table ‘SMSOptOut‘.
   2b. If an item is found with the customer response as any valid keyword for Opt-out (Refer section Keywords in scope), the process stops and Amazon Pinpoint APIs won’t be called by InvokeSendTextMessage function as the customer chose to opt-out.
   2c. If an item is not found or is found with the customer response as any valid keyword for Opt-in (Refer section Keywords in scope), the function calls Amazon Pinpoint SMS and Voice V2 API – SendTextMessage to deliver it to the customer/destination phone number.

NOTE: Amazon DynamoDB table can also be configured to receive the Opt-out or Opt-in information through various other channels (app, website, customer care etc.) if you have multiple interfaces for customer to do so but that is not in the scope for this blog.

Refer to the section, ‘InvokeSendTextMessage function code’ to understand the sample AWS Lambda function code. The code uses Python 3.12 language.

3. The message is successfully delivered to a destination phone number.
4. If the customers responds to the same OID (because you have enabled 2-way SMS feature) with a keyword that is a valid value from all the keywords in scope (Refer section Keywords in scope), Amazon SNS topic is configured with Amazon Pinpoint which captures the customer response.
   Note: The other keywords are not in scope for this blog, but you can specifically add all possible keywords that customers can respond with. There can be an accidental responses by a customer which will be ignored by the AWS Lambda code.
5. AWS Lambda function ‘AddOptOutInDynamoDB’ is a subscriber to the topic in Amazon SNS and processes customer responses.

6. AWS Lambda function ‘AddOptOutInDynamoDB’ performs few tasks as described below
7. 6a. If the customer response is a keyword that is a valid value from all the keywords in scope (Refer section Keywords in scope), Amazon Lambda function ‘AddOptOutInDynamoDB‘ extracts the OID and customer phone number information from the response and adds the entry in the Amazon DynamoDB table ‘SMSOptOut’. This way Amazon DynamoDB table keeps getting latest customer opt-in/opt-out status.
   6b. Once the item is successfully put in dynamodb table ‘SMSOptOut‘, if the customer response was any Opt-out keyword (Refer section Keywords in scope), the function sends a SMS to the customer who has just opted out to confirm the status. “YOU HAVE BEEN UNSUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT “JOIN” TO THIS NUMBER TO BE RESUBSCRIBED”.
   If the customer response was any Opt-in keyword (Refer section Keywords in scope) the function sends a SMS to the customer who has just opted back in to confirm the status. “YOU HAVE BEEN SUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT “STOP” OR “UNSUBSCRIBE” TO THIS NUMBER TO BE UNSUBSCRIBED”. (But SMS recipients can still respond with any valid keyword mentioned in Opt-out keyword list)

NOTE: Refer the section ‘AddOptOutInDynamoDB function code’ to understand the sample code. The code uses Python3.12 language.

7. The Opt-in/Opt-out status confirmation SMS is successfully delivered to a customer/destination phone number.

Amazon Pinpoint setup

1. Enable 2-way SMS messaging for the OID that you procured. Refer to the screenshot below for your reference.

2-way SMS setting:

2. Enable the self-managed opt-out feature for the OID. Once enabled, Amazon Pinpoint does not respond to opt-out messages sent to the SNS topic by your recipients. You can collect the response from the customers in an AWS SNS topic and process it as per your business needs.

Self Managed Opt-Out feature setting:

Amazon SNS setup

1. On Amazon SNS console, click on ‘Topics’ and then ‘create a topic’ as shown below.

2. Click ‘Create Subscription‘ to add the Lambda function ‘AddOptOutInDynamoDB‘ as a subscriber by using the Amazon Resource Name (ARN).

Amazon DynamoDB Setup

Table Name: ‘SMSOptOut‘

The Customer phone number is used as the primary key(PK). The sort key(SK) contains multiple values that include OID, timestamp, and the customer response separated by #. By having generic attribute names as PK and SK, you can expand the usage of this table for accommodating any custom business needs. For example: Customer can use any of the individual phone numbers like short code, long code, or 10DLC to send the SMS and any of these values can be accomodated as a part of the sort key (SK). The sort key can be used for granular retrieval to see the latest customer status (For example: ‘STOP‘). It can then additionally have attributes like OID, Timestamp, Response and others as per your requirements. The table uses On-demand Read/Write capacity mode. Refer to this document to understand On-demand capacity mode in detail.

Sample item in DynamoDB table is below

InvokeSendTextMessage function code

This AWS Lambda function calls Amazon Pinpoint SMS and Voice V2 API – SendTextMessage. It uses Query API for DynamoDB to scan the items for SourcePhoneNumber (customer phone number) and OID (Part of SK) in descending order of the timestamp. If an item exists with customer response value is a valid keyword for Opt-out (Refer section Keywords in scope), it means the customer has opted-out and the SMS can’t be sent. If no item is found or the customer response value is a valid keyword for Opt-in (Refer section Keywords in scope), the customer can be contacted and the funtion calls SendTextMessage API with the same OID and customer phone number.

import boto3
import os
from boto3.dynamodb.conditions import Key, Attr
import json

dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('SMSOptOut')
pinpoint = boto3.client('pinpoint-sms-voice-v2')
OptOutKeyword = ['ARRET','CANCEL','END','OPT-OUT','OPTOUT','QUIT','REMOVE','STOP','TD','UNSUBSCRIBE']
OptInKeyword = ['JOIN']

#adds item in the DynamoDB table
def query_table(OID, SourcePhoneNumber):
    try:
        response = table.query(
            KeyConditionExpression=Key('PK').eq(SourcePhoneNumber) & Key('SK').begins_with(OID),
            ScanIndexForward=False,
            Limit=1
        )
    except Exception as e: 
        print("Error when writing an item in DynamoDB table: ",e) 
        raise e
    return response

#send opt-in/opt-out confirmation text using send_text_message.
def send_confirmation_text(SourcePhoneNumber,OID,messageBody,messageType): 
    
    try: 
        response = pinpoint.send_text_message(DestinationPhoneNumber=SourcePhoneNumber, 
        OriginationIdentity=OID,
        MessageBody=messageBody, 
        MessageType=messageType 
        ) 
    except Exception as e: 
        print("Error in sending text message using Pinpoint send_text_message api:", e) 
        raise e

#gets the message from SNS topic
def lambda_handler(event, context):
    OID = event['OID']
    SourcePhoneNumber = event['SourcePhoneNumber']

    response=query_table(OID, SourcePhoneNumber)
    items = response['Items']
    
    #Count number of items. The value will be either 1 or 0.
    count = len(items)

    # If the latest customer response is any OptOutKeyword
    if count == 1 and items[0]['Response'] in OptOutKeyword:
        print("Exit : Customer has opted out, do not send SMS")
    # If the latest customer response is any OptOutKeyword
    elif count == 0 or (count == 1 and items[0]['Response'] in OptInKeyword):
        send_confirmation_text(SourcePhoneNumber,OID,'This is a test message from Amazon Pinpoint','TRANSACTIONAL')
    # Only allowed values for customer response are valid OptOutKeyword or OptInKeyword 
    else: 
        print("The customer response is not one of the allowed keyword")

AddOptOutInDynamoDB Lambda function code

For example: When customer responds with ‘STOP’, the response is captured in the SNS topic that you configured with Amazon Pinpoint. The response json looks as shown below –

{
"originationNumber": "+1224xxxxxxx",
"destinationNumber": "+1844xxxxxxx",
"messageKeyword": "KEYWORD_xxxxxxxxxxxx",
"messageBody": "STOP",
"previousPublishedMessageId": "xxxxxxxxxxxxxx",
"inboundMessageId": "xxxxxxxxxxxxxx"
}

This Lambda function extracts the OID (destinationNumber), Customer phone number (originationNumber), and the customer response (messageBody) from the json payload above and adds an entry in the DynamoDB table (SMSOptOut). Once the item is put successfully in DynamoDB table, the function also sends out a confirmation SMS (either Opt-in or Opt-out) to the customer phone number using SendTextMessage.
For example:

• If the customer response value is a valid keyword for Opt-out (Refer section Keywords in scope), the confirmation SMS is ‘YOU HAVE BEEN UNSUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT “JOIN” TO THIS NUMBER TO BE RESUBSCRIBED’.
• If the customer response value is a valid keyword for Opt-in (Refer section Keywords in scope), the confirmation SMS is ‘YOU HAVE BEEN SUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT “STOP” OR “UNSUBSCRIBE” TO THIS NUMBER TO BE UNSUBSCRIBED’.

import json
import boto3
import datetime

dynamodb = boto3.resource('dynamodb')
dynamodb_table = dynamodb.Table('SMSOptOut')
pinpoint = boto3.client('pinpoint-sms-voice-v2')
OptOutKeyword = ['ARRET','CANCEL','END','OPT-OUT','OPTOUT','QUIT','REMOVE','STOP','TD','UNSUBSCRIBE']
OptInKeyword = ['JOIN']

#adds item in the DynamoDB table
def put_item(data,current_timestamp):
    print(dynamodb_table)
    try:
        response = dynamodb_table.put_item(
            Item = {
                'PK': data['originationNumber'],
                'SK': data['destinationNumber']+'#'+current_timestamp+'#'+data['messageBody'], 
                'OID': data['destinationNumber'],
                'Timestamp': current_timestamp,
                'Response': data['messageBody']
            }
        )
    except Exception as e:
        print("Error when writing an item in DynamoDB table: ",e)
        raise e

#send opt-in/opt-out confirmation text using send_text_message.
def send_confirmation_text(data,messageBody,messageType):
    try:
        response = pinpoint.send_text_message(
            DestinationPhoneNumber=data['originationNumber'],
            OriginationIdentity=data['destinationNumber'],
            MessageBody=messageBody,
            MessageType=messageType
            )
    except Exception as e:
        print("Error in sending text message using Pinpoint send_text_message api:", e)
        raise e
        
#gets the message from SNS topic
def lambda_handler(event, context):
    message = event['Records'][0]['Sns']['Message']
    data = json.loads(message)
    current_timestamp = datetime.datetime.now().isoformat()

    if data['messageBody'] in OptOutKeyword:
        put_item(data,current_timestamp)
        send_confirmation_text(data, 'YOU HAVE BEEN UNSUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT "JOIN" TO THIS NUMBER TO BE RESUBSCRIBED', 'TRANSACTIONAL')
    elif data['messageBody'] in OptInKeyword:
        put_item(data,current_timestamp)
        send_confirmation_text(data, 'YOU HAVE BEEN SUBSCRIBED. IF THIS WAS A MISTAKE PLEASE TEXT "STOP" OR "UNSUBSCRIBE" TO THIS NUMBER TO BE UNSUBSCRIBED', 'TRANSACTIONAL')
    else:
        print("The customer response is not one of the allowed keyword")

Clean Up

DynamoDB storage and any Lambda invocation will incur a cost so it is important to delete these resources if you do not plan on using them as shown below.

DynamoDB:

1. 1. On DynamoDB table, select table ‘SMSOptOut’ and click Delete. Confirm the action.

Lambda:

1. On Lambda console, find the 2 functions you created and click Actions → Delete. Confirm the actions.

Amazon Pinpoint

1. After deleting the DynamoDB table and Lambda functions your self-managed Opt-out flow will not work so you will need to disable self-managed opt-outs in Pinpoint for the respective OID as shown below.

Conclusion
In this post, you learned how to implement a self-managed opt-out workflow when using Pinpoint SMS. Keep in mind that when you implement the self-managed Opt-out flow, Pinpoint will not track or maintain any opt-out status for the OID that it was enabled for.

Take the time to plan out your approach, follow the steps outlined in this blog, and take advantage of any resources available to you within your support tier.

Decide what origination IDs you will need here
Review the documentation for the V2 SMS and Voice API here
Check out the support tiers comparison here

Resources:
https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-sms-by-country.html
https://aws.amazon.com/blogs/messaging-and-targeting/how-to-utilise-amazon-pinpoint-to-retry-unsuccessful-sms-delivery/
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-limitations-opt-out.html
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-simulator.html
https://docs.aws.amazon.com/dynamodb/
https://docs.aws.amazon.com/sns/
https://docs.aws.amazon.com/lambda/

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-send-sms-using-a-sender-id-with-amazon-pinpoint/

Amazon Pinpoint enables you to send text messages (SMS) to recipients in over 240 regions and countries around the world. Pinpoint supports all types of origination identities including Long Codes, 10DLC (US only), Toll-Free (US only), Short Codes, and Sender IDs.
NOTE: Certain subtypes of Origination Identities (OIDs), such as Free to End User (FTEU) Short Codes might not be supported

Unlike other origination identities, a Sender ID can include letters, enabling your recipients to receive SMS from “EXAMPLECO” rather than a random string of numbers or phone number. A Sender ID can help to create trust and brand awareness with your recipients which can increase your deliverability and conversion rates by improving customer interaction with your messages. In this blog we will discuss countries that allow the use of Sender IDs, the types of Sender IDs that Pinpoint supports, how to configure Pinpoint to use a Sender ID, and best practices for sending SMS with a Sender ID. Refer to this blog post for guidance planning a multi-country rollout of SMS.

What is a Sender ID?

A sender ID is an alphanumeric name that identifies the sender of an SMS message. When you send an SMS message using a sender ID, and the recipient is in an area where sender ID is supported, your sender ID appears on the recipient’s device instead of a phone number, for example, they will see AMAZON instead of a phone number such as “1-206-555-1234”. Sender IDs support a default throughput of 10 messages per second (MPS), which can be raised in certain situations. This MPS is calculated at the country level. As an example, a customer can send 10 MPS with “SENDERX” to Australia (AU) and 10 MPS with “SENDERX” to Germany (DE).

The first step in deciding whether to use a Sender ID is finding out whether the use of a Sender ID is supported by the country(ies) you want to send to. This table lists all of the destinations that Pinpoint can send SMS to and the Origination Identities that they support. Many countries support multiple origination identities so it’s important to know the differences between them. The two main considerations when deciding what originator to use is throughput and whether it can support a two-way use case.

Amazon Pinpoint supports three types of Sender IDs detailed below. Your selection is dependent on the destination country for your messages, consult this table that lists all of the destinations that Pinpoint can send SMS to.

Dynamic Sender ID – A dynamic sender ID allows you to select a 3-11 character alphanumeric string to use as your originator when sending SMS. We suggest using something short that outlines your brand and use case like “[Company]OTP.” Dynamic sender IDs vary slightly by country and we recommended senders review the specific requirements for the countries they plan to send to. Pay special attention to any notes in the registration section. If the country(ies) you want to send to require registration, read on to the next type of Sender ID.

Registered Sender ID – A registered SenderID generally follows the same formatting requirements as a Dynamic Sender ID, alowing you to select a 3-11 character alphanumeric string to use, but has the added step of completing a registration specific to the country you want to use a Sender ID for. Each country will require slightly different information to register, may require specific forms, as well as a potential registration fee. Use this list of supported countries to see what countries support Sender ID as well as which ones require registration.

Generic, or “Shared” Sender ID – In countries where it is supported, when you do not specify a dynamic Sender ID, or you have not set a Default Sender ID in Pinpoint, the service may allow traffic over a Generic or Shared SenderID like NOTICE. Depending on the country, traffic could also be delivered using a service or carrier specific long or short code. When using the shared route your messages will be delivered alongside others also sending in this manner.

As mentioned, Sender IDs support 10 MPS, so if you do not need higher throughput than this may be a good option. However, one of the key differences of using a Sender ID to send SMS is that they do not support two-way use cases, meaning they cannot receive SMS back from your recipients.

IMPORTANT: If you use a sender ID you must provide your recipients with alternative ways to opt-out of your communications as they cannot text back any of the standard opt-out keywords or any custom opt-in keywords you may have configured. Common ways to offer your recipients an alternative way of opting out or changing their communication preferences include web forms or an app preference center.

How to Configure a Sender ID

The country(ies) you plan on sending to using a Sender ID will determine the configuration you will need to complete to be able to use them. We will walk through the configuration of each of the three types of Sender IDs below.

Step 1 – Request a Sender ID(Dependent on Country, Consult this List)

Some countries require a registration process. Each process, dependent on the country can be unique so it is required that a case be opened to complete this process. The countries requiring Sender ID registration are noted in the following list.
When you request a Sender ID, we provide you with an estimate of how long the request will take to complete. This estimate is based on the completion times that we’ve seen from other customers.

NOTE: This time is not an SLA. It is recommended that you check the case regularly and make sure that nothing else is required to complete your registration. If your registration requires edits it will extend this process each time it requires edits. If your registration passes over the estimated time it is recommended that you reply to the case.

Because each country has its own process, completion times for registration vary by destination country. For example, Sender ID registration in India can be completed in one week or less, whereas it can take six weeks or more in Vietnam. These requests can’t be expedited, because they involve the carriers themselves making changes to the ways that their networks are configured and certify the use case onto their network. We suggest that you start your registration process early so that you can start sending messages as soon as you launch your product or service.

IMPORTANT: Make sure that you are checking on your case often as support may need more details to complete your registration and any delay extends the expected timeline for procuring your Sender ID

Generic Sender ID – In countries that support a Generic or Shared ID like NOTICE there is no requirement to register or configure prior to sending we will review how to send with this type of Sender ID in Step 2.

Dynamic Sender ID – A Dynamic Sender ID can be requested via the API or in the console, complete the following steps to configure these Sender IDs in the console.
NOTE: If you are using the API to send it is not required that you request a Sender ID for every country that you intend on sending to. However, it is recommended, because the request process will alert you to any Sender IDs that require registration so you do not attempt to send to countries that you cannot deliver successfully to. All countries requiring registration for Sender IDs can be found here.

1. Navigate to the SMS Console
   1. Make sure you are in the region you plan on using to send SMS out of as each region needs to be configured independently and any registrations also need to be made in the account and region in which you will be sending from
2. Select “Sender IDs” from the left rail
   1. Click on “Request Originator”
      
   2. Choose a country from the drop down that supports Sender ID
   3. Choose “SMS”
      1. Leave “Voice” unchecked if it is an option.
         NOTE: If you choose Voice than you will not be able to select a Sender ID in the next step
      2. Select your estimated SMS volume
      3. Choose whether your company is local or international in relation to the country you are wanting to configure. Some countries, like India, require proof of residency to access local pricing so select accordingly.
      4. Select “No” for two-way messaging or you will not be able to select a Sender ID in the next step
   4. Click next and choose “Sender ID” and provide your preferred Sender ID.
      NOTE: Refer to the following criteria when selecting your Sender ID for configuration (some countries may override these)
      1. Numeric-only Sender IDs are not supported
      2. No special characters except for dashes ( – )
      3. No spaces
      4. Valid characters: a-z, A-Z, 0-9
      5. Minimum of 3 characters
      6. Maximum of 11 characters. NOTE: India is exactly 6 Characters
      7. Must match your company branding and SMS service or use case.
         1. For example, you wouldn’t be able to choose “OTP” or “2FA” even though you might be using SMS for that type of a use case. You could however use “ANYCO-OTP” if your company name was “Any Co.” since it complies with all above criteria.

NOTE: If the console instructs you to open a case as seen below than your Sender ID likely requires some form of registration. Read on to configure a Registered Sender ID.

Registered Sender ID – A registered sender ID follows the same criteria above for a Dynamic Sender ID, although some countries may have minor criteria changes or formatting restrictions. Follow the directions here to complete this process, AWS support will provide the correct forms needed for the country that you are registering. Each Registered Sender ID will need a separate case per country. Follow the link to the “AWS Support Center” and follow these instructions when creating your case

Step 2 – How to Send SMS with a Sender ID

Sender IDs can be used via three different mechanisms

Option 1 – Using the V2 SMS and Voice API and “SendTextMessage“
This is the preferred method of sending and this set of APIs is where all new functionality will be built on.

1. SendTextMessage has many options for configurability but the only required parameters are the following:
   1. DestinationPhoneNumber
   2. MessageBody
      
2. “OriginationIdentity” is optional, but it’s important to know what the outcome is dependent on how you use this parameter:
   1. Explicitly stating your SenderId
      1. Use this option if you want to ONLY send with a Sender ID. Setting this has the effect of only sending to recipients in countries that accept SenderIDs and rejecting any recipients whose country does not support Sender IDs. The US for example cannot be sent to with a Sender ID
   2. Explicitly stating your SenderIdArn
      1. Same effect as “SenderID” above
   3. Leaving OriginationIdentity Blank
      1. If left blank Pinpoint will select the right originator based on what you have available in your account in order of decreasing throughput, from a Short Code, 10DLC (US Only), Long Code, Sender ID, or Toll-Free (US Only), depending on what you have available.
         1. Keep in mind that sending this way opens you up to sending to countries you may not have originators for. If you would like to make sure that you are only sending to countries that you have originators for then you need to use Pools.
   4. Explicitly stating a PoolId
      1. A pool is a collection of Origination Identities that can include both phone numbers and Sender IDs. Use this option if you are sending to multiple country codes and want to make sure that you send to them with the originator that their respective country supports.
         1. NOTE: There are various configurations that can be set on a pool. Refer to the documentation here
            1. Make sure to pay particular attention to “Shared Routes” because in some countries, Amazon Pinpoint SMS maintains a pool of shared origination identities. When you activate shared routes, Amazon Pinpoint SMS makes an effort to deliver your message using one of the shared identities. The origination identity could be a sender ID, long code, or short code and could vary within each country. Turn this feature off if you ONLY want to send to countries for which you have an originator.
            2. Make sure to read this blogpost on Pools and Opt – Outs here
   5. Explicitly stating a PoolArn
      1. Same effect as “PoolId” above

Option 2 – Using a journey or a Campaign

1. If you do not select an “Origination Phone Number” or a Sender ID Pinpoint will select the correct originator based on the country code being attempted to send to and the originators available in your account.
   1. Pinpoint will attempt to send, in order of decreasing throughput, from a Short Code, 10DLC (US Only), Long Code, Sender ID, or Toll-Free (US Only), depending on what you have available. For example, if you want to send from a Sender ID to Germany (DE), but you have a Short Code configured for Germany (DE) as well, the default function is for Pinpoint to send from that Short Code. If you want to override this functionality you must specify a Sender ID to send from.
      1. NOTE: If you are sending to India on local routes you must fill out the “Entity ID and Template ID that you received when you registered your template with the Telecom Regulatory Authority of India (TRAI)
   2. You can set a default Sender ID for your Project in the SMS settings as seen below.
      NOTE: Anything you configure at the Campaign or Journey level overrides this project level setting
      

Option 3 – Using Messages in the Pinpoint API

1. Using “Messages“ is the second option for sending via the API. This action allows for multi-channel(SMS, email, push, etc) bulkified sending but is not recommended to standardize on for SMS sending.
   1. NOTE: Using the V2 SMS and Voice API and “SendTextMessage” detailed in Option 1 above is the preferred method of sending SMS via the API and is where new features and functionality will be released. It is recommended that you migrate SMS sending to this set of APIs.

Conclusion:
In this post you learned about Sender IDs and how they can be used in your SMS program. A Sender ID can be a great option for getting your SMS program up and running quickly since they can be free, many countries do not require registration, and you can use the same Sender ID for lots of different countries, which can improve your branding and engagement. Keep in mind that one of the big differences in using a Sender ID vs. a short code or long code is that they don’t support 2-way communication. Common ways to offer your recipients an alternative way of opting out or changing their communication preferences include web forms or an app preference center.

A few resources to help you plan for your SMS program:
Use this spreadsheet to plan for the countries you need to send to Global SMS Planning Sheet
The V2 API for SMS and Voice has many more useful actions not possible with the V1 API so we encourage you to explore how it can further help you simplify and automate your applications.
If you are needing to use pools to access the “shared pools” setting read this blog to review how to configure them
Confirm the origination IDs you will need here
Check out the support tiers comparison here

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-build-a-compliant-sms-opt-in-process-with-amazon-pinpoint/

SMS messaging is a great way to stay in touch with your customers and send them timely, relevant messages. However, it’s always required to get their permission before you start sending them texts. This is known as opting in.

There are a few different ways to opt-in users to your SMS program. One common method is to have them sign up on your website or in your app. You can also collect opt-ins at in-person events or via phone call through your customer service team; though it’s not limited to just those options.

No matter which method you choose, it’s important to make sure that your opt-in process is clear, concise, and compliant with all applicable local laws and regulations in the countries that you are sending to. Here are some best practices:

• Get explicit consent. Explicit consent is the intentional action taken by a end-user to request a specific message from your service.
• Provide clear instructions. Tell users how to opt-in, what they are opting into, and how to opt-out of your program. Be sure to include your contact information at the opt-in location in case they have any questions or concerns.
• Give users the option to choose what kind of messages they want to receive. For example, you might allow them to opt-in to OTP/2FA messages, shipping notifications, or both.
• Respect users’ privacy. Never sell or share users’ phone numbers with third parties without their permission. 3rd party data sharing is generally considered a prohibited practice by mobile carriers and violates privacy regulations in many countries.
• Make it easy to opt-out. Users should be able to opt-out of your program at any time by replying with a simple text message, such as “STOP.” See additional relevent documentation related to this: Opting out. Self-managed opt-outs.

The above will help you build a strong audience of engaged subscribers who want to hear from you and improve your chances in successfully registering for a dedicated number. By following these best practices, you can ensure that your SMS opt-in process is compliant and effective.

What carriers require for a compliant opt-in workflow and call-to-action

The primary purpose of the opt-in workflow is to demonstrate that the end-user explicitly consents to receive text messages and understands the nature of the program. Your application is being reviewed by a 3rd party reviewer and sometimes multiple 3rd party reviewers for a single registration, so make sure to provide clear and thorough information about how your end-users opt-in to your SMS service and any associated fees or charges. If the reviewer cannot determine how your opt-in process works or if it is not compliant then your application will be denied and returned. It is important to note that Amazon does not review or approve your use cases and that it’s a telecom industry standard in most countries for 3rd parties to review and approve your use case prior to sending.

Note: If you have a use case that is internal to your business, you are still required to demonstrate explicit opt-in consent from the recipients. There are no exceptions to having an opt-in workflow and explicit consent is always required.

If your opt-in process requires a login, is not yet public, is a verbal opt-in, or if it occurs on printed forms or fliers then make sure to thoroughly document how this process is completed by the end-user receiving messages — remember, these are 3rd party reviewers and if they’re unable to access where your end-users opt-in, they will require thorough information via other means like text or screenshots. Provide a screenshot of the Call to Action (CTA) in such cases. If the consent is being asked for and supplied verbally, as in a contact center situation, make sure to provide the verbal scripts to ensure the entire CTA is shown. Host any screenshots on a publicly accessible website (like S3, OneDrive, or Google Drive) and provide the URL when you submit (NOTE: toll-free number registration process supports attachments and do not require a public URL to be included). Regardless of the medium used to collect end-user information (e.g., webform, point of sale, fliers, or verbal opt-ins), the requirements are the same. In the case of online and printed materials, they would be shown as text to the end-users. In the case of verbal opt-ins (i.e., on the phone), the information below would be verbally read to the end-user.

Call-to-action/opt-in requirements

The following items are the minimum that must be presented to an end-user at the time of opt-in to ensure your SMS program is compliant:

• Program (brand) name
• Message frequency disclosure. (example: “Message frequency varies” or “One message per login”)
• Customer care contact information (example: “Text HELP or call 1-800-111-2222 for support.”)
• Opt-out information (example: “Text STOP to opt-out of future messages.”)
• Include “Message and data rates may apply” disclosure.
• Link to a publicly accessible Terms & Conditions page
  • Terms & conditions: See section “Publicly accessible Terms & Conditions page” below
• Link to a publicly accessible Privacy Policy page
  • Privacy Policy: See section “Publicly accessible Privacy Policy page” below

**Now lets break the above bullet points down into more detail:

Program, service, brand name

All SMS originator types that require registration must disclose the program name, product description, or both in service messages, on the call-to-action, and in the terms and conditions. The program name is the sponsor of the messaging program, often the brand name or company name associated with the sending use case. The product description describes the product advertised by the program.

Publicly accessible terms & conditions page

The terms should be live and publicly accessible. For verbal scripts, a URL must be read off to the end-user enrolling in the SMS program, or the comprehensive terms must be directly included in the script. You should provide a compliant screenshot, link, or mockup of the SMS Terms of Service in the registration submission.

Below is a copy of the boilerplate terms of service that cover minimum requirements from the carriers:

1. {Program name}
2. {Insert program description here; this is simply a brief description of the kinds of messages users can expect to receive when they opt-in.}
3. You can cancel the SMS service at any time. Just text “STOP” to the short code. After you send the SMS message “STOP” to us, we will send you an SMS message to confirm that you have been unsubscribed. After this, you will no longer receive SMS messages from us. If you want to join again, just sign up as you did the first time and we will start sending SMS messages to you again.
4. If you are experiencing issues with the messaging program you can reply with the keyword HELP for more assistance, or you can get help directly at {support email address or toll-free number}.
5. Carriers are not liable for delayed or undelivered messages
6. As always, message and data rates may apply for any messages sent to you from us and to us from you. You will receive {message frequency}. If you have any questions about your text plan or data plan, it is best to contact your wireless provider.
7. If you have any questions regarding privacy, please read our privacy policy: {link to privacy policy}

Publicly accessible privacy policy page

Message Senders are responsible for protecting the privacy of Consumers’ information and must comply with applicable privacy law. Message Senders should maintain a privacy policy for all programs and make it accessible from the initial call-to-action. The privacy policy should be labeled clearly and all cases, terms and conditions and privacy policy disclosures must provide up-to-date, accurate information about program details and functionality. For verbal scripts, a URL must be read off to the end-user enrolling in the SMS program, or the comprehensive terms must be directly included in the script.

One of the key items carriers look for in a Privacy Policy is the sharing of end-user information with third-parties. If your privacy policy mentions data sharing or selling to non-affiliated third parties, there is a concern that customer data will be shared with third parties for marketing purposes.

Express consent is required for SMS; therefore, sharing data is prohibited. Privacy policies must specify that this data sharing excludes SMS opt-in data and consent. Privacy policies can be updated (or draft versions provided) where the practice of sharing personal data to third parties is expressly omitted from the number registration.

Example: “The above excludes text messaging originator opt-in data and consent; this information will not be shared with any third parties.”

Message frequency disclosure

The message frequency disclosure provides end-users an indication of how often they’ll receive messages from you. For example, a recurring messaging program might say “one message per week.” A one-time password or multi-factor authentication use case might say “message frequency varies” or “one message per login attempt”.

Customer care contact information

Customer care contact information must be clear and readily available to help Consumers understand program details as well as their status with the program. Customer care information should result in Consumers receiving help.

Numbers should always respond to customer care requests, regardless of whether the requestor is subscribed to the program. At a minimum, Message Senders must respond to messages containing the HELP keyword with the program name and further information about how to contact the Message Sender. SMS programs should promote customer care contact instructions at program opt-in and at regular intervals in content or service messages, at least once per month.

Example: “For more information, text ‘HELP’ or call 1-800-123-1234.”

Opt-Out Information

Opt-out mechanisms facilitate Consumer choice to terminate communications from text messaging programs. Message Senders should acknowledge and respect Consumers’ opt-out requests consistent with the following guidelines:

• Message Senders should ensure that Consumers have the ability to opt-out at any time
• Message Senders should support multiple mechanisms of opt-out, including: phone call, email, or text
• Message Senders should acknowledge and honor all Consumer opt-out requests by sending one final opt-out confirmation message to notify the Consumer that they have opted-out successfully. No further messages should be sent following the confirmation message.

Message Senders should include opt-out information in the call-to-action, terms and conditions, and opt-in confirmation.

If a 2FA/OTP program requires end-users to opt-in and request an OTP from the same CTA, and it is compliant with all applicable regulations, then the sender does not need to explicitly opt-out that number if the user texts “STOP” to the business’s number. However, the sender must still respond with a compliant opt-out response.

See the following Amazon Pinpoint blog post on How to Manage SMS Opt-Outs with Amazon Pinpoint

“Message and data rates may apply” disclosure

All SMS programs must display or must be read out loud (if a verbal opt-in) the disclosure verbatim: “Message and data rates may apply”. By requiring the disclosure, US mobile carriers are helping to ensure that consumers are aware of the potential costs of sending and receiving text messages, and that they have consented to receive those messages before they are sent.

SMS Opt-Ins for Independent Software Vendors (ISVs)

Definitions

In this section, we’ll outline the terms we use, to help better explain each party, and the requirements.

ISV: ISVs are positioned between Amazon Pinpoint and the ISV’s end-business customers. While they may operate differently, and/or offer different services, their requirements for SMS program registrations are largely the same.

End Business: The End Business is how we refer to your ISV customers. This is generally the entity that creates the messaging content, distributes it through your platform, and interacts with their end-users (message recipients).

Note: In some rare cases, an ISV platform can be considered the end business if they control content via templates, and collect and manage opt-in in their entirety — meaning the ISV information directly will be used for the registration and will be branded as such in the text messages. If you are unsure, we recommend including the information for the entity (your customer) that is engaging with the opted-in handset with registration. ISVs who don’t include this information (if it is required) risk their verification request being rejected.

End-User: The message recipient is considered the end-user. The person with the handset where messages terminate. As an independent software vendor (ISV), you need to comply with all applicable laws and regulations when it comes to SMS opt-ins. This means that your end business(es) need to get explicit consent from their end-users before text messages start being sent and give end-users the option to opt-out of their program at any time. You also need to provide them with a registered and approved phone number to send their SMS messages to ensure that they are delivered reliably and not flagged as spam.

When does an ISV have to submit each end business?

SMS program registrations requires end-user business information, not ISV information. This means the ISV needs to provide a mechanism for their end businesses to provide their information to be submitted for registration. For ISVs or aggregators who provide messaging services to businesses, it’s expected that the information provided represents the entity (your customer) that is sending messages to the opted-in handset.

NOTE: Amazon uses this information in accordance with all applicable obligations, and only to verify the end-user is a legitimate business. Amazon will not contact the end-business user with the information provided.

Submissions that are missing information or are populated with ISV/aggregator information may be rejected. Exceptions may apply when the use case clearly showcases that the ISV manages opt-in mechanisms, is the sole message content creator, and the messages clearly come from the ISV, not their end businesses. For example, if the ISV owns a web application that requires their end-customers to enroll into OTP.

If you are unsure, we recommend including the information for the entity (your customer) that is engaging with the opted-in handset with registration. ISVs who don’t include this information (if it is required) risk their verification request being rejected.

In conclusion

Getting user consent through a compliant opt-in process is crucial for any SMS messaging program. Key elements include clearly disclosing the program details, providing easy opt-out methods, having accessible terms of service and privacy policies, and adhering to all applicable regulations. For ISVs enabling businesses to send SMS messages, it’s important they provide a way for each end business to submit their own information for registration and comply with the requirements. By following SMS best practices around opt-ins, businesses can build trust with subscribers and ensure deliverability of their text messaging campaigns.

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-migrate-your-sms-program-to-amazon-pinpoint/

How to Migrate Your SMS Program to Amazon Pinpoint

In the fast-paced realm of communication, where every second counts and attention spans are shorter than ever, the choice of channels that you use to deliver your message to your recipients is critical. While we often find ourselves swept away by the allure of flashy social media platforms and sleek email interfaces, it’s the unassuming text message, or SMS, that continually proves to be one of the most effective options. According to Statista, there over 5 billion mobile internet users globally, amounting to over 60% of the earth’s population of ~8 billion. SMS obviously provides an expansive reach that can help businesses connect with a diverse audience but in order to do that at scale, you need to use a service like Amazon Pinpoint that facilitates the ability to send SMS to over 240 countries and/or regions around the world. If you have a current SMS provider and are considering Pinpoint SMS for its global reach, scalability, cost effective pricing, and demonstrably high deliverability, this guide will walk you through how to migrate from your current provider.

There are several common reasons our customers give us when considering a migration. Don’t worry if your situation doesn’t fit into a neat box, we help customers navigate the dynamic landscape of SMS that is constantly evolving. Let’s dive deep into each of the below to highlight some common things we hear from our customers.

• My current provider doesn’t deliver to countries I want to send to
  • We send to over 240 countries and/or regions so if there is a country you want to send SMS to, it’s very likely we can deliver. Please review this post on global sending for a strategy on how to prepare.
• My current provider is more expensive than Pinpoint pricing
  • Our pricing is available on the public pricing page here. Each country has it’s own cost associated with it so enter in the countries you would like to see pricing for. These prices are per message sent so if you are planning on sending to multiple countries factor in the types of messages that you will want to send as well as the countries. If your use case includes 2 way communication make sure to factor the number of inbound messages you expect into your calculations.
    • NOTE: Depending on the language the available characters per message varies, which can affect your calculations on cost. See here for an explanation
• My current provider doesn’t have features that Pinpoint has
  • Among many other features Pinpoint has the ability to send over multiple channels, including: SMS, Email, Push/In-App, Voice, Over the Top (OTT) services such as WhatsApp, as well as interact with third-party APIs giving you the flexibility to send to many other channels.
• My current provider is not native to AWS
  • Pinpoint, being native to the AWS Cloud, boasts the capability to seamlessly integrate with a wide array of services, including AI/ML offerings such as Amazon Personalize, Amazon Bedrock, and Amazon SageMaker, among others. This means you can leverage various AWS services to create innovative solutions that enhance and optimize the communications sent through Pinpoint.
• My current provider does not have good deliverability
  • Price is not the only factor to consider when looking at SMS providers. If you find another provider with lower pricing make sure to ask about their deliverability to the countries you are wanting to send to. There is a big difference between sending an SMS at a low price, and actually delivering that SMS. We are happy to discuss deliverability with you, just reach out to your Account Manager if you have one or contact us to start a conversation about your migration.
• I’m not happy with the customer support of my current provider
  • The SMS landscape is constantly changing and our SMS experts are here to help guide you through the process. Whether it’s regulatory changes, pricing changes, or creating complex architectures to support your needs. Reach out to your Account Manager if you have one or contact us to start a conversation about your migration and get your questions answered.

Regardless of your reason for considering migrating there are four scenarios that most of our customers find themselves in when beginning to plan for an SMS migration.

I have not sent SMS before but I would like to start sending through Pinpoint
Skip ahead to the section on “Checklist for Planning an SMS Migration” to start planning for sending SMS

I have number(s) (Also known as Originators, Origination Identities (OIDs), Toll-Free, 10DLC, Long Code, Short Code, and/or SenderID) with a different provider and I would like to move those to Pinpoint
The ability to “port” numbers from other providers is dependent on the type of originator, the vendor you procured them from, and the country that they support. You may need to get new originators so factor that into your timeline and reach out to your Account Manager to determine whether your originators are able to be ported over. Once you have done that, pull the reports for how much volume you are sending to each country with your current provider and then skip ahead to the section on “Checklist for Planning an SMS Migration” to start planning for sending SMS

I have a current provider but I would like to procure new numbers from Pinpoint
Pull the reports for how much volume you are sending to each country with your current provider and then skip ahead to the section on “Checklist for Planning an SMS Migration” to start planning for sending SMS

I have a current provider but would like to split traffic between them and Pinpoint
Pull the reports for how much volume you are sending to the countries you plan on migrating to AWS and then skip ahead to the section on “Checklist for Planning an SMS Migration” to start planning for sending SMS. Make sure that you consider how you will be managing opt-outs across two providers. Pinpoint offers centrally managed opt-outs but self-management is also an option. All Delivery Receipts/Reporting (DLRs) and inbound/outbound events can be streamed through Amazon Kinesis, Amazon CloudWatch, and/or Amazon Simple Notification Service (SNS) if you need to send those events to another location inside or outside of the AWS Cloud.

Checklist for Planning an SMS Migration

• Setup a spreadsheet similar to the one outlined in this post
• Identify your use case(s)
  • Note whether your use case is one-way or two-way
    • NOTE: Not all countries support 2-way communications, which is the ability to have the recipient send a message back to the OID.
    • NOTE: Sender ID also does not support 2-way communication so if you are planning on using Sender ID you will need to account for how to opt recipients out of future communications.
• Identify your countries
  • Take note of which countries require registration as this will affect your timeline
    • Supported Countries and Regions
• Identify your volume per country
  • If you are already sending SMS with another provider pull a report over a representative time period.
• Identify your throughput needs (Also referred to as Messages per Second, MPS, Transactions per Second, or TPS) for each country
  • Most origination identities are chosen for their ability to support a certain level of MPS, not volume, so if you have seasonality make sure to account for burst rates. There are quotas for the APIs that govern sending as well as quotas for the different types of originators.
• Identify which origination identities you will need for each country using this guide
  • Make note of any countries/OIDs that require registration
  • Reach out to your Account Manager if you have one or contact us to start a conversation about your migration.
  • If you have OIDs you would like to migrate make sure you determine whether that is possible ASAP since your timelines could be affected by the outcome.

Make sure you give ample time for your migration. There are many entities involved in delivering SMS, from governments, to mobile carriers, to third-party registrars, and more, which means that timelines are not always within your control. Ask questions, take advantage of the expert resources we have at AWS, and the content we have produced around these topics.

Content to read

• Review the countries and regions we support here
• Use the format for aggregating information on your use cases outlined in this post here
• Decide what origination IDs you will need here
• Review the documentation for the V2 SMS and Voice API here
• Review the Pinpoint API and SendMessage here
• Check out the support tiers comparison here

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/amazon-pinpoint-10dlc-campaign-types-and-quotas-for-sms/

The following 10DLC Campaigns, or, Use Cases outlined in Table 2 are currently supported by Amazon Pinpoint. As part of the process to register for sending SMS to US based phone numbers you must select at least one Campaign that will be associated with the 10DLC number you procure. If you require more than one Use Case then you will need more than one 10DLC, or you can select the standard mixed use case which supports lower volumes of messages. Throughput is determined based on the company vetting score of the registered sender of the message and what is being sent, not on the amount of numbers associated with the Campaign. For a breakdown of vetting scores and quotas see below:

Throughput and Volume Quotas for 10DLC Vetted Companies

*Note that by default each number associated to a 10DLC campaign supports 1 MPS. In order to increase your numbers to match what your campaign qualifies for by carriers you will be required to submit a MPS increase request.

Table 1

Standard 10DLC Campaign Use Cases

Select the campaign that most closely aligns with your use case(s).

Table 2

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-send-sms-using-configurations-sets-with-amazon-pinpoint/

In a previous blog post we walked through how to manage opt-outs for SMS in Amazon Pinpoint using the V2 SMS and Voice API. The post detailed a scenario where a user needed to manage multiple use-cases such as marketing and One-Time Password (OTP) or Multi-Factor Authentication (MFA). This works great if all of your data can be streamed to a single location, but what if you have multiple business units or you are an Independent Software Vendor (ISV) and need to manage SMS sending for multiple customers? You need a way to not only manage multiple use-cases and opt-out lists, but also sender details and separate event destinations for metrics. Read on to learn how to combine SMS Opt-Out Lists with Configuration Sets to simplify your sending and solve your multi-tenant challenge.

Prerequisites

• In order to manage Configuration Sets you need to use the V2 API for SMS and voice
• You must Purchase/Register an Origination Identity (OID) for each use-case in each country you plan to support.
  • Example: If you are sending marketing materials and OTP messages in the US and are using a short code then you will need to purchase at least two short codes (one for each use-case) and register each use-case.
  • If you need help determining what OID you need use this guide.

The Scenario:
For the sake of simplicity our scenario will use two different senders that need to manage two distinct use-cases but these steps can scale as you need.

SMS Sender 1 Details:

• Sending only in the US
• Sending OTP via a US Short Code
  • Send text events to an Amazon Simple Notification Service (SNS) topic
    • Note: You can control the events you want to stream by using the “MatchingEventTypes” parameter when creating an event destination
  • Send text events to an Amazon CloudWatch destination
• Sending Marketing messages via a 10DLC
  • Send text events to an Amazon Kinesis Data Firehose destination
  • Send text events to an Amazon CloudWatch destination

SMS Sender 2 Details:

• Sending SMS Globally
• Sending OTP via multiple country specific originators
  • Send events to an Amazon Kinesis Data Firehose destination
  • Send all events to an Amazon CloudWatch destination

The V2 SMS and Voice API has several helpful actions to configure this scenario above, some of which will expand upon our previous blog post that covered managing SMS opt-outs so make sure to read that one first and have it handy as you review.

What is a Configuration Set for SMS?

A Configuration Set is a container that is used to hold information about Event Destinations as well as rules that you apply to the SMS messages that you send. Configuration Sets are used when sending messages with the SendTextMessage Action in the V2 API for SMS and voice. When you use SendTextMessage you can specify a Configuration Set that determines how the messages are treated and where the events from that particular send are streamed. The image below explains the concepts we will walk through in this post.

How to Create Configuration Sets and Send SMS
Below we will walk through the steps needed to configure each of the above scenarios. Note that the default quota for Configuration Sets is 25 per account but this can be increased if needed

• Scenario 1 –
  • Short Code Configuration
    • Create a Pool for the US Short Code delivering OTP messages
      • Associate the short code to that Pool by setting “OriginationIdentity” using the PhoneNumberArn of your US Short Code
        • You can use DescribePhoneNumbers to find the values for PhoneNumberArn
        • Note: You can have multiple OIDs per Pool if necessary
        • Note: Opt-Out Lists of OIDs and Pools must match. If you previously associated an Opt-Out List to any OIDs you may need to update those OIDs to match that of the Pool prior to associating it with the Pool
      • Set the IsoCountryCode to “US”
    • Use the “UpdatePool” action to ensure we only send to US phone numbers as well as to create an Opt-Out List specifically for the OTP use-case
      • Set “SharedRoutesEnabled” to False. This will ensure that only the OIDs in this pool will be used to send messages.
        • Since we will only have a US Shortcode in this pool then only US based phone numbers will be sent messages, other destination phone numbers will generate a ConflictException error
          • An error occurred (ConflictException) when calling the SendTextMessage operation: Conflict Occurred – Reason=”NO_ORIGINATION_IDENTITIES_FOUND”
      • Set an Opt-Out List for the Pool by specifying the “OptOutListName”
    • Use the “PutKeyword” action to create at least one Opt-In Keyword
      • This will allow destination numbers to opt back into your use-case
    • Create a Configuration Set
      • This is a container for your Event Destinations which you will set up next. Each configuration set can contain between 0 and 5 event destinations. Each event destination can contain a reference to a single destination, such as a CloudWatch or Kinesis Data Firehose destination
      • Give your Configuration a descriptive name by setting “ConfigurationSetName”
    • Create an SNS Topic that will receive all of the events. Dependent on your needs you can decide where you want to publish these events. Your options are:
      • HTTP/HTTPS
      • Email/Email-JSON
      • Amazon Kinesis Data Firehose
      • Amazon SQS
      • AWS Lambda
      • Platform application endpoint
      • SMS
    • Create a CloudWatch Log Group that will receive all of the events you would like to log
    • Create Event Destinations – Each event destination can contain a reference to a single destination, since we are adding two destinations (SNS and CloudWatch) we will need to make this call twice, once for each destination
      • Create the SNS destination.
        • Set the “ConfigurationSetName” to the Configuration Set you just created
        • Set “MatchingEventTypes” to the event types you are wanting to log
          • Note: See all of the event types available here
        • Set the SNS Event Destination
          • Set the “TopicArn”
      • Create the CloudWatch Destination
        • Set the “ConfigurationSetName” to the Configuration Set you just created
        • Set “MatchingEventTypes” to the event types you are wanting to log
          • Note: See all of the event types available here
            • As an example you might choose to log all of the error events so you can set an alarm
        • Set “IamRoleArn” to the ARN of an Amazon Identity and Access Management (IAM) role that is able to write event data to an Amazon CloudWatch destination
        • Set the “LogGroupArn” to the Log Group in CloudWatch you want the events to stream to
  • 10DLC Configuration
    • • Create a Pool for the 10DLC delivering Marketing messages
        • Associate the 10DLC to that Pool by setting “OriginationIdentity” using the PhoneNumberArn of your 10DLC
          • You can use DescribePhoneNumbers to find the values for PhoneNumberArn
          • Note: You can have multiple OIDs per Pool if necessary
          • Note: Opt-Out Lists of OIDs and Pools must match, so if you previously associated an Opt-Out List to any OIDs you may need to update those OIDs to match that of the Pool prior to associating it with the Pool
        • Set the IsoCountryCode to “US”
      • Use the “UpdatePool” action to ensure we only send to US phone numbers as well as to create an Opt-Out List specifically for the Marketing use-case
        • Set “SharedRoutesEnabled” to False. This will ensure that only the OIDs in this pool will be used to send messages.
          • Since we will only have a 10DLC in this pool then only US based phone numbers will be sent messages, other destination phone numbers will generate an error
        • Set an Opt-Out List for the Pool by specifying the “OptOutListName”
      • Use the “PutKeyword” action to create at least one Opt-In Keyword
      • Create a Configuration Set
        • Give your Configuration a descriptive name by setting “ConfigurationSetName”
      • Create a Kinesis Data Firehose Delivery Stream that will receive all of the events.
        • You can find a list of many options for Kinesis to stream to here
      • Create a CloudWatch Log Group that will receive all of the events you would like to log
      • Create Event Destinations – Each event destination can contain a reference to a single destination. We are adding two destinations (SNS and CloudWatch) so we need to make this call twice, once for each destination
        • Create the Kinesis destination.
          • Set the “ConfigurationSetName” to the Configuration Set you just created
          • Set “MatchingEventTypes” to the event types you are wanting to log
          • Set the Kinesis Event Destination
            • Set the “DeliveryStreamArn” to the Stream you created earlier
            • Set the “IamRoleArn” to the ARN of an IAM role that is able to write event data to an Amazon Firehose destination
        • Create the CloudWatch Destination
          • Set the “ConfigurationSetName” to the Configuration Set you just created
          • Set “MatchingEventTypes” to the event types you are wanting to log
          • Set “IamRoleArn” to an IAM role that is able to write event data to an Amazon CloudWatch destination
          • Set the “LogGroupArn” to the Log Group in CloudWatch you want the events to stream to
• Scenario 2
  • Global OTP Configuration
    • Create a Pool for delivering the OTP messages
      • Associate all of your OIDs being used to that Pool
        • You can use DescribePhoneNumbers to find the values for PhoneNumberArn
        • Note: Opt-Out Lists of OIDs and Pools must match, so if you previously associated an Opt-Out List to any OIDs you may need to update those OIDs to match that of the Pool prior to associating it with the Pool
    • Use the “UpdatePool” action to create an Opt-Out List specifically for the OTP use-case.
      • Set an Opt-Out List for the Pool by specifying the “OptOutListName”
    • Use the “PutKeyword” action to create at least one Opt-In Keyword
      • This will allow destination numbers to opt back into your use-case, in this case OTP
    • Create a Configuration Set
      • Give your Configuration a descriptive name by setting “ConfigurationSetName”
    • Create a Kinesis Data Firehose Delivery Stream that will receive all of the events
      • You can find a list of many options for Kinesis to stream to here
    • Create a CloudWatch Log Group that will receive all of the events you would like to log
    • Create Event Destinations – Each event destination can contain a reference to a single destination, since we are adding two destinations (SNS and CloudWatch) we will need to make this call twice, once for each destination
      • Create the Kinesis destination.
        • Set the “ConfigurationSetName” to the Configuration Set you just created
        • Set “MatchingEventTypes” to the event types you are wanting to log
          • Note: See all of the event types available here
        • Set the Kinesis Event Destination
          • Set the “DeliveryStreamArn” to the Stream you created earlier
          • Set the “IamRoleArn” to the ARN of an IAM role that is able to write event data to an Amazon Firehose destination
      • Create the CloudWatch Destination
        • Set the “ConfigurationSetName” to the Configuration Set you just created
        • Set “MatchingEventTypes” to the event types you are wanting to log
          • Note: See all of the event types available here
            • As an example you might choose to log all of the error events so you can set an alarm
        • Set “IamRoleArn” to an IAM role that is able to write event data to an Amazon CloudWatch destination
        • Set the “LogGroupArn” to the Log Group in CloudWatch you want the events to stream to

Your configuration should look like this once you have completed the above steps

How to Send Your Messages

• Send your SMS with the “SendTextMessage” action
  • Set the “ConfigurationSetName” using either the ConfigurationSetName or ConfigurationSetArn
    • You can find these using the “DescribeConfigurationSets” action
    • This field is used for any country-specific registration requirements. Currently, this setting is only used when you send messages to recipients in India using a sender ID.
  • Use either PoolId, or PoolArn for “OriginationIdentity”
    • You can find these using the “DescribePools” action

Conclusion

In this post you have learned how to create Configuration Sets that give you more control over how you send SMS. Using Configuration Sets allows you to simplify your sending while maintaining multiple sending configurations and event destinations . The V2 API for SMS and Voice has many more useful actions not possible with the V1 API so we encourage you to explore how it can further help you simplify and automate your applications.

Review the documentation for the V2 SMS and Voice API here
Confirm the origination IDs you will need here
Check out the support tiers comparison here

Resources
https://docs.aws.amazon.com/pinpoint/latest/apireference_smsvoicev2/Welcome.html
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-originating-identities-choosing.html
https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-limitations-opt-out.html
https://docs.aws.amazon.com/pinpoint/latest/developerguide/sms-voice-v2-pools.html
https://docs.aws.amazon.com/pinpoint/latest/developerguide/sms-voice-v2-configuration-sets.html
https://docs.aws.amazon.com/pinpoint/latest/developerguide/sms-voice-v2-keywords.html