# Getting Started Configure your project to register SMS users with Airship, and send them a message. When working with SMS, you must register each audience member's [MSISDN](https://www.airship.com/docs/reference/glossary/#msisdn) with a `sender` using the Channels API or a keyword operation. Registering an SMS channel returns a [Channel ID](https://www.airship.com/docs/reference/glossary/#channel_id). If the audience member did not explicitly opt in to notifications when they register, you'll trigger a double opt-in process. This document explains the registration processes for SMS channels. See the [SMS Channels API reference](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/) for more information about SMS channel endpoints. > **Tip:** If you use an AI coding assistant, you can connect it to Airship with Skills and an MCP server. See [Airship AI Tools](https://www.airship.com/docs/developer/ai-tools/ai-tools/). ## Configure Your Project [Contact Airship Sales](https://www.airship.com/contact-us/) to: 1. Provision your project for SMS notifications. 1. Set up your **sender IDs**. A sender ID is an originating phone number or string identifier used to indicate who an SMS message comes from. Members of your audience subscribe (opt in) to each sender ID they want to receive messages from. Your project can have multiple senders, and your audience can opt in to multiple senders within your project. If your Airship project has more than one sender ID, you can select one when you create your message. Selecting an individual sender ID ensures that your message only goes to members of your audience subscribed to that sender. When your sender ID is a short code, prepend the 2-letter [ISO 3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) when using the short code in the API. This is similar to the way that you would prepend a country code to a standard phone number. See [SMS senders](https://www.airship.com/docs/developer/api-integrations/sms/senders/) and [RCS branded senders](https://www.airship.com/docs/developer/api-integrations/sms/rcs/). > **Important:** Procuring or migrating an existing sender code is not instantaneous. Short code migrations may require up to eight weeks of lead time. ## Set Up Keywords You can set up keywords in the Airship dashboard. See: [SMS keywords](https://www.airship.com/docs/guides/messaging/features/sms-keywords/). ## Register SMS Users After Airship completes your project setup, you can register SMS users, which returns [Channel IDs](https://www.airship.com/docs/reference/glossary/#channel_id). The process to register users can depend on local data privacy laws and whether or not your audience explicitly opts in to notifications. There are multiple ways to register users: * **Phone number submission in a Scene** — A user can submit their phone number using the [SMS element](https://www.airship.com/docs/guides/messaging/in-app-experiences/configuration/content/#sms) in a [Scene](https://www.airship.com/docs/reference/glossary/#scene). Registration automatically triggers the [Double Opt-In](https://www.airship.com/docs/reference/glossary/#double_opt_in) process, and the phone number is associated with the [Contact](https://www.airship.com/docs/reference/glossary/#contact) viewing the Scene. * **Mobile-originated message** — A user can text you a keyword that explicitly opts them in to your sender's audience. * **Opt-in form** — A user can sign up for SMS messages through an [opt-in form](https://www.airship.com/docs/guides/messaging/features/opt-in-forms/) you can add to your website. * **SMS channel registration API** — Use the SMS channel registration API to register individual channels. This may be helpful if your audience opts into SMS messages from your app or website. * **Simultaneously send a message and register new user** — See [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send). * **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 upload [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) --- Users explicitly opting into notifications using a keyword trigger an opt in flow. Airship defaults to a double opt-in, but it is common to use a single opt-in flow for keyword purposes. If your user does not explicitly opt into notifications, or provides you their `msisdn` without using a keyword (through a sign up on your website, in your app, etc.), you will trigger a double opt-in by registering the user through the channel registration API without an `opted_in` value. If you register a member of your audience using the channel registration API with an `opted_in` value, the user will not receive a notification confirming that they opted in. ```mermaid graph TD A[User provides
MSISDN] -->B{Did user
explicitly opt in?} B -->|No| C[Create channel] B --> |Yes, with keyword| D[Create channel] B --> |"Yes, without keyword
(Register through API)"| Z[Create channel] subgraph Single Opt-in D end C -->|Send MSISDN MT opt-in request| E{Did user respond
with opt-in keyword?} E -->|Yes| F[Update channel with opt-in] E -->|No| G[User cannot receive messages] F --> |Send user confirmation| H[User can receive messages] D -->|Send user confirmation| H Z --> H subgraph Double Opt-in C E F G end subgraph Silent Opt-in Z end ``` ### SMS Channel Registration API You can use the [SMS channel registration API](https://www.airship.com/docs/developer/rest-api/ua/operations/sms/#registersmschannel) to register SMS users when they opt in to SMS notifications through your website or app. Users register and opt in to messages from particular senders, so Airship generates a unique `channel_id` for each `msisdn`/`sender` combination. You can also create channels that are not opted in to notifications, triggering a double opt-in flow. You might do this when offering shipping notifications or event updates to users who have opted in to different notifications from you. If you do not provide an `opted_in` date when registering a new user, Airship starts a double opt-in process and sends an message to the MSISDN, asking the user to respond with a keyword to initiate the opt-in process, followed by a second message to text "Y" (or "y") to complete the opt-in. **You cannot send a message to a user until you update their channel with a valid `opted_in` value.** **Example request** ```http POST /api/channels/sms HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "msisdn" : "15558675309", "sender": "12345", "opted_in": "2018-07-10T11:59:59" } ``` **Example response** ```http HTTP/1.1 201 Created Content-Type: application/vnd.urbanairship+json; version=3 Location: https://go.urbanairship.com/api/channels/34b3dfc1-d717-40fe-89e8-10584ed1c123df6a6b50-9843-0304-d5a5-743f246a4946 { "ok": true, "channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946" } ``` ### Send a Message While Registering Users {#create-and-send} If your audience provides you their MSISDNs, you can register them with Airship and send them a message at the same time using [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send). If you provide a `ua_opted_in` value for the new channels in your audience, they will be eligible to receive future messages. If you do not set a `ua_opted_in` value for the new channels, they'll receive the message and begin the double opt-in flow. Addresses in the list that are already registered with Airship will receive your message if either of the following conditions are true: * They are already opted in for messaging (their channel has a valid `opted_in` value). * You provide a `ua_opted_in` date-time value for an `msisdn` that is newer than an `opted_out` value on the channel. This does not update the `opted_in` value on the channel; it only overrides the `opted_out` value to send the current message. You must update the `opted_in` value using [SMS channel update API](https://www.airship.com/docs/developer/api-integrations/sms/opt-in-out-handling/#update-sms-channel) to opt it back into your messaging audience. Your CSV must include `ua_msisdn`, `ua_sender` and `ua_opted_in` headings. You can use additional headings to personalize messages with [Handlebars](https://www.airship.com/docs/reference/glossary/#handlebars). See [CSV formatting](https://www.airship.com/docs/guides/audience/segmentation/bulk-sending/#csv-formatting) in *Bulk sending*. **Create and Send CSV example** ```text ua_msisdn,ua_sender,ua_opted_in,fav_food 5558675309,12345,2020-05-05T10:34:22,tacos 5559867543,12345,2020-05-05T12:03:45,pizza ``` **Create and Send message example** ```http POST /api/create-and-send HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "audience": { "create_and_send": [ { "ua_msisdn": "15558675309", "ua_sender": "12345", "ua_opted_in": "2020-05-05T10:34:22", "fav_food": "tacos" }, { "ua_msisdn": "15551234567", "ua_sender": "12345", "ua_opted_in": "2020-05-05T12:03:45", "fav_food": "pizza" } ] }, "device_types": [ "sms" ], "notification": { "sms": { "alert": "Hey, I hear you like {{fav_food}}" } } } ``` ### Determining Time Zone and Locale for SMS Channels {#timezone} When you register or update an SMS user in Airship, you can set their IANA `timezone`, `locale_country`, and `locale_language`. If you don't set these values yourself, Airship attempts to infer country and time zone information from the country code and format of your audience's phone numbers ([MSISDNs](https://www.airship.com/docs/reference/glossary/#msisdn)). You can use this information to reach your SMS audience at the right time and in the right language. > **Note:** Airship does not infer `locale_language` values. Airship takes advantage of the `timezone` when you schedule a message using `local_scheduled_time` in the API or the [Delivery By Time Zone](https://www.airship.com/docs/reference/glossary/#delivery_by_time_zone) checkbox in the Delivery step in the Airship dashboard, and sends your message to your audience at the specified time in their respective time zones. These values all appear in an SMS channel's `tag_groups`. **Register an SMS channel with a short code and country designation** ```http POST /api/channels/sms HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "msisdn" : "15035556789", "sender": "12345", "opted_in": "2020-02-13T11:58:59", "timezone": "America/Los_Angeles", "locale_country": "US", "locale_language": "en" } ``` > **Note:** Payloads without country codes are acceptable only if your project has a single short code for a single country.