Sending RCS messages

AWS End User Messaging uses the same SendTextMessage API for both RCS and SMS delivery. How the service routes your message depends on the origination identity you specify in the request. You can send messages through a phone pool (recommended), at the account level, or directly through an AWS RCS Agent ARN.

This section explains the three sending patterns, how to interpret delivery receipts, and provides code examples. For details on sticky sending, origination identity priority order, and automatic SMS fallback, see RCS to SMS fallback using phone pools. For details on managing AWS RCS Agents, see Managing RCS agents.

Sending patterns

AWS End User Messaging supports three patterns for sending RCS messages. Each pattern determines how the service selects an origination identity and whether automatic SMS fallback is available.

Pool-based sending (recommended)

Pool-based sending is the recommended approach for all RCS use cases. When you specify a pool ID as the origination identity in your SendTextMessage request, AWS End User Messaging selects the best origination identity from the pool based on the destination, channel availability, and sticky sending history.

If the pool contains both an AWS RCS Agent and SMS phone numbers, the service attempts RCS delivery first. If RCS delivery fails, the service automatically falls back to SMS using a phone number from the same pool. Because all identities in the pool are registered for the same use case, the fallback message is always sent from an appropriate number.

For details on creating and configuring pools with AWS RCS Agents, see RCS to SMS fallback using phone pools.

Account-level sending

When you omit the origination identity from your SendTextMessage request, AWS End User Messaging selects an origination identity from all available identities in your account. The service uses the origination identity priority order to determine which identity to use. For details, see Fallback logic and priority order.

Direct send (RCS only)

When you specify an AWS RCS Agent ARN as the origination identity in your SendTextMessage request, AWS End User Messaging sends the message via RCS only. There is no automatic SMS fallback. If RCS delivery fails, the message is not retried on another channel.

Use direct sending when:

Sticky sending, priority order, and SMS fallback

When you send messages through a pool or at the account level, AWS End User Messaging uses sticky sending (a 25-hour routing optimization), an origination identity priority order, and automatic SMS fallback to select the best channel and identity for each message. For complete details on how these mechanisms work, including automatic fallback, delivery receipts during fallback, and billing implications, see RCS to SMS fallback using phone pools.

Code examples

The following Python examples demonstrate how to send RCS messages using each of the three sending patterns. All examples use the boto3 pinpoint-sms-voice-v2 client and the SendTextMessage API.

Pool-based sending example

The following example sends a message through a phone pool. The service selects the best origination identity from the pool and automatically falls back to SMS if RCS delivery is not possible.

import boto3

client = boto3.client('pinpoint-sms-voice-v2')

response = client.send_text_message(
    DestinationPhoneNumber='+12065550100',
    OriginationIdentity='pool-a1b2c3d4e5f6g7h8i',
    MessageBody='Your appointment is confirmed for tomorrow at 2:00 PM.',
    MessageType='TRANSACTIONAL'
)

print(f"Message ID: {response['MessageId']}")
            

Account-level sending example

The following example sends a message at the account level by omitting the origination identity. The service selects an identity from all available identities in your account using the priority order.

import boto3

client = boto3.client('pinpoint-sms-voice-v2')

response = client.send_text_message(
    DestinationPhoneNumber='+12065550100',
    MessageBody='Your verification code is 123456.',
    MessageType='TRANSACTIONAL'
)

print(f"Message ID: {response['MessageId']}")
            

Direct send example

The following example sends a message directly through an AWS RCS Agent ARN. The message is delivered via RCS only, with no SMS fallback.

import boto3

client = boto3.client('pinpoint-sms-voice-v2')

response = client.send_text_message(
    DestinationPhoneNumber='+12065550100',
    OriginationIdentity='arn:aws:sms-voice:us-east-1:123456789012:rcs-agent/rcs-a1b2c3d4',
    MessageBody='Welcome to our RCS channel! Reply HELP for assistance.'
)

print(f"Message ID: {response['MessageId']}")
            

AI agent prompt for sending RCS messages

If you use a generative AI coding assistant or AI agent, you can use the following prompt to get help sending RCS messages using the AWS CLI or SDK.

