AWS Messaging Blog
Creating and testing an End User Messaging RCS agent with AWS CLI
A step-by-step walkthrough for setting up a Rich Communication Services (RCS) test agent, from brand assets to verified inbound messaging.
If you’re still sending plain SMS, you’re leaving a significant experience gap on the table. SMS gives you 160 characters of unformatted text, no branding, and zero confirmation that your message was even read. Rich Communication Services (RCS) changes that entirely. It delivers branded carousels, read receipts, typing indicators, high-resolution images, and verified sender identity, all through the native messaging app your customers already use. No app download required, no new account to create.
Compared to over-the-top (OTT) platforms like WhatsApp or iMessage for Business, RCS doesn’t fragment your audience. It works on an Android’s default messaging app with RCS enabled or an iPhone on iOS 18 or later, which means you reach users where they already are. You are not limited to the ones who happen to have a specific app installed. And compared to building a custom in-app messaging experience, RCS requires no SDK, no UI work, and no convincing users to enable notifications.
With AWS End User Messaging, standing up an RCS agent is surprisingly fast. You configure your brand assets, submit a registration, and within minutes you have a test agent sending branded messages through production APIs. This is real infrastructure, not a sandbox. That means you can prototype, validate your integration, and show stakeholders a working demo before committing to a full build.
This post walks through the entire process of creating an RCS test agent using only the AWS Command Line Interface (AWS CLI). Using the CLI means every step is a repeatable, scriptable command. Need to spin up another agent in a different account or Region? Run the same script and you’re done in minutes. By the end, you will have a working agent that can send branded messages to verified testers and receive inbound messages with automatic responses.
What you will build
In this walkthrough, you will:
- Create an RCS agent and configure its brand identity (logo, banner, accent color).
- Submit a test registration for automated approval.
- Add a verified tester device.
- Send your first branded RCS message.
- Configure and verify inbound messaging with an automatic keyword response.
Prerequisites
Before you begin, confirm you have:
- An AWS account with access to AWS End User Messaging (Amazon Pinpoint SMS and Voice v2 API)
- AWS CLI v2.35.12 or later installed and configured with credentials that have
pinpoint-sms-voice-v2:*permissions. Version 2.35.12 adds thesend-rcs-messagecommand, which you will need for rich media messages (rich cards, carousels, and suggestion chips) beyond this walkthrough. For production deployments, scope the IAM policy down to only the specific actions your application requires. Thepinpoint-sms-voice-v2:*scope is convenient for testing but broader than necessary. - rsvg-convert for generating brand asset images from SVG (install with
brew install librsvgon macOS) - A test phone that supports RCS messaging.
Verify your setup:
If you use a named AWS CLI profile, append --profile <your-profile> to every AWS command in this walkthrough.
Step 1: Create the RCS agent
The first step is to create an empty RCS agent container. The agent’s display name and branding come from the registration you will configure in Step 2.
Expected output:
Save the RcsAgentId and RcsAgentArn values. You will use them throughout this walkthrough.
Next, enable deletion protection to prevent accidental removal. This is especially important once carrier approvals are in place, since re-creating an agent requires a new registration and approval cycle:
Step 2: Generate brand assets
Your RCS agent needs a logo (224×224 px, must be under 50 KB as PNG) and a banner (1440×448 px, must be under 200 KB as PNG). Both must be JPEG or PNG format. You can use your own designs as long as they meet these dimension and size requirements. In this example, we generate them as SVGs and convert to PNG.
Create the logo SVG
Create a file named brand-assets/logo.svg:
Create the banner SVG
Create a file named brand-assets/banner.svg:
Convert to PNG
Verify the file sizes. The logo must be under 50 KB and the banner under 200 KB:
Step 3: Create and configure the registration
RCS agents require a registration that contains all brand details. For testing, use the TEST_RCS_LAUNCH_REGISTRATION type.
Create the registration
Expected output:
Save the RegistrationId.
Link the registration to your agent
Upload brand assets
Upload the logo and banner as registration attachments. Note that --attachment-body and --attachment-url cannot be used together. Use --attachment-body with the fileb:// prefix:
Set registration fields
The registration has 23 fields. Each field has a specific type that determines which CLI parameter to use:
| Field type | CLI parameter | Example |
| TEXT | --text-value |
--text-value "My Brand" |
| SELECT | --select-choices |
--select-choices "MULTI_USE" |
| ATTACHMENT | --registration-attachment-id |
--registration-attachment-id "attachment-abc123" |
Do not use --field-values. That parameter does not exist in this CLI.
Set all the TEXT fields:
Set the SELECT fields. These use --select-choices instead of --text-value:
Set the ATTACHMENT fields. These use --registration-attachment-id:
A note on accent color
The accent color must meet a 4.5:1 contrast ratio against white. This is the WCAG AA accessibility standard, enforced to make sure the text is readable for users with visual impairments. Colors with an HSL lightness value above ~45% will typically fail this threshold and be rejected with ACCENT_COLOR_CONTRAST_INSUFFICIENT. Safe choices include #0D47A1 (blue), #1B5E20 (green), #BF360C (orange), #B71C1C (red), and #4A148C (purple). If you are using a custom brand color, verify it passes before submitting using the WebAIM Contrast Checker.
Submit the registration
Expected output:
Step 4: Wait for approval
Poll the registration and agent status. Test registrations typically complete within a few minutes.
You will see the status progress through these stages:
| Registration status | Agent status | Testing status | Meaning |
| SUBMITTED | PENDING | PENDING | Under review |
| REVIEWING | PENDING | PENDING | Automated checks in progress |
| COMPLETE | TESTING | ACTIVE | Ready to use |
Wait until TestingAgent.Status shows ACTIVE before proceeding.
NOTE: If the registration returns REQUIRES_UPDATES, run describe-registration-field-values to find fields with a DeniedReason. Create a new registration version with create-registration-version, re-populate all 23 fields (new versions do not inherit values), fix the issue, and re-submit.
Step 5: Add a verified tester
Wait at least 120 seconds after agent creation before adding testers. Then register your test device:
You will receive a tester invitation on your phone within 2 to 20 minutes from “RBM Tester Management.” On iPhone, check the Unknown Senders folder. Tap “Make me a tester” to accept.
After accepting, verify the status:
Expected output once accepted:
Step 6: Send your first RCS message
Before sending, check for potential blockers.
Check the protect configuration
Verify that the US is not blocked in your account’s default protect configuration:
If the US status is BLOCK, update it to ALLOW:
Check the opt-out list
If your test number appears in the list, remove it:
Now, send the test message:
Expected output:
Check your phone. You should see a branded message from your agent with the logo and accent color you configured. On iPhone, check the Unknown Senders folder.
Step 7: Configure and test inbound messaging
With inbound messaging, your agent can respond to messages that testers send back. Configure an automatic keyword response, then verify it end to end.
Set up an automatic keyword response
The put-keyword API configures an automatic reply when someone sends a specific keyword to your agent. With it, you can verify inbound messaging without writing any backend code:
Test inbound messaging
While the previous steps used the CLI exclusively, the inbound testing deep link is most easily accessed through the console. Navigate to your agent and use the Testing tab to generate the deep link:
- Open the AWS End User Messaging console: https://console.aws.amazon.com/sms-voice/home?region=[REGION]#/rcs-agents.
- Select your agent and choose the Testing tab.
- Choose Inbound deep link.
- Enter RCSINBOUNDTESTING in the message body field.
- Choose Generate link.
- Scan the QR code with your test phone. The message is pre-filled.
- Send the message.
You should receive the automatic response: “Inbound test successful! Your message was received.”
Clean up
To avoid unexpected charges, remove the resources created during this walkthrough when you are finished testing. You must delete resources in the following order. Attempting to delete the agent before its registration results in a ConflictException: RESOURCE_NOT_EMPTY error.
If you modified the protect configuration (changed US from BLOCK to ALLOW), revert it to its original state if your account does not need US messaging enabled.
Summary
You now have a working RCS test agent that can send and receive branded messages. Here is a recap of the resources created:
| Resource | Value |
| Agent ID | rcs-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 |
| Registration ID | registration-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 |
| Region | us-east-1 |
| Console | https://us-east-1.console.aws.amazon.com/sms-voice/home?region=us-east-1#/rcs-agents |
Registration field reference
For reference, here is the complete list of registration fields and their types:
| Field | Type | Requirement |
agentDetails.brandName |
TEXT | Required |
agentDetails.serviceName |
TEXT | Required |
agentDetails.senderDisplayName |
TEXT | Required |
agentDetails.useCase |
SELECT | Required |
agentDetails.agentDescription |
TEXT | Required |
agentDetails.bannerImage |
ATTACHMENT | Required |
agentDetails.logoImage |
ATTACHMENT | Required |
agentDetails.accentColor |
TEXT | Required |
agentDetails.contactPhoneNumber |
TEXT | Conditional |
agentDetails.contactPhoneLabel |
TEXT | Conditional |
agentDetails.contactEmailAddress |
TEXT | Conditional |
agentDetails.contactEmailLabel |
TEXT | Conditional |
agentDetails.contactWebsite |
TEXT | Conditional |
agentDetails.contactWebsiteLabel |
TEXT | Conditional |
agentDetails.privacyPolicyUrl |
TEXT | Required |
agentDetails.privacyPolicyLabel |
TEXT | Optional |
agentDetails.termsAndConditionsUrl |
TEXT | Required |
agentDetails.termsAndConditionsLabel |
TEXT | Optional |
agentDetails.averageMonthlyRcsFrequency |
SELECT | Required |
agentDetails.billingCategory |
SELECT | Required |
agentDetails.monthlyRcsVolume |
TEXT | Required |
complianceKeywords.helpResponse |
TEXT | Conditional |
complianceKeywords.stopResponse |
TEXT | Conditional |
Troubleshooting
| Error | Resolution |
ACCENT_COLOR_CONTRAST_INSUFFICIENT |
Use a darker accent color with 4.5:1 contrast ratio against white. Create a new registration version and re-populate all fields. |
DESTINATION_COUNTRY_BLOCKED_BY_PROTECT_CONFIGURATION |
Update the protect configuration to set the US to ALLOW for SMS capability. |
DESTINATION_PHONE_NUMBER_OPTED_OUT |
Remove the number from the Default opt-out list with delete-opted-out-number. |
Registration REQUIRES_UPDATES |
Run describe-registration-field-values to find fields with DeniedReason. Create a new version, re-populate all 23 fields, fix the issue, and re-submit. |
| No tester invitation received | Wait up to 20 minutes. Check the Unknown Senders folder on iPhone. Verify the agent status is ACTIVE. |
| Message delivered as SMS instead of RCS | Confirm the agent is ACTIVE, the device supports RCS, and you used the correct origination identity. |
Next steps
With your test agent running, you can explore richer message types such as cards and carousels, set up event destinations for programmatic inbound message handling, or add more verified testers. For production use, submit a full launch registration instead of a test registration.
For an overview of the business case for RCS and implementation strategy, see Upgrade business messaging with RCS on AWS. For sample code and scripts that automate this walkthrough, see the sample-rcs-agent-setup-and-send-messages repository on GitHub. For more information, see the AWS End User Messaging service page and the RCS documentation.