Enviar mensagens RCS

AWS O End User Messaging usa a mesma SendTextMessage API para entrega de RCS e SMS. A forma como o serviço encaminha 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 AWS RCS Agent ARN.

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, ordem de prioridade de identidade de origem e substituição automática de SMS, consulte. Substituição de RCS para SMS usando grupos telefônicos Para obter detalhes sobre o gerenciamento de agentes do AWS RCS, consulteGerenciar agentes RCS.

Padrões de envio

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

Pool-based envio (recomendado)

Pool-based o envio é 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 fixo de envio.

Se o pool contiver um agente do AWS RCS e números de telefone SMS, o serviço tentará primeiro entregar o 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 como criar e configurar pools com agentes do AWS RCS, consulte. Substituição de RCS para SMS usando grupos telefônicos

Account-level enviando

Quando você omite a identidade de origem da sua SendTextMessage solicitação, o AWS End User Messaging seleciona uma identidade de origem de todas as identidades disponíveis em sua conta. Se sua conta tiver um agente do AWS RCS ativo, o serviço tentará primeiro entregar o RCS. Se a entrega do RCS falhar, o serviço retornará a um número de telefone dedicado ou ID de remetente na conta. As rotas de SMS compartilhadas não são suportadas pelo RCS fallback. Se a conta não contiver um originador dedicado válido para o país de destino, a mensagem falhará. O serviço usa a ordem de prioridade de identidade de origem para determinar qual identidade usar. Para obter detalhes, consulte Lógica de fallback e ordem de prioridade.

Envio direto (somente RCS)

Quando você especifica um AWS RCS Agent ARN como a identidade de origem em sua SendTextMessage solicitação, o AWS End User Messaging envia a mensagem somente via RCS. Não há substituto 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, ordem prioritária e reserva de SMS

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

Pool-based exemplo de envio

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

Account-level exemplo de envio

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 de prioridade.

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 AWS RCS Agent ARN. A mensagem é entregue somente via RCS, sem recurso 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 aviso a seguir para obter ajuda para enviar mensagens RCS usando a AWS CLI ou o 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
            

Tratamento de recibos de entrega

AWS O End User Messaging fornece recibos de entrega de mensagens RCS por meio da Amazon EventBridge e define a configuração de destinos de eventos. 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 atribuição de canal que indica se a mensagem foi entregue via RCS ou SMS. Isso é importante para entender seu mix de entregas e para fins de cobrança.

Para obter detalhes sobre CloudWatch métricas de RCS e padrões de entrega de monitoramento, 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.