SMS

Custom SMS response

Respond to a mobile-originated message based on a keyword consumed by your custom-response webhook, using a mobile-originated ID. See SMS Keyword Webhooks for information about setting up a custom response webhook server.

Jump to examples ↓

POST /api/sms/custom-response

Security:

bearerAuth

Request headers:

X-UA-Appkey stringREQUIRED

Request body:

Content-Type: application/json
One of
- object
- object

Responses

200
The operation was successful.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - ok boolean
    If true, your request was successful.
  - operation_id string
    A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
  - push_id string
    A unique identifier for a push operation.
404
The mobile_originated_id could not be found.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - error string
    A plain-text explanation of the error.
  - ok boolean
    If false, your request was unsuccessful.
  - operation_id string
    A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.

Examples

POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "sms" : {
      "alert": "Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.",
      "shorten_links": true
  },
  "mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setBearerToken("<token>")
        .build();

CustomSmsResponseSmsPayload customSmsResponseChannelSms = CustomSmsResponseSmsPayload.newBuilder()
        .setAlert("Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.")
        .setMobileOriginatedId("28883743-4868-4083-ab5d-77ac4542531a")
        .setShortenLinks(true)
        .build();

CustomSmsResponseRequest customSmsResponseRequest = CustomSmsResponseRequest.newRequest(customSmsResponseChannelSms);
Response<CustomSmsResponseResponse> response = client.execute(customSmsResponseRequest);

from urbanairship import (
    BearerTokenClient, SmsCustomResponse,
    sms, mms
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

custom_response = SmsCustomResponse(
    client=client,
    mobile_originated_id="28883743-4868-4083-ab5d-77ac4542531a"
)

custom_response.sms = sms(
    alert="Your balance is $1234.56. Go to https://www.example.com/myaccount/my-balance?ua-tag-add=balance_prefs:sms to see more about your account.",
    shorten_links=True
)

response = custom_response.send()

POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <bearer token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
  "mms" : {
    "fallback_text": "See fun cat pics at https://example.com/cat/pics/12345678",
    "slides": [
      {
        "media": {
          "url": "https://example.com/cat/pics/12345678.gif",
          "content_type": "image/gif",
          "content_length": 23098
        }
      }
    ],
    "shorten_links": true
  },
  "mobile_originated_id" : "3e1e4fb3-2d3c-431e-96bf-9b235a12f84b"
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
      "ok": true,
      "operation_id": "f3d0993e-e3e1-4aae-b1c0-864a715bfaff",
      "push_id": "7502abe6-e6ea-4f2b-906f-ebbab612c69e"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setBearerToken("<token>")
        .build();

MmsSlides mmsSlides = MmsSlides.newBuilder()
        .setText("Test")
        .setMediaUrl("https://example.com/cat/pics/12345678.gif")
        .setMediaContentType("image/gif")
        .setMediaContentLength(23098)
        .build();

CustomSmsResponseMmsPayload customSmsResponseMmsPayload = CustomSmsResponseMmsPayload.newBuilder()
        .setFallbackText("See fun cat pics at https://example.com/cat/pics/12345678")
        .setMobileOriginatedId("28883743-4868-4083-ab5d-77ac4542531a")
        .setSlides(mmsSlides)
        .build();

CustomSmsResponseRequest customSmsResponseRequest = customSmsResponseRequest.newRequest(customSmsResponseMmsPayload);
Response<CustomSmsResponseResponse> response = client.execute(customSmsResponseRequest);

from urbanairship import (
    BearerTokenClient, SmsCustomResponse,
    mms
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

custom_response = SmsCustomResponse(
    client=client,
    mobile_originated_id="3e1e4fb3-2d3c-431e-96bf-9b235a12f84b"
)

custom_response.mms = mms(
    fallback_text="See fun cat pics at https://example.com/cat/pics/12345678",
    slides=[{
        "media": {
            "url": "https://example.com/cat/pics/12345678.gif",
            "content_type": "image/gif",
            "content_length": 23098
        }
    }],
    shorten_links=True
)

response = custom_response.send()

Manually trigger a keyword interaction

Trigger Mobile Originated (MO) keyword interactions on behalf of an MSISDN.

Jump to examples ↓

POST /api/sms/{msisdn}/keywords

Security:

Request headers:

X-UA-Appkey stringREQUIRED

Path parameters:

msisdn stringREQUIRED
The identifier for the SMS channel you want to trigger a mobile originated keyword from.

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- keyword stringREQUIRED
  The keyword you want to trigger an action for. Must be an alphanumeric string with no spaces.
- sender_ids array[string]REQUIRED
  The sender IDs with keyword actions that you want to test. Airship returns a 400 if the keyword is not configured for one or more of the senders in the array.
- timestamp string
  The date-time when the MO keyword was sent. If absent, Airship uses the server-time of your request.

Responses

200
The operation was successful.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - ok boolean
    If true, your request was successful.
400
The operation was not successful. If the request is formatted correctly, one or more sender_ids does not exist or the keyword is not configured for one or more of the sender_ids.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/sms/15035556789/keywords HTTP/1.1
User-Agent: Apache-HttpAsyncClient/4.0.1 (java 1.5)
Content-Type: application/json
Authorization: Basic <user:pass>
Connection: close

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

KeywordInteractionRequest request = KeywordInteractionRequest.newRequest("15035556789")
        .addKeyword("stop")
        .addSenderId("54321")
        .addSenderId("1234");

Response<CustomSmsResponseResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, KeywordInteraction
)
from datetime import datetime

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

interaction = KeywordInteraction(
    client=client,
    keyword="stop",
    sender_ids=["54321", "1234"],
    timestamp=datetime(2021, 10, 8, 12, 0, 0)
)
response = interaction.post()

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "ok" : false,
  "error" : "The following sender(s) are not configured for the 'stop' keyword: ['1234']",
  "error_code" : 400
}

