RCS Suppressions & Opt-outs

Each Agent has its own suppression list — the phone numbers that will no longer receive RCS messages from that Agent. This protects recipients who've opted out and helps preserve your Agent's reputation. A message is not delivered to a recipient on the list.

A number on the list carries one of the following reasons:

Managing the list

POST /rcs/agents/{agentId}/suppression-lists/unsubscribe
GET /rcs/agents/{agentId}/suppression-lists/unsubscribe
GET /rcs/agents/{agentId}/suppression-lists/unsubscribe/{phone}
DELETE /rcs/agents/{agentId}/suppression-lists/unsubscribe/{phone}

To add a number, send its phone in the request body. The list and detail endpoints return each number with its reason and the time it was added (createdAt).

Full request and response reference:

• Add a phone number to the suppression list
• Retrieve the suppression list for an agent
• Get a suppression detail for a phone number
• Remove a phone number from the suppression list

Confirming an opt-out

When a recipient opts out, it's good practice to confirm that you received their request. Naxai notifies you through the rcs.unsubscribe.v1 webhook event — see Receiving Inbound RCS Messages — and you can reply with a short confirmation message.

To do this, send the message with messageTrafficType set to ACKNOWLEDGEMENT. This value tells the carrier the message simply confirms an action the recipient took, rather than being marketing or a new conversation.

{
  "to": "32478123456",
  "messageTrafficType": "ACKNOWLEDGEMENT",
  "message": {
    "type": "text",
    "text": "You've been unsubscribed and won't receive further messages from us. Thanks."
  }
}

Send it to POST /rcs/agents/{agentId}/messages/send, the same endpoint as any other message. See Sending RCS Messages via API.

A few things to keep in mind:

• Use ACKNOWLEDGEMENT only to confirm the opt-out. Don't add promotional content, offers, or suggestions to re-subscribe.
• Send the confirmation right after you receive the rcs.unsubscribe.v1 event.
• If you don't set messageTrafficType, the message is sent according to your Agent's use case, so set it explicitly for confirmations.

Re-subscribing

A recipient who has opted out can subscribe again at any time by sending START to your Agent. This is the only keyword that works, but it isn't case-sensitive, so start or Start works too. Their number is then removed from your Agent's suppression list, and they receive your RCS messages again.

Naxai notifies you through the rcs.subscribe.v1 webhook event — see Receiving Inbound RCS Messages — so you can update the recipient's status in your own systems.

This is the only way to lift an opt-out made by the recipient: you can't remove these numbers yourself. If a recipient tells you through another channel that they want to hear from you again, ask them to send START to your Agent.

Suppressions and RCS Broadcasts

When sending an RCS Broadcast to a segment of contacts, use an unsubscribe-aware segment so opted-out contacts aren't included in the first place. Numbers on your Agent's suppression list won't receive the message regardless of how they were included.

What's next

• Receiving Inbound RCS Messages
• RCS Broadcasts
• RCS Status & Error Codes