Receiving inbound RCS media

Users can send media (images, videos, audio files, and documents) in RCS conversations with your agent. When you configure inbound media storage, AWS End User Messaging downloads the media from the RCS provider, uploads it to your Amazon S3 bucket, and publishes a notification to your two-way Amazon SNS topic with the S3 location and file metadata.

For general information about receiving inbound RCS messages (text, location, and suggestion responses), see Receiving inbound RCS messages. For information about sending rich media to users, see Sending rich RCS messages.

How inbound media works

When a user sends a media file in an RCS conversation, AWS End User Messaging processes the message through the following steps:

For LOCATION and SUGGESTION message types, no S3 upload occurs. The content is delivered directly in the SNS notification body. For details about these message types, see Receiving inbound RCS messages.

Configuring inbound media storage

To receive inbound media, configure the following fields on your RCS agent using the UpdateRcsAgent API. Two-way messaging must be enabled on the agent before you configure media storage.

The S3 bucket and IAM role are required together. If you specify one, you must specify both.

S3 key format

Media objects are stored with the following key format, where the original file name is appended after a # separator:

{prefix}/rcs/{messageId}#{fileName}

For example, if you set the key prefix to inbound-media, a media file might be stored as:

inbound-media/rcs/msg-abc123def456#photo_2026.jpg

Creating the IAM role for inbound media

Create an IAM role that allows the AWS End User Messaging service to upload media files to your S3 bucket. The role requires a trust policy that permits the service to assume it, and a permission policy that grants s3:PutObject access to your bucket.

Trust policy

The following trust policy allows the AWS End User Messaging service principal to assume the role. Replace 123456789012 with your AWS account ID.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "sms-voice.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "123456789012"
                }
            }
        }
    ]
}

Permission policy

The following permission policy grants the role access to write objects to your S3 bucket. Replace my-rcs-media-bucket with your bucket name.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": "arn:aws:s3:::my-rcs-media-bucket/*"
        }
    ]
}

Configuring media storage (CLI)

The following AWS CLI command configures inbound media storage on an existing RCS agent:

aws pinpoint-sms-voice-v2 update-rcs-agent \
    --rcs-agent-id rcs-agent-1234567890abcdef0 \
    --two-way-media-s3-bucket-name my-rcs-media-bucket \
    --two-way-media-s3-key-prefix "inbound-media" \
    --two-way-media-s3-role arn:aws:iam::123456789012:role/RcsInboundMediaRole \
    --region us-east-1

Inbound media notification payload

When AWS End User Messaging receives a media file, it publishes a notification to your two-way SNS topic. The notification is a JSON object with a messageBody field that contains a stringified JSON document with the media status and, on success, the S3 location and file metadata.

The following example shows a successful inbound media notification:

{
    "originationNumber": "+14255551234",
    "destinationNumber": "rcs-cb1e6e519e9049fabf8c0ae38e4d876b",
    "messageBody": "{\"mediaStatus\":\"SUCCESS\",\"s3Bucket\":\"my-rcs-media-bucket\",\"s3Key\":\"inbound-media/rcs/msg-abc123def456#photo_2026.jpg\",\"mimeType\":\"image/jpeg\",\"fileName\":\"photo_2026.jpg\",\"fileSizeBytes\":1211843}",
    "inboundMessageId": "8821d750-4bc5-4cb1-a8c3-c3d64a38d019"
}

The top-level notification contains the following fields:

The messageBody JSON contains the following fields:

Media download failure handling

If AWS End User Messaging cannot download or store media from the RCS provider, the service still publishes a notification to your two-way SNS topic. The messageBody carries a failure mediaStatus (UPLOAD_FAILED or ROLE_ASSUME_FAILED) and a mediaStatusMessage describing the cause, with no S3 location fields.

For example, an IAM role assumption failure produces the following messageBody content:

{
    "mediaStatus": "ROLE_ASSUME_FAILED",
    "mediaStatusMessage": "Media received but could not assume the configured IAM role",
    "mimeType": "image/heic",
    "fileName": "IMG_7115.heic",
    "fileSizeBytes": 1211843
}

Common causes of media download failures include:

To troubleshoot delivery failures, verify that your IAM role trust and permission policies are correctly configured, and that the S3 bucket exists and is accessible from the service. Monitor your agent's CloudWatch metrics for media upload failures.

Accepted media types

AWS End User Messaging accepts the following inbound media MIME types:

Best practices