Inbound SMS - Handle unsubscribe requests

When you set up Inbound SMS, you need to be ready to process unsubscribe requests from end users. An unsubscribe request occurs when an end user includes keyword” in their Mobile Originated (MO) message that is mapped to the “stop” action. While you are responsible for maintaining and managing any opt-in or opt-out lists, Telesign’s role is to send confirmation to end users of whether the unsubscribe succeeded or failed. The processes for "help" and "start" actions (for adding an end user to an opt-in list) are similar to this procedure.



This procedure only applies to an HTTP setup.

If you are using SMPP and need assistance with this task, contact our Customer Support Team.

Key terms

Action: An event that is triggered in response to specific keywords in an MO message. These actions are "stop", "start", "help" and "generic."

Keyword: Specific words in a MO message from an end user that triggers certain actions. Each keyword can have different response template. Some keywords trigger automatic responses. For the "stop" action, these are arrêt, arret, cancel, end, quit, stop, unsubscribe.

Response message: A predefined text that you send to an end-user to notify them that their request was either successful or unsuccessful after the end-user's request that contained a specific keyword in a transaction. To handle an unsubscribe request, you need two messages for each keyword associated with "stop": one notifying an end-user that they were successfully unsubscribed and another message notifying an end-user that the unsubscribe failed. These messages are based on either a Telesign predefined template or your own.

Before you begin

  • Set up Inbound SMS: See Inbound SMS - Get started for instructions.

  • Enable SMS or SMS Verify API: Either SMS or SMS Verify API must be enabled for your account for you to use Inbound SMS. If you are a full-service customer, contact [email protected] to enable one of these products. If you are a self-service customer, these products are already enabled for your account.

  • Create response messages for keywords: Work with our Customer Support Team to create a separate response message for each keyword (arrêt, arret, cancel, end, quit, stop, unsubscribe) associated with the "stop" action so that each keyword can use a response message that suitable for that keyword. (You'll want to also create response messages for keywords associated with the "help" and "start" actions too).


  1. The end user sends a response to your transaction that contains a keyword associated with the "stop" action ("arrêt", "arret", "cancel", "end", "quit", "stop", "unsubscribe").
  2. When we detect any of these keywords, we notify you so you can update the opt-out list that you manage.
  3. Your Transaction Callback Service responds to our callback request with an HTTP status code.
  4. If this HTTP status code is in the range of 200-299, we notify the end user that the transaction was a success.
  5. If you don't respond to our callback request with an HTTP status code in the range of 200-299. you don't respond at all, or if a timeout occurs, we notify the end user that the transaction wasn't successful.



See Transaction Callback Service - Retries for an explanation on Telesign's retry attempts for sending notifications to your Transaction Callback Service.