How to build international two-way SMS with Amazon Connect Customer, Part 1

Introduction

International two-way SMS with Amazon Connect Customer requires navigating country-specific telecom regulations, origination identity types, and registration processes.

Contact centers serving global customers need to reach them via SMS in their local country, but each country has different origination identity types, registration requirements, and two-way messaging capabilities. Amazon Connect Customer natively supports two-way SMS through its integration with AWS End User Messaging (EUM). You can import phone numbers and route SMS contacts through flows. However, reaching the UK, Germany, Australia, India, the UAE, and other countries simultaneously, with dynamic origination identity selection and custom session management, requires an extended architecture using phone pools and AWS Lambda-based routing.

This two-part series shows you how to build a multi-country SMS architecture using Amazon Connect Customer and AWS End User Messaging (EUM). Part 1 (this post) covers the challenge and the solution architecture so you understand the full design. Part 2 walks through the implementation of a sample project, including the country routing AWS Lambda function, configuration, and deployment steps.

Here, you learn how to register country-specific origination identities and how they group into phone pools for automatic routing, and how the messaging integration links SMS delivery to agent chat sessions so that agents work from a single inbox regardless of where the customer is located.

This post also covers country-specific nuances, such as the difference between sender IDs (outbound-only) and short codes or long codes (which support two-way messaging), and pool configuration requirements such as using the TRANSACTIONAL message type for interactive agent conversations, which require careful attention during international rollouts.

Solution overview and architecture

The following design extends the native capability using real-time chat message streaming for bidirectional message flow between SMS customers and Amazon Connect Customer through AWS End User Messaging.

Inbound path (customer sends SMS)

1. A customer sends a text message to the phone number managed by AWS End User Messaging.
2. AWS End User Messaging receives the message and delivers it to an Amazon SNS topic through the two-way SMS configuration.
3. Amazon SNS triggers an AWS Lambda function (Inbound SMS Handler) to process the incoming message. The AWS Lambda function identifies the customer by their phone number and reads the message content.
4. The Inbound SMS Handler checks Amazon DynamoDB to determine whether this customer already has an open conversation.If no active conversation exists, the handler creates a new session:
   1. Calls the StartChatContact API, which returns a ContactId and ParticipantToken. The handler passes the customer’s phone number and channel type (SMS) as contact attributes.
   2. Calls StartContactStreaming with the SNS topic ARN to activate real-time message streaming, so that outbound messages from Amazon Connect Customer are published to Amazon SNS.
   3. Calls CreateParticipantConnection with ConnectParticipant set to true, which signals that the customer is ready to receive messages and triggers contact flow execution. This call must occur within five minutes of StartChatContact.
   4. Stores the session details (ContactId, ParticipantToken, and customer phone number) in Amazon DynamoDB for future messages.

   If the customer already has an active conversation, the handler reconnects them to the existing session using the stored ParticipantToken.

5. The message is delivered into the Amazon Connect Customer chat through the Amazon Connect Participant Service and the contact flow routes it to the appropriate queue/agent.

Outbound path (a message is sent from Amazon Connect Customer to SMS)

1. Amazon Connect Customer sends a message to the customer participant. Amazon Connect Customer publishes the message to the outbound SNS topic through the streaming configuration.Note: Messages published through this path can originate from a human agent, an Amazon Lex bot, an AI agent, or an automated contact flow action such as a PlayPrompt block. The streaming path is the same regardless of source.
2. An Amazon SNS subscription delivers the message to an Amazon SQS queue. While you can invoke the Outbound SMS Handler directly from SNS, the SQS queue adds retry handling and dead-letter queue support for failed messages. This is optional, but the remainder of this post assumes the SQS queue is in place.
3. The message in the Amazon SQS queue triggers the Outbound SMS Handler AWS Lambda function.
4. Outbound SMS Handler looks up the conversation in Amazon DynamoDB using the contact ID to retrieve the customer’s phone number and channel type.
5. The handler sends the reply to the customer through the AWS End User Messaging SMS service, using the configured business origination number.
6. The customer receives the message as a text on their phone.

How two-way SMS works in this architecture