Opt-out of SMS messages

This will mark an SMS channel as opted-out (inactive) and it will not receive alerts even when they are addressed in the future. To opt the user back in, call the registration function again with a valid opted_in value.

Jump to examples ↓

POST /api/channels/sms/opt-out

Security:

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- msisdn stringREQUIRED
  The mobile phone number you want to opt-out of SMS messages. Must be numeric characters only, without leading zeros. 15 digits maximum.
- sender stringREQUIRED
  A long or short code the app is configured to send from. For example, 12345.

Responses

202
The msisdn/channel is opted-out of SMS notifications.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - ok boolean
    If true, the operation completed successfully.
400
The request body is not valid.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - details object
    OBJECT PROPERTIES
    - error string
      Specific error message that explains why the request was unsuccessful.
  - error string
    Returned with 40x responses; explains why the request was unsuccessful.
  - error_code integer
    The 5-digit Airship error code, pointing to a more specific error than the HTTP status.
  - ok boolean
    If false, the request was unsuccessful.

Examples

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

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

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newOptOutRequest("12345", "15035556789");

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Sms
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sms = Sms(
    client=client,
    sender='12345',
    msisdn='15035556789'
)
response = sms.opt_out()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opt_out

Register SMS channel

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 or your Account Manager to provision your project for SMS notifications and complete the configuration.

Jump to examples ↓

POST /api/channels/sms

Note

Avoid repeated registration attempts. Repeated registrations of the same MSISDN and sender without an opted_in value will result in multiple opt-in instruction messages being sent to the MSISDN.

Security:

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- 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 stringREQUIRED
  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
  The date-time that represents the date and time when explicit permission was received from the user to receive messages.
- sender stringREQUIRED
  A long or short code the app is configured to send from. For example, 12345.
- tag_operations object<Tag Group object>
  Optionally one or more tag group objects associated with the SMS channel.
  Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.
  A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.
- 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.

Responses

