--- title: "Register SMS channel" method: POST path: "/api/channels/sms" tags: ["SMS"] --- # Register SMS channel `POST /api/channels/sms` ## Request - Base URL: `https://go.urbanairship.com` - URL: `https://go.urbanairship.com/api/channels/sms` - Auth: one of: - HTTP basic - HTTP bearer - OAuth 2 - Client credentials - Token URL: `http://oauth2.{domain}.com/token` scopes: `chn` - TypeScript: (a function with typed inputs; its response is checked against the schema) Create an SMS channel. If the channel has not opted in yet (the request did not contain `opted_in`), Airship creates the channel with `opt_in` set to `false` and the user receives a message prompting them to complete the opt-in flow; you can assign tags and organize `pending` channels before the user has finished the opt-in process, but you cannot send messages to channels until they opt in to your audience. SMS notifications require a `sender` - a number that recipients will receive SMS notifications from. [Contact Airship Sales](https://www.airship.com/contact-us/) or your Account Manager to provision your project for SMS notifications and complete the configuration. ## Request body - object - `attributes` object: An optional object containing the customer-provided attributes associated with the SMS channel. - `locale_country` string: The ISO 3166 two-character country code. The value for this field becomes a tag in the `ua_locale_country` tag group. - `locale_language` string: The ISO 639-1 two-character language code. The value for this field becomes a tag in the `ua_locale_language` tag group. - `msisdn` string, required: The mobile phone number you want to register as an SMS channel (or send a request to opt-in). Must be numeric characters only, without leading zeros. - `opted_in` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) that represents the date and time when explicit permission was received from the user to receive messages. - `sender` string, required: A long or short code the app is configured to send from. For example, `12345`. - `tag_operations` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/). - `timezone` string: The IANA identifier for a time zone, e.g., `America/Los_Angeles`. The value in this field becomes a tag in the `timezone` tag group. ## Response `200` A channel with this msisdn/sender combination already exists. - union - SmsWithOptin: The request included a valid `opted_in` value. Airship creates a channel that is opted in to your audience. - `attributes` object - `ok` boolean: If `true`, the attributes were set correctly. - `channel_id` string, uuid: Unique channel ID for the SMS channel. - `ok` boolean: If true, Airship creates a channel value with `opt_in` set to `true`. - `operation_id` string, uuid: A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. - `tags` object - `ok` boolean: If `true`, the tags were set correctly. - SmsWithoutOptin: Response to a request that does not include an `opted_in` value. Airship creates a channel with `opt_in` set to `false` and sends the user a message prompting them to opt in. - `attributes` object - `ok` boolean: If `true`, the attributes were set correctly. - `channel_id` string, uuid, required: Unique channel ID for the SMS channel. This channel is created with `opt_in` set to `false`, as the user has not yet opted in to your audience. - `ok` boolean, required: If true, Airship creates a channel with `opt_in` set to `false` and Airship sends a message prompting the user to opt in to your audience. - `operation_id` string, uuid, required: A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. - `push_id` string, uuid, required: Identifies the message prompting the user to opt in to your audience, sent as a result of a request without an `opted_in` value. - `status` 'pending', required: The channel has been created but has not yet opted-in. - `tags` object - `ok` boolean: If `true`, the tags were set correctly. ## Other responses - `201`: The channel was created. If the request did not contain an `opted_in` value, the channel is created with a `pending` status and the channel's `opt_in` value is set to `false`; you can assign assign tags and organize `pending` channels before the user has finished the opt-in process, but you cannot send messages to channels until they complete the opt-in flow. - `400`: The channel could not be created. This error occurs when the project is not configured with a valid sender, the request was missing required fields, or the MSISDN does not meet the E.164 international standard. ## Changes - **2026-06-24** `38241778b0c1`: 2 breaking, 2 info - added `#/components/schemas/sms_with_optin, #/components/schemas/sms_without_optin` to the response body `oneOf` list for the response status `200` - added `#/components/schemas/sms_with_optin, #/components/schemas/sms_without_optin` to the response body `oneOf` list for the response status `201` - removed `subschema #1: New channel with opt-in, subschema #2: New channel without opt-in` from the response body `oneOf` list for the response status `200` - removed `subschema #1: New channel with opt-in, subschema #2: New channel without opt-in` from the response body `oneOf` list for the response status `201` - …this revision’s changelog is incomplete - **2025-11-19** `43eb86d7e2d0`: 1 warning, 1 info - removed the request property `tags` - added the new optional request property `tag_operations` - …this revision’s changelog is incomplete - **2025-08-28** `3304568aaadc`: 1 breaking - the `opted_in` request property format changed from no format to `date-time` - …this revision’s changelog is incomplete - **2022-03-24** `ca569bd1394d`: 1 breaking, 1 info - added the new required request property `sender/sms_sender` - the `sender` request property's minLength was decreased from `1` to `0` [Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/channels/sms/post.md) --- [API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)