## RCS Messaging Assistant Prompt

Help me send RCS messages using AWS End User Messaging SMS with the
`pinpoint-sms-voice-v2` service. Show me exact CLI commands and Python/boto3
examples. Ask me for my details before generating any commands.

**Important rules for generating commands:**
- The API is `send-text-message` — the same command used for SMS. There is
  NO separate RCS send API.
- There is NO `describe-messages` API. Do not generate it.
- The boto3 method is `send_text_message` on the
  `pinpoint-sms-voice-v2` client.
- Use the term "testing" — NOT "sandbox".

**Prerequisites:** I have an existing RCS agent (created via the setup process)
and a verified test device.

### Pattern 1: Direct RCS sending (simplest, good for testing)

Send directly through my RCS Agent ARN. RCS-only delivery, no SMS fallback.
If the recipient's device doesn't support RCS, the message is not delivered.

CLI: `send-text-message --destination-phone-number <E.164>
--origination-identity <agent-arn> --message-body "<text>"
--message-type <TRANSACTIONAL|PROMOTIONAL>`

Returns `MessageId`.

### Pattern 2: Pool-based sending (recommended for production)

Send through a phone pool containing my RCS agent (and optionally SMS phone
numbers for fallback). The service tries RCS first, then falls back to SMS
asynchronously if no RCS signal within 25 seconds. This is NOT synchronous
fallback — the SMS is sent as a separate attempt after the timeout.

To set up a pool:
- `create-pool --origination-identity <rcs-agent-id> --message-type TRANSACTIONAL` → returns `PoolId`
- Optionally add SMS numbers: `associate-origination-identity --pool-id <id>
  --origination-identity <phone-number-id>`

CLI: `send-text-message --destination-phone-number <E.164>
--origination-identity <pool-id> --message-body "<text>"
--message-type <TRANSACTIONAL|PROMOTIONAL>`

### Pattern 3: Account-level sending

Send without specifying `--origination-identity`. The service auto-selects
the best identity from the account.

CLI: `send-text-message --destination-phone-number <E.164>
--message-body "<text>" --message-type <TRANSACTIONAL|PROMOTIONAL>`

**Compliance warning:** If the account has multiple RCS agents, SMS numbers,
or different use cases, the service picks an identity automatically — which
may not be the intended one. Use pool-based or direct sending for explicit
control over which identity is used.

### Delivery verification

- For testing: check the test device directly — the message appears from
  the branded RCS agent.
- For production: configure event destinations BEFORE sending using
  `create-event-destination` (SNS, CloudWatch Logs, or Firehose). Event
  destinations do not retroactively capture events for already-sent messages.
- CloudWatch metrics in `AWS/SMSVoice` namespace provide aggregate delivery
  statistics.

### Behavioral notes

- Sticky sending: the service remembers the last successful identity per
  destination number for 25 hours.
- Pool-based sending is recommended for production because it provides
  automatic SMS fallback.
- All three patterns use the same `send-text-message` API — the only
  difference is what you pass (or don't pass) as `--origination-identity`.

---

**Before generating commands, ask me for:**
- Which sending pattern I want to use (direct, pool-based, or account-level)
- My RCS Agent ARN
- My pool ID (if using pool-based sending)
- Destination phone number in E.164 format
- Message type (TRANSACTIONAL or PROMOTIONAL)
- Message text
            

Delivery receipt handling

AWS End User Messaging provides delivery receipts for RCS messages through Amazon EventBridge and configuration set event destinations. Delivery receipts indicate the final status of your message and which channel was used for delivery. To learn how to set up event destinations to capture delivery receipts and other message events, see Event destinations in AWS End User Messaging SMS.

Delivery status values

The following delivery status values apply to RCS messages:

Channel attribution

Delivery receipts include channel attribution that indicates whether the message was delivered via RCS or SMS. This is important for understanding your delivery mix and for billing purposes.

For details on RCS CloudWatch metrics and monitoring delivery patterns, see RCS CloudWatch metrics and monitoring. For information about how delivery channel affects billing, see RCS billing and pricing model.