Inbound (customer to agent): A customer in the UK texts your UK long code. AWS End User Messaging receives the message on that origination identity and publishes it to an Amazon SNS topic. SNS triggers the Inbound SMS Handler AWS Lambda function, which checks Amazon DynamoDB for an existing conversation. If none exists, AWS Lambda creates a new chat session through the Amazon Connect Participant Service, activates real-time message streaming, and stores the session details in Amazon DynamoDB. If a session already exists, AWS Lambda reconnects the customer to it.

The message is delivered into the Amazon Connect Customer chat, where the contact flow checks the sender’s country code (+44), sets the locale to English (UK), and routes the contact to the International Support queue. The agent sees the conversation in their Connect workspace alongside voice and chat.

The four layers

A. Amazon Connect Customer (agent workspace) is where agents handle SMS alongside voice and chat. Contact flows also send automated messages through this layer via Lex bots, AI agents, and PlayPrompt blocks. Contact flows control inbound routing, checking the sender’s country code and setting the locale before assigning the right queue. For outbound, Amazon Connect Customer publishes messages to the SNS topic that was configured in the initial StartContactStreaming API call. These messages may come from agents typing in the workspace, Lex bots, AI agents, or automated contact flow actions. Agents interact with this layer directly. The remaining layers operate behind the scenes.

B. Messaging integration (Amazon SNS, Amazon SQS, AWS Lambda, Amazon DynamoDB) is the bridge between Amazon Connect Customer and AWS End User Messaging. For inbound messages, SNS receives events from EUM and triggers the Inbound SMS Handler AWS Lambda function. This function checks Amazon DynamoDB for an existing conversation. If one exists, it reconnects the chat session. Otherwise, it creates a new session through the Amazon Connect Participant Service and stores the session state. For outbound, the SNS topic streams all contact events (messages, participant events, and typing indicators) to an SQS queue, which triggers the Outbound SMS Handler AWS Lambda function. The handler filters for message content and discards non-message events. This handler looks up the conversation in Amazon DynamoDB and determines whether the destination is US/Canada (routed through the International Toll-Free Number (ITFN)) or international (routed through the international phone pool, where EUM selects the correct origination identity from your registered numbers). Amazon DynamoDB serves as the session store throughout, linking customer phone numbers to active Connect chat sessions.

C. AWS End User Messaging (delivery layer) manages phone pools and origination identities. A phone pool groups origination identities from multiple countries together. When a message is sent through a pool, EUM selects the correct origination identity based on the destination country code. For inbound, each two-way-enabled origination identity publishes received messages to the SNS topic configured in the messaging integration layer, completing the inbound loop.

D. Country registration (compliance layer) must be completed before any messages flow. Each target country supports different origination identity types, each with distinct registration requirements, timelines, and two-way messaging capabilities. Plan phone number acquisition well in advance. Published registration timelines assume approval on the first attempt. Rejections due to incomplete documentation or compliance gaps can delay phone number availability.

How the layers connect: An inbound SMS flows D to C to B to A (the registered origination identity in EUM receives the message, publishes to SNS, AWS Lambda processes it through Amazon DynamoDB, and creates or reconnects a chat session in Connect). An outbound SMS flows A to B to C to D. Connect streams outbound events through SNS and SQS to the Outbound AWS Lambda, which filters for message content, looks up the session in Amazon DynamoDB, resolves the pool ID, and sends through EUM to the correct registered identity. The messaging integration layer (B) handles both directions, with Amazon DynamoDB maintaining session continuity across message exchanges.

Prerequisites

To apply the concepts in this post, you should have the following in place:

• An active AWS account
• An Amazon Connect Customer instance with the SMS channel enabled
• Access to AWS End User Messaging
• Your target country list, with the required origination identity types identified

Part 2 covers the detailed setup prerequisites for building the sample project.

Country requirements

Before registering numbers, map out your target countries and the origination identity types each supports. This is a common source of configuration errors, particularly around two-way capability.

A common misconception is that if a country requires sender ID registration, that country must be one-way only. Sender IDs are outbound-only by nature, but many of these same countries also support short codes or long codes that support two-way messaging. Check the AWS End User Messaging supported countries table for the full picture.

Registration timelines: Short codes take 8 to 12 weeks in most regions. Start the registration process during the design phase, not during implementation.

Sender ID + long code pairing: In countries where you use a sender ID for branded outbound, pair it with a long code for inbound. Customers see your brand name on outbound messages and can reply to the long code number.

Choosing origination identities