200
A channel with this msisdn/sender combination already exists.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  One of
  - New channel with opt-in object
    The request included a valid opted_in value. Airship creates a channel that is opted in to your audience.
    OBJECT PROPERTIES
    - attributes object
      OBJECT PROPERTIES
      - ok boolean
        If true, the attributes were set correctly.
    - channel_id string
      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
      A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
    - tags object
      OBJECT PROPERTIES
      - ok boolean
        If true, the tags were set correctly.
  - New channel without opt-in object
    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.
    OBJECT PROPERTIES
    - attributes object
      OBJECT PROPERTIES
      - ok boolean
        If true, the attributes were set correctly.
    - channel_id stringREQUIRED
      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 booleanREQUIRED
      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 stringREQUIRED
      A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
    - push_id stringREQUIRED
      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 stringREQUIRED
      The channel has been created but has not yet opted-in.
      Possible values: pending
    - tags object
      OBJECT PROPERTIES
      - ok boolean
        If true, the tags were set correctly.
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.
Response headers:
- location string
  URI of the channel, used for later registrations.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  One of
  - New channel with opt-in object
    The request included a valid opted_in value. Airship creates a channel that is opted in to your audience.
    OBJECT PROPERTIES
    - attributes object
      OBJECT PROPERTIES
      - ok boolean
        If true, the attributes were set correctly.
    - channel_id string
      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
      A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
    - tags object
      OBJECT PROPERTIES
      - ok boolean
        If true, the tags were set correctly.
  - New channel without opt-in object
    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.
    OBJECT PROPERTIES
    - attributes object
      OBJECT PROPERTIES
      - ok boolean
        If true, the attributes were set correctly.
    - channel_id stringREQUIRED
      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 booleanREQUIRED
      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 stringREQUIRED
      A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
    - push_id stringREQUIRED
      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 stringREQUIRED
      The channel has been created but has not yet opted-in.
      Possible values: pending
    - tags object
      OBJECT PROPERTIES
      - ok boolean
        If true, the tags were set correctly.
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.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - errors string
    Returned with 40x responses; explains reason for the unsuccessful request.
  - ok boolean
    If false, the request was unsuccessful.

Examples

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": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en",
  "tag_operations": {
    "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
    }
  },
  "attributes": {
      "my_fav_attribute1": "attribute1",
      "my_fav_attribute2": "attribute2"
  }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newRegistrationRequest("12345", "15035556789", DateTime.parse("2020-02-13T11:58:59Z"));

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BearerTokenClient, Sms
)
from datetime import datetime

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

sms_channel = Sms(
    client=client,
    sender="12345",
    msisdn="15035556789",
    opted_in=datetime.fromisoformat("2020-02-13T11:58:59"),
    locale_country="US",
    locale_language="en",
    timezone="America/Los_Angeles"
)

response = sms_channel.register()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.opted_in = '2020-02-13T11:58:59'
sms_channel.register

HTTP/1.1 201 Created
Location: https://go.urbanairship.com/api/channels/7c5d7328-9bb4-4ff7-86b0-96a5f1da5868
Content-Type: application/json

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "channel_id": "7c5d7328-9bb4-4ff7-86b0-96a5f1da5868",
  "attributes": {"ok": true},
  "tags": {"ok": true}
}

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://go.urbanairship.com/api/channels/79fbe330-d033-11e9-adfb-df10b89c5e04

{
  "ok": true,
  "operation_id": "62077236-d032-11e9-af71-ab156113d166",
  "push_id": "26350f60-d033-11e9-80e3-33def0e528d1",
  "channel_id": "79fbe330-d033-11e9-adfb-df10b89c5e04",
  "status": "pending",
  "attributes": {"ok": true},
  "tags": {"ok": true}
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "ok": false,
    "errors": "Unable to retrieve details for sender 12345 with app_key <application key>"
}

SMS channel lookup

Lookup an SMS channel by msisdn and sender.

Jump to examples ↓

GET /api/channels/sms/{msisdn}/{sender}

Security:

Path parameters:

msisdn integerREQUIRED
The mobile phone number you want to lookup a channel for. 15 digits maximum; may not contain leading zeroes.
sender integerREQUIRED
A long or short code the app is configured to send from.

Responses

200
Returns an SMS channel object. An SMS channel object includes tag groups for ua_channel_type, ua_sender_id, and ua_opt_in.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - channel object<Channel listing object>
    Describes a channel listing object.
  - ok boolean
    Success.
404
A channel_id does not exist for the msisdn and sender.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - error string
    Returned with 40x responses; explains why the request was unsuccessful.
  - error_code integer
    The 5-digit Airship error code, pointing to a more specific error than the HTTP status.
  - ok boolean
    If false, the request was unsuccessful.

