Managing AWS RCS Agents in pools - AWS End User Messaging SMS
Creating a pool with an AWS RCS AgentAdding AWS RCS Agents to existing poolsPool configuration requirements for RCSRemoving AWS RCS Agents from pools

Managing AWS RCS Agents in pools

You can add an AWS RCS Agent as an origination identity in a phone pool alongside your SMS phone numbers. When a pool contains both an AWS RCS Agent and SMS phone numbers, AWS End User Messaging attempts RCS delivery first and automatically falls back to SMS if RCS delivery is not possible. For details on how fallback works, see RCS to SMS fallback using phone pools.

Note

When you add an AWS RCS Agent to a pool, use ZZ as the ISO country code. The ZZ code indicates that the RCS agent is not country-specific at the pool level. Country-specific routing is handled through the agent's country launch registrations. A pool can contain phone numbers from multiple countries alongside the RCS agent.

The ISO country code is provided at pool creation time but is not persisted on the pool. If you call DescribePools, the ISO country code does not appear in the response.

Creating a pool with an AWS RCS Agent

You can create a new pool that includes your AWS RCS Agent using the AWS End User Messaging console or the CreatePool API.

Console
To create a pool with an AWS RCS Agent using the console

  1. Open the AWS End User Messaging console.

  2. In the navigation pane, choose Phone pools.

  3. Choose Create pool.

  4. For Origination identity, select your AWS RCS Agent. The pool inherits its configuration from the origination identity you select.

  5. Configure the pool settings as needed, then choose Create pool.

  6. After the pool is created, add your SMS phone numbers to the pool to enable SMS fallback. All origination identities in the pool must have matching configuration. For details, see Pool configuration requirements for RCS.

AWS CLI

Use the CreatePool API to create a pool with your AWS RCS Agent as the initial origination identity. Specify the AWS RCS Agent ARN as the origination identity when creating the pool.

The following example creates a pool using the AWS CLI:

aws pinpoint-sms-voice-v2 create-pool \
    --origination-identity arn:aws:sms-voice:region:account-id:rcs-agent/rcs-agent-id \
    --iso-country-code ZZ \
    --message-type TRANSACTIONAL

After the pool is created, use the AssociateOriginationIdentity API to add SMS phone numbers to the pool for fallback.

Adding AWS RCS Agents to existing pools

If you already have a pool with SMS phone numbers, you can add your AWS RCS Agent to the pool to enable RCS messaging with SMS fallback. You can also add additional SMS phone numbers to a pool that already contains an AWS RCS Agent.

Important

Before adding an origination identity to an existing pool, verify that the pool's configuration matches the identity you are adding. All origination identities in a pool must have identical metadata. If there is a mismatch, the operation fails with a ConflictException. For details on which fields must match and how to resolve mismatches, see Pool configuration requirements for RCS.

Console

Before adding an AWS RCS Agent to a pool using the console, inspect the pool's details page to review its current configuration. Confirm that the pool's message type, ISO country code, and other settings are compatible with the AWS RCS Agent you want to add.

To add an AWS RCS Agent to an existing pool using the console

  1. Open the AWS End User Messaging console.

  2. In the navigation pane, choose Phone pools.

  3. Choose the pool that you want to add the AWS RCS Agent to.

  4. Review the pool's configuration on the details page. Confirm that the message type and other settings match the AWS RCS Agent you want to add.

  5. In the Origination identities section, choose Add origination identity.

  6. Select your AWS RCS Agent from the list and choose Add.

AWS CLI

Before adding an AWS RCS Agent to a pool using the CLI or API, use the DescribePools API to retrieve the pool's current configuration. Verify that the pool's settings match the AWS RCS Agent you want to add.

The following example retrieves pool details:

aws pinpoint-sms-voice-v2 describe-pools \
    --pool-ids pool-id

After confirming the configuration matches, use the AssociateOriginationIdentity API to add the AWS RCS Agent to the pool:

aws pinpoint-sms-voice-v2 associate-origination-identity \
    --pool-id pool-id \
    --origination-identity arn:aws:sms-voice:region:account-id:rcs-agent/rcs-agent-id \
    --iso-country-code ZZ

Pool configuration requirements for RCS

All origination identities in a pool must have identical metadata. When you add an origination identity to a pool, AWS End User Messaging compares the identity's configuration with the pool's existing configuration. If there is a mismatch, the operation fails with a ConflictException that includes details about the specific fields that differ.

Pool configuration fields fall into two categories: immutable fields that are set when the pool is created and cannot be changed, and mutable fields that you can update after creation.

Immutable versus mutable pool configuration fields
Field Mutability Notes
Message type Immutable Set at pool creation. All identities must match.
ISO country code Immutable Set at pool creation. For AWS RCS Agents, the value is ZZ. Pools can contain phone numbers from multiple countries.
Deletion protection Mutable Can be toggled after creation. Must be consistent across identities.
Opt-out list Mutable Can be changed after creation. Must be consistent across identities.

The following configuration fields must match across all origination identities in a pool:

  • Message type — All identities must be configured for the same message type (for example, TRANSACTIONAL or PROMOTIONAL).

  • ISO country code — Set at pool creation. For AWS RCS Agents, use ZZ as the ISO country code. Pools can contain phone numbers from multiple countries.

  • Deletion protection — The deletion protection setting must be consistent across identities.

  • Opt-out list — All identities must be associated with the same opt-out list, or none of them should have an opt-out list.

Understanding ConflictException errors

When you attempt to add an origination identity to a pool and the configuration does not match, the AssociateOriginationIdentity or CreatePool API returns a ConflictException. The exception message includes details about which fields differ between the identity and the pool.

For example, if you try to add a phone number configured for PROMOTIONAL messages to a pool configured for TRANSACTIONAL messages, the error message indicates that the message type does not match.

To resolve a ConflictException:

  1. Review the error message to identify which fields differ.

  2. Update the origination identity or the pool configuration so that the fields match.

  3. Retry the AssociateOriginationIdentity or CreatePool operation.

Note

If you cannot resolve the configuration mismatch, consider creating a separate pool for the origination identity. Each pool can have its own configuration, and you can use different pools for different use cases.

Removing AWS RCS Agents from pools

You can remove an AWS RCS Agent from a pool using the AWS End User Messaging console or the DisassociateOriginationIdentity API. Removing an AWS RCS Agent from a pool disables RCS delivery for messages sent through that pool. Messages sent to the pool after the agent is removed are delivered via SMS only (using the remaining phone numbers in the pool).

Console
To remove an AWS RCS Agent from a pool using the console

  1. Open the AWS End User Messaging console.

  2. In the navigation pane, choose Phone pools.

  3. Choose the pool that contains the AWS RCS Agent you want to remove.

  4. In the Origination identities section, select the AWS RCS Agent.

  5. Choose Remove, then confirm the removal.

AWS CLI

Use the DisassociateOriginationIdentity API to remove an AWS RCS Agent from a pool:

aws pinpoint-sms-voice-v2 disassociate-origination-identity \
    --pool-id pool-id \
    --origination-identity arn:aws:sms-voice:region:account-id:rcs-agent/rcs-agent-id \
    --iso-country-code ZZ

After removing the AWS RCS Agent, messages sent through the pool are delivered via SMS only. To re-enable RCS delivery, add the AWS RCS Agent back to the pool using the AssociateOriginationIdentity API.