Each country supports different origination identity types, and the type you register determines your two-way capability and your lead time. The countries below are examples of the decisions you will face; apply the same reasoning to your own target list:

• US and Canada (example): An ITFN covers both countries for two-way SMS. Confirm your ITFN is provisioned for Canadian delivery, as not all ITFNs cover Canada under the +1 country code. Higher-throughput options (10-Digit Long Code, short code) exist if you need them.
• UK: A long code handles two-way. A sender ID is required for branded outbound but is outbound-only, so it pairs with the long code for inbound replies.
• India: A short code provides two-way. A sender ID (registered through the Distributed Ledger Technology, or DLT, process) is outbound-only. A long code can serve inbound-only needs such as opt-out handling.
• UAE: A short code provides two-way. A sender ID (registered through the local carriers) is outbound-only.

The pattern that matters: a sender ID never provides two-way on its own, so a country that “requires a sender ID” is not automatically one-way. Pair it with a short code or long code for inbound. Part 2 covers the console steps and per-country registration timelines.

Phone pools

Phone pools group multiple origination identities together. When you send a message through a pool, EUM selects the correct origination identity based on the destination country. For US and Canada, you send directly through your ITFN, so no pool is needed. For other countries, you can create an international phone pool containing origination identities for each target country.

Dedicated pool routing vs. shared routes

Dedicated pool routing (default): When you send through a pool, EUM selects the origination identity that matches the destination country from your registered identities in that pool. This requires no “shared routes” enablement.

Shared routes (optional fallback): When enabled, EUM attempts to deliver messages to countries where you have no dedicated identity in the pool, using AWS-maintained shared origination identities (generic sender IDs, which vary by country). Shared routes are subject to increased downstream filtering. Dedicated routes are recommended.

Pool configuration matching

Every origination identity you add to a pool must match the pool’s configuration. The pool inherits its settings from the first origination identity you add, including two-way messaging status, message type, opt-out list, and self-managed opt-out configuration. You cannot mix configurations within a single pool.

Message type requirement

When you create a pool, you set a message type that cannot be changed afterward. For this solution, use TRANSACTIONAL. Agent conversations with customers are time-sensitive, interactive messages, which is what the TRANSACTIONAL type is designed for. It also provides higher delivery priority than PROMOTIONAL. The PROMOTIONAL type exists for non-critical marketing campaigns and is not appropriate for two-way contact center messaging, so it is not used here. Because the message type is fixed at creation and every origination identity in the pool must share it, create your pool as TRANSACTIONAL from the start.

Part 2 provides the AWS CLI commands to create the pool and associate each origination identity.

The messaging integration

The messaging integration layer is what bridges Amazon Connect Customer and AWS End User Messaging. Rather than the deployment steps (which Part 2 covers), here is what each component does and why it is in the design:

• Amazon DynamoDB session table: Holds active-conversation state, linking a customer phone number to its Amazon Connect Customer chat session so that replies find the right contact.
• Two Standard SNS topics: One receives inbound SMS events from EUM; one receives outbound streaming events from Amazon Connect Customer. They must be Standard type (the streaming APIs do not support FIFO) and in the same Region as your instance. The outbound topic carries all contact events, not just messages, so the outbound handler filters for message content.
• Amazon SQS queue: Buffers outbound events between SNS and the outbound handler, adding retry handling and a dead-letter queue for failed sends. Optional, but assumed throughout this design.
• Two AWS Lambda functions: The inbound handler creates or reconnects chat sessions; the outbound handler resolves the session and sends the SMS through EUM with country-based routing.

A note on permissions: each function follows least privilege. The inbound handler needs only to start contacts and write session state; the outbound handler needs only to read session state and send messages. The SNS topic that Amazon Connect Customer publishes to needs a resource-based policy scoped with aws:SourceAccount and aws:SourceArn conditions to prevent cross-service confused-deputy issues. Part 2 provides the exact policies.

Note: The StartContactStreaming and StopContactStreaming APIs have default service quotas that may impact high-volume deployments. Review the Amazon Connect Customer service quotas documentation and request increases through the Service Quotas console before going to production.

The routing decision

Outbound messages need to leave from the right number for each destination. With the ITFN handling US and Canada directly, the routing logic makes one decision: is the destination domestic or international? Domestic goes through the ITFN; international goes through the phone pool, where EUM selects the correct origination identity for the destination country.