Examples

GET /api/channels/sms/15035556789/12345 HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Data-Attribute: channel
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "channel": {
      "channel_id": "84e36d69-873b-4ffe-81cd-e74c9f002057",
      "device_type": "sms",
      "installed": true,
      "push_address": null,
      "named_user_id": null,
      "alias": null,
      "tags": [],
      "tag_groups": {
         "ua_channel_type": [
            "sms"
         ],
         "ua_sender_id": [
            "12345"
         ],
         "ua_opt_in": [
            "true"
         ]
      },
      "created": "2020-04-27T22:06:21",
      "opt_in": true,
      "opt_in_date": "2022-07-07T03:23:13",
      "msisdn": "150355551234",
      "last_registration": "2020-05-14T19:51:38"
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ChannelRequest channelRequest = ChannelRequest.newSmsLookupRequest("15035556789","12345");
Response<ChannelResponse> response = client.execute(channelRequest);

from urbanairship import (
    BasicAuthClient, Sms
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sms = Sms(
    client=client,
    sender='12345',
    msisdn='15035556789'
)
channel_info = sms.lookup()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.lookup

HTTP/1.1 200 OK
Data-Attribute: channel
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "channel": {
      "channel_id": "84e36d69-873b-4ffe-81cd-e74c9f002057",
      "device_type": "sms",
      "installed": true,
      "push_address": null,
      "named_user_id": null,
      "alias": null,
      "tags": [],
      "tag_groups": {
         "ua_channel_type": [
            "sms"
         ],
         "ua_sender_id": [
            "12345"
         ],
         "ua_opt_in": [
            "true"
         ]
      },
      "created": "2020-04-27T22:06:21",
      "opt_in": false,
      "opt_in_date": "2022-07-07T03:23:13",
      "opt_out_date": "2022-07-08T03:23:13",
      "msisdn": "150355551234",
      "last_registration": "2020-05-14T19:51:38"
   }
}

SMS tags

Add, remove, or set tags for a single SMS channel.

Jump to examples ↓

POST /api/channels/sms/tags

Security:

Request body:

A single request body can contain an add and/or remove field or a single set field. One or more of the add, remove, or set keys must be present in the request.

Content-Type: application/json
OBJECT PROPERTIES
- add object<Tag Group object>
  Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation.
  Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.
  A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.
- audience objectREQUIRED
  Specifies the MSISDN and sender you want to perform tag operations against.
  OBJECT PROPERTIES
  - msisdn string
    The mobile phone number corresponding to the SMS channel. Must be numeric characters only, without leading zeros. 15 digits maximum.
  - sender string
    A long or short code the app is configured to send from. For example, 12345.
- remove object<Tag Group object>
  Removes the specified tags from the channel.
  Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.
  A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.
- set object<Tag Group object>
  Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed.
  Tags belong to Tag Groups. Tag Groups appear within the tags object for a Named User or the tag_groups object for a channel. See also Device Properties ua_ is a reserved prefix for Airship-specific tag groups.
  A Tag Group has two parts: a “name” string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters.

Responses

200
Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 will be returned with a warning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OK response
  Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
403
Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/channels/sms/tags HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "audience": {
    "sender": "12345",
    "msisdn": "15035556789"
   },
   "add": {
      "my_fav_tag_group1": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group2": ["tag1", "tag2", "tag3"],
      "my_fav_tag_group3": ["tag1", "tag2", "tag3"]
   }
}

Uninstall SMS channel

Removes phone numbers and accompanying data from Airship. Use with caution. Uninstalling an SMS channel will prevent you from retrieving opt-in and opt-out history for the corresponding msisdn. If the uninstalled msisdn opts-in again, it will generate a new channel_id. The new channel_id cannot be reassociated with any opt-in information, tags, Named Users, Performance Analytics reports, or other information from the uninstalled SMS channel.

Jump to examples ↓

POST /api/channels/sms/uninstall

Security:

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- msisdn stringREQUIRED
  The mobile phone number you want to remove from the Airship system. Must be numeric characters only, without leading zeros. 15 digits maximum.
