Enviando mensagens RCS

AWS O End User Messaging usa a mesma SendTextMessage API para entrega de RCS e SMS. A forma como o serviço roteia sua mensagem depende da identidade de origem especificada na solicitação. Você pode enviar mensagens por meio de um pool telefônico (recomendado), no nível da conta ou diretamente por meio de um ARN do AWS RCS Agent.

Esta seção explica os três padrões de envio, como interpretar os recibos de entrega e fornece exemplos de código. Para obter detalhes sobre envio fixo, pedido prioritário de identidade de origem e retorno automático de SMS, consulte. Fallback de RCS para SMS usando pools telefônicos Para obter detalhes sobre o gerenciamento de agentes do AWS RCS, consulteGerenciando agentes RCS.

Padrões de envio

AWS O End User Messaging suporta três padrões de envio de mensagens RCS. Cada padrão determina como o serviço seleciona uma identidade de origem e se o fallback automático de SMS está disponível.

Envio baseado em pool (recomendado)

O envio baseado em pool é a abordagem recomendada para todos os casos de uso do RCS. Quando você especifica um ID de pool como a identidade de origem em sua SendTextMessage solicitação, o AWS End User Messaging seleciona a melhor identidade de origem do pool com base no destino, na disponibilidade do canal e no histórico de envio fixo.

Se o pool contiver um AWS RCS Agent e números de telefone SMS, o serviço tentará primeiro a entrega do RCS. Se a entrega do RCS falhar, o serviço retornará automaticamente ao SMS usando um número de telefone do mesmo pool. Como todas as identidades no pool são registradas para o mesmo caso de uso, a mensagem alternativa é sempre enviada de um número apropriado.

Para obter detalhes sobre a criação e configuração de pools com agentes do AWS RCS, consulte. Fallback de RCS para SMS usando pools telefônicos

Envio em nível de conta

Quando você omite a identidade de origem de sua SendTextMessage solicitação, o AWS End User Messaging seleciona uma identidade de origem de todas as identidades disponíveis em sua conta. O serviço usa a ordem de prioridade de identidade de origem para determinar qual identidade usar. Para obter detalhes, consulte Lógica alternativa e ordem de prioridade.

Envio direto (somente RCS)

Quando você especifica um ARN do AWS RCS Agent como a identidade de origem em SendTextMessage sua solicitação AWS , o End User Messaging envia a mensagem somente via RCS. Não há retorno automático de SMS. Se a entrega do RCS falhar, a mensagem não será repetida em outro canal.

Use o envio direto quando:

Envio fixo, pedido prioritário e retorno de SMS

Quando você envia mensagens por meio de um pool ou no nível da conta, o AWS End User Messaging usa o envio fixo (uma otimização de roteamento de 25 horas), uma ordem de prioridade de identidade de origem e um retorno automático de SMS para selecionar o melhor canal e identidade para cada mensagem. Para obter detalhes completos sobre como esses mecanismos funcionam, incluindo fallback automático, recibos de entrega durante o fallback e implicações de cobrança, consulte. Fallback de RCS para SMS usando pools telefônicos

Exemplos de código

Os exemplos de Python a seguir demonstram como enviar mensagens RCS usando cada um dos três padrões de envio. Todos os exemplos usam o pinpoint-sms-voice-v2 cliente boto3 e a SendTextMessage API.

Exemplo de envio baseado em pool

O exemplo a seguir envia uma mensagem por meio de um pool telefônico. O serviço seleciona a melhor identidade de origem do pool e volta automaticamente para o SMS se a entrega do RCS não for possível.

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']}")
            

Exemplo de envio em nível de conta

O exemplo a seguir envia uma mensagem no nível da conta omitindo a identidade de origem. O serviço seleciona uma identidade de todas as identidades disponíveis em sua conta usando a ordem prioritária.

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']}")
            

Exemplo de envio direto

O exemplo a seguir envia uma mensagem diretamente por meio de um ARN do AWS RCS Agent. A mensagem é entregue somente via RCS, sem retorno de SMS.

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']}")
            

Solicitação do agente de IA para enviar mensagens RCS

Se você usa um assistente de codificação de IA generativo ou um agente de IA, pode usar o prompt a seguir para obter ajuda para enviar mensagens RCS usando a CLI ou o SDK AWS .

## 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
            

Tratamento do recibo de entrega

AWS O End User Messaging fornece recibos de entrega de mensagens RCS por meio da Amazon EventBridge e de destinos de eventos definidos por meio de configurações. Os recibos de entrega indicam o status final da sua mensagem e qual canal foi usado para entrega. Para saber como configurar destinos de eventos para capturar recibos de entrega e outros eventos de mensagens, consulte. Destinos de eventos em SMS de mensagens de usuário AWS final

Valores do status de entrega

Os seguintes valores de status de entrega se aplicam às mensagens RCS:

Atribuição de canal

Os recibos de entrega incluem a atribuição do canal que indica se a mensagem foi entregue via RCS ou SMS. Isso é importante para entender seu mix de entrega e para fins de cobrança.

Para obter detalhes sobre CloudWatch métricas de RCS e padrões de monitoramento de entrega, consulteCloudWatch Métricas e monitoramento do RCS. Para obter informações sobre como o canal de entrega afeta o faturamento, consulteModelo de cobrança e preços do RCS.