The insight that shapes this logic: whether a country can do two-way SMS depends on what you have registered, not on what the country theoretically supports. If you have registered only a sender ID for a country, inbound has to fall back to another channel until you register a short code or long code. Your routing logic should reflect your current registration state, not the country’s capabilities.

A minimal version of that decision looks like this:

def get_origination(destination_number):
    country = resolve_country(destination_number)   # see Part 2
    if country in ("US", "CA"):
        return ITFN_ID              # domestic: send via the ITFN
    return INTERNATIONAL_POOL_ID    # international: pool picks the identity

Part 2 provides the routing function, the approach to resolving a country from a destination number (which is non-trivial and best handled by an established E.164 parsing library rather than inline prefix matching), and how to externalize the country configuration so adding a country does not require redeploying code.

Integrate with Amazon Connect Customer

With identities registered, pools configured, and the messaging integration deployed, the final step connects everything to the agent workspace. The outcome: SMS contacts arrive in the same workspace as voice and chat, and a contact flow routes them by country.

Conceptually, the inbound handler passes contact attributes (such as channel and customer phone number) when it starts the chat contact. The contact flow reads those attributes to branch:

• Confirms the contact is SMS (versus voice or chat)
• Determines the sender’s country
• Sets the language or locale
• Routes to the appropriate queue
• Optionally hands off to a self-service bot before an agent

Part 2 provides the number-claiming steps and the contact-flow configuration.

Handle edge cases

Not every country supports full two-way SMS natively. The following scenarios address common gaps and transitional approaches.

Countries with sender ID only (no short code registered)

For countries where you have only registered a sender ID without a short code, send outbound notifications through the sender ID and include a callback URL or WhatsApp link in the message for the customer to respond. Route inbound responses through WhatsApp Business messaging or web chat. Agents see all channels in the same Connect workspace.

This is a transitional approach. For countries such as India and UAE, registering a short code removes the need for this workaround.

Opt-out management

For the US and Canada, the STOP keyword must be honored, and EUM handles this automatically through the ITFN. In the EU, General Data Protection Regulation (GDPR) consent requirements apply, so you must maintain explicit opt-in records. In India, the Do Not Disturb (DND) registry applies and EUM checks it automatically.

EUM maintains opt-out lists per pool and honors them automatically. Part 2 covers how to configure them.

Failover and redundancy

Add multiple origination identities per country to your pool for redundancy. If one identity has delivery issues, EUM routes through the next available. For business-critical messaging, implement redundant channels (SMS, WhatsApp, and email). Monitor delivery rates per origination identity using Amazon CloudWatch metrics published by EUM.

Country requirements reference

For each target country, evaluate the following dimensions:

• Supported origination types (ITFN, 10DLC, long code, short code, sender ID)
• Two-way SMS capability per origination type
• Registration requirements (varies by type and country)
• Typical registration timelines

Refer to the AWS End User Messaging supported countries documentation (linked in the For more information section) for current details.

Cost considerations

SMS costs have three additive components:

• An Amazon Connect Customer (or Amazon Connect Basic) per-message usage fee
• An AWS End User Messaging carrier delivery fee (varies by destination country)
• Phone number monthly lease fees (vary by type)

Refer to the pricing pages (linked in the For more information section) for current rates.

Conclusion

In this post, you learned the architecture for international two-way SMS with Amazon Connect Customer and AWS End User Messaging: the four layers, how inbound and outbound messages flow, and the country-registration considerations that shape the design. In Part 2, you build it, deploying the inbound and outbound handlers, the session store, and the country routing logic, and wiring everything into Amazon Connect Customer.

Before assuming a country is one-way only, check the AWS supported countries table. Countries such as India and UAE support two-way SMS through short codes, even though their sender IDs are outbound-only. The origination identity type you register determines your capability, not the country alone.

To get started, identify your target countries, check which origination types each supports, and plan your registrations early. Part 2 walks through building and deploying the solution.

For more information

The following resources provide additional detail on the services and configurations discussed in this post:

• Supported countries and regions for SMS messaging
• Phone pools in AWS End User Messaging
• Setting up SMS in Amazon Connect Customer
• AWS End User Messaging pricing
• Amazon Connect Customer pricing

Authors