- sender stringREQUIRED
  A long or short code the app is configured to send from. For example, 12345.

Responses

202
The SMS channel and all information associated with the msisdn is uninstalled.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - ok boolean
    If true, the operation was successful.
400
The request body is not valid.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - details object
    OBJECT PROPERTIES
    - error string
      Specific error message that explains why the request was unsuccessful.
  - error string
    Returned with 40x responses; explains why the request was unsuccessful.
  - error_code integer
    The 5-digit Airship error code, pointing to a more specific error than the HTTP status.
  - ok boolean
    If false, the request was unsuccessful.

Examples

POST /api/channels/sms/uninstall HTTP/1.1
Authorization: Bearer <authorization token>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

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

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SmsRegistrationRequest request = SmsRegistrationRequest
        .newUninstallRequest("12345", "15035556789");

Response<SmsRegistrationResponse> response = client.execute(request);

from urbanairship import (
    BasicAuthClient, Sms
)

client = BasicAuthClient(
    key='<app_key>',
    secret='<master_secret>'
)

sms = Sms(
    client=client,
    sender='12345',
    msisdn='15035556789'
)
response = sms.uninstall()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

sms_channel = UA::Sms.new(client: airship)
sms_channel.msisdn = '15035556789'
sms_channel.sender = '12345'
sms_channel.uninstall

Update SMS channel

Update an existing SMS channel to reflect opt-in date, time zone and/or locale changes. The msisdn and sender in the request must match the existing channel or the request will 404.

Jump to examples ↓

PUT /api/channels/sms/{channel_id}

Security:

Path parameters:

channel_id stringREQUIRED
The identifier for the SMS channel you want to update.

Request body:

Content-Type: application/json
OBJECT PROPERTIES
- 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 stringREQUIRED
  The phone number corresponding to the channel_id in the request. You cannot change this value for the existing channel.
- opted_in string
  The date-time that represents when explicit permission was received from the user to receive messages.
- sender stringREQUIRED
  The sender corresponding to the channel_id in the request. You cannot change this value for an existing channel.
- 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.

Responses

200
The SMS channel was updated successfully.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - ok boolean
    True if the request was successful.
  - operation_id string
    A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.
400
The request to update the channel failed. This error occurs when the MSISDN does not fall into the geographical region supported by the sender or the request is incorrect, e.g., missing or mismatching msisdn or sender, the msisdn is not a valid E.164 standard MSISDN, or invalid timezone/locale values are supplied.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - errors string
    Returned with 40x responses; explains reason for the unsuccessful request.
  - ok boolean
    If false, the request was unsuccessful.
404
Occurs when the msisdn and/or sender don’t match any existing channel_id.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - errors string
    A plain-text explanation of the error.
  - ok boolean
    If false, your request was unsuccessful.

Examples

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": "2020-02-13T11:58:59",
  "timezone": "America/Los_Angeles",
  "locale_country": "US",
  "locale_language": "en"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

UpdateSmsChannel updateSmsChannel = UpdateSmsChannel.newBuilder()
        .setMsisdn("13609048615")
        .setSender("17372004196")
        .setOptedIn(DateTime.parse("2021-10-11T02:03:03"))
        .setLocaleCountry("US")
        .setLocaleLanguage("en")
        .setTimeZone("America/Los_Angeles")
        .build();

UpdateSmsChannelRequest updateSmsChannelRequest = UpdateSmsChannelRequest.newRequest("308303cf-9c10-4d71-9bc2-d9f3a671ed0c", updateSmsChannel);

Response<GenericResponse> response = client.execute(updateSmsChannelRequest);

from urbanairship import (
    BearerTokenClient, Sms
)
from datetime import datetime

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

sms_channel = Sms(
    client=client,
    sender="12345",
    msisdn="15035556789",
    opted_in=datetime.fromisoformat("2021-02-13T11:58:59"),
    locale_country="US",
    locale_language="en",
    timezone="America/Los_Angeles"
)

# Update properties
sms_channel.locale_country = "FR"
sms_channel.opted_in = datetime.fromisoformat("2020-02-13T11:58:59")

response = sms_channel.update()