# Opt-In/Out Handling

Airship handles requests to opt in and opt out of SMS notifications.
Users must opt in to receive SMS messages from your Sender ID and can opt out at any time. There are four ways users can opt in or opt out of your SMS audience:

* **Mobile-Originated (MO) Message:** A message originating from the mobile handset can contain a keyword that triggers an opt-in. The opt-in keyword can trigger a single or double opt-in flow.
* **External Opt-In:** Users can opt in to SMS messages through your website using [Opt-in Forms](https://www.airship.com/docs/guides/messaging/features/opt-in-forms/) or through your app or other channels, [using the API](#non-mobile-single-opt-in).
* **SDK:** Register an SMS channel through the [Android](https://www.airship.com/docs/developer/sdk-integration/android/audience/contacts/#sms-channel-association) and [Apple](https://www.airship.com/docs/developer/sdk-integration/apple/audience/contacts/#sms-channel-association) SDKs.
* **CSV Upload:** You can include the `ua_opted_in` field when uploading [MSISDNs](https://www.airship.com/docs/reference/glossary/#msisdn) in a CSV file to set [Tags](https://www.airship.com/docs/reference/glossary/#tag) or [Attributes](https://www.airship.com/docs/reference/glossary/#attributes). Airship registers new channels for MSISDN/sender combinations that are new to your project. See: 
    * [Setting attributes using a CSV file](https://www.airship.com/docs/guides/audience/attributes/setting/#csv-file)
    * [Setting tags using a CSV file](https://www.airship.com/docs/guides/audience/tags/#file-upload)

## SMS Data Protection and Compliance

Requests to opt in to or out of SMS notifications are processed by the Airship Service, but the obligation to comply with such requests remains with the customer. Our opt-in and opt-out database is encrypted and is also segregated from campaign content. For opt-ins and opt-outs that occur via mobile-originated messages, Airship stores date/time data for those opt-ins and opt-outs for a rolling 4 years.

## Mobile-Originated Opt-Ins

A *mobile-originated message* is a message sent from a member of your audience (originating from the mobile handset of a user) to you.

### Single Opt-In

Single opt-in is the process of registering users and considering them opted in when they send you a single message containing a keyword. This method does not require users to confirm that they want to opt in through a second mobile-originated (MO) message.

While a single opt-in is a simple way to register users, it may not always be an optimal opt-in method. Airship mobile-originated opt-in handling defaults to a double opt-in process. [Contact Airship Support](https://support.airship.com/) if you want to take advantage of a single opt-in workflow.

The response to the keyword is a confirmation text message that provides information about the text program. The message usually:

* confirms that the user has subscribed to an ongoing text program.
* provides the number of messages the subscriber can expect to receive.
* informs the subscriber where they can obtain more information and how they can opt out.

Example:
: *BrandX: Welcome to the BrandX Info and Alerts Program! Message frequency varies by use. For help, reply HELP. To end, reply, STOP. Msg&DataRatesMayApply.*

### Double Opt-In

Double opt-in requires a user to send you a keyword indicating that they want to receive mobile messages, and a second keyword confirming their choice:

1. Your audience texts a keyword to trigger the opt-in process.
1. Airship sends your audience a message requesting confirmation using a keyword.
1. Your audience texts the confirmation keyword, opting in to your audience.

Because each message in the opt-in workflow supports unique keywords, the double opt-in method provides multiple indices to categorize users as they opt in to your audience; you can add, remove, or replace tags for any of the opt-in messages, ensuring that you precisely segment your audiences and target future messages to the right users.

<!-- Add example from Mitzi later?
BrandX: Thanks for your interest to join the rewards program, to confirm, please reply YES. Msg&DataRatesMayApply. For help, reply HELP. To end, reply STOP.

YES

BrandX: Welcome! You will receive 5 msg/mo. No purchase required. Msg&DataRatesMayApply. To end, reply STOP. For help, reply HELP. For more info, https://airsp.co/Oi9dy76d .
-->

### Keywords

You can add additional keywords to trigger an opt-in or opt-out. See: [SMS keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/).

## Non-Mobile Single Opt-In

If users provide consent to receive text messages without a mobile-originated keyword — like through your website or app — you can register them through the API in a single step. Use the [`/api/channels/sms`](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/#registersmschannel) endpoint with the date-time when the user `opted_in`.

> **Tip:** It may take up to an hour before you can message new users. If you want to message a new SMS user immediately, you can register new SMS users and send a message simultaneously using [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send).


```http
POST /api/channels/sms HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "msisdn" : "15035556789",
    "sender": "12345",
    "opted_in": "2018-02-13T11:58:59"
}
```


When registering your audience without a mobile keyword, it is your responsibility to obtain express written consent from users. If users have not provided sufficient consent, you should perform a double opt-in.

## Non-Mobile Double Opt-In

If users provide their phone numbers and express interest in SMS messages through your website or app but do not give sufficient consent to receive SMS messages from a particular sender, you can register them through the Airship API without an `opted_in` value.

When you register a user through the API without an `opted_in` value, Airship sends them a message prompting them to opt in. The user must then respond with a valid keyword to opt in to notifications.

> **Tip:** Airship generates a `channel_id` even when you register users who have not opted in. You can add tags to these channels and associate them with named users before audience members opt in.


```mermaid
sequenceDiagram
Participant Audience
Participant You
Participant Airship
Audience->> You: Registers via webform/app
You->> Airship: Register user through API
Airship->>Airship: Creates channel ID for audience
You-->> Airship: (Optional) add tags to new channel
Airship->> Audience: Sends opt-in request via SMS
Audience->> Airship: Texts opt-in keyword to Airship
note over Audience, Airship: Your audience/channel ID is opted in and can receive messages
```


When registering your audience without a mobile keyword, it is your responsibility to ensure that your users understand that they are agreeing to receive SMS messages from you and provide express written consent to receive SMS messages from you.

## Creating a One-Click Opt-In Link Using HTML

For mobile websites, you can set up a hyperlink or a button on a page that will open up the device's messaging app and prepopulate the long or short code and keyword for the SMS opt-in.

> **Note:** This feature will work on most mobile devices as well as a few desktop devices, but is not guaranteed to work on every mobile device model or operating system.


**HTML Hyperlink Template:**


```html
<a href="sms://CODE?&body=KEYWORD">Click Here to Opt-In</a>
```


**HTML Hyperlink Example:**


```html
<a href="sms://54321?&body=JOIN">Click Here to Opt-In</a>
```


## Update Opt-in Status {#update-sms-channel}

If your audience opts in to messaging outside of a standard opt-in flow — through your website or app — you can update the channel's `opted_in` value to add them to your messaging audience.

You can also update a channel to change its time zone and locale information.

> **Note:** You must know the `channel_id` to update a channel. You can look up a channel by `msisdn` and `sender` combination to find the channel identifier that you want to update.


**Update the `opted_in` value for a channel**

```http
PUT /api/channels/sms/{channel_id} HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "msisdn": "15035556789",
   "sender": "12345",
   "opted_in": "2018-02-13T11:58:59",
   "timezone": "America/Los_Angeles",
   "locale_country": "US",
"locale_language": "en"
}
```


## Opt out of SMS messages

If your audience opts out of messaging, you can mark the channel as opted-out (inactive) and they will not receive alerts even when they are addressed in the future. Use the [`/api/channels/sms/opt-out`](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/#optoutsmschannel) endpoint and specify the `sender` and `msisdn`.

**Opt-out of SMS messages**

```http
POST /api/channels/sms/opt-out HTTP/1.1
Authorization: Basic <application authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "sender": "12345",
   "msisdn": "15035556789"
}
```


## Automated Opt-In Interactions

You can define automated responses to opt-in keywords based on whether an `msisdn` is opting in for the first time or is currently opted in. [Contact Airship Support](https://support.airship.com/) to set up automated opt-in interactions. Examples:

* **First time opting in** — Send a welcome message: *"Thanks for joining BrandX! Here is your offer code...."*
* **Currently opted in** — Send a welcome message without an offer: *"Looks like you are already subscribed to BrandX."*

<!-- Postponed features:

You can set up several automated responses to opt-in keywords based on whether an `msisdn` is opting in for the first time, is already opted in, or has previously opted in within a certain time frame, as well as limit opt-in attempts. [Contact Airship Support](https://support.airship.com/) to set up automated opt-in interactions.

Opt-in Status - Send a message based on whether an `msisdn` is opting in for the first time or is currently opted-in:
* **First time opting in** - Send a welcome message - _"Thanks for joining BrandX! Here is your offer code..."_
* **Currently opted in** - Send a message without an offer - _"Looks like you are already subscribed to BrandX"_

Previously Opted In** - Send a different message to a user who has previously opted out, based on their opt-out date, such as X number of days:
* **Before last opt-out date** - If opted-out prior to the last 60 days, send an opt-in message with an offer.
* **Within last opt-out date** - If opted-out within the last 60 days, send an opt-in message without offer, or a rejection message.

Limit Opt-In Attempts - Limit the number of attempts to confirm a double opt-in and send a different message based on the number of attempts:
* **Within opt-in attempt limit** - Send a confirmation request message - _"Sorry, we did not recognize the response, to confirm your opt-in, please reply Y or YES."_
* **Exceeded opt-in attempt limit** - Send a limit reached message - _"We were unable to confirm your opt-in, to restart the opt-in process, text JOIN to 12345."_

-->
## Manually Triggered Keyword Interactions

You can trigger a keyword interaction on behalf of your audience, without receiving a mobile originated (MO) message, using the Airship API. You may want to do this to test your keywords or to trigger keyword interactions on behalf of your audience — including keywords that opt users in or out of your messaging audience.

For example, if a member of your audience requests to be removed from your messaging audience over the phone, you could use the following operation to opt them out. This triggers the mobile terminated message confirming that the user has been removed from your messaging audience.

**Trigger a "STOP" Keyword Interaction**

```http
POST /api/sms/15035556789/keywords HTTP/1.1
Content-Type: application/json
Authorization: Basic <master authorization string>

{
   "keyword" : "stop",
   "sender_ids" : [ "54321", "1234"]
}
```