{ "components": { "parameters": { "appKeyHeader": { "description": "The application key for your project.", "in": "header", "name": "X-UA-Appkey", "required": true, "schema": { "title": "Airship App Key header", "type": "string" }, "x-inline-component": true }, "precision": { "description": "Granularity of results to return. Defaults to `DAILY`.", "in": "query", "name": "precision", "required": false, "schema": { "default": "DAILY", "enum": [ "HOURLY", "DAILY", "MONTHLY" ], "type": "string" }, "x-inline-component": true }, "precisionRequired": { "description": "Granularity of results to return. Defaults to `DAILY`.", "in": "query", "name": "precision", "required": true, "schema": { "default": "DAILY", "enum": [ "HOURLY", "DAILY", "MONTHLY" ], "type": "string" }, "x-inline-component": true } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "Everything worked as expected." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The request has been accepted for processing." }, "204": { "description": "An API request was successful, but there is no response body to return." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "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." }, "401": { "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Authentication information (the app key and secret or bearer token) was either incorrect or missing." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "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." }, "404": { "content": { "application/vnd.urbanairship+json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "The requested resource doesn't exist." }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Returned when a request is made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules." }, "406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "The request conflicts with another request." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Returned when the request is too large to be processed." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Too many requests hit the API too quickly. For example, if we are not ready to create a channel for this payload; e.g., it is rate limited. You should wait before retrying the channel creation." } }, "schemas": { "actionsObject": { "description": "Describes Actions to be performed by the SDK when a user interacts with the notification. You can personalize message actions using [Handlebars](/guides/personalization/handlebars/).", "properties": { "add_custom_event": { "description": "Emit a custom event when a user interacts with the push notification.", "properties": { "name": { "description": "The name of the custom event.", "type": "string" }, "properties": { "description": "A JSON object with the properties associated with the event.", "type": "object" }, "value": { "description": "An integer or decimal value of the event.", "type": "number" } }, "required": [ "name" ], "type": "object" }, "add_tag": { "$ref": "#/components/schemas/tagArray", "description": "Add tag action. When a user interacts with the notification, these tags will be added to the user's Channel ID." }, "app_defined": { "additionalProperties": { "title": "Application-Defined Action Payload", "type": "object" }, "description": "A map of registered action names to payloads as defined by the app or SDK. Some of these actions are supported as their own property on the Actions object, but be aware that their registered names in the SDK may be different. For a summary of the actions registered by the SDK, including usage information, see the [SDK Actions](/sdk-topics/actions/) docs.", "type": "object" }, "attributes": { "description": "Set or remove attributes on a channel or contact when a user interacts with the notification.", "items": { "oneOf": [ { "$ref": "#/components/schemas/setAttributesActionItem" }, { "$ref": "#/components/schemas/removeAttributesActionItem" } ] }, "type": "array" }, "open": { "description": "Open action. When a user interacts with the notification, opens one of: URL, deep link, or landing page as described in the associated `content` property.", "oneOf": [ { "description": "Opens a URL or passes a string for use as a custom action.", "properties": { "content": { "description": "Any string. A URL string that starts with either `http` or `https` will open a URL or a string that starts with `tel:` followed by a sequence of numbers will open the phone app.", "example": [ "https://www.airship.com/docs", "tel:15035551234" ], "type": "string" }, "type": { "enum": [ "url" ], "type": "string" } }, "required": [ "type", "content" ], "title": "Open URL Action", "type": "object" }, { "description": "Opens a deep link.", "properties": { "content": { "description": "A non-blank string.", "maxLength": 1024, "minLength": 1, "type": "string" }, "fallback_url": { "$ref": "#/components/schemas/fallbackUrl" }, "type": { "enum": [ "deep_link" ], "type": "string" } }, "required": [ "type", "content" ], "title": "Open Deep Link Action", "type": "object" }, { "description": "Opens a landing page.", "properties": { "content": { "$ref": "#/components/schemas/landingPageContent" }, "type": { "enum": [ "landing_page" ], "type": "string" } }, "required": [ "type", "content" ], "title": "Open Landing Page", "type": "object" } ], "type": "object" }, "remove_tag": { "$ref": "#/components/schemas/tagArray", "description": "Remove tag action. Upon interaction with the notification, the defined tag or tags will be removed from the user's Channel ID." }, "share": { "description": "String indicating the text that will populate the share action.", "example": "Hey guys check this out!", "maxLength": 1024, "minLength": 1, "type": "string" }, "subscription_list": { "description": "Alter subscription list membership for a channel or contact.", "items": { "$ref": "#/components/schemas/subscriptionListAction" }, "type": "array" }, "tags": { "description": "Add or remove tags on a channel or contact when a user interacts with the notification. Can coexist with `add_tag` and `remove_tag`, but the same device-level tag cannot appear in both.", "items": { "$ref": "#/components/schemas/tagsActionArg" }, "type": "array" } }, "title": "Actions", "x-schema-tag": "Push" }, "activityLogObject": { "description": "The activity log data.", "properties": { "delivery": { "properties": { "app": { "properties": { "alerting": { "description": "The number of alerting pushes sent.", "type": "integer" }, "in_app": { "properties": { "impressions": { "description": "The number of impressions from the push.", "type": "integer" }, "impressions_opted_in": { "description": "The number of opted in impressions from the push.", "type": "integer" }, "impressions_opted_out": { "description": "The number of opted out impressions from the push.", "type": "integer" } }, "type": "object" }, "rich": { "description": "The number of rich pushes sent.", "type": "integer" }, "silent": { "description": "The number of silent pushes sent.", "type": "integer" } }, "type": "object" }, "web": { "properties": { "total": { "description": "The number of web pushes delivered.", "type": "integer" } }, "type": "object" } }, "type": "object" }, "details": { "properties": { "interaction": { "properties": { "app": { "properties": { "direct": { "description": "The number of direct opens of your app.", "type": "integer" }, "indirect": { "description": "The number of indirect opens of your app.", "type": "integer" }, "influenced": { "description": "The number of influenced opens of your app.", "type": "integer" }, "rich_read": { "description": "The number of app rich messages read.", "type": "integer" } }, "type": "object" }, "web": { "properties": { "clicks": { "description": "The number of direct clicks on the web notification.", "type": "integer" }, "sessions": { "description": "The number of sessions created during the specified timeframe.", "type": "integer" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "experiment": { "description": "A boolean value indicating whether or not the push is an experiment.", "type": "boolean" }, "push_id": { "description": "Unique identifier that represents a specific push message delivery.", "format": "uuid", "type": "string" }, "timestamp": { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format) for the end of the report.", "format": "date-time", "type": "string" }, "type": { "description": "The type of push. `GROUP` is for a group message, like push to local time or automation. `PUSH` is for other pushes.", "enum": [ "PUSH", "GROUP" ], "type": "string" } }, "type": "object", "x-inline-component": true }, "activityLogReport": { "description": "The activity log data.", "properties": { "activities": { "description": "An array of activity log data.", "items": { "$ref": "#/components/schemas/activityLogObject" }, "type": "array" }, "app_key": { "description": "The app key for the application.", "type": "string" }, "end": { "description": "The end [date-time](/developer/rest-api/ua/introduction/#date-time-format) for the report.", "format": "date-time", "type": "string" }, "limit": { "description": "The optional limit for the number of entries to return per request. Defaults to 100.", "type": "integer" }, "next_page": { "description": "There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.", "format": "url", "type": "string" }, "start": { "description": "The start [date-time](/developer/rest-api/ua/introduction/#date-time-format) for the report.", "format": "date-time", "type": "string" } }, "type": "object", "x-inline-component": true }, "activityObject": { "description": "The `activity` object defines the target audience based on lifecycle actions or custom event activity, using comparison operators on activity count and recency. Optionally include a `where` object, which filters for specific activity values.\n\nIn the example to the right, the target audience is users who have opened your app from a notification from the \"neowise\" campaign at least twice, 3 days ago.\n", "properties": { "activity": { "description": "The target event activity, e.g., `app_open`.\n\nDefault event values are enumerated below. If you create a custom or predefined event that you wish to segment users on, you must register the event in the Airship dashboard. See [Manage events](/guides/audience/events/manage/).\n", "enum": [ "app_open", "message_received", "message_center_read", "message_center_delivered", "message_center_deleted", "in_app_message_display", "in_app_message_resolution", "in_app_message_expiration", "screen_view", "web_session", "web_click", "short_link_click", "first_seen", "sms_aborted", "sms_delivered", "sms_dispatched", "sms_expired", "sms_failed", "sms_rejected", "sms_undeliverable", "sms_unknown", "email_bounce", "email_click", "email_delay", "email_delivered", "email_injection", "email_open", "email_unsubscribe", "scene_displayed", "scene_completed", "scene_incomplete", "survey_displayed", "survey_submitted", "survey_not_submitted" ], "type": "string" }, "after": { "description": "A date value for an absolute comparison or an integer value for a relative comparison.\n", "oneOf": [ { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format), for example: `\"after\": \"2020-08-01T12:00:00\"`.", "format": "date-time", "type": "string" }, { "type": "integer" } ] }, "before": { "description": "A date value for an absolute comparison or an integer value for a relative comparison.\n", "oneOf": [ { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format), for example: `\"before\": \"2020-08-01T12:00:00\"`.", "format": "date-time", "type": "string" }, { "type": "integer" } ] }, "metric": { "description": "The metric you are targeting for the event.\n\nWhen using the metric `count` or `total_value`, `operator` and `value` are required.\n\nWhen using either `first` or `last`, `operator` and `value` are not allowed. Use one of the following combinations instead:\n\n* `before`/`precision`\n* `after`/`precision`\n* `on`/`on_precision`\n\n| Metric | Description |\n|---|---|\n| `count` | Evaluate based on the number of event occurrences. |\n| `total_value` | Evaluate based on the cumulative event `value` associated with the target user. |\n| `last` | Evaluate based on the last occurrence of an event for a given user/time window. |\n| `first` | Evaluate based on the first occurrence of an event for a given user/time window. |\n", "enum": [ "count", "total_value", "last", "first" ], "type": "string" }, "on": { "description": "Use `on` in conjunction with the `first` or `last` metric to indicate either a specific date or period with precision. Use either:\n\n* A date in ISO 8601 format, e.g., `2020-08-10T17:28:34+0000` or\n* An integer that, when combined with the `on_precision` property, specifies the time period. For example, use `\"on\": 12` with `\"on_precision: \"month\"` to target events that occurred in December.\n", "oneOf": [ { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format).", "format": "date-time", "type": "string" }, { "type": "integer" } ], "type": "string" }, "on_precision": { "description": "When using the `first` or `last` metric with the `on` property to target events on. For example, for the 5th of any month, or only in March, use `on_precision`.", "enum": [ "day", "month", "month_day", "year_month", "year_month_day" ], "type": "string" }, "operator": { "description": "The comparison operator used to evaluate the activity expression. Use these operators (greater/less than, equal to, equal or greater/equal or less) when the `metric` is either `count` or `total_value`.\n", "enum": [ "greater", "less", "equals", "greater_eq", "less_eq" ], "type": "string" }, "precision": { "default": "days", "description": "If using a relative number (integer) for the `before`/`after`/`on` property,\nthe `precision` value will be interpreted as the number of time units ago, e.g.,\n*7 days ago*. Defaults to `days`.\n", "enum": [ "days", "weeks", "months", "years" ], "type": "string" }, "value": { "description": "The value that the `operator` uses to evaluate the target audience.\n", "type": "number" }, "where": { "$ref": "#/components/schemas/whereObject" } }, "required": [ "activity", "operator", "value" ], "title": "Activity audience object", "type": "object", "x-inline-component": false, "x-schema-tag": "Event segmentation" }, "allRichPushPlatformsObject": { "properties": { "responses": { "description": "The number of opens or clicks to the notification.", "type": "integer" }, "sends": { "description": "The number of sends for the given push.", "type": "integer" } }, "type": "object", "x-inline-component": true }, "allSelector": { "description": "The simplest selector, which targets the entire audience.", "enum": [ "all" ], "title": "All selector", "type": "string", "x-inline-component": true }, "amazonOverrideObject": { "description": "The platform override section for Kindle Fire (for Amazon Device Messaging).", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "alert": { "description": "A string that override the alert value provided at the top level, if any.", "type": "string" }, "consolidation_key": { "description": "A string representing a key to suppress previous messages sent with the same key.", "type": "string" }, "expires_after": { "$ref": "#/components/schemas/expiryObject", "description": "An integer or ISO-formatted UTC timestamp indicating how long ADM will retain the message if the device is offline. The integer value in seconds and valid range is 60 - 2678400 (1 minute to 31 days), inclusive." }, "extra": { "$ref": "#/components/schemas/extraObject" }, "icon": { "description": "A string representing an image file included in the application’s resources.", "type": "string" }, "icon_color": { "description": "A string representing the icon color in API Color Format. i.e., `#rrggbb`", "type": "string" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "notification_channel": { "description": "A string representing a notification channel. Used to group notifications with similar behavior.", "type": "string" }, "notification_tag": { "description": "A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification.", "type": "string" }, "sound": { "description": "A string representing a sound file name included in the application’s resources.", "type": "string" }, "style": { "$ref": "#/components/schemas/style" }, "summary": { "description": "A string representing a summary/subtitle of the notification.", "type": "string" }, "title": { "description": "A string representing the title of the notification. The default value is the name of the app.", "type": "string" } }, "title": "Fire OS overrides", "type": "object", "x-schema-tag": "Platform overrides" }, "amazonOverrideWithTemplate": { "description": "Use a `template` with a Fire OS-specific message. You can reference a template by ID, or use `{{handlebars}}` directly in your message.", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "consolidation_key": { "description": "A string representing a key to suppress previous messages sent with the same key.", "type": "string" }, "expires_after": { "$ref": "#/components/schemas/expiryObject", "description": "An integer or ISO-formatted UTC timestamp indicating how long ADM will retain the message if the device is offline. The integer value in seconds and valid range is 60 - 2678400 (1 minute to 31 days), inclusive." }, "extra": { "$ref": "#/components/schemas/extraObject" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "notification_channel": { "description": "A string representing a notification channel. Used to group notifications with similar behavior.", "type": "string" }, "notification_tag": { "description": "A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification.", "type": "string" }, "sound": { "description": "A string representing a sound file name included in the application’s resources.", "type": "string" }, "style": { "$ref": "#/components/schemas/style" }, "template": { "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "type": "object" }, { "properties": { "external_id": { "$ref": "#/components/schemas/external_id" } }, "type": "object" }, { "properties": { "fields": { "description": "Items in the field object are personalizable with handlebars.", "properties": { "alert": { "description": "A string that override the alert value provided at the top level, if any.", "type": "string" }, "icon": { "description": "A string representing an image file included in the application’s resources.", "type": "string" }, "icon_color": { "description": "A string representing the icon color in API Color Format. i.e., `#rrggbb`", "type": "string" }, "summary": { "description": "A string representing a summary/subtitle of the notification.", "type": "string" }, "title": { "description": "A string representing the title of the notification. The default value is the name of the app.", "type": "string" } }, "type": "object" } }, "type": "object" } ] } }, "title": "Fire OS overrides with template", "type": "object", "x-schema-tag": "Platform overrides with templates" }, "amazon_channel": { "description": "The unique channel identifier used to target a Fire OS device.", "properties": { "amazon_channel": { "oneOf": [ { "format": "uuid", "type": "string" }, { "$ref": "#/components/schemas/uuidArray" } ] } }, "required": [ "amazon_channel" ], "title": "Fire OS channel selector", "type": "object", "x-inline-component": true }, "androidOverrideObject": { "description": "The platform override section for Android. Maximum 4,096 bytes.", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "alert": { "description": "A string that override the alert value provided at the top level, if any.", "type": "string" }, "category": { "description": "Helps determine notification sort order. Available on Android Lollipop+.", "enum": [ "alarm", "call", "email", "err", "event", "msg", "promo", "recommendation", "service", "social", "status", "sys", "transport" ], "type": "string" }, "collapse_key": { "description": "A key indicating that this message can replace, or be replaced by, another message with the same `collapse_key`. This feature comes into play when a device is offline (e.g., airplane mode) or in doze mode; if multiple messages are available with the same collapse_key when a device comes back online, it will display only the most recent message and discard previous messages using the same `collapse_key`.", "type": "string" }, "delay_while_idle": { "default": false, "deprecated": true, "description": "After November 15, 2016, this was still accepted by GCM, but ignored. When set to `true`, it indicates that the message should not be sent until the device becomes active. The default value is false.", "type": "boolean" }, "deliver_to": { "default": "all", "description": "Filters out Android channels that are not able to receive notifications. If the value is `opted_in`, the payload is only sent to opted-in devices. If the value is `all`, the payload is sent to opted-in and background enabled devices. Defaults to `all` if not provided.", "enum": [ "all", "opted_in" ], "type": "string" }, "delivery_priority": { "default": "normal", "description": "Sets the FCM/GCM priority of the message. Defaults to `normal` if not provided.", "enum": [ "high", "normal" ], "type": "string" }, "extra": { "additionalProperties": { "type": "string" }, "description": "A JSON dictionary of string-to-string key-value pairs. The keys `from`, `message_type`, `data` and keys that start with `google` or `gcm` are disallowed.", "type": "object" }, "icon": { "description": "A string representing an image file included in the application’s resources.", "type": "string" }, "icon_color": { "description": "A string representing the icon color in API Color Format. i.e., `#rrggbb`", "type": "string" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "live_update": { "description": "JSON object that represents the content sent to a Live Update notification. Live Updates are an [AXP feature](/reference/feature-packages/). \n\n**Note**: Using this object transforms the Android notification to a Live Update notification.\nWhen `event` is equal to `start`, the entire targeted audience will receive the Live Update content.\nWhen `event` is equal to `update` or `end`, only devices that have a Live Update started for the specified `name` field will receive the Live Update content.", "properties": { "content_state": { "$ref": "#/components/schemas/contentStateObject" }, "dismissal_date": { "description": "An optional epoch timestamp in seconds, used when you end the Live Update.", "format": "int32", "type": "integer" }, "event": { "description": "Use `start` to start a Live Update.\nUse `update` to update a current Live Update.\nUse `end` to emit the last update and end the Live Update.", "enum": [ "start", "update", "end" ], "type": "string" }, "name": { "description": "The name of the Live Update to target. When `event` is equal to `update` or `end`, the audience will be limited to devices that have a Live Update started for the specified name.", "type": "string" }, "timestamp": { "description": "An optional epoch timestamp in seconds, used to enforce the Live Update ordering. If you don't provide one, the current timestamp is used.", "format": "int32", "type": "integer" }, "type": { "description": "Used to map Live Update events to the corresponding handler in your app.", "type": "string" } }, "type": "object" }, "local_only": { "default": false, "description": "If true, the notification is only shown on wearable devices.", "type": "boolean" }, "notification_channel": { "description": "A string representing a notification channel. Used to group notifications with similar behavior.", "type": "string" }, "notification_tag": { "description": "A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification. Similar to the iOS `collapse_id`.", "type": "string" }, "priority": { "description": "An integer in the range from -2 to 2 inclusive. Used to help determine notification sort order. 2 is the highest priority, -2 is the lowest, and 0 is the default priority.", "format": "int32", "maximum": 2, "minimum": -2, "type": "integer" }, "public_notification": { "description": "An optional notification to show on lock screen instead of the redacted one. This is only useful with visibility set to -1 (private). The object may contain any of the following string fields `title`, `alert`, and `summary`.", "properties": { "alert": { "type": "string" }, "summary": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "sound": { "description": "A string representing a sound file name included in the application’s resources.", "type": "string" }, "style": { "$ref": "#/components/schemas/style" }, "summary": { "description": "A string representing a summary/subtitle of the notification.", "type": "string" }, "time_to_live": { "$ref": "#/components/schemas/expiryObject", "description": "An integer (in seconds) or ISO-formatted timestamp specifying how long the message should be stored if the device is offline. O indicates that the message should not be stored. (i.e., Now or never delivery)." }, "title": { "description": "A string representing the title of the notification. The default value is the name of the app.", "type": "string" }, "visibility": { "description": "An integer in the range from -1 to 1 inclusive. 1 = public (default), 0 = private, -1 = secret. Secret does not show any notifications. Private shows a redacted version of the notification.", "enum": [ -1, 0, 1 ], "format": "int32", "type": "integer" }, "wearable": { "description": "Provides options for messages displayed on wearable Android devices.", "properties": { "background_image": { "description": "The URL to a background image to display on the wearable device.", "type": "string" }, "extra_pages": { "description": "An array of objects, each with a `title` and `alert` string attributes specifying extra pages of text to appear as pages after the notification alert on the wearable device.", "items": { "properties": { "alert": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "type": "array" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" } }, "type": "object" } }, "title": "Android overrides", "type": "object", "x-schema-tag": "Platform overrides" }, "androidOverrideWithTemplate": { "description": "Use a `template` with an Android-specific fields. You can reference a template by ID, or use `{{handlebars}}` directly in your message.", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "category": { "description": "Helps determine notification sort order. Available on Android Lollipop+.", "enum": [ "alarm", "call", "email", "err", "event", "msg", "promo", "recommendation", "service", "social", "status", "sys", "transport" ], "type": "string" }, "collapse_key": { "description": "A key indicating that this message can replace, or be replaced by, another message with the same `collapse_key`. This feature comes into play when a device is offline (e.g., airplane mode) or in doze mode; if multiple messages are available with the same collapse_key when a device comes back online, it will display only the most recent message and discard previous messages using the same `collapse_key`.", "type": "string" }, "delay_while_idle": { "default": false, "deprecated": true, "description": "After November 15, 2016, this was still accepted by GCM, but ignored. When set to `true`, it indicates that the message should not be sent until the device becomes active. The default value is false.", "type": "boolean" }, "deliver_to": { "default": "all", "description": "Filters out Android channels that are not able to receive notifications. If the value is `opted_in`, the payload is only sent to opted-in devices. If the value is `all`, the payload is sent to opted-in and background enabled devices. Defaults to `all` if not provided.", "enum": [ "all", "opted_in" ], "type": "string" }, "delivery_priority": { "default": "normal", "description": "Sets the FCM/GCM priority of the message. Defaults to `normal` if not provided. ", "enum": [ "high", "normal" ], "type": "string" }, "extra": { "additionalProperties": { "type": "string" }, "description": "A JSON dictionary of string-to-string key-value pairs. The keys `from`, `message_type`, `data` and keys that start with `google` or `gcm` are disallowed.", "type": "object" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "local_only": { "default": false, "description": "If true, the notification is only shown on wearable devices.", "type": "boolean" }, "notification_channel": { "description": "A string representing a notification channel. Used to group notifications with similar behavior.", "type": "string" }, "notification_tag": { "description": "A string representing a notification tag. If a message is currently displaying and has a tag set, sending another message with the same tag will replace the posted notification. Similar to the iOS `collapse_id`.", "type": "string" }, "priority": { "description": "An integer in the range from -2 to 2 inclusive. Used to help determine notification sort order. 2 is the highest priority, -2 is the lowest, and 0 is the default priority.", "format": "int32", "maximum": 2, "minimum": -2, "type": "integer" }, "public_notification": { "description": "An optional notification to show on lock screen instead of the redacted one. This is only useful with visibility set to -1 (private). The object may contain any of the following string fields `title`, `alert`, and `summary`.", "properties": { "alert": { "type": "string" }, "summary": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "sound": { "description": "A string representing a sound file name included in the application’s resources.", "type": "string" }, "style": { "$ref": "#/components/schemas/style" }, "template": { "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "type": "object" }, { "properties": { "external_id": { "$ref": "#/components/schemas/external_id" } }, "type": "object" }, { "properties": { "fields": { "description": "Items in the field object are personalizable with handlebars.", "properties": { "alert": { "description": "A string that override the alert value provided at the top level, if any.", "type": "string" }, "icon": { "description": "A string representing an image file included in the application’s resources.", "type": "string" }, "icon_color": { "description": "A string representing the icon color in API Color Format. i.e., `#rrggbb`", "type": "string" }, "summary": { "description": "A string representing a summary/subtitle of the notification.", "type": "string" }, "title": { "description": "A string representing the title of the notification. The default value is the name of the app.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "time_to_live": { "$ref": "#/components/schemas/expiryObject", "description": "An integer (in seconds) or ISO-formatted timestamp specifying how long the message should be stored if the device is offline. O indicates that the message should not be stored. (i.e., Now or never delivery)." }, "visibility": { "description": "An integer in the range from -1 to 1 inclusive. 1 = public (default), 0 = private, -1 = secret. Secret does not show any notifications. Private shows a redacted version of the notification.", "enum": [ -1, 0, 1 ], "format": "int32", "type": "integer" }, "wearable": { "description": "Provides options for messages displayed on wearable Android devices.", "properties": { "background_image": { "description": "The URL to a background image to display on the wearable device.", "type": "string" }, "extra_pages": { "description": "An array of objects, each with a `title` and `alert` string attributes specifying extra pages of text to appear as pages after the notification alert on the wearable device.", "items": { "properties": { "alert": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "type": "array" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" } }, "type": "object" } }, "title": "Android overrides with template", "type": "object", "x-schema-tag": "Platform overrides with templates" }, "android_channel": { "description": "The unique channel identifier used to target an Android device.", "properties": { "android_channel": { "oneOf": [ { "format": "uuid", "type": "string" }, { "$ref": "#/components/schemas/uuidArray" } ] } }, "required": [ "android_channel" ], "title": "Android channel selector", "type": "object", "x-inline-component": true }, "appAndWebTemplatesObject": { "description": "The app and web push fields for a template.", "properties": { "alert": { "description": "The text that will display in your push notification.", "type": "string" }, "icon": { "description": "A string representing a URL or an image file included in the application's resources.", "type": "string" }, "summary": { "description": "Supplemental text displayed with the notification.", "type": "string" }, "title": { "description": "A heading that appears above the notification text when applicable.", "type": "string" } }, "required": [ "alert" ], "title": "App and web content template object", "type": "object", "x-schema-tag": "Content objects" }, "assertionJwt": { "allOf": [ { "$ref": "#/components/schemas/assertionJwtHeaders" }, { "$ref": "#/components/schemas/assertionJwtClaims" } ], "description": "A JSON Web Token (JWT) used for authorization in [OAuth token requests](/developer/rest-api/ua/operations/oauth/#requestoauthtoken). The JWT must be signed with the private key corresponding to the `client_id` in the `kid` header using the ES384 algorithm.", "title": "Assertion JWT", "type": "object", "x-schema-tag": "OAuth" }, "assertionJwtClaims": { "description": "Assertion JWT claims", "properties": { "aud": { "description": "The valid request endpoint. Example: `https://oauth2.asnapius.com/token`", "type": "string" }, "exp": { "description": "The `assertion`'s expiration timestamp in seconds since epoch, after which it is not valid. The expiry must not be more than 10 minutes in the future. This is for the `assertion`, not for the token that will be returned. Example: `1681862754`", "type": "integer" }, "iat": { "description": "The issue timestamp in seconds since epoch. Example: `168186250`", "type": "integer" }, "ipaddr": { "description": "A space-delimited list of CIDR representations of valid IP addresses to which the issued token is restricted.", "type": "string" }, "iss": { "description": "The issuer, the `client_id`.", "type": "string" }, "nonce": { "description": "A unique string that must not have been used recently with this `client_id`. We will store this for a minimum of 2 hours. If you are relying on the nonce to defend against replay attacks, it is recommended to also enforce a narrow *ipaddr* range in order to prevent requests that utilize the returned access token from being replayed by an outside client.", "maxLength": 50, "minLength": 1, "type": "string" }, "scope": { "$ref": "#/components/schemas/oauthScope", "description": "A space-delimited list of scopes to which the returned claim should be restricted. If not provided, the full list of scopes the `client_id` is granted will be in the returned claim." }, "sub": { "$ref": "#/components/schemas/subject", "description": "A space-delimited set of identifiers for which subjects a token is allowed. An `app` subject is required. Example: `app:`." } }, "required": [ "iss", "aud", "exp", "iat", "sub", "nonce" ], "title": "Claims", "type": "object", "x-inline-component": true }, "assertionJwtHeaders": { "description": "Assertion JWT headers", "properties": { "alg": { "description": "The signing algorithm.", "enum": [ "ES384" ], "type": "string" }, "kid": { "description": "The key used to sign the JWT, the `client_id`.", "type": "string" } }, "required": [ "kid", "alg" ], "title": "Headers", "type": "object", "x-inline-component": true }, "atomicSelector": { "description": "Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag.", "oneOf": [ { "$ref": "#/components/schemas/allSelector" }, { "$ref": "#/components/schemas/tag" }, { "$ref": "#/components/schemas/segment" }, { "$ref": "#/components/schemas/channel" }, { "$ref": "#/components/schemas/named_user" }, { "$ref": "#/components/schemas/amazon_channel" }, { "$ref": "#/components/schemas/android_channel" }, { "$ref": "#/components/schemas/open_channel" }, { "$ref": "#/components/schemas/sms_sender" }, { "$ref": "#/components/schemas/sms_id" }, { "$ref": "#/components/schemas/static_list" }, { "$ref": "#/components/schemas/subscription_list" }, { "$ref": "#/components/schemas/textAttribute" }, { "$ref": "#/components/schemas/numberAttribute" }, { "$ref": "#/components/schemas/dateAttribute" }, { "$ref": "#/components/schemas/jsonAttribute" }, { "$ref": "#/components/schemas/activityObject" }, { "$ref": "#/components/schemas/triggeredSelector" } ], "title": "Atomic selector", "type": "object", "x-schema-tag": "Audience selection" }, "attributeListMetadataObject": { "description": "Contains all user-specified data when defining an attributes list in Airship.", "properties": { "description": { "description": "An optional description for the list.", "maxLength": 1000, "minLength": 1, "type": "string" }, "extra": { "additionalProperties": { "example": { "key": "value" }, "type": "string" }, "description": "An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters." }, "name": { "description": "The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.\n\nNote: Since the `name` portion of the URL may represent any Unicode string, it must be encoded properly as a URI path component. The `encodeURIComponent` function in JavaScript can be used.\n\nThe list name must include a prefix that determines how empty values are handled:\n - Lists with `ua_attributes_` prefix: Empty or null values are ignored, preserving any existing attribute values not explicitly set in the CSV. This mode is useful for making partial updates to a user's attributes without affecting others.\n - Lists with `ua_attributes_snapshot_` prefix: Empty or null values trigger removing those attributes from the user. This mode is useful for synchronizing attribute states with external systems, ensuring the attributes in the CSV exactly match the user's attributes.", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]*$", "type": "string" } }, "required": [ "name" ], "title": "Attribute list metadata object", "type": "object", "x-inline-component": true }, "attributes": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" } ] }, "description": "Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign.\n\nThis object enumerates predefined attributes, but you can [create your own in the Airship dashboard](/guides/audience/attributes/adding/).\n", "properties": { "account_creation": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the user created their account.", "format": "date-time", "type": "string" }, "advertising_id": { "description": "The IDFA associated with a user.", "type": "string" }, "age": { "description": "The user's age.", "type": "integer" }, "altitude": { "description": "The altitude associated with a user.", "type": "number" }, "birthdate": { "description": "The user's birthdate.", "type": "string" }, "city": { "description": "The city associated with the user.", "type": "string" }, "company": { "description": "The company that a user is associated with.", "type": "string" }, "country": { "description": "The country associated with the user.", "type": "string" }, "email": { "description": "A user's email address.", "type": "string" }, "first_name": { "description": "The first name of a user.", "type": "string" }, "full_name": { "description": "A user's first and last names.", "type": "string" }, "gender": { "description": "A user's gender.", "type": "string" }, "home_phone": { "description": "The user's home phone number — similar to an SMS channel `msisdn`.", "type": "integer" }, "last_name": { "description": "The last name of a user.", "type": "string" }, "latitude": { "description": "The latitude associated with a user — maybe their default location.", "type": "number" }, "longitude": { "description": "The longitude associated with a user — maybe their default location.", "type": "number" }, "loyalty_tier": { "description": "The loyalty program tier that a user is associated with, e.g., gold, platinum, etc.", "type": "string" }, "mobile_phone": { "description": "The user's mobile phone number — similar to an SMS channel `msisdn`.", "type": "integer" }, "region": { "description": "The state, province, principality, etc. associated with the user.", "type": "string" }, "title": { "description": "A default attribute. You must enable this attribute in the dashboard before you can assign it.", "type": "string" }, "username": { "description": "A user's username — generally a part of their login information.", "type": "string" }, "work_phone": { "description": "The user's work phone number — similar to an SMS channel `msisdn`.", "type": "integer" }, "zipcode": { "description": "A user's zipcode. This is different from the SMS channel `ua_ndc` attribute, that records user's area code or phone number prefix.", "type": "integer" } }, "title": "Custom and predefined attributes", "type": "object", "x-schema-tag": "Attributes", "x-weight": 2 }, "attributesArray": { "description": "The array can hold string, number, boolean, objects, and array. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. Objects must be valid JSON or the request will fail.\n", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "$ref": "#/components/schemas/attributesArray" } ] }, "title": "Array", "type": "array", "x-schema-tag": "Attributes" }, "attributesObject": { "properties": { "attributes": { "description": "The attributes that you want to set for, or remove from, your `audience`. You can have both `set` and `remove` actions in the same request.\n", "items": { "oneOf": [ { "$ref": "#/components/schemas/setAttributeObject" }, { "$ref": "#/components/schemas/removeAttributeObject" } ] }, "minItems": 1, "type": "array" } }, "required": [ "attributes" ], "title": "Attribute assignment", "type": "object", "x-inline-component": false, "x-schema-tag": "Attributes", "x-weight": 4 }, "attributesValueObject": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "$ref": "#/components/schemas/attributesArray" } ] }, "properties": { "exp": { "description": "The JSON attribute expiration date, set as the number of seconds since the epoch (January 1st, 1970). After expiration, Airship ignores the attribute where used in segmentation and personalization. If omitted, Airship automatically sets a value of 90 days from the current date and time.\nThe maximum expiry delay for a JSON attribute is 731 days.\n", "type": "number" } }, "type": "object", "x-inline-component": true }, "audienceLimitsObject": { "description": "Defines limits to be applied to Push Notifications and standard in-app messages (not In-App Automations or Scenes) only. See [Audience Limit](/guides/messaging/messages/delivery/delivery/#audience-limit) in the *Message delivery* user guide for additional information and limitations.", "properties": { "max_recipients": { "description": "The maximum number of recipients a push can be delivered to.", "type": "integer" } }, "title": "Audience limits object", "type": "object", "x-schema-tag": "Audience limits" }, "audienceSelector100": { "description": "An audience selector forms the expression that determines the set of channels to target.", "maxItems": 100, "oneOf": [ { "$ref": "#/components/schemas/compoundSelector" }, { "$ref": "#/components/schemas/atomicSelector" } ], "title": "Audience selector (max 100)", "x-schema-tag": "Audience selection" }, "audienceSelector1000": { "description": "An audience selector forms the expression that determines the set of channels to target.", "maxItems": 1000, "oneOf": [ { "$ref": "#/components/schemas/compoundSelector" }, { "$ref": "#/components/schemas/atomicSelector" } ], "title": "Audience selector (max 1000)", "x-schema-tag": "Audience selection" }, "banListParametersObject": { "additionalProperties": { "example": { "key": "value" }, "type": "string" }, "description": "A list of parameters, where the key and value are both strings, that will be used to override the default values set for variables in a [ban list](/guides/audience/segmentation/ban-lists/) request URL.\n", "title": "Ban list parameters", "type": "object", "x-schema-tag": "Audience limits" }, "bulkSendObject": { "description": "A bulk send object describes everything about a [Send message with bulk ID](/developer/rest-api/ua/operations/bulk-sending/#bulksendpush) or [Schedule message with bulk ID](/developer/rest-api/ua/operations/bulk-sending/#schedulebulksendpush) notification. The acceptable fields are identical to a standard push with two exceptions. The audience field can only be a single `bulk_id` and there can only be one `device_type`.", "properties": { "audience": { "properties": { "bulk_id": { "description": "A unique string obtained from the [Create bulk send audience operation](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending.\n", "format": "uuid", "type": "string" } }, "required": [ "bulk_id" ], "type": "object" }, "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "device_types": { "description": "An array containing exactly one targeted platform.", "items": { "enum": [ "android", "amazon", "ios", "web", "sms", "mms", "email", "open::open_platform_name" ], "type": "string" }, "maxItems": 1, "minItems": 1, "type": "array" }, "feed_references": { "$ref": "#/components/schemas/feedReferences" }, "global_attributes": { "$ref": "#/components/schemas/globalAttributes" }, "in_app": { "$ref": "#/components/schemas/inAppObject" }, "localizations": { "description": "An array of localizations. Channels bearing the specified language/country combination will receive the corresponding message.", "items": { "$ref": "#/components/schemas/localization" }, "type": "array" }, "message": { "oneOf": [ { "$ref": "#/components/schemas/messageObject" }, { "$ref": "#/components/schemas/messageObjectWithTemplate" } ] }, "message_type": { "$ref": "#/components/schemas/messageType" }, "notification": { "$ref": "#/components/schemas/notificationObject" }, "options": { "$ref": "#/components/schemas/pushOptions" }, "orchestration": { "$ref": "#/components/schemas/orchestrationObject" }, "snippet_references": { "$ref": "#/components/schemas/snippetReferences" } }, "required": [ "audience", "device_types" ], "title": "Bulk send object", "type": "object", "x-schema-tag": "Bulk sending" }, "buttons": { "description": "Contains one or two buttons that perform actions for the web notification. If you do not specify `actions` for a button, the button closes the notification without performing an action.", "items": { "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "id": { "description": "The `action` ID on the service worker notification event that fires when your audience clicks the button.", "type": "string" }, "label": { "description": "The button label.", "type": "string" } }, "required": [ "id", "label" ], "type": "object" }, "maxItems": 2, "minItems": 1, "type": "array", "x-inline-component": true, "x-schema-tag": "Push" }, "campaignsObject": { "description": "An object specifying custom campaign categories related to the notification.", "properties": { "categories": { "description": "Array of strings representing the campaigns you wish to associate with the notification. Must have between 1 to 10 items in the array with a 64 character/byte maximum per item.", "example": [ "shoes", "running", "summer 2017" ], "items": { "maxLength": 64, "type": "string" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "categories" ], "title": "Campaigns object", "type": "object", "x-schema-tag": "Push" }, "channel": { "description": "The unique channel identifier used to target an open channel device or web device, i.e., web browser. ", "properties": { "channel": { "oneOf": [ { "format": "uuid", "type": "string" }, { "$ref": "#/components/schemas/uuidArray" } ] } }, "required": [ "channel" ], "title": "Channel selector", "type": "object", "x-inline-component": true }, "channelIdContactIdAssociation": { "properties": { "channel_id": { "description": "The Channel ID you want to associate with a Contact.", "example": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5", "format": "uuid", "type": "string" }, "contact_id": { "description": "A string value identifying the user, without leading or trailing whitespace.", "example": "john_doe", "maxLength": 128, "minLength": 1, "pattern": "^(?!\\s).{1,128}(?" ], "type": "string" }, "type": "array", "x-inline-component": true }, "directInfluencedObject": { "properties": { "direct": { "description": "The number of direct opens of your app.", "example": 20, "type": "integer" }, "influenced": { "description": "The number of influenced opens of your app.", "example": 50, "type": "integer" } }, "type": "object", "x-inline-component": true }, "email": { "description": "The payload for a Create and Send operation to email channels. When sending to email channels, `device_types` must be set to `email`.", "properties": { "audience": { "oneOf": [ { "$ref": "#/components/schemas/cnsEmailAudienceObject" }, { "properties": { "bulk_id": { "description": "A unique string obtained from the [Create bulk send audience operation](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending.\n", "format": "uuid", "type": "string" } }, "required": [ "bulk_id" ], "type": "object" } ] }, "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "device_types": { "$ref": "#/components/schemas/device_types" }, "notification": { "description": "An `alert` notification or a platform override matching the value in `device types`. A notification with a platform override that does not match your `device_types` will result in a 400 error.", "properties": { "email": { "description": "You can either provide the standard object that you would provide when performing a `/api/push` to an email platform, or you can provide some of the email platform override fields along with an inline template.", "oneOf": [ { "$ref": "#/components/schemas/emailOverrideObject" }, { "$ref": "#/components/schemas/emailOverrideWithTemplate" } ] } }, "type": "object" } }, "required": [ "audience", "device_types", "notification" ], "title": "Create and Send to email channels", "type": "object", "x-schema-tag": "Create and Send" }, "emailAddressContactIdAssociation": { "properties": { "contact_id": { "description": "The existing Contact.", "example": "john_doe", "maxLength": 128, "minLength": 1, "pattern": "^(?!\\s).{1,128}(?Unsubscribe\\*.\nYou can send the user to a custom \"goodbye\" page by providing an href\nattribute in the link: *\\Unsubscribe\\*. If your unsubscribe link includes an\n`href`, Airship unsubscribes the user before redirecting to your page.\nAdditionally, *\\Subscribe* and\n*\\Subscribe* will\nbe replaced by a link that will opt the user in to both commercial and\ntransactional messaging and optionally redirect the user to a customer-supplied landing page.\n* See: [Email image recommendations](/reference/messages/media-guidelines/#email).\n", "example": [ "

Greetings

Hello!

Unsubscribe

" ], "type": "string" }, "message_type": { "description": "Must be `transactional` or `commercial`. If a message type is specified in the push payload, the email message type must match. Otherwise, it will result in a 400-level error.", "enum": [ "transactional", "commercial" ], "example": "commercial", "type": "string" }, "open_tracking": { "default": true, "description": "True by default. Set to `false` to prevent `open` tracking for GDPR compliance.\n", "type": "boolean" }, "plaintext_body": { "description": "The plain text body of the email, **no larger than 100 KB**.\n\nWhen `\"message_type\": \"commercial\"`, the body must contain a *[[ua_unsubscribe]]*\nlink, which will be replaced by the unsubscribe link in Airship.\nYou can send the user to a custom \"goodbye\" page by providing an href\nin the format *[[ua-unsubscribe href=\"your url here\"]]*. If you include an `href`, Airship unsubscribes the user before redirecting to your page.\nAdditionally, *[[ua-opt-in]]* and *[[ua-opt-in href=\"YOUR_URL_HERE\"]]* will be replaced by a\nlink that will opt the user in to both commercial and transactional messaging and optionally\nredirect the user to a customer-supplied landing page.\n", "example": "Greetings. Hello there! [[ua-unsubscribe]]", "type": "string" }, "reply_to": { "description": "The reply-to address. The username portion of the reply-to address can be set dynamically using [Handlebars](/guides/personalization/handlebars/). The domain portion of the reply-to address can be any correctly formatted domain.\n", "example": "no-reply@example.com", "type": "string" }, "sender_address": { "description": "The email address of the sender. The domain of the email must be enabled in the email provider at the delivery tier (ie: SparkPost). The username portion of the sender address can be set dynamically using [Handlebars](/guides/personalization/handlebars/). The domain portion of the sender address must match one of your project's configured email sending domains.", "example": "no-reply@example.com", "type": "string" }, "sender_name": { "description": "The common name for the sender, visible to email recipients. The sender name can be set dynamically using [Handlebars](/guides/personalization/handlebars/).", "example": "My Company", "type": "string" }, "subject": { "description": "The subject line of the email.", "example": "Test Email", "type": "string" }, "url_parameters": { "$ref": "#/components/schemas/urlParametersObject" } }, "required": [ "message_type", "subject", "plaintext_body", "sender_name", "sender_address", "reply_to" ], "title": "Email overrides", "type": "object", "x-schema-tag": "Platform overrides" }, "emailOverrideWithTemplate": { "description": "Notification fields specific to email messages with an inline template for use in a [Create and Send](/developer/rest-api/ua/operations/bulk-sending/#createandsend) payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with `{{#operator}}` and end with `{{/operator}}`. For more information, see [Handlebars](/guides/personalization/handlebars/).", "properties": { "bcc": { "description": "An array of email addresses that you want to blind copy on this email. Contact your Account Manager to enable BCC addresses. Using addresses that your Airship Account Manager has not enabled for BCC will return a 400.", "items": { "format": "email address", "type": "string" }, "type": "array" }, "click_tracking": { "default": true, "description": "True by default. Set to `false` to prevent click tracking for GDPR compliance.\n", "type": "boolean" }, "message_type": { "description": "The type of email you are sending, `transactional` or `commercial`.", "enum": [ "transactional", "commercial" ], "example": "commercial", "type": "string" }, "open_tracking": { "default": true, "description": "True by default. Set to `false` to prevent `open` tracking for GDPR compliance.\n", "type": "boolean" }, "reply_to": { "description": "The reply-to address. The username portion of the reply-to address can be set dynamically using [Handlebars](/guides/personalization/handlebars/). The domain portion of the reply-to address can be any correctly formatted domain.\n", "example": "no-reply@example.com", "type": "string" }, "sender_address": { "description": "The email address of the sender. The domain of the email must be enabled in the email provider at the delivery tier (ie: SparkPost). The username portion of the sender address can be set dynamically using [Handlebars](/guides/personalization/handlebars/). The domain portion of the sender address must match one of your project's configured email sending domains.", "example": "no-reply@example.com", "type": "string" }, "sender_name": { "description": "The common name for the sender, visible to email recipients. The sender name can be set dynamically using [Handlebars](/guides/personalization/handlebars/).", "example": "My Company", "type": "string" }, "template": { "description": "Specify a `template_id` created in the Airship UI or use an inline template.", "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "required": [ "template_id" ], "type": "object" }, { "$ref": "#/components/schemas/inlineEmailTemplate" } ] }, "url_parameters": { "$ref": "#/components/schemas/urlParametersObject" } }, "required": [ "message_type", "sender_name", "sender_address", "reply_to", "template" ], "title": "Email notification with template", "type": "object", "x-schema-tag": "Platform overrides with templates" }, "emailTemplatesObject": { "description": "The email-specific fields for a template.", "properties": { "html_body": { "description": "The HTML content of the email.", "type": "string" }, "plaintext_body": { "description": "The plaintext content of the email.", "type": "string" }, "subject": { "description": "The email subject.", "type": "string" } }, "required": [ "subject", "html_body", "plaintext_body" ], "title": "Email content template object", "type": "object", "x-schema-tag": "Content objects" }, "error": { "description": "Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.", "properties": { "details": { "description": "Provides information relating to the specific `error_code` when possible. For `400` errors, this object may include the `path` and `location` of validation failures.", "properties": { "error": { "description": "Specific information about the semantic error, helping you better understand why the request failed.", "type": "string" }, "location": { "description": "The specific line and column where the validation error occurred, if known.", "properties": { "column": { "description": "The column containing the semantic error.", "type": "integer" }, "line": { "description": "The line containing the semantic error.", "type": "integer" } }, "type": "object" }, "path": { "description": "The path to the key containing the validation error.", "type": "string" } }, "type": "object" }, "error": { "description": "A plain-text explanation of the error.", "type": "string" }, "error_code": { "description": "The Airship error code. This is normally the HTTP error code appended with a 2-digit identifier, helping provide more specific details about the error.", "example": 40401, "type": "integer" }, "ok": { "description": "2xx responses return `true`; 4xx responses return `false`.", "example": false, "type": "boolean" } }, "required": [ "ok", "error" ], "title": "Error response", "type": "object", "x-note": "We recommend logging all non-2XX responses. Include the entire request and response, including headers, to help you or [Support](https://support.airship.com) troubleshoot issues.", "x-schema-tag": "Responses" }, "errorResponseObject": { "description": "Token request error.", "properties": { "error": { "description": "Error code.", "enum": [ "invalid_scope", "invalid_request", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_client" ], "type": "string" }, "error_description": { "description": "A plain-text description of the error.", "type": "string" } }, "required": [ "error" ], "title": "Error response", "type": "object", "x-inline-component": true }, "eventIdentifier": { "description": "Event identifiers describe events that Automation can detect and act on. They may be described by a simple string, e.g., `open`, or by an object for parameterized events, e.g., `{ \"tag_added\" : \"\" }`.", "oneOf": [ { "description": "Triggers the pipeline whenever an event of the following types occurs. `first_open` and `first_opt_in` are only available in immediate triggers.\n\n\n* `open` events occur whenever your audience opens your app.\n* `first_open` events occur when your audience opens your app for the first time.\n* `first_opt_in` events represent the first time your audience opts into `email` (commercial only), `sms`, or `open` notifications.\n* `double_opt_in` events occur when a new email channel registration occurs with the `\"opt_in_mode\": \"double\"` parameter.\n* When used without a value, `region_entered` and `region_exited` types cause the trigger to fire whenever an audience member enters or exits any region.\n", "enum": [ "open", "first_open", "first_opt_in", "double_opt_in", "region_entered", "region_exited" ], "title": "Simple event identifier", "type": "string" }, { "description": "A compound event identifier is a JSON dictionary with a single key indicating the event type, and a value specifying the specific parameter to match on.", "properties": { "activation_time": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) indicating a time at which the trigger will automatically become active.\n", "format": "date-time", "type": "string" }, "condition": { "$ref": "#/components/schemas/conditionSet" }, "custom_event": { "$ref": "#/components/schemas/complexEventSelector", "description": "A custom event selector is an event selector that describes the\nspecific criteria a custom event must fulfill in order to trigger an automation.\nSupported custom event fields in the default scope are `\"name\"` (string) and `[\"value\"]`.\ncustom events also have a map of properties that may also be selected under the `\"properties\"` scope. Values for the `\"properties\"` key may be string, boolean, number, or an array of strings." }, "deactivation_time": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) indicating a time at which the trigger will automatically become inactive.\n", "format": "date-time", "type": "string" }, "double_opt_in": { "description": "Matches when a double opt-in registration matching the specified criteria was made for a channel.\nA double opt-in selector is a complex selector that describes the specific criteria a double opt-in\nregistration must fulfill in order for it to qualify as a match for triggering pipelines.\nThe only supported value for `scope` is `properties`. All value selectors, except for `date`, are supported.\nThe `key` object supports a simple string to select the value of a top-level key or any JsonPath query for maximum flexibility.\nFor situations where a compound event identifier is necessary (e.g., when including `trigger_id`),\nbut no selector is present or desired, an empty object `{}` is allowed.\n`\"immediate_trigger\": \"double_opt_in\"` and `\"immediate_trigger\": { \"id\": \"8e1a61d7-7e9d-4870-a548-2d4d6eb6405f\", \"double_opt_in\": {} }`\nare equivalent (assuming the ID is correct).\n", "oneOf": [ { "$ref": "#/components/schemas/complexEventSelector" } ] }, "pipeline_event": { "$ref": "#/components/schemas/pipelineEventSelector", "description": "Matches when a pipeline event matching the specified criteria was emitted for a child." }, "region_entered": { "$ref": "#/components/schemas/triggerRegionSelector", "description": "Matches when a channel enters a region meeting this criteria." }, "region_exited": { "$ref": "#/components/schemas/triggerRegionSelector", "description": "Matches when a device/channel exits a region meeting this criteria." }, "subscription_added": { "description": "Matches when the specified subscription list is added. The value of the identifier is a simple string identifying the subscription list.", "type": "string" }, "subscription_removed": { "description": "Matches when the specified subscription list is removed. The value of the identifier is a simple string identifying the subscription list.", "type": "string" }, "tag_added": { "$ref": "#/components/schemas/tagSelector", "description": "Matches when a tag meeting the value criteria is added." }, "tag_removed": { "$ref": "#/components/schemas/tagSelector", "description": "Matches when a tag meeting the value criteria is removed." } }, "title": "Compound event identifier", "type": "object" } ], "title": "Event identifier", "x-schema-tag": "Pipeline objects" }, "eventValueSelector": { "description": "Defines an event value to match.", "properties": { "key": { "description": "The field you want to match a value against.", "type": "string" }, "scope": { "description": "Specifies an inner-dictionary on a potentially-matching event.", "type": "string" }, "value": { "description": "Specifies the criteria qualifying a value as a match. Integer values support\nup to 6 digits of decimal precision. You can specify a range of values using\n`at_least`/`greater_than` and `at_most`/`less_than`, but the value for\n`at_least`/`greater_than` must be less than the value of `at_most`/`less_than`\nor your request will return an error.\n", "properties": { "array_contains": { "description": "Matches if an array contains the specified string value.", "type": "string" }, "at_least": { "description": "Matches values greater than the specified value.", "type": "integer" }, "at_most": { "description": "Matches values less than the specified value.", "type": "integer" }, "equals": { "anyOf": [ { "type": "boolean" }, { "type": "string" }, { "type": "integer" } ], "description": "Specifies an exact match. String values are case sensitive and must match exactly." }, "greater_than": { "description": "Matches values greater than the specified value.", "type": "integer" }, "less_than": { "description": "Matches values less than the specified value.", "type": "integer" } }, "type": "object" } }, "required": [ "key", "value" ], "title": "Event value selector", "type": "object", "x-inline-component": true, "x-schema-tag": "Pipeline objects" }, "experimentObject": { "description": "An experiment object describes an A/B test, including the audience and variant portions.", "properties": { "audience": { "$ref": "#/components/schemas/audienceSelector1000", "description": "The audience for the experiment." }, "campaigns": { "$ref": "#/components/schemas/campaignsObject", "description": "Campaigns object that will be applied to resulting pushes.", "type": "object" }, "control": { "description": "The proportional subset of the audience that will not receive a push. The remaining audience will be split between the variants. It may help to think of this value as a percentage. See [Audience groups in the API](/guides/experimentation/a-b-tests/messages/#audience-groups-in-the-api) in *Message A/B tests*.", "format": "float", "type": "number" }, "created_at": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the experiment was created. This value is created and assigned automatically by Airship and appears in responses only.", "format": "date-time", "readOnly": true, "type": "string" }, "description": { "description": "A description of the experiment.", "type": "string" }, "device_types": { "$ref": "#/components/schemas/deviceTypesSelector" }, "id": { "description": "The unique ID assigned to this experiment. This value is created and assigned automatically by Airship and appears in responses only.", "format": "uuid", "readOnly": true, "type": "string" }, "name": { "description": "A name for the experiment.", "type": "string" }, "push_id": { "description": "The push ID associated with this experiment. This value is created and assigned automatically by Airship and appears in responses only.", "format": "uuid", "readOnly": true, "type": "string" }, "variants": { "description": "The variants for the experiment. An experiment must have at least 1 variant and no more than 26.", "items": { "description": "Each object represents a push that will be sent to a subset of the experiment’s audience. Message Center is not currently supported for experiments.", "properties": { "description": { "description": "A description of the variant.", "type": "string" }, "id": { "description": "Reflects the position of the variant in the array (beginning at 0). This ID is applied automatically and only appears in responses.", "readOnly": true, "type": "integer" }, "name": { "description": "A name for the variant.", "type": "string" }, "push": { "description": "A push object without `audience` and `device_types` fields. These two fields are not allowed because they are already defined in the experiment object.", "properties": { "in_app": { "$ref": "#/components/schemas/inAppObject" }, "notification": { "$ref": "#/components/schemas/notificationObject" }, "options": { "$ref": "#/components/schemas/pushOptions" } }, "type": "object" }, "schedule": { "$ref": "#/components/schemas/scheduleSpec", "description": "The time when the push notification should be sent.", "type": "object" }, "weight": { "description": "The proportion of the audience that will receive this variant. Defaults to 1.", "type": "integer" } }, "required": [ "push" ], "type": "object" }, "maximum": 26, "minimum": 1, "type": "array" } }, "required": [ "audience", "device_types", "variants" ], "title": "Experiment object", "type": "object" }, "expiryObject": { "description": "Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.", "oneOf": [ { "description": "Number of seconds from now. When the delivery platform supports it, a value of zero (0) indicates that the message should be delivered immediately and never stored for later attempts.", "example": 3600, "type": "integer" }, { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format).", "example": "2018-03-01T12:00:00", "format": "date-time", "type": "string" } ], "title": "Expiry", "type": "object", "x-inline-component": true }, "external_id": { "description": "The user-provided identifier of a template created in the Airship dashboard or the API. See [Using content templates](/guides/personalization/content/templates/#using-content-templates) for more information.", "type": "string", "x-inline-component": true }, "extraObject": { "additionalProperties": { "type": "string" }, "description": "A JSON dictionary of string-to-string key-value pairs. If you wish to pass structured data in an extra key, it must be JSON-encoded as a string.", "example": { "en": "English", "fr": "French" }, "title": "Extra", "type": "object", "x-inline-component": true }, "fallbackUrl": { "description": "A URL that can be used on platforms that don't have full support for the otherwise defined action.", "example": "https://www.airship.com/docs", "format": "url", "pattern": "^http.*:\\/\\/.+", "title": "Fallback URL", "type": "string", "x-inline-component": true }, "feedReferences": { "description": "An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a `templates` object in the payload or set the `personalization` option to `true`.", "properties": { "defaults": { "additionalProperties": { "additionalProperties": { "description": "A list of default values, where the key is the name of the property you want to set a default for.", "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "The feed you want to specify default values for.", "type": "object" }, "description": "Default parameter values for your feed. These values override any defaults you set for your feed in the Airship dashboard.", "minProperties": 1, "type": "object" }, "feeds": { "description": "An array of feeds that you want to use to personalize your message.", "items": { "properties": { "name": { "description": "The feed ID set in the dashboard.", "type": "string" }, "on_error": { "default": "cancel", "description": "Determines how the message is handled if the feed is unreachable or does not return an expected response. Defaults to `cancel`.", "enum": [ "continue", "cancel" ], "type": "string" }, "params": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "An optional dictionary of overrides for default parameters in handlebars referencing the feed.", "type": "object" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "required": [ "feeds" ], "title": "Feed references object", "type": "object", "x-schema-tag": "External Data Feeds references" }, "geofenceObject": { "description": "A Geofence object describes a geographical boundary corresponding to a physical location of relevance to the application or application owner. The geofence `type` can be a `polygon`, a `circle`, or provided by a `confidential` source.", "oneOf": [ { "description": "A Geofence subtype describing a polygon.", "properties": { "points": { "description": "An ordered array of Points that correspond to the vertices of the polygon on the globe.", "items": { "$ref": "#/components/schemas/pointObject" }, "type": "array" }, "type": { "description": "The key `type` indicating a polygon geofence subtype.", "enum": [ "POLYGON" ], "type": "string" } }, "required": [ "type", "points" ], "title": "Polygon Geofence object", "type": "object" }, { "description": "A Geofence subtype describing a circle.", "properties": { "center": { "$ref": "#/components/schemas/pointObject", "description": "A single Point indicating the center fo the circle." }, "radius": { "description": "An integer indicating the size (in meters) of the radius of the circle whose edge is the geofence boundary.", "type": "integer" }, "type": { "description": "The key `type` indicating a circle geofence subtype.", "enum": [ "CIRCLE" ], "type": "string" } }, "required": [ "type", "center", "radius" ], "title": "Circle Geofence object", "type": "object" }, { "description": "A confidential Geofence subtype.", "properties": { "id": { "description": "The source-specific identifier for this geofence.", "type": "string" }, "source": { "description": "The name of the company providing the geofence.", "type": "string" }, "type": { "description": "The key `type` indicating a confidential geofence subtype.", "enum": [ "CONFIDENTIAL" ], "type": "string" }, "version": { "description": "The version number for the source of this geofence.", "type": "string" } }, "required": [ "type", "source", "version", "id" ], "title": "Confidential Geofence object", "type": "object" } ], "title": "Geofence object", "x-schema-tag": "Regions" }, "globalAttributes": { "description": "The global attributes object may contain an arbitrary set of keys and values, including arrays and nested objects, which will be added to the global attributes rendering namespace for this push. Top-level keys must start with a letter and cannot start with the reserved sequence ``ua_``. If the global attributes object is nonempty, it implies the ``personalization: true`` option.", "title": "Global attributes", "type": "object", "x-inline-component": true }, "historicalTriggerObject": { "description": "Defines a condition that matches against event data trended over time. It consists of an event identifier, a time period, and a matching operator with a value\nindicating the number of occurrences of the event. The operator indicates whether to match greater than, less than, or exactly the number of occurrences specified.\nValid matching operators are `equals`, `greater_than`, or `less_than`. The matching window is specified in days, with an upper limit of 90 days.\nA historical trigger will be periodically evaluated against the event history for every active device belonging to the application.\nPipelines with historical triggers cannot also have a timing object.\n", "properties": { "creation_time": { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format) returned when getting a pipeline with a `historical_trigger`. Include this field in a `PUT` request to ensure that the historical_trigger is not reset.", "format": "date-time", "type": "string" }, "days": { "description": "A time period key. An integer indicating the length of the matching window, in days. Maximum 90 days.", "maximum": 90, "minimum": 1, "type": "integer" }, "equals": { "description": "A matching operator. Since we are measuring inactivity with the historical trigger object, `0` is the only value supported with the equals operator, i.e., we are measuring number of events in a defined time window. Any number higher than zero would therefore represent activity.", "type": "integer" }, "event": { "$ref": "#/components/schemas/eventIdentifier" }, "greater_than": { "description": "A matching operator. Specifies the number of events that must be targeted before the historical trigger will fire.", "type": "integer" }, "less_than": { "description": "A matching operator. Specifies the number of events that must be targeted before the historical trigger will fire.", "type": "integer" } }, "title": "Historical trigger object", "type": "object", "x-inline-component": true, "x-schema-tag": "Pipeline objects" }, "hoursConstraint": { "description": "Limits the number of pushes any individual audience member will receive from the pipeline over a number of hours.", "properties": { "hours": { "description": "An integer, specifying the time period in number of hours.", "maximum": 72, "type": "integer" }, "pushes": { "$ref": "#/components/schemas/pushes" } }, "title": "Pushes/hours constraint", "type": "object", "x-inline-component": true }, "iOSChannelObject": { "description": "Contains parameters that apply when the `device_type` is set to `ios`.", "properties": { "badge": { "description": "The iOS badge number. Must be greater than zero.", "format": "int32", "type": "integer" }, "quiettime": { "description": "Quiet time settings. Requires presence of `tz`.", "properties": { "end": { "description": "Quiet time end in `HH:MM` format.", "example": "07:30", "nullable": true, "type": "string" }, "start": { "description": "Quiet time start in `HH:MM` format.", "example": "21:30", "nullable": true, "type": "string" } }, "title": "Quiet Time Object", "type": "object" }, "scheduled_summary": { "description": "If true, the scheduled summary notification status is enabled.", "type": "boolean" }, "time_sensitive": { "description": "If true, the time sensitive notification status is enabled.", "type": "boolean" }, "tz": { "description": "The channel's time zone. A list of possible time zone values is maintained at the [IANA Time Zone Database](http://www.iana.org/time-zones).", "example": "America/Los_Angeles", "nullable": true, "type": "string" } }, "title": "iOS channel object", "type": "object", "x-schema-tag": "Channels" }, "identifyAnonymousContactResponse": { "description": "The Contact ID in the response will be based on these precedence rules:\n* From the Named User if it exists\n* From the channel if it is associated to an [Anonymous Contact](/developer/sdk-integration/mobile/audience/#contacts)\n* From the payload if provided\n* Randomly generated\n", "properties": { "contact_id": { "description": "The resolved Contact ID.\n", "format": "uuid", "type": "string" }, "ok": { "description": "Set to `true` when status code is `200`.\n", "type": "boolean" } }, "required": [ "ok", "contact_id" ], "title": "Identify Anonymous Contact response", "type": "object", "x-inline-component": true }, "inAppObject": { "description": "A JSON object describing an in-app message payload.", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "alert": { "description": "The text displayed on the in-app message.", "type": "string" }, "display": { "description": "The allowed fields for this object depend on the value of of the `display_type` field. Currently, the only valid `display_type` is `banner`, so the following is an associated display object for the banner display type.", "properties": { "duration": { "default": 15, "description": "Specifies how long the notification should stay on the screen in seconds before automatically disappearing; set to `15` by default.", "type": "integer" }, "position": { "default": "bottom", "description": "One of either `top` or `bottom`, specifies the screen position of the message. Defaults to `bottom`.", "enum": [ "top", "bottom" ], "type": "string" }, "primary_color": { "description": "Specifies the primary color of the in-app message (format `#rrggbb`).", "example": "#FF0000", "type": "string" }, "secondary_color": { "description": "Specifies the secondary color of the in-app message (format `#rrggbb`).", "example": "#00FF00", "type": "string" } }, "type": "object" }, "display_type": { "description": "Specifies the display type.", "enum": [ "banner" ], "type": "string" }, "expiry": { "$ref": "#/components/schemas/expiryObject", "description": "An integer (in seconds) or [date-time](/developer/rest-api/ua/introduction/#date-time-format) specifying the time when the in-app message will expire. Defaults to 90 days from the time of the API request." }, "extra": { "$ref": "#/components/schemas/extraObject" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" } }, "required": [ "alert", "display_type" ], "title": "In-app message", "type": "object", "x-schema-tag": "Push" }, "inlineEmailTemplate": { "properties": { "fields": { "description": "The template you want to construct for the message. Provide variables in the template in double curly brackets — `{{variable_name}}`. The variable name must be a case-sensitive match of a key in your `create_and_send` objects to be replaced as a part of the template.", "properties": { "html_body": { "description": "The rich-text HTML body of the email, **no larger than 100 KB**.\n* When `\"message_type\": \"commercial\"`, the body must contain an unsubscribe\nlink in the format *\\Unsubscribe\\*.\nYou can send the user to a custom \"goodbye\" page by providing an href\nattribute in the link: *\\Unsubscribe\\*. If your unsubscribe link includes an\n`href`, Airship unsubscribes the user before redirecting to your page.\nAdditionally, *\\Subscribe* and\n*\\Subscribe* will\nbe replaced by a link that will opt the user in to both commercial and\ntransactional messaging and optionally redirect the user to a customer-supplied landing page.\n* See [Email image recommendations](/reference/messages/media-guidelines/#email).\n", "type": "string" }, "plaintext_body": { "description": "The plain text body of the email, **no larger than 100 KB**.\n\n\nWhen `\"message_type\": \"commercial\"`, the body must contain a `[[ua_unsubscribe]]` link, which will be replaced by the unsubscribe link in Airship.\nYou can send the user to a custom \"goodbye\" page by providing an href\nin the format *[[ua-unsubscribe href=\"your url here\"]]*. If you include an `href`, Airship unsubscribes the user before redirecting to your page.\nAdditionally, *[[ua-opt-in]]* and *[[ua-opt-in href=\"YOUR_URL_HERE\"]]* will be replaced by a\nlink that will opt the user in to both commercial and transactional messaging and optionally\nredirect the user to a customer-supplied landing page.", "type": "string" }, "subject": { "description": "The subject line of the email you want to send.", "type": "string" } }, "required": [ "subject", "plaintext_body" ], "type": "object" } }, "required": [ "fields" ], "type": "object", "x-inline-component": true }, "inlineSmsTemplate": { "properties": { "fields": { "description": "The template you want to construct for the message. Provide variables in the template in double curly brackets — `{{variable_name}}`. The variable name must be a case-sensitive match of a key in your `create_and_send` objects to be replaced as a part of the template.", "properties": { "alert": { "description": "The notification you want to send to an SMS audience.", "type": "string" } }, "required": [ "alert" ], "type": "object" } }, "type": "object", "x-inline-component": true }, "interactiveObject": { "description": "An interactive notification.\n\nAttempting to specify an interactive payload for an unsupported device type will result in an HTTP 400 response.", "properties": { "button_actions": { "description": "An object containing keys that must be the button IDs for the specified interactive notification type. If the notification type begins with `ua_`, the keys must match exactly the button IDs for that type or a strict subset. The names of the button IDs cannot be validated for custom notifications.", "oneOf": [ { "description": "Yes/No button action", "properties": { "no": { "$ref": "#/components/schemas/actionsObject" }, "yes": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Yes/No", "type": "object" }, { "description": "Accept/decline button action", "properties": { "accept": { "$ref": "#/components/schemas/actionsObject" }, "decline": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Accept/Decline", "type": "object" }, { "description": "Shop now button action", "properties": { "shop_now": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Shop Now", "type": "object" }, { "description": "Buy now button action", "properties": { "buy_now": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Buy Now", "type": "object" }, { "description": "Follow button action", "properties": { "follow": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Follow", "type": "object" }, { "description": "Opt in button action", "properties": { "opt_in": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Opt In", "type": "object" }, { "description": "Unfollow button action", "properties": { "unfollow": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Unfollow", "type": "object" }, { "description": "Opt out button action", "properties": { "opt_out": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Opt Out", "type": "object" }, { "description": "Opt in/remind button action", "properties": { "opt_in": { "$ref": "#/components/schemas/actionsObject" }, "remind": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Opt In/Remind", "type": "object" }, { "description": "Remind button action", "properties": { "remind": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Remind", "type": "object" }, { "description": "More info button action", "properties": { "more_info": { "$ref": "#/components/schemas/actionsObject" } }, "title": "More Info", "type": "object" }, { "description": "Download button action", "properties": { "download": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Download", "type": "object" }, { "description": "Share button action", "properties": { "share": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Share", "type": "object" }, { "description": "Download/share button action", "properties": { "download": { "$ref": "#/components/schemas/actionsObject" }, "share": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Download/Share", "type": "object" }, { "description": "Remind/share button action", "properties": { "remind": { "$ref": "#/components/schemas/actionsObject" }, "share": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Remind/Share", "type": "object" }, { "description": "Opt in/share button action", "properties": { "opt_in": { "$ref": "#/components/schemas/actionsObject" }, "share": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Opt In/Share", "type": "object" }, { "description": "Opt out/share button action", "properties": { "opt_out": { "$ref": "#/components/schemas/actionsObject" }, "share": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Opt Out/Share", "type": "object" }, { "description": "Follow/share button action", "properties": { "follow": { "$ref": "#/components/schemas/actionsObject" }, "share": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Follow/Share", "type": "object" }, { "description": "Unfollow/share button action", "properties": { "share": { "$ref": "#/components/schemas/actionsObject" }, "unfollow": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Unfollow/Share", "type": "object" }, { "description": "Shop now/share button action", "properties": { "share": { "$ref": "#/components/schemas/actionsObject" }, "shop_now": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Shop Now/Share", "type": "object" }, { "description": "Buy now/share button action", "properties": { "buy_now": { "$ref": "#/components/schemas/actionsObject" }, "share": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Buy Now/Share", "type": "object" }, { "description": "More like/less like button action", "properties": { "less_like": { "$ref": "#/components/schemas/actionsObject" }, "more_like": { "$ref": "#/components/schemas/actionsObject" } }, "title": "More Like/Less Like", "type": "object" }, { "description": "Like/dislike button action", "properties": { "dislike": { "$ref": "#/components/schemas/actionsObject" }, "like": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Like/Dislike", "type": "object" }, { "description": "Like button action", "properties": { "like": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Like", "type": "object" }, { "description": "Like/share button action", "properties": { "like": { "$ref": "#/components/schemas/actionsObject" }, "share": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Like/Share", "type": "object" }, { "description": "Add to calendar/remind button action", "properties": { "add_calendar": { "$ref": "#/components/schemas/actionsObject" }, "remind": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Add to Calendar/Remind", "type": "object" }, { "description": "Add button action", "properties": { "add": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Add", "type": "object" }, { "description": "Save button action", "properties": { "save": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Save", "type": "object" }, { "description": "Follow/Save button action", "properties": { "follow": { "$ref": "#/components/schemas/actionsObject" }, "save": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Follow/Save", "type": "object" }, { "description": "Rate button action", "properties": { "rate": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Rate", "type": "object" }, { "description": "Rate/remind button action", "properties": { "rate": { "$ref": "#/components/schemas/actionsObject" }, "remind": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Rate/Remind", "type": "object" }, { "description": "Search button action", "properties": { "search": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Search", "type": "object" }, { "description": "Book button action", "properties": { "book": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Book", "type": "object" }, { "description": "Happy/Sad button action", "properties": { "happy": { "$ref": "#/components/schemas/actionsObject" }, "sad": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Happy/Sad", "type": "object" }, { "description": "Up/down button action", "properties": { "down": { "$ref": "#/components/schemas/actionsObject" }, "up": { "$ref": "#/components/schemas/actionsObject" } }, "title": "Up/Down", "type": "object" }, { "additionalProperties": { "$ref": "#/components/schemas/actionsObject" }, "description": "Custom button action", "title": "Custom Action", "type": "object" } ] }, "type": { "description": "A string that specifies the name of either a predefined or a custom-defined interactive notification type. Predefined types are prefixed with `ua_`.", "enum": [ "ua_yes_no_foreground", "ua_yes_no_background", "ua_accept_decline_foreground", "ua_accept_decline_background", "ua_shop_now", "ua_buy_now", "ua_follow", "ua_opt_in", "ua_unfollow", "ua_opt_out", "ua_opt_in_remind", "ua_remind_me_later", "ua_more_info", "ua_download", "ua_share", "ua_download_share", "ua_remind_share", "ua_opt_in_share", "ua_opt_out_share", "ua_follow_share", "ua_unfollow_share", "ua_shop_now_share", "ua_buy_now_share", "ua_more_like_less_like", "ua_like_dislike", "ua_like", "ua_like_share", "ua_add_calendar_remind", "ua_add", "ua_save", "ua_follow_save", "ua_rate", "ua_rate_remind", "ua_search", "ua_book", "ua_icons_happy_sad", "ua_icons_up_down", "" ], "example": "ua_yes_no_foreground", "title": "Interactive Notification Type ID", "type": "string" } }, "required": [ "type" ], "title": "Interactive notification object", "type": "object", "x-schema-tag": "Push" }, "iosOverrideObject": { "description": "The platform override section for iOS. Maximum 4,096 bytes.", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "alert": { "description": "Override the alert value provided at the top level, if any. May be a JSON string or an object which conforms to Apple’s push service spec.", "oneOf": [ { "description": "Alert override text for iOS devices.", "type": "string" }, { "description": "JSON object that conforms to Apple's [Payload Key Reference](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html).\n\nWhen using `thread_id` to group notifications, you might want to use\nthe `summary-arg` and `summary-arg-count` keys to help users identify the\ngroup.", "properties": { "action-loc-key": { "description": "If a string is specified, the system displays an alert that includes the Close and View buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of \"View\".", "nullable": true, "type": "string" }, "body": { "description": "The content of the alert message.", "type": "string" }, "launch-image": { "description": "The name of the launch image file you want to display with the\nalert. If the user chooses to launch your app, the contents of\nthe specified image or storyboard file are displayed instead of your app's normal launch image.", "type": "string" }, "loc-args": { "description": "An array of strings containing replacement values for variables in your message text. Each %@ character in the string specified by `loc-key` is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.", "items": { "type": "string" }, "type": "array" }, "loc-key": { "description": "The key for a localized message string. Use this key, instead of the body key, to retrieve the message text from your app's `Localizable.strings` file. The value must contain the name of a key in your strings file.", "type": "string" }, "subtitle": { "description": "Additional information explaining the purpose of the notification.", "nullable": true, "type": "string" }, "subtitle-loc-args": { "description": "An array of strings containing replacement values for variables in your subtitle string. Each %@ character in the string specified by `subtitle-loc-key` is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.", "items": { "type": "string" }, "type": "array" }, "subtitle-loc-key": { "description": "The key for a localized subtitle string. Use this key, instead of the subtitle key, to retrieve the subtitle from your app's `Localizable.strings` file. The value must contain the name of a key in your strings file.", "type": "string" }, "summary-arg": { "description": "A string added to the summary of grouped notifications represented\nby the `thread_id`", "type": "string" }, "summary-arg-count": { "description": "The number of summary-arg strings that a group of notifications\nrepresented by a `thread_id` will display.", "type": "integer" }, "title": { "description": "The title of the notification. Apple Watch displays this string in the short look notification interface. Specify a string that is quickly understood by the user.", "type": "string" }, "title-loc-args": { "description": "An array of strings containing replacement values for variables in your title string. Each %@ character in the string specified by the `title-loc-key` is replaced by a value from this array. The first item in the array replaces the first instance of the %@ character in the string, the second item replaces the second instance, and so on.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "title-loc-key": { "description": "The key for a localized title string. Specify this key instead of the title key to retrieve the title from your app’s `Localizable.strings` files. The value must contain the name of a key in your strings file.", "nullable": true, "type": "string" } }, "type": "object" } ] }, "badge": { "description": "May be an integer, the value `auto`, or an increment value. Increments are expressed by integers formatted as strings, and prefixed with either `+` (U+002B) or `-` (U+002D). The numeric portion may be an integer value.", "example": "+1", "format": "int32", "type": "integer" }, "category": { "description": "Sets the APNs category for the push. This maps directly to the `category` field in the `aps` section of the APNs payload. Any interactive notification specified for the IOS platform will take precedence and this value will be ignored (the interactive notification type will be used for the category).", "type": "string" }, "collapse_id": { "description": "When there is a newer message that renders an older, related message irrelevant to the client app, the new message replaces the older message with the same `collapse_id`. Similar to the Android `notification_tag`. The value of this key must not exceed 64 bytes. iOS 10 or above.", "type": "string" }, "content_available": { "description": "If true, the payload is delivered to your app in the background.\n\nThis flag is automatically set to true if there is an In-App Message in the payload. Attempting to override this value to false when there is an in-app message will result in a 400 Bad Request response from the API.", "type": "boolean" }, "expiry": { "$ref": "#/components/schemas/expiryObject", "description": "The expiry time for APNs to cease trying to deliver a push. Can be an integer encoding number of seconds from now, or an absolute timestamp in ISO UTC format. An integer value of 0 (zero) will be passed directly to Apple, and indicates that the push should be delivered immediately and not stored by APNs (\"now or never\" delivery)." }, "extra": { "additionalProperties": { "type": "string" }, "description": "A dictionary of string keys to arbitrary JSON values. The key `aps` would conflict with the generated APNs payload and is disallowed.", "type": "object" }, "filter_criteria": { "description": "The criteria the system evaluates to determine if it displays the notification in the current Focus.", "type": "string" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "interruption_level": { "default": "active", "description": "Indicates the importance and delivery timing of a notification.\n\n**Note**: Using a `critical` interruption level requires a special entitlement from Apple. If you have this entitlement, please contact your Airship Account Manager or our Support team to enable usage for your project.", "enum": [ "passive", "active", "time-sensitive", "critical" ], "type": "string" }, "live_activity": { "description": "JSON object that represents the content sent to a [Live Activity Notification](https://developer.apple.com/documentation/activitykit/update-and-end-your-live-activity-with-remote-push-notifications). Live Activities are an [AXP feature](/reference/feature-packages/).\n\n**Note**: Using this object transforms the iOS notification to a Live Activity notification. Only devices targeted by the Live Activity `name` field will receive the Live Activity update. \nFields outside of the `live_activity` object will be ignored.", "properties": { "alert": { "description": "An optional alert content for the Live Activity push payload. \n\nOn Apple Watch, the system uses the title and body attributes for the alert. \nOn iPhone, the system doesn't show a regular alert but instead shows the expanded Live Activity in the Dynamic Island.\nOn devices that don't support the Dynamic Island, the system displays a banner on the Home Screen that uses the expanded view of your Live Activity.", "properties": { "body": { "description": "The content of the Apple Watch alert message.", "type": "string" }, "sound": { "description": "The name of the sound file in your app's bundle that you want to play for the alert.", "type": "string" }, "title": { "description": "The title of the Apple Watch notification. Apple Watch displays this string in the short look notification interface. Specify a string that is quickly understood by the user.", "type": "string" } }, "type": "object" }, "attributes": { "additionalProperties": { "type": "string" }, "description": "The attributes that describe the Live Activity for a `start` event.", "type": "object" }, "attributes_type": { "description": "The type of attributes that describe the Live Activity for a `start` event.", "type": "string" }, "content_state": { "$ref": "#/components/schemas/contentStateObject" }, "dismissal_date": { "description": "An optional epoch timestamp in seconds, used when you end the Live Activity. If you don't provide one, the default behavior (after 4 hours) is used.", "format": "int32", "type": "integer" }, "event": { "description": "Use `start` to start a Live Activity.\nUse `update` to update a current Live Activity. \nUse `end` to emit the last update and end the Live Activity.", "enum": [ "start", "update", "end" ], "type": "string" }, "name": { "description": "The name of the Live Activity to target. The audience will be limited to devices that have a Live Activity registered for the specified name.", "type": "string" }, "priority": { "description": "Sets the APNs priority of the Live Activity delivery. Valid values are 10 (immediate delivery) and 5\n(conserve battery).\nenum: [5, 10]", "format": "int32", "type": "integer" }, "relevance_score": { "description": "An optional number, determines which of the Live Activities appears in the Dynamic Island and the order of your Live Activities on the lock screen.", "format": "double", "type": "number" }, "stale_date": { "description": "An optional epoch timestamp in seconds, tells the system when the Live Activity content becomes outdated.", "format": "int32", "type": "integer" }, "timestamp": { "description": "An optional epoch timestamp in seconds, used to enforce the Live Activity updates ordering. If you don't provide one, the current timestamp is used.", "format": "int32", "type": "integer" } }, "type": "object" }, "media_attachment": { "description": "The `media_attachment` key on the iOS override is a JSON object that describes a media attachment to be handled by the Airship Media Attachment extension in iOS 10.", "properties": { "content": { "description": "A JSON object that describes portions of the notification that should be modified if the media attachment succeeds, with any of the following fields", "properties": { "body": { "type": "string" }, "subtitle": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "options": { "description": "A JSON object that describes how to display the resource at the URL specified above, with any of the following fields.", "properties": { "crop": { "description": "A JSON object that describes the crop parameters to be used in the thumbnail. Each field is a decimal, normalized from 0 to 1. Before displaying the thumbnail, iOS additionally crops the thumbnail down to a square. See: [Media guidelines](/reference/messages/media-guidelines/).", "properties": { "height": { "description": "The height of the final crop.", "format": "double", "type": "number" }, "width": { "description": "The width of the final crop.", "format": "double", "type": "number" }, "x": { "description": "The X offset where the crop begins.", "format": "double", "type": "number" }, "y": { "description": "The Y offset where the crop begins.", "format": "double", "type": "number" } }, "type": "object" }, "hidden": { "description": "A boolean, when true, the thumbnail will be hidden.", "type": "boolean" }, "time": { "description": "A decimal, the frame of the animated resource that should be [used in the thumbnail](https://developer.apple.com/reference/usernotifications/unnotificationattachmentoptionsthumbnailtimekey). For GIFs, this value should be the frame number (an integer, with the first frame being frame 1) to show in the thumbnail. For video, the value should be the time (in seconds) into the video from which to grab the thumbnail. This value should not be set for static resources like JPGs. If the time does not exist in the resource, either because it is out of bounds or because the resource is static, the thumbnail will not show.", "format": "int32", "type": "integer" } }, "type": "object" }, "url": { "description": "The URL to be downloaded by the Airship Media Attachment extension. The media file should be one of the following types, and not exceed the maximum file size. Image (5 MB): JPEG, GIF, PNG. Audio (10 MB): AIFF, WAV, MP3, M4A. Video (50 MB): MPEG, MPEG2, MP4, AVI. Although these are the theoretical file size maximums, for performance the actual resources should be much smaller. See [Media Guidelines](/reference/messages/media-guidelines/).", "type": "string" } }, "required": [ "url" ], "type": "object", "x-note": "It is recommended that you restrict image media attachments to one MB or less. While larger file sizes are technically supported, the ability to receive media may be limited by the download speed of the receiving device. If media is too large and takes too long to download, a notification may render without it.\n" }, "mutable_content": { "description": "When set to true, content may be modified by an extension. This flag will be automatically set to true if there is a media_attachment in the payload. iOS 10 or above. Defaults to false.", "type": "boolean" }, "priority": { "description": "Sets the APNs priority of the delivery. Valid values are 10 (immediate delivery) and 5 (conserve battery). The default value will be 10 if the notification is user-visible (In-App Message payload does not count towards visibility) which means there is either an alert, badge, or sound. If the notification is not user-visible, the priority will default to 5 and it is not legal to override this value to 10. Attempts to do so will cause the API respond with a 400 Bad Request response. enum: [5, 10]", "format": "int32", "type": "integer" }, "relevance_score": { "default": 0, "description": "A number from 0.0 to 1.0. Used to sort notifications for an app. The notification with highest score is featured in the notification summary.", "example": 1.2, "format": "double", "type": "number" }, "sound": { "description": "The name of the sound file in your app's bundle that you want to play for the alert. If the notification is critical, the dictionary has a key for `\"name\"` (equivalent to the current sound string), `\"volume\"` (a number between 0 and 1 indicating the volume), and `\"critical\"` (a boolean indicating if the alert should override local device settings and still notify).", "type": "string" }, "subtitle": { "description": "A string that will display below the title of the notification. This is provided as a convenience for setting the subtitle in the alert JSON object. If a subtitle is also defined in the alert JSON object, this value is ignored. iOS 10.", "type": "string" }, "target_content_id": { "description": "The identifier of the window to bring forward when the notification is opened. Used for multi-window content, such as App Clips.", "type": "string" }, "thread_id": { "description": "A unique identifier used to group notifications into separate threads in the Notification Center and on the lock screen. Grouped notifications are available beginning with iOS 12.", "type": "string" }, "title": { "description": "A short string describing the purpose of the notification. This is provided as a convenience for setting the title in the alert JSON object. If a title is also defined in the alert JSON object, this value is ignored.", "type": "string" } }, "title": "iOS overrides", "type": "object", "x-schema-tag": "Platform overrides" }, "iosOverrideWithTemplate": { "description": "Use a `template` with iOS-specific message. You can reference a template by ID, or use `{{handlebars}}` directly in your message.", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "badge": { "description": "May be an integer, the value `auto`, or an increment value. Increments are expressed by integers formatted as strings, and prefixed with either `+` (U+002B) or `-` (U+002D). The numeric portion may be an integer value.", "example": "+1", "format": "int32", "type": "integer" }, "category": { "description": "Sets the APNs category for the push. This maps directly to the `category` field in the `aps` section of the APNs payload. Any interactive notification specified for the IOS platform will take precedence and this value will be ignored (the interactive notification type will be used for the category).", "type": "string" }, "collapse_id": { "description": "When there is a newer message that renders an older, related message irrelevant to the client app, the new message replaces the older message with the same `collapse_id`. Similar to the Android `notification_tag`. The value of this key must not exceed 64 bytes. iOS 10 or above.", "type": "string" }, "content_available": { "description": "If true, the payload is delivered to your app in the background.\n\nThis flag is automatically set to true if there is an In-App Message in the payload. Attempting to override this value to false when there is an in-app message will result in a 400 Bad Request response from the API.", "type": "boolean" }, "expiry": { "$ref": "#/components/schemas/expiryObject", "description": "The expiry time for APNs to cease trying to deliver a push. Can be an integer encoding number of seconds from now, or an absolute timestamp in ISO UTC format. An integer value of 0 (zero) will be passed directly to Apple, and indicates that the push should be delivered immediately and not stored by APNs (\"now or never\" delivery)." }, "extra": { "additionalProperties": { "type": "string" }, "description": "A dictionary of string keys to arbitrary JSON values. The key `aps` would conflict with the generated APNs payload and is disallowed.", "type": "object" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "media_attachment": { "description": "The `media_attachment` key on the iOS override is a JSON object that describes a media attachment to be handled by the Airship Media Attachment extension in iOS 10.", "properties": { "content": { "description": "A JSON object that describes portions of the notification that should be modified if the media attachment succeeds, with any of the following fields.", "properties": { "body": { "type": "string" }, "subtitle": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "options": { "description": "A JSON object that describes how to display the resource at the URL specified above, with any of the following fields.", "properties": { "crop": { "description": "A JSON object that describes the crop parameters to be used in the thumbnail. Each field is a decimal, normalized from 0 to 1. Before displaying the thumbnail, iOS additionally crops the thumbnail down to a square. See: [Media guidelines](/reference/messages/media-guidelines/).", "properties": { "height": { "description": "The height of the final crop.", "format": "double", "type": "number" }, "width": { "description": "The width of the final crop.", "format": "double", "type": "number" }, "x": { "description": "The X offset where the crop begins.", "format": "double", "type": "number" }, "y": { "description": "The Y offset where the crop begins.", "format": "double", "type": "number" } }, "type": "object" }, "hidden": { "description": "A boolean, when true, the thumbnail will be hidden.", "type": "boolean" }, "time": { "description": "A decimal, the frame of the animated resource that should be [used in the thumbnail](https://developer.apple.com/reference/usernotifications/unnotificationattachmentoptionsthumbnailtimekey). For GIFs, this value should be the frame number (an integer, with the first frame being frame 1) to show in the thumbnail. For video, the value should be the time (in seconds) into the video from which to grab the thumbnail. This value should not be set for static resources like JPGs. If the time does not exist in the resource, either because it is out of bounds or because the resource is static, the thumbnail will not show.", "format": "int32", "type": "integer" } }, "type": "object" }, "url": { "description": "The URL to be downloaded by the Airship Media Attachment extension. The media file should be one of the following types, and not exceed the maximum file size. Image (5 MB): JPEG, GIF, PNG. Audio (10 MB): AIFF, WAV, MP3, M4A. Video (50 MB): MPEG, MPEG2, MP4, AVI. Although these are the theoretical file size maximums, for performance the actual resources should be much smaller. See [Media Guidelines](/reference/messages/media-guidelines/).", "type": "string" } }, "required": [ "url" ], "type": "object", "x-note": "It is recommended that you restrict image media attachments to one MB or less. While larger file sizes are technically supported, as shown in the table below, the ability to receive media may be limited by the download speed of the receiving device. If media is too large and takes too long to download, a notification may render without it.\n" }, "mutable_content": { "description": "When set to true, content may be modified by an extension. This flag will be automatically set to true if there is a media_attachment in the payload. iOS 10 or above. Defaults to false.", "type": "boolean" }, "priority": { "description": "Sets the APNs priority of the delivery. Valid values are 10 (immediate delivery) and 5 (conserve battery). The default value will be 10 if the notification is user-visible (In-App Message payload does not count towards visibility) which means there is either an alert, badge, or sound. If the notification is not user-visible, the priority will default to 5 and it is not legal to override this value to 10. Attempts to do so will cause the API respond with a 400 Bad Request response. enum: [5, 10]", "format": "int32", "type": "integer" }, "sound": { "description": "The name of the sound file in your app's bundle that you want to play for the alert. If the notification is critical, the dictionary has a key for `\"name\"` (equivalent to the current sound string), `\"volume\"` (a number between 0 and 1 indicating the volume), and `\"critical\"` (a boolean indicating if the alert should override local device settings and still notify).", "type": "string" }, "template": { "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "type": "object" }, { "properties": { "fields": { "description": "Items in the field object are personalizable with handlebars.", "properties": { "alert": { "description": "Alert override text for iOS devices.", "type": "string" }, "subtitle": { "description": "A string that will display below the title of the notification. This is provided as a convenience for setting the subtitle in the alert JSON object. If a subtitle is also defined in the alert JSON object, this value is ignored. iOS 10.", "type": "string" }, "title": { "description": "A short string describing the purpose of the notification. This is provided as a convenience for setting the title in the alert JSON object. If a title is also defined in the alert JSON object, this value is ignored.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "thread_id": { "description": "A unique identifier used to group notifications into separate threads in the Notification Center and on the lock screen. Grouped notifications are available beginning with iOS 12.", "type": "string" } }, "title": "iOS overrides with template", "type": "object", "x-schema-tag": "Platform overrides with templates" }, "ios_channel": { "description": "The unique channel identifier used to target an iOS device.", "properties": { "ios_channel": { "oneOf": [ { "format": "uuid", "type": "string" }, { "$ref": "#/components/schemas/uuidArray" } ] } }, "required": [ "ios_channel" ], "title": "iOS channel selector", "type": "object", "x-inline-component": true }, "ipaddr": { "description": "A list of CIDR representations of valid IP addresses to which the issued token is restricted. IP addresses can be sent as a URL-encoded, space-delimited list (example: `ipaddr=24.20.40.0%2F24%202001%3A4860%3A4860%3A%3A8888%2F32`) or as a list as expected in a query parameter form (example: `ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32`).", "type": "string", "x-inline-component": true }, "jsonAttribute": { "description": "An attribute object with a `JSON` schema type. Performs value comparisons based on the JSON value for an attribute on a channel or Named User.", "properties": { "attribute": { "description": "The name of the attribute.", "maxLength": 1024, "minLength": 1, "type": "string" }, "where": { "description": "An object that filters on the JsonPath expression that you provide.\n", "properties": { "compare_as": { "description": "Selects the property type for comparison.", "enum": [ "text", "number", "date", "boolean" ], "type": "string" }, "operator": { "description": "The operator used to evaluate the attribute expression. If the JsonPath expression maps to an array, the only available operators are `is_empty`, `not_empty`, `contains`, or `not_contains`.", "enum": [ "equals", "contains", "not_contains", "less", "less_eq", "greater", "greater_eq", "range", "before", "after", "is_empty", "not_empty" ], "type": "string" }, "precision": { "description": "Used only for date values.", "enum": [ "minutes", "days", "months", "years" ], "type": "string" }, "property": { "description": "The JsonPath expression that will be used to look up the value in a predefined attribute, for example `\"$.x['store']['book'][0]['title']\"`.\nThis is different from selecting based on primitive string attributes, because the JsonPath expression can map to a single attribute or an array of attributes.\nSee [JsonPath](https://github.com/json-path/JsonPath) for more information about JsonPath expressions and usage.\n", "type": "string" }, "relative_to": { "description": "Used only for date values.", "enum": [ "future", "past" ], "type": "string" }, "value": { "description": "The value of the property you are filtering for in the `where` object. Use `compare_as` to select the type for comparison. This is required for all operators except `is_empty` and `not_empty`.\n", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "property", "operator" ], "type": "object" } }, "required": [ "attribute", "where" ], "title": "JSON attribute selector", "type": "object", "x-schema-tag": "Attributes", "x-weight": 8 }, "landingPageContent": { "oneOf": [ { "properties": { "url": { "description": "The URL to be opened as a landing page. This value supports `http` or `https` schemes and can be personalized using handlebars expressions.", "format": "url", "type": "string" } }, "required": [ "url" ], "type": "object" }, { "allOf": [ { "properties": { "content_encoding": { "description": "A string specifying the encoding of the text in the `body` attribute. Defaults to `utf-8`.", "enum": [ "utf-8", "base64" ], "type": "string" }, "content_type": { "description": "A non-blank string, which must be a MIME type.", "example": "text/html", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "content_type" ], "type": "object" }, { "oneOf": [ { "properties": { "body": { "description": "A string containing content which will be uploaded to our internal content hosting system.", "example": "content", "maxLength": 8192, "minLength": 1, "type": "string" } }, "required": [ "body" ], "type": "object" }, { "properties": { "template": { "oneOf": [ { "properties": { "template_id": { "type": "string" } }, "required": [ "template_id" ], "type": "object" }, { "properties": { "fields": { "properties": { "html_body": { "description": "A string containing templated HTML content of the landing page. Corresponds to (and overrides) the \"body\" field. Note that the only legal values for \"content-type\" and \"content-encoding\" fields when used with this template field are \"text/html\" and \"utf-8\", respectively.", "maxLength": 8192, "minLength": 1, "type": "string" } }, "required": [ "html_body" ], "type": "object" } }, "required": [ "fields" ], "type": "object" } ] } }, "required": [ "template" ], "type": "object" } ] } ] } ], "title": "Landing page content", "x-schema-tag": "Push" }, "lifetimesConstraint": { "description": "Limits the number of pushes any individual audience member will ever receive from the pipeline.", "properties": { "lifetimes": { "description": "An integer specifying a lifetime.", "maximum": 1, "minimum": 1, "type": "integer" }, "pushes": { "$ref": "#/components/schemas/pushes" } }, "title": "Pushes/lifetime constraint", "type": "object", "x-inline-component": true }, "listMetadataObject": { "description": "Contains all user-specified data when defining a static list in Airship.", "properties": { "description": { "description": "An optional description for the list.", "maxLength": 1000, "minLength": 1, "type": "string" }, "extra": { "additionalProperties": { "example": { "key": "value" }, "type": "string" }, "description": "An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters." }, "name": { "description": "The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.\n\nNote: Since the `name` portion of the URL may represent any Unicode string, it must be encoded properly as a URI path component. The `encodeURIComponent` function in JavaScript can be used.", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]*$", "type": "string" } }, "required": [ "name" ], "title": "List metadata object", "type": "object", "x-inline-component": true }, "listMetadataResponse": { "properties": { "description": { "description": "An optional description for the list.", "maxLength": 1000, "minLength": 1, "type": "string" }, "extra": { "additionalProperties": { "example": { "key": "value" }, "type": "string" }, "description": "An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters." }, "name": { "description": "The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]*$", "type": "string" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object", "x-inline-component": true }, "listObject": { "description": "Contains all user-specified data about a static list or attributes list (metadata), but does not contain CSV list contents. Use the `/api/lists/{name}/csv` endpoints to [upload](/developer/rest-api/ua/operations/static-lists/#updatestaticlist) or [download](/developer/rest-api/ua/operations/static-lists/#getstaticlist) list contents.", "properties": { "channel_count": { "description": "A count of resolved channel identifiers for the last uploaded and successfully processed identifier list. This will always be 0 for attribute lists.", "readOnly": true, "type": "integer" }, "created": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the list was initially created.", "format": "date-time", "readOnly": true, "type": "string" }, "description": { "description": "An optional description for the list.", "maxLength": 10000, "type": "string" }, "error_path": { "description": "If non-empty, indicates that there were errors in the processed CSV file. The value is either an empty string or a URL to download a file describing the errors.", "type": "string" }, "extra": { "additionalProperties": { "example": { "key": "value" }, "type": "string" }, "description": "An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters." }, "last_updated": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the identifiers of the list were last updated successfully.", "format": "date-time", "readOnly": true, "type": "string" }, "name": { "description": "The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.", "maxLength": 64, "minLength": 1, "type": "string" }, "status": { "description": "A string value representing the state of the list.\n\n* `ready` — The list was processed successfully and is ready for sending.\n* `processing` — The list is being processed.\n* `failure` — There was an error processing the last uploaded list.\n", "enum": [ "ready", "processing", "failure" ], "readOnly": true, "type": "string" } }, "required": [ "name" ], "title": "List response object", "type": "object" }, "localization": { "description": "An object used to indicate that message content delivered to a device should be customized for a specific locale subset.\nEach localization object must have at least one of country and language. Which of those two fields are present does not need to be consistent across localizations.\n\nIn addition, each localization object must have one of `notification`, `message`, or `in_app` set. If the top level `notification`, `message`, or `in_app` fields are set,\nthey will be delivered to any user in the audience not matching any of the localizations.\n", "properties": { "country": { "description": "The ISO 3166-2 two-letter country code for this localization.", "type": "string" }, "in_app": { "$ref": "#/components/schemas/inAppObject" }, "language": { "description": "The ISO 639-1 two-letter language code for this localization.", "type": "string" }, "message": { "$ref": "#/components/schemas/messageObject" }, "notification": { "$ref": "#/components/schemas/notificationObject" } }, "title": "Localization object", "type": "object", "x-schema-tag": "Push" }, "localized_ids": { "description": "An array of identifiers used for reporting. Each ID represents a localized message (push object with `localizations` array).", "items": { "format": "uuid", "type": "string" }, "type": "array", "x-inline-component": true }, "messageCenterTemplatesObject": { "description": "The Message Center-specific fields for a template.", "properties": { "html_body": { "description": "The body of the message. This can be a full HTML message.", "type": "string" }, "title": { "description": "A heading that appears above the message and in the Message Center inbox.", "type": "string" } }, "required": [ "html_body" ], "title": "Message Center content template object", "type": "object", "x-schema-tag": "Content objects" }, "messageObject": { "description": "A Message Center message.", "properties": { "body": { "description": "The body of the message.", "type": "string" }, "content_encoding": { "default": "utf-8", "description": "A string denoting encoding type of the data in body. Defaults to `utf-8`. `base64` encoding can be used in cases which would be complex to escape properly, just as HTML containing embedded javascript code, which itself may contain embedded JSON data.", "example": "utf-8", "type": "string" }, "content_type": { "description": "A string denoting the MIME type of the data in body. Defaults to `text/html`.", "example": "text/html", "type": "string" }, "expiry": { "$ref": "#/components/schemas/expiryObject", "description": "The expiration time of the message in the user's inbox. Can be an integer encoding number of seconds from now, or an absolute timestamp in ISO UTC format. An integer value of 0 (zero) is equivalent to no expiry set." }, "extra": { "$ref": "#/components/schemas/extraObject" }, "icons": { "description": "A JSON dictionary of string key and value pairs representing icons. At this time, only the `list_icon` key is supported. Values must be URI/URLs to icon resources. For resources hosted by UA, use the following URI format `ua:`.", "properties": { "list_icon": { "example": "ua: 9bf2f510-050e-11e3-9446-14dae95134d2", "type": "string" } }, "type": "object" }, "title": { "description": "The title of the message.", "type": "string" } }, "required": [ "title", "body" ], "title": "Message Center object", "type": "object", "x-schema-tag": "Push" }, "messageObjectWithTemplate": { "description": "Use a `template` with a message center message. You can reference a template by ID, or use `{{handlebars}}` directly in your message.\n", "properties": { "content_encoding": { "default": "utf-8", "description": "A string denoting encoding type of the data in body. Defaults to `utf-8`. `base64` encoding can be used in cases which would be complex to escape properly, just as HTML containing embedded javascript code, which itself may contain embedded JSON data.", "example": "utf-8", "type": "string" }, "content_type": { "description": "A string denoting the MIME type of the data in body. Defaults to `text/html`.", "example": "text/html", "type": "string" }, "expiry": { "$ref": "#/components/schemas/expiryObject", "description": "The expiration time of the message in the user's inbox. Can be an integer encoding number of seconds from now, or an absolute timestamp in ISO UTC format. An integer value of 0 (zero) is equivalent to no expiry set." }, "extra": { "$ref": "#/components/schemas/extraObject" }, "icons": { "description": "A JSON dictionary of string key and value pairs representing icons. At this time, only the `list_icon` key is supported. Values must be URI/URLs to icon resources. For resources hosted by UA, use the following URI format `ua:`.", "properties": { "list_icon": { "example": "ua: 9bf2f510-050e-11e3-9446-14dae95134d2", "type": "string" } }, "type": "object" }, "template": { "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "type": "object" }, { "properties": { "external_id": { "$ref": "#/components/schemas/external_id" } }, "type": "object" }, { "properties": { "fields": { "description": "Items in the field object are personalizable with handlebars.", "properties": { "html_body": { "description": "The body of the message. This can be a full HTML message.", "type": "string" }, "title": { "description": "The title of the message.", "type": "string" } }, "type": "object" } }, "type": "object" } ] } }, "title": "Message Center with template", "type": "object", "x-schema-tag": "Push" }, "messageType": { "description": "Indicates the purpose of a message.", "enum": [ "transactional", "commercial" ], "title": "Message type", "type": "string", "x-schema-tag": "Push" }, "mms": { "description": "The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, `device_types` must be set to `mms`.", "properties": { "audience": { "oneOf": [ { "$ref": "#/components/schemas/cnsSmsAudienceObject" }, { "properties": { "bulk_id": { "description": "A unique string obtained from the [Create bulk send audience operation](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending.\n", "format": "uuid", "type": "string" } }, "required": [ "bulk_id" ], "type": "object" } ] }, "device_types": { "$ref": "#/components/schemas/device_types", "description": "Set to `mms` when sending MMS notifications." }, "notification": { "properties": { "mms": { "description": "A platform override for MMS messages; `device_types` must be set to `mms`. A notification with a platform override that does not match your `device_types` will result in a 400 error.", "oneOf": [ { "$ref": "#/components/schemas/mmsOverrideObject" }, { "$ref": "#/components/schemas/mmsOverrideWithTemplate" } ] } }, "required": [ "mms" ], "type": "object" } }, "required": [ "audience", "device_types", "notification" ], "title": "Create and Send MMS notification", "type": "object", "x-schema-tag": "Create and Send" }, "mmsOverrideObject": { "description": "Provides the content for a push to MMS channels. If `sms` is in the `device_type` array, your request may include this object.\nIt cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload.\n", "properties": { "fallback_text": { "description": "If a member of your audience cannot receive MMS messages, they will receive your fallback text with a link to the original content.\n", "maxLength": 160, "minLength": 1, "type": "string" }, "shorten_links": { "$ref": "#/components/schemas/shorten_links" }, "slides": { "description": "An array containing a single slide object. A slide is a multimedia object.\n", "items": { "properties": { "media": { "description": "Contains information about the media you want to send.", "properties": { "content_length": { "description": "The length of the attachment in bytes. Maximum size is 2 MB for `image/jpeg` and `image/png`, 1,024 KB for `image/gif` or `audio/.* MIME types`,\nand 2,048 KB for `text/vcard`. While this is optional, it is recommended since pushes will get dropped if the content size is incorrect.\n", "type": "integer" }, "content_type": { "description": "The MIME type of the image specified in the URL. The MIME type must match the extension in the `url`.", "enum": [ "image/jpeg", "image/gif", "image/png", "text/vcard", "audio/wav", "audio/3gpp", "audio/3gpp2", "audio/mp4", "audio/mpeg" ], "type": "string" }, "url": { "description": "The HTTP or HTTPS URL of the media attachment for the slide. The URL must end in one of `.gif`, `.jpeg`, `.jpg`, `.png`,\n`.mp1`, `.mp2`, `.mp3`, `.m1a`, `.m2a`, `.mpa`, `.wav`, `.3gp`, `.3g2`, `.m4a`, `.m4b`, `.m4r`, or `.vcf` (case-insensitive).\n\nWhile the `content_length` field is optional, your image must still be under 2 MB for JPEGs and PNGs, 1 MB for GIFs, or 2,048 KB for `text/vcard`.\n", "maxLength": 2000, "type": "string" } }, "required": [ "url", "content_type" ], "type": "object" }, "text": { "description": "Text that you want to display along with the media attachment. The order of media and text in the message is not guaranteed.\n", "maxLength": 5000, "minLength": 0, "type": "string" } }, "required": [ "media" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "subject": { "description": "The subject for the MMS message, normally displayed in bold. The subject might not appear for recipients if the Sender is a Toll-Free number. An empty string is valid.\n", "maxLength": 80, "minLength": 0, "type": "string" } }, "required": [ "fallback_text", "slides" ], "title": "MMS platform overrides", "type": "object", "x-schema-tag": "Platform overrides" }, "mmsOverrideWithTemplate": { "description": "Template and notification overrides for a Create and Send payload with `device_types` set to `mms`. With a template, you can provide and populate variables and conditional statements based on those variables. Conditionals begin with `{{#operator}}` and end with `{{/operator}}`. For more information, see [Handlebars](/guides/personalization/handlebars/).\n", "properties": { "slides": { "description": "An array containing a single slide object. A slide is a multimedia object.\n", "items": { "properties": { "media": { "properties": { "content_length": { "description": "The length of the attachment in bytes. Maximum size is 2 MB for `image/jpeg` and `image/png`, 1,024 KB for `image/gif` or `audio/.* MIME types`,\nand 2,048 KB for `text/vcard`. While this is optional, it is recommended since pushes will get dropped if the content size is incorrect.\n", "type": "integer" }, "content_type": { "description": "The MIME type of the image specified in the URL. The MIME type must match the extension in the `url`.", "enum": [ "image/jpeg", "image/gif", "image/png", "text/vcard", "audio/wav", "audio/3gpp", "audio/3gpp2", "audio/mp4", "audio/mpeg" ], "type": "string" }, "url": { "description": "The HTTP or HTTPS URL of the media attachment for the slide. The URL must end in one of `.gif`, `.jpeg`, `.jpg`, `.png`,\n`.mp1`, `.mp2`, `.mp3`, `.m1a`, `.m2a`, `.mpa`, `.wav`, `.3gp`, `.3g2`, `.m4a`, `.m4b`, `.m4r`, or `.vcf` (case-insensitive).\n\nWhile the `content_length` field is optional, your image must still be under 2 MB for JPEGs and PNGs, 1 MB for GIFs, or 2,048 KB for `text/vcard`.\n", "maxLength": 2000, "type": "string" } }, "required": [ "url", "content_type" ], "type": "object" } }, "required": [ "media" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "template": { "description": "Specify a `template_id` created in the Airship UI or use an inline template.", "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "required": [ "template_id" ], "type": "object" }, { "properties": { "fields": { "properties": { "fallback_text": { "description": "If a member of your audience cannot receive MMS messages, they will receive your fallback text with a link to the original content.\n", "maxLength": 160, "minLength": 1, "type": "string" }, "subject": { "description": "The subject for the MMS message, normally displayed in bold. The subject might not appear for recipients if the Sender is a Toll-Free number. An empty string is valid.\n", "maxLength": 80, "minLength": 0, "type": "string" }, "text": { "description": "Text that you want to display along with the media attachment. The order of media and text in the message is not guaranteed.\n", "maxLength": 5000, "minLength": 0 } }, "required": [ "fallback_text" ], "type": "object" } }, "type": "object" } ] } }, "title": "MMS notification with inline template", "type": "object", "x-schema-tag": "Platform overrides with templates" }, "mobile_originated_id": { "description": "The identifier that you received through your SMS webhook corresponding to the mobile-originated message that you're issuing a custom response to. The `mobile_originated_id` is valid for 10 minutes from the `received_timestamp` in the payload sent to your webhook server's `/inbound-sms` endpoint.\n", "format": "uuid", "type": "string", "x-inline-component": true }, "namedUserAttributesModificationResponse": { "description": "Body may contain warnings about portions of the request which\nwere not processed.\n", "properties": { "ok": { "description": "Set to `true` when status code is `200`.\n", "type": "boolean" }, "warnings": { "description": "Warnings encountered when updating Named User attributes.\n", "type": "string" } }, "title": "Named User attributes modification response", "type": "object", "x-inline-component": true }, "namedUserChannelTarget": { "properties": { "channel_id": { "example": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5", "format": "uuid", "type": "string" }, "device_type": { "description": "The device type of the channel.\nIf the channel is not yet registered in Airship and `device_type` is not provided a 400 will be returned.\n", "enum": [ "ios", "android", "amazon", "web", "email", "sms", "open" ], "type": "string" } }, "required": [ "channel_id" ], "title": "Channel", "type": "object", "x-inline-component": true }, "namedUserDeviceType": { "description": "The device type of the channel.", "enum": [ "ios", "android", "amazon", "web", "open", "email", "sms" ], "title": "Device type", "type": "string", "x-inline-component": true }, "namedUserEmailTarget": { "properties": { "email_address": { "description": "This email channel must already be registered in Airship or a 400 will be returned\n", "example": "user@example.com", "format": "email", "type": "string" } }, "required": [ "email_address" ], "title": "Email address", "type": "object", "x-inline-component": true }, "namedUserResponseBody": { "description": "The response body for a Named User listing, including tags, channels and attributes associated with the Named User.", "properties": { "attributes": { "$ref": "#/components/schemas/attributes" }, "channels": { "description": "Listing of channels associated with the Named User.", "items": { "$ref": "#/components/schemas/channelListingObject" }, "type": "array" }, "created": { "description": "The creation [date-time](/developer/rest-api/ua/introduction/#date-time-format).", "format": "date-time", "type": "string" }, "last_modified": { "description": "The last modified [date-time](/developer/rest-api/ua/introduction/#date-time-format).", "format": "date-time", "type": "string" }, "named_user_id": { "description": "A customer-chosen ID that represents a user, e.g., CRM ID. This ID cannot have leading or trailing whitespace.", "example": "john_doe", "type": "string" }, "subscription_lists": { "description": "A list of subscription list items associated with the Named User.", "items": { "$ref": "#/components/schemas/namedUserSubscriptionListItem" }, "type": "array" }, "tags": { "$ref": "#/components/schemas/tagGroupObject", "description": "One or more tag group objects associated with the Named User. See [Named User Tags](/developer/rest-api/ua/operations/tags/#modifynamedusertags)." }, "user_attributes": { "description": "User attributes consist of three values that are copied from the last channel associated with the Named User.", "properties": { "ua_country": { "description": "An ISO 3166 two-character country code. Example: \"US\".", "type": "string" }, "ua_language": { "description": "An ISO 639-1 two-character language code. Example: \"en\".", "type": "string" }, "ua_local_tz": { "description": "Time zone as a string. Example: \"America/Los_Angeles\"", "type": "string" } }, "type": "object" } }, "required": [ "named_user_id", "tags", "channels", "created", "last_modified", "attributes", "user_attributes", "subscription_lists" ], "title": "Named User object", "type": "object", "x-schema-tag": "Named User" }, "namedUserSubscriptionListItem": { "description": "An item consisting of a list of list IDs and scope.", "properties": { "list_ids": { "description": "A list of subscription lists associated to the specified scope. If no scope is specified these subscription lists are not scoped.", "example": [ "example_listId-1", "example_listId-5" ], "items": { "$ref": "#/components/schemas/subscriptionListId" }, "maxItems": 100, "minItems": 1, "type": "array" }, "scope": { "description": "Scope as a string.", "enum": [ "app", "email", "sms", "web" ], "type": "string" } }, "required": [ "list_ids" ], "title": "Subscription List item object", "type": "object", "x-schema-tag": "Subscription Lists" }, "namedUserSubscriptionListsObject": { "description": "Defines the Subscription List changes.", "properties": { "subscribe": { "description": "Subscribe to the specified Subscription List identifier.", "items": { "type": "string" }, "type": "array" }, "unsubscribe": { "description": "Unsubscribe the specified Subscription List identifier.", "items": { "type": "string" }, "type": "array" } }, "title": "Named User Subscription List object", "type": "object", "x-schema-tag": "Subscription Lists" }, "namedUserTags": { "description": "Add, remove, or set tags on a Named User. A single request body may\ncontain add and/or remove objects or a single set field. At least one of the add, remove, or set objects\nmust be present in a request.\n\nA tag must be < 128 characters. A request with one or more tags longer than 128 characters will return\na 400 response.\n\nIf at least one of the tags included in the request is valid,\ni.e., at least one tags exists, Airship returns a 200 with a warning containing a\nlist of tags that failed to update.\n", "properties": { "add": { "$ref": "#/components/schemas/tagGroupObject", "description": "Add the list of tags to the Named User, but do not remove any. If the tags are already present, they are not modified." }, "remove": { "$ref": "#/components/schemas/tagGroupObject", "description": "Remove the list of tags from the Named User, but do not remove any others. If the tags are not currently present, nothing happens." }, "set": { "$ref": "#/components/schemas/tagGroupObject", "description": "Set these tags for the Named User; any tags previously associated that are not in this current list are removed." } }, "title": "Tags", "type": "object", "x-inline-component": true }, "namedUserTagsResponse": { "description": "Body may contain warnings about portions of the request which\nwere not processed.\n", "properties": { "ok": { "description": "Set to `true` when status code is `200`.\n", "type": "boolean" }, "tag_warnings": { "description": "Warnings encountered when processing tags for this Named User.\n", "type": "string" } }, "required": [ "ok" ], "title": "Named User response", "type": "object", "x-inline-component": true }, "namedUserUpdate": { "description": "At least one of `associate`, `disassociate`, `tags`, or `attributes` must be provided.\nIf a channel is provided in both `associate` and `disassociate` sections, a 400 will be returned.\n", "properties": { "associate": { "description": "Associate a list of channels or email addresses with the Named User.\nIf the `channel_id` or `email_address` is already associated with the Named User,\nthis operation will do nothing.\n", "items": { "anyOf": [ { "$ref": "#/components/schemas/namedUserChannelTarget" }, { "$ref": "#/components/schemas/namedUserEmailTarget" } ] }, "type": "array" }, "attributes": { "description": "Set or remove attributes on a Named User.\n\nA single request body may contain `set` or `remove` operations, or both.\nIf both `set` and `remove` fields are present and the intersection of the attributes in these fields\nis not empty, then a 400 will be returned.\n\nIf at least one of the attributes included in the request is valid,\ni.e., at least one attribute exists, Airship returns a 200 with a warning containing a\nlist of attributes that failed to update.\n", "items": { "$ref": "#/components/schemas/attributesObject" }, "type": "array" }, "disassociate": { "description": "Disassociate a channel or an email address from the Named User.\n", "items": { "anyOf": [ { "$ref": "#/components/schemas/namedUserChannelTarget" }, { "$ref": "#/components/schemas/namedUserEmailTarget" } ] }, "type": "array" }, "tags": { "$ref": "#/components/schemas/namedUserTags", "type": "object" } }, "title": "Named User update payload", "type": "object", "x-schema-tag": "Named User" }, "namedUserUpdateResponse": { "description": "Body may contain warnings about portions of the request which\nwere not processed.\n", "properties": { "attribute_warnings": { "description": "Warnings encountered when processing attributes for this Named User.\n", "type": "string" }, "ok": { "description": "Set to `true` when status code is `200`.\n", "type": "boolean" }, "tag_warnings": { "description": "Warnings encountered when processing tags for this Named User.\n", "type": "string" } }, "required": [ "ok" ], "title": "Create/update Named User response", "type": "object", "x-inline-component": true }, "named_user": { "description": "A `named_user` is an alternate, non-unique name, mapped to a user profile in a different database, e.g., CRM, that can be used to target devices associated with that profile.", "example": [ "john_doe", "ID#998877" ], "properties": { "named_user": { "oneOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "$ref": "#/components/schemas/stringArray" } ] } }, "required": [ "named_user" ], "title": "Named User selector", "type": "object", "x-inline-component": true }, "notAcceptableResponseObject": { "description": "Unsupported `Accept` header. The request only supports `application/json`, `application/x-www-form-urlencoded`, `text/plain`.", "properties": { "error": { "description": "Error code.", "enum": [ "invalid_request" ], "type": "string" }, "error_description": { "description": "A plain-text description of the error.", "type": "string" } }, "required": [ "error" ], "title": "Error response", "type": "object", "x-inline-component": true }, "notificationObject": { "description": "The notification payload that is required unless either `message` or `in_app` is present. You can provide an `alert` and any platform overrides that apply to the `device_type` platforms you specify.", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "alert": { "description": "A notification message, displayed for any platforms receiving the push without a platform override.", "type": "string" }, "amazon": { "oneOf": [ { "$ref": "#/components/schemas/amazonOverrideObject" }, { "$ref": "#/components/schemas/amazonOverrideWithTemplate" } ] }, "android": { "oneOf": [ { "$ref": "#/components/schemas/androidOverrideObject" }, { "$ref": "#/components/schemas/androidOverrideWithTemplate" } ] }, "email": { "oneOf": [ { "$ref": "#/components/schemas/emailOverrideObject" }, { "$ref": "#/components/schemas/emailOverrideWithTemplate" } ] }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "ios": { "oneOf": [ { "$ref": "#/components/schemas/iosOverrideObject" }, { "$ref": "#/components/schemas/iosOverrideWithTemplate" } ] }, "mms": { "oneOf": [ { "$ref": "#/components/schemas/mmsOverrideObject" }, { "$ref": "#/components/schemas/mmsOverrideWithTemplate" } ] }, "open::open_platform_name": { "oneOf": [ { "$ref": "#/components/schemas/openChannelOverrideObject" }, { "$ref": "#/components/schemas/openChannelOverrideWithTemplate" } ] }, "sms": { "oneOf": [ { "$ref": "#/components/schemas/smsOverrideObject" }, { "$ref": "#/components/schemas/smsOverrideWithTemplate" } ] }, "web": { "oneOf": [ { "$ref": "#/components/schemas/webOverrideObject" }, { "$ref": "#/components/schemas/webOverrideWithTemplate" } ] } }, "title": "Notification object", "type": "object", "x-schema-tag": "Push" }, "npsSurveyAttributes": { "description": "Attributes automatically generated by Airship based on data from your NPS surveys.\n", "properties": { "ua_nps_category": { "description": "A category based on the score a user submits in an NPS survey. Scores of 9 and 10 are categorized as `promoter`, 7 and 8 are categorized as `passive`, and 0-6 are `detractor`.", "type": "string" }, "ua_nps_score": { "description": "The score (0-10) a user submits in an NPS (Net Promoter Score) survey.", "type": "number" } }, "title": "NPS survey Attributes", "type": "object", "x-inline-component": false, "x-schema-tag": "Attributes", "x-weight": 3 }, "numberAttribute": { "description": "An attribute object with a `NUMBER` schema type. Performs value comparisons based on the number value for an attribute on a channel or Named User.", "properties": { "attribute": { "description": "The key for the number attribute that you previously defined in the Airship UI, e.g., `\"lifetime_value\"`.", "maxLength": 256, "minLength": 1, "type": "string" }, "operator": { "description": "The operator used to evaluate the attribute expression.", "enum": [ "equals", "contains", "less", "greater", "is_empty" ], "type": "string" }, "value": { "description": "The value of the number attribute that you are targeting. For example, `15000`.", "type": "number" } }, "required": [ "attribute", "operator", "value" ], "title": "Number attribute selector", "type": "object", "x-schema-tag": "Attributes", "x-weight": 9 }, "oauthScope": { "description": "The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope. For more information about scope values, see [OAuth token scopes](/developer/rest-api/ua/api-auth-reference/#oauth-token-scopes) in the *Airship API Authorization Reference* documentation.\n * `att`: Attachments\n * `chn`: Channels\n * `tpl`: Content\n * `evt`: Events\n * `lst`: Lists\n * `nu`: Named Users\n * `pln`: Pipelines\n * `psh`: Push\n * `rpt`: Reports\n * `sch`: Schedules", "enum": [ "att", "chn", "tpl", "evt", "lst", "nu", "pln", "psh", "rpt", "sch" ], "title": "OAuth Scope", "type": "string", "x-schema-tag": "OAuth" }, "okOauthTokenResponse": { "description": "Issued access token.", "properties": { "access_token": { "description": "The issued token that can be used for all endpoints as allowed by set scopes.", "type": "string" }, "expires_in": { "description": "The number of seconds from the time the token is generated until it expires.", "type": "integer" }, "scope": { "$ref": "#/components/schemas/oauthScope", "description": "A space-delimited list of scopes of the issued token. There may be undocumented scopes in this list." }, "token_type": { "description": "The type of issued token.", "enum": [ "Bearer" ], "type": "string" } }, "title": "OK response", "type": "object", "x-inline-component": true }, "okResponseObject": { "description": "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.", "properties": { "ok": { "description": "Success.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operations that modify resources. Use the operation ID to locate and track grouped operations (i.e., a batch push operation may generate multiple `push_id` strings, but a single `operation_id`) or operations that change an existing resource.", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "title": "OK response", "type": "object", "x-schema-tag": "Responses" }, "open": { "description": "The payload for a Create and Send operation to open channels. When sending to open channels, the `device_type` must be set to `open::`.", "properties": { "audience": { "oneOf": [ { "$ref": "#/components/schemas/cnsOpenAudienceObject" }, { "properties": { "bulk_id": { "description": "A unique string obtained from the [Create bulk send audience operation](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending.\n", "format": "uuid", "type": "string" } }, "required": [ "bulk_id" ], "type": "object" } ] }, "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "device_types": { "$ref": "#/components/schemas/device_types" }, "notification": { "description": "An `alert` notification or a platform override matching the value in `device types`. A notification with a platform override that does not match your `device_types` will result in a 400 error.", "properties": { "open::open_platform_name": { "$ref": "#/components/schemas/openChannelOverrideWithTemplate" } }, "type": "object" } }, "required": [ "audience", "device_types", "notification" ], "title": "Create and Send to open channels", "type": "object", "x-schema-tag": "Create and Send" }, "openChannelIdentifier": { "description": "The request body containing an address and `open_platform_name`.", "properties": { "address": { "description": "Where notifications sent to this `channel_id` will be sent. Examples: email address, phone number. If missing, `channel_id` must be present. The `address` is one-to-one with the `channel_id`. New addresses on existing channels will overwrite old associations.", "example": [ "new_email@example.com" ], "type": "string" }, "open_platform_name": { "description": "An alphanumeric string that must be the name of a pre-created open platform object.", "example": [ "twitter" ], "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "address", "open_platform_name" ], "title": "Open channel identifier", "type": "object", "x-inline-component": true }, "openChannelObject": { "description": "Describes an open channel.", "properties": { "address": { "description": "The address to send push notifications to when `device_type` is `email` or `open`.", "example": "email@example.com", "type": "string" }, "channel_id": { "description": "The unique channel identifier for a device.", "example": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5", "format": "uuid", "type": "string" }, "created": { "description": "The creation [date-time](/developer/rest-api/ua/introduction/#date-time-format) of this channel.", "format": "date-time", "readOnly": true, "type": "string" }, "last_registration": { "description": "The last registration [date-time](/developer/rest-api/ua/introduction/#date-time-format) of this channel, if known.", "format": "date-time", "nullable": true, "readOnly": true, "type": "string" }, "locale_country": { "description": "The two-letter country locale short code. Will set the `ua_locale_country` tag group to the specified value.", "type": "string" }, "locale_language": { "description": "The two-letter language locale short code. Will set the `ua_locale_language` tag group to the specified value.", "type": "string" }, "named_user_id": { "description": "A customer-chosen ID that represents the device user, e.g., CRM ID. This ID cannot have leading or trailing whitespace.", "example": "john_doe", "maxLength": 128, "minLength": 1, "nullable": true, "pattern": "^[^\\s].{1,125}\\S$", "type": "string" }, "open": { "description": "Contains options that apply when the `device_type` is set to `open`.", "properties": { "identifiers": { "additionalProperties": true, "description": "A set of up to 100 key:value pairs representing identifiers for this channel in your own delivery systems and delivered as a part of webhook payloads.", "example": { "slack-handle": "slackinator" }, "type": "object" }, "old_address": { "description": "If a channel exists for the value of `old_address`, replaces that channel's address with the value of `address`. Use infrequently, such as when an end user's phone number or email address permanently changes.", "type": "string" }, "open_platform_name": { "description": "The name of the open channel that this `channel_id` is registered on.", "example": "Slack", "type": "string" } }, "title": "Open channel options", "type": "object" }, "opt_in": { "description": "If true, the channel is opted in to push notifications. If false, it is not.", "type": "boolean" }, "set_tags": { "description": "When `true`, replaces all device tags on the channel with the set provided in `\"tags\"`. When `false` or absent, the `\"tags\"` set is unioned with existing device tags.", "type": "boolean" }, "tag_groups": { "$ref": "#/components/schemas/tagGroupObject", "description": "One or more tag group objects (including [Device Property Tags](/reference/device-property-tags/)) associated with this channel." }, "tags": { "$ref": "#/components/schemas/tagArrayBig", "description": "An array of tags associated with this channel." }, "timezone": { "description": "An IANA tzdata identifier for the time zone as a string, e.g., `\"America/Los_Angeles\"`. Will set the `timezone` tag group tag with the specified value.", "type": "string" }, "type": { "description": "Specifies the device platform for a channel.", "enum": [ "open" ], "type": "string" } }, "title": "Open channel object", "type": "object", "x-inline-component": true }, "openChannelOptionsObject": { "description": "Contains options that apply when the `device_type` is set to `open`.", "properties": { "identifiers": { "additionalProperties": true, "description": "A set of up to 100 key:value pairs representing identifiers for this channel in your own delivery systems and delivered as a part of webhook payloads.", "example": { "slack-handle": "slackinator" }, "type": "object" }, "old_address": { "description": "If a channel exists for the value of `old_address`, replaces that channel's address with the value of `address`. Use infrequently, such as when an end user's phone number or email address permanently changes.", "type": "string" }, "open_platform_name": { "description": "The name of the open channel that this `channel_id` is registered on.", "example": "Slack", "type": "string" } }, "required": [ "open_platform_name" ], "title": "Open channel options", "type": "object", "x-schema-tag": "Channels" }, "openChannelOverrideObject": { "description": "The platform override section for open platforms uses the prefix attribute `open::` before the configured open platform name. The `open::` object will contain an object with the following attributes.", "properties": { "alert": { "description": "Override the alert value provided at the top level, if any.", "type": "string" }, "extra": { "$ref": "#/components/schemas/extraObject" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "media_attachment": { "description": "A URI for an image or video somewhere on the internet.", "format": "uri", "type": "string" }, "summary": { "description": "A string value for providing a content summary.", "type": "string" }, "title": { "description": "A string representing the title of the notification.", "type": "string" } }, "title": "Open channel override", "type": "object", "x-schema-tag": "Platform overrides" }, "openChannelOverrideWithTemplate": { "description": "Use a `template` with an open channel-specific message. You can reference a template by ID, or use `{{handlebars}}` directly in your message.\n", "properties": { "extra": { "$ref": "#/components/schemas/extraObject" }, "interactive": { "$ref": "#/components/schemas/interactiveObject" }, "template": { "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "type": "object" }, { "properties": { "fields": { "properties": { "alert": { "description": "Override the alert value provided at the top level, if any.", "type": "string" }, "media_attachment": { "description": "A URI for an image or video somewhere on the internet.", "format": "uri", "type": "string" }, "summary": { "description": "A string value for providing a content summary.", "type": "string" }, "title": { "description": "A string representing the title of the notification.", "type": "string" } }, "type": "object" } }, "type": "object" } ] } }, "required": [ "template" ], "title": "Open channel overrides with template", "type": "object", "x-schema-tag": "Platform overrides with templates" }, "openChannelSendsObject": { "description": "Contains an array of the number of send counts per open platform. If there were no open channels sends associated with the push ID, an empty result will be returned.", "properties": { "platforms": { "description": "An array of objects indicating the total sends by open platform.", "items": { "description": "An object containing the send counts per platform.", "properties": { "id": { "description": "The key representing the canonical identifier in the Airship system for the given open platform.", "example": "platform_name", "type": "string" }, "sends": { "description": "The number of sends for the given push ID and the given open platform.", "example": 26, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object", "x-inline-component": true }, "openChannelTemplatesObject": { "description": "The open channel-specific fields for a template.", "properties": { "alert": { "description": "The text that will display in your open channel message.", "type": "string" }, "media_attachment": { "description": "The URL for media you want to include in your message.", "type": "string" }, "summary": { "description": "Supplemental text displayed with the notification.", "type": "string" }, "title": { "description": "A heading that appears above the notification text when applicable.", "type": "string" } }, "required": [ "alert" ], "title": "Open channel content template object", "type": "object", "x-schema-tag": "Content objects" }, "open_channel": { "description": "The unique channel identifier used to target a device on an open platform.", "properties": { "open_channel": { "oneOf": [ { "format": "uuid", "type": "string" }, { "$ref": "#/components/schemas/uuidArray" } ] } }, "required": [ "open_channel" ], "title": "Open channel selector", "type": "object", "x-inline-component": true }, "open_tracking_opted_in": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user opted in to open tracking.\n", "format": "date-time", "type": "string", "x-inline-component": true }, "open_tracking_opted_out": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user opted out of open tracking.\n", "format": "date-time", "type": "string", "x-inline-component": true }, "operation_id": { "description": "A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes.", "format": "uuid", "title": "Operation ID", "type": "string", "x-inline-component": true }, "orchestrationObject": { "description": "An object used to indicate the strategy to employ when deciding which channels to target for a contact.\nAn orchestration object can be stored in Airship as the default strategy. If the orchestration section is included in a push payload,\nit will override the configured default value. The overall default strategy is `fan_out`.\n", "properties": { "channel_priority": { "description": "An array of channel types in priority order. Required if `type` is set to `channel_priority`.\n", "items": { "description": "A channel type. One of `app`, `web`, `sms`, `email`, and `open::`\n", "type": "string" }, "type": "array" }, "type": { "description": "The name of the orchestration strategy to employ.\n", "enum": [ "channel_priority", "fan_out", "triggering_channel", "last_active" ], "type": "string" } }, "required": [ "type" ], "title": "Orchestration object", "type": "object", "x-inline-component": true }, "outcomeObject": { "description": "An outcome object contains a single push object where the `audience` field must be set to `triggered`.", "properties": { "push": { "$ref": "#/components/schemas/pipelinesPushObject" } }, "required": [ "push" ], "title": "Outcome object", "type": "object", "x-inline-component": true, "x-schema-tag": "Pipeline objects" }, "perGroupPushDetail": { "allOf": [ { "properties": { "group_id": { "description": "The UUID representing a specific group push.", "format": "uuid", "type": "string" } }, "type": "object" }, { "$ref": "#/components/schemas/perPushPerGroupDetailReporting" } ], "description": "The response body for detail reporting per push group.", "x-inline-component": true }, "perGroupPushTimeSeriesReport": { "allOf": [ { "properties": { "group_id": { "description": "The UUID representing a specific group push.", "format": "uuid", "type": "string" } }, "type": "object" }, { "$ref": "#/components/schemas/commonSeriesReportResponse" }, { "properties": { "counts": { "description": "Array of total count objects, each representing counts within the given [date-time](/developer/rest-api/ua/introduction/#date-time-format) range and precision.", "items": { "$ref": "#/components/schemas/countsTimeSeriesObject" }, "type": "array" } }, "type": "object" } ], "description": "The response body for per push time series report.", "x-inline-component": true }, "perPushDetail": { "allOf": [ { "properties": { "push_id": { "description": "The UUID representing a specific push.", "format": "uuid", "type": "string" } }, "type": "object" }, { "$ref": "#/components/schemas/perPushPerGroupDetailReporting" } ], "description": "The response body for detail reporting per push.", "x-inline-component": true }, "perPushPerGroupDetailReporting": { "description": "The response body for detail reporting per push or per group.", "properties": { "alerting_sends": { "description": "The number of alerting sends.", "type": "integer" }, "app_key": { "description": "The app key for the given push.", "type": "string" }, "created": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the push was created.", "format": "date-time", "readOnly": true, "type": "string" }, "direct_responses": { "description": "The number of direct responses.", "type": "integer" }, "influenced_responses": { "description": "The total number of influenced responses.", "type": "integer" }, "platforms": { "properties": { "amazon": { "$ref": "#/components/schemas/platformObject" }, "android": { "$ref": "#/components/schemas/platformObject" }, "ios": { "$ref": "#/components/schemas/platformObject" }, "web": { "$ref": "#/components/schemas/platformObject" } }, "type": "object" }, "rich_deletions": { "description": "The number of rich deletions.", "type": "integer" }, "rich_responses": { "description": "The number of rich responses.", "type": "integer" }, "rich_sends": { "description": "The number of rich sends.", "type": "integer" }, "sends": { "description": "The number of pushes sent.", "type": "integer" }, "silent_sends": { "description": "The number of silent sends.", "type": "integer" } }, "type": "object", "x-inline-component": true }, "perPushTimeSeriesReport": { "allOf": [ { "properties": { "push_id": { "description": "The UUID representing a specific push.", "format": "uuid", "type": "string" } }, "type": "object" }, { "$ref": "#/components/schemas/commonSeriesReportResponse" }, { "properties": { "counts": { "description": "Array of total count objects, each representing counts within the given [date-time](/developer/rest-api/ua/introduction/#date-time-format) range and precision.", "items": { "$ref": "#/components/schemas/countsTimeSeriesObject" }, "type": "array" } }, "type": "object" } ], "description": "The response body for per push time series report.", "x-inline-component": true }, "pipelineCreatedResponseBody": { "description": "The response body for a create pipeline request.", "properties": { "ok": { "description": "Success.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying a single API call.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "pipeline_urls": { "description": "An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.", "items": { "description": "A string URL of the newly created pipeline.", "example": [ "https://go.urbanairship/api/pipelines/4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4" ], "format": "uri", "type": "string" }, "type": "array" } }, "title": "Pipeline created response body", "x-inline-component": true, "x-schema-tag": "Pipeline objects" }, "pipelineEventSelector": { "description": "A JSON dictionary describing which pipeline events for a specified pipeline should be considered a match\nand should therefore trigger the pipeline.\n", "properties": { "cancellation_reason": { "description": "For cancelled type selectors, the specific cancellation reason to consider for triggering. All others will be ignored.", "enum": [ "cancellation_trigger", "timing", "condition", "rewritten", "rate_limit" ], "type": "string" }, "message_id": { "description": "Unique identifier for an In-App Automation. This is required when `type` is `in_app_fallback`.", "type": "string" }, "pipeline_id": { "description": "The UUID of a pipeline whose events should be considered. If this is not provided, then `trigger_ids` must be provided. This is not required if `message_id` is provided.", "type": "string" }, "trigger_ids": { "description": "The list of trigger IDs that should be considered. If this is not provided, then `pipeline_id` must be provided. This is not required if `message_id` is provided.", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "type": { "description": "The type of event for the specified pipeline which should be considered.", "enum": [ "entered", "cancelled", "fulfilled", "in_app_fallback" ], "type": "string" } }, "required": [ "type" ], "title": "Pipeline event selector", "type": "object", "x-inline-component": true, "x-schema-tag": "Pipeline objects" }, "pipelineObject": { "description": "A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of `immediate_trigger` or `historical_trigger` must be supplied.", "properties": { "activation_time": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the pipeline becomes active and begins processing triggers and issuing push notifications.\n\n\nIf this value is in the future, the pipeline's `status` is `pending`.\n", "format": "date-time", "type": "string" }, "cancellation_trigger": { "oneOf": [ { "$ref": "#/components/schemas/eventIdentifier" }, { "description": "Defines event conditions that will cancel the fulfillment of a pipeline. If a pipeline has multiple cancellation triggers, they’re combined via an implicit OR operation. Any one of the triggers will cancel the fulfillment of the pipeline. Cancellation triggers are only allowed when a pipeline has no historical triggers and it is possible for a pipeline’s fulfillment to be delayed using the Timing Object.\nThe `first_open` event identifier is not valid as a cancellation trigger.\n", "items": { "$ref": "#/components/schemas/eventIdentifier" }, "type": "array" } ] }, "condition": { "description": "One or more conditions, combined by operators. A\n condition set may contain a maximum of 20 conditions. Taken together, the\n operator and set of conditions form a boolean expression which must evaluate\n to true for a pipeline to be activated and its outcomes executed. Valid\n operators for a condition set are `and` and `or`. Nesting of operators\n is not supported within a condition set, i.e., you may not combine `and`\n logic with `or` logic.", "items": { "oneOf": [ { "properties": { "and": { "items": { "$ref": "#/components/schemas/conditionObject" }, "type": "array" } }, "title": "AND selector", "type": "object" }, { "properties": { "or": { "items": { "$ref": "#/components/schemas/conditionObject" }, "type": "array" } }, "title": "OR selector", "type": "object" } ], "type": "object" }, "type": "array" }, "constraint": { "description": "An array of rate objects determining the maximum number of messages each audience member can receive over a period of time.\nYou can set a `lifetimes` constraint as well, limiting a pipeline to an absolute maximum number of messages ever.", "items": { "$ref": "#/components/schemas/rateLimitConstraintsObject" }, "maxItems": 3, "type": "array", "uniqueItems": true }, "creation_time": { "description": "Read-only timestamp. The [date-time](/developer/rest-api/ua/introduction/#date-time-format) indicating the time that the pipeline was initially created. This is a read-only field that is present on GET responses. If it is included in a POST or PUT request it will be ignored.", "format": "date-time", "readOnly": true, "type": "string" }, "deactivation_time": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the pipeline becomes inactive and quits processing triggers and issuing push notifications.\n\n\nIf this value is in the past, the pipeline's `status` is `completed`.\n", "format": "date-time", "type": "string" }, "enabled": { "description": "A boolean value indicating whether or not the pipeline is active.", "type": "boolean" }, "historical_trigger": { "oneOf": [ { "$ref": "#/components/schemas/historicalTriggerObject" }, { "description": "Historical trigger objects are limited to inactivity triggers, which trigger when a user fails to open the app within a defined number of days.", "items": { "$ref": "#/components/schemas/historicalTriggerObject" }, "type": "array" } ] }, "immediate_trigger": { "oneOf": [ { "$ref": "#/components/schemas/eventIdentifier" }, { "description": "Defines a condition that activates a trigger immediately when an event matching it occurs. If a pipeline has multiple immediate triggers, they’re combined via an implicit OR operation. Any one of the triggers firing will activate the pipeline. Immediate triggers are all event identifiers. `first_open` is a valid event identifier for immediate triggers. However, events within the trigger support AND and OR compound selection.", "items": { "$ref": "#/components/schemas/eventIdentifier" }, "type": "array" } ] }, "last_modified_time": { "description": "Read-only timestamp. The [date-time](/developer/rest-api/ua/introduction/#date-time-format)indicating the time that the pipeline was last modified. This is a read-only field that is present on GET responses. If it is included in a POST or PUT request it will be ignored.", "format": "date-time", "readOnly": true, "type": "string" }, "name": { "description": "A descriptive name for the pipeline.", "type": "string" }, "outcome": { "oneOf": [ { "$ref": "#/components/schemas/outcomeObject" }, { "items": { "$ref": "#/components/schemas/outcomeObject" }, "type": "array" } ] }, "status": { "description": "Read-only field indicating whether or not the pipeline is currently issuing push notifications.\n\n* `pending`: The pipeline is not yet active. Occurs when the current time is less than or equal to the `activation_time`.\n* `live`: The pipeline is active.\n* `completed`: The pipeline has finished running. Occurs when the current time is greater than or equal to the `deactivation_time`.\n* `disabled`: The pipeline is not active.", "enum": [ "pending", "live", "completed", "disabled" ], "readOnly": true, "type": "string" }, "timing": { "description": "Determines when pipelines will be sent in accordance with triggers.", "properties": { "delay": { "description": "Determines the time that Airship should wait after a triggering event before processing the pipeline outcome.", "properties": { "seconds": { "description": "An integer value greater than 0 seconds representing the number of seconds to delay.", "minimum": 1, "type": "integer" } }, "required": [ "seconds" ], "title": "Delay object", "type": "object" }, "schedule": { "description": "The time(s) when the pipeline can issue pushes and behavior for events occurring outside scheduled time(s).", "properties": { "dayparts": { "description": "A list of daypart objects that, when combined, are non-intersecting and form a nonempty group of time ranges on a nonzero number of days of the week. Daypart is a term borrowed from\n [television/radio marketing](https://en.wikipedia.org/wiki/Dayparting).", "items": { "properties": { "allowed_times": { "description": "A list of allowed time objects. Time intervals specified by allowed time objects may not overlap.", "items": { "properties": { "end": { "description": "End time in ISO 8601 format `hh:mm:ss`. Optional, unless start is specified.", "format": "time", "type": "string" }, "preferred": { "description": "Optional, preferred time in ISO 8601 format `hh:mm:ss` to process an outcome. Must be between the start and end time. This time is used when an outcome is triggered or delayed until a disallowed time. If the subsequent allowed time object contains a preferred time, the outcome will be scheduled for that time instead of the next possible time.", "format": "time", "type": "string" }, "start": { "description": "Start time in ISO 8601 format `hh:mm:ss`. Optional, unless end is specified.", "format": "time", "type": "string" } }, "type": "object" }, "title": "Allowed times", "type": "array" }, "days_of_week": { "description": "A list of days of the week that the `allowed_times` field is applicable for.", "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" }, "miss_behavior": { "description": "Behavior of the pipeline when a triggering event occurs outside the range of `daypart` objects and `allowed_times`. You can specify `cancel` (do not process the outcome) or `wait` (delay the outcome until the preferred time of the next allowed_times window or the beginning of that window). Defaults to `wait` if unspecified.", "enum": [ "wait", "cancel" ], "type": "string" }, "type": { "description": "The mode in which to interpret the times in this schedule. Default is `local`.", "enum": [ "local", "utc" ], "type": "string" } }, "required": [ "dayparts" ], "title": "Timing schedule object", "type": "object" } }, "type": "object" }, "uid": { "description": "The canonical identifier of the pipeline. This is a read-only field present on responses from the API, but it will be ignored if it is present on requests.", "readOnly": true, "type": "string" }, "url": { "description": "Read-only string. The canonical resource URL of the pipeline. This is a read-only field present on responses from the API, but it will be ignored if present on requests.", "format": "URL", "readOnly": true, "type": "string" } }, "required": [ "enabled", "outcome" ], "title": "Pipeline object", "type": "object", "x-schema-tag": "Pipeline objects" }, "pipelineResponseBody": { "description": "The response body for a pipelines request.", "properties": { "next_page": { "description": "An URI that points to the next page of pipelines. The page size is specified by the `limit` parameter and the start point by the `start` parameter. If there are no more pipelines for a next page we omit the next page link.", "type": "string" }, "ok": { "description": "Success.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying a single API call.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "pipeline_ids": { "description": "An array of pipeline IDs.", "items": { "description": "A string uniquely identifying a pipeline.", "example": [ "4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4", "08c806fe-6b2b-403f-be05-68aa5513ef71" ], "type": "string" }, "type": "array" }, "pipeline_urls": { "description": "An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.", "items": { "description": "A string URL of the newly created pipeline.", "example": [ "https://go.urbanairship/api/pipelines/4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4" ], "format": "uri", "type": "string" }, "type": "array" }, "pipelines": { "description": "A list of pipeline objects.", "items": { "$ref": "#/components/schemas/pipelineObject" }, "type": "array" }, "prev_page": { "description": "An URI that points to the previous page of pipelines. The page size is specified by the `limit` parameter and the start point by the `start` parameter. If there are no more pipelines for a previous page we omit the previous page link.", "type": "string" }, "total_count": { "description": "The total count of pipelines.", "type": "integer" } }, "title": "Pipeline response body", "x-inline-component": true, "x-schema-tag": "Pipeline objects" }, "pipelinesPushObject": { "description": "A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.", "properties": { "audience": { "$ref": "#/components/schemas/triggeredSelector" }, "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "device_types": { "$ref": "#/components/schemas/deviceTypesSelector" }, "in_app": { "$ref": "#/components/schemas/inAppObject" }, "message": { "oneOf": [ { "$ref": "#/components/schemas/messageObject" }, { "$ref": "#/components/schemas/messageObjectWithTemplate" } ] }, "notification": { "$ref": "#/components/schemas/notificationObject" }, "options": { "$ref": "#/components/schemas/pushOptions" }, "orchestration": { "$ref": "#/components/schemas/orchestrationObject" } }, "required": [ "audience", "device_types" ], "type": "object", "x-inline-component": true }, "platformObject": { "properties": { "direct_responses": { "description": "The number of direct responses (clicks/app opens) to the notification on this platform as measured by the SDK.", "type": "integer" }, "influenced_responses": { "description": "The number of opens or clicks resulting from your notification (directly or indirectly).", "type": "integer" }, "sends": { "description": "The total number of audience members accounted on the specified platform.", "type": "integer" } }, "type": "object", "x-inline-component": true }, "pointObject": { "description": "A Point object is a simple JSON object corresponding to a point on the globe, consisting of only two keys: latitude and longitude.", "properties": { "latitude": { "description": "Decimal with maximum 6 digits of decimal precision in the range [-90,90].", "format": "float", "type": "number" }, "longitude": { "description": "Decimal with maximum 6 digits of decimal precision in the range of [0, 180)", "format": "float", "type": "number" } }, "required": [ "latitude", "longitude" ], "title": "Point object", "type": "object", "x-schema-tag": "Regions" }, "pushAccepted": { "description": "A push response contains a list of identifiers for the notifications sent in the request.", "properties": { "content_urls": { "$ref": "#/components/schemas/urlArray", "description": "An array of URLs where the push payload contains a landing page action." }, "localized_ids": { "$ref": "#/components/schemas/localized_ids" }, "message_ids": { "description": "An array of message IDs, each uniquely identifying a Message Center message.", "items": { "type": "string" }, "type": "array" }, "ok": { "description": "Success.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "push_ids": { "$ref": "#/components/schemas/uuidArray", "description": "An array of push IDs, each uniquely identifying a push." } }, "type": "object", "x-inline-component": true, "x-schema-tag": "Push" }, "pushObject": { "description": "A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.", "properties": { "audience": { "$ref": "#/components/schemas/audienceSelector1000" }, "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "device_types": { "$ref": "#/components/schemas/deviceTypesSelector" }, "feed_references": { "$ref": "#/components/schemas/feedReferences" }, "global_attributes": { "$ref": "#/components/schemas/globalAttributes" }, "in_app": { "$ref": "#/components/schemas/inAppObject" }, "localizations": { "description": "An array of localizations. Channels bearing the specified language/country combination will receive the corresponding message.", "items": { "$ref": "#/components/schemas/localization" }, "type": "array" }, "message": { "oneOf": [ { "$ref": "#/components/schemas/messageObject" }, { "$ref": "#/components/schemas/messageObjectWithTemplate" } ] }, "message_type": { "$ref": "#/components/schemas/messageType" }, "notification": { "$ref": "#/components/schemas/notificationObject" }, "options": { "$ref": "#/components/schemas/pushOptions" }, "orchestration": { "$ref": "#/components/schemas/orchestrationObject" }, "snippet_references": { "$ref": "#/components/schemas/snippetReferences" } }, "required": [ "audience", "device_types" ], "title": "Push object", "type": "object", "x-schema-tag": "Push" }, "pushOptions": { "description": "A JSON dictionary for specifying non-payload options related to the delivery of the push.", "properties": { "audience_limits": { "$ref": "#/components/schemas/audienceLimitsObject" }, "ban_list_parameters": { "$ref": "#/components/schemas/banListParametersObject" }, "bypass_ban_list_processing": { "default": false, "description": "If true, a user's status on a [ban list](/guides/audience/segmentation/ban-lists/) will not be verified before sending the push.\n", "type": "boolean" }, "bypass_frequency_limits": { "default": false, "description": "If true, the push ignores any [message limits](/guides/messaging/project/config/message-limits/) that would otherwise apply to your message.\n", "type": "boolean" }, "bypass_holdout_groups": { "default": false, "description": "If true, the push ignores withholding any messages for users in a holdout group for a [Holdout Experiment](/guides/experimentation/holdout-experiments/) that is active at send time.\n", "type": "boolean" }, "expiry": { "$ref": "#/components/schemas/expiryObject" }, "no_throttle": { "default": false, "description": "If true, the push will ignore global throttling rates that have been configured for the application, resulting in delivery as quickly as possible.", "type": "boolean" }, "omit_from_activity_log": { "default": false, "description": "If true, the push is omitted from the [Activity Log](/guides/reports/activity-log/).\n", "type": "boolean" }, "personalization": { "default": false, "description": "If true, enables Handlebars-style template syntax for eligible fields in a [notification](/developer/rest-api/ua/schemas/others/#notificationobject) or [message center](/developer/rest-api/ua/schemas/others/#messageobject) objects. You can do this to enable handlebars for all available fields without using individual `template` objects for different platform overrides.\n\nThis setting is implicitly true whenever your payload includes a [platform override](/developer/rest-api/ua/schemas/platform-overrides/) with a `template` object.\n", "type": "boolean" }, "redact_payload": { "default": false, "description": "If true, the push payload will not appear in Airship's logs. You cannot use this option with Message Center, A/B Tests, Automation, or Scheduled pushes, which all require the payload to be stored separately by design.", "type": "boolean" }, "use_strict_sms_validation": { "description": "This field is only compatible for [Create and Send](/developer/rest-api/ua/operations/bulk-sending/#createandsend) requests targeting `SMS` and `MMS` `device_types`.\n\nIf true, Create and Send requests containing any selector entries that would result in silent row drops will return\na `400 Bad Request` response code. Detailed error messages will be returned for all invalid rows.\n\nIf false, requests that contain row entries with silent errors as documented for the targeted required selector fields will return a `200` status code.\nHowever, all invalid entries will be **silently** dropped during request processing.\n\nBy default, this attribute is implicitly set to `false` unless every entry in the request would be dropped silently as determined by the targeted selector\ntype, at least one malformed JSON error is found in the request, or at least one validation error is encountered for a required selector field that is not\ndocumented to handle invalid data with silent drops.\n", "type": "boolean" } }, "title": "Push options", "type": "object", "x-inline-component": false, "x-schema-tag": "Push" }, "pushTemplatePayload": { "description": "A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.", "properties": { "audience": { "$ref": "#/components/schemas/audienceSelector1000", "description": "The audience for the template." }, "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "device_types": { "$ref": "#/components/schemas/deviceTypesSelector" }, "merge_data": { "description": "A template selector describing the template ID and variable substitutions to use with it.", "properties": { "substitutions": { "description": "An object containing overrides for your template's variables. The key-value pairs in this object are the value of the `key` items defined in your template, and the values you want to substitute for the `default_value` of those keys.", "type": "object" }, "template_id": { "description": "Specifies the template to override; corresponds to the `id` in `/templates` responses.", "example": "ef34a8d9-0ad7-491c-86b0-aea74da15161", "format": "uuid", "type": "string" } }, "required": [ "template_id" ], "type": "object" } }, "required": [ "audience", "device_types", "merge_data" ], "title": "Push template payload", "type": "object", "x-schema-tag": "Personalization template objects" }, "push_id": { "description": "A unique identifier for a push operation.", "format": "uuid", "title": "Push ID", "type": "string", "x-inline-component": true }, "pushes": { "description": "An integer, specifying the maximum number of pushes to any individual audience member per time period.", "type": "integer", "x-inline-component": true }, "rateLimitConstraintsObject": { "description": "A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.\n", "properties": { "rate": { "description": "A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.", "oneOf": [ { "$ref": "#/components/schemas/daysConstraint" }, { "$ref": "#/components/schemas/hoursConstraint" }, { "$ref": "#/components/schemas/lifetimesConstraint" } ], "type": "object" } }, "title": "Rate limit constraint", "type": "object", "x-inline-component": true, "x-schema-tag": "Pipeline objects" }, "regionObject": { "description": "A Region object describes a geographical boundary or set of hardware identifiers and associated attributes that correspond to a physical location of relevance to the application or application owner.", "properties": { "attributes": { "description": "An attribute object is an object containing the customer-provided region attributes associated with a particular region.", "type": "object" }, "beacons": { "description": "An array of beacon objects.", "items": { "properties": { "id": { "description": "The hardware ID of the beacon.", "example": "2034071230471204710", "type": "string" }, "name": { "description": "The user-supplied name of the beacon.", "example": "Exhibit A", "type": "string" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "created_at": { "description": "The creation [date-time](/developer/rest-api/ua/introduction/#date-time-format) for the region.", "example": "2018-03-01T12:00:00", "format": "date-time", "type": "string" }, "geofence": { "$ref": "#/components/schemas/geofenceObject" }, "name": { "description": "A human-readable name for the region.", "example": "My Favorite Place", "type": "string" }, "region_id": { "description": "A string containing a UUID that is the canonical identifier for this object, elsewhere referred to as `region_id`.", "example": "abe5deb3-00d0-446e-8c5d-94b6421a01e0", "format": "uuid", "type": "string" }, "source_info": { "description": "A Source Info object is a simple JSON object providing the details about the origin of the region data.", "properties": { "region_id": { "description": "Internal identifier used by source for this region.", "example": "4BPSFLKJSDFLKJSDFLKJ", "type": "string" }, "source": { "description": "Name of the company who originated the region data.", "example": "GIMBAL", "type": "string" }, "vendor_href": { "description": "URI indicating the location of the original source of this region data.", "example": "https://manager.gimbal.com/api/2/places/4BPSFLKJSDFLKJSDFLKJ", "type": "string" } }, "required": [ "source", "region_id" ], "type": "object" }, "updated_at": { "description": "The last updated [date-time](/developer/rest-api/ua/introduction/#date-time-format) for the region.", "example": "2018-03-01T12:00:00", "format": "date-time", "type": "string" } }, "required": [ "region_id", "created_at", "updated_at" ], "title": "Region object", "type": "object", "x-schema-tag": "Regions" }, "removeAttributeObject": { "description": "Remove an existing attribute from the audience.\n", "properties": { "action": { "description": "Indicate that you want to `remove` an attribute from the audience.\n", "enum": [ "remove" ], "type": "string" }, "key": { "description": "The attribute ID for the attribute you want to set. JSON attribute key values must be in format `#`. See [JSON attributes](/guides/audience/attributes/about/#json-attributes) in *About attributes*.", "maxLength": 64, "type": "string" }, "timestamp": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. If you don't enter a timestamp, Airship uses the current time.\n", "format": "date-time", "type": "string" } }, "required": [ "action", "key" ], "title": "Remove attribute", "type": "object", "x-schema-tag": "Attributes", "x-weight": 6 }, "removeAttributesActionItem": { "description": "Removes a channel or contact attribute when a user interacts with the notification.", "properties": { "action": { "enum": [ "remove" ], "type": "string" }, "name": { "description": "The attribute name. To remove a JSON attribute instance, the name must be in `attributeId#instanceId` format where neither part is empty and `instanceId` does not start with a digit.", "type": "string" }, "type": { "description": "Determines whether to target a channel or contact attribute.", "enum": [ "channel", "contact" ], "type": "string" } }, "required": [ "action", "type", "name" ], "title": "Remove attribute action", "type": "object", "x-schema-tag": "Push" }, "requestTokenBasicAuth": { "properties": { "grant_type": { "enum": [ "client_credentials" ], "type": "string" }, "ipaddr": { "$ref": "#/components/schemas/ipaddr" }, "scope": { "$ref": "#/components/schemas/oauthScope", "description": "A list of scopes to which the issued token will be entitled. Scopes can be sent as URL-encoded, space-delimited list (example: `scope=chn%20nu`) or as a list as expected in a query parameter form (example: `scope=chn&scope=nu`)." }, "sub": { "$ref": "#/components/schemas/subject", "description": "A space-delimited set of identifiers for which subjects a token is allowed. An `app` subject is required. Example: `app:`." } }, "required": [ "grant_type", "sub" ], "title": "Request token with Basic Auth", "type": "object", "x-inline-component": true }, "requestTokenWithAssertion": { "properties": { "assertion": { "$ref": "#/components/schemas/assertionJwt", "description": "An encoded JWT that contains the required headers and claims and is signed with the client credentials' private key." }, "grant_type": { "enum": [ "client_credentials" ], "type": "string" } }, "required": [ "grant_type", "assertion" ], "title": "Request token with assertion", "type": "object", "x-inline-component": true }, "resolveAnonymousContactsResponse": { "properties": { "contact_id": { "description": "The resolved Contact ID.\n", "format": "uuid", "type": "string" }, "is_anonymous": { "description": "Specifies whether the Contact is anonymous or not.\n", "type": "boolean" }, "ok": { "description": "Set to `true` when status code is `200`.\n", "type": "boolean" } }, "required": [ "ok", "contact_id", "is_anonymous" ], "title": "Resolve Anonymous Contact response", "type": "object", "x-inline-component": true }, "scheduleObject": { "description": "A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.", "properties": { "localization_ids": { "$ref": "#/components/schemas/localized_ids" }, "name": { "description": "An optional string.", "type": "string" }, "push": { "$ref": "#/components/schemas/pushObject" }, "push_ids": { "$ref": "#/components/schemas/uuidArray", "description": "An array of the push IDs associated with the schedule. The `push_ids` key is set by the server, and so is present in responses but not in creation requests sent from the client. Requests that contain this key will return a `HTTP 400 Bad Request`.", "readOnly": true }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/scheduleSpec" }, { "description": "Recurring schedules allow you to send a message multiple times at a set cadence. This is useful for subscription reminders, birthdays, etc. This is accomplished by adding recurring data to the schedule endpoint.", "properties": { "recurring": { "properties": { "cadence": { "description": "Defines how often the message is to be sent. It consists of the type (unit) and an optional value (count).", "oneOf": [ { "properties": { "count": { "description": "The frequency of messaging corresponding to the `type`. For example, a `count` of 2 results in a message every 2 hours, days, weeks, months, etc. based on the `type` value.", "minimum": 1, "type": "integer" }, "type": { "description": "The unit of measurement for the cadence.", "enum": [ "hourly", "daily", "monthly", "yearly" ], "type": "string" } }, "required": [ "type", "count" ], "title": "Standard Cadence", "type": "object" }, { "properties": { "count": { "description": "The frequency of messaging on the weekly cadence. For example, a `count` of 2 results in a message every 2 weeks.", "minimum": 1, "type": "integer" }, "days_of_week": { "description": "The days of the week on which Airship can send your message.", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": { "enum": [ "weekly" ], "type": "string" } }, "required": [ "type", "count" ], "title": "Weekly Cadence", "type": "object" } ] }, "end_time": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the schedule will end and stop sending messages.", "format": "date-time", "type": "string" }, "exclusions": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) ranges when messages are not sent.", "items": { "oneOf": [ { "properties": { "hour_range": { "description": "The hourly interval exclude from your cadence. Use 24-hour time separated by a dash, example: `\"12-14\"`. Times are inclusive.\n", "example": "12-14", "type": "string" } }, "title": "Hour range", "type": "object" }, { "properties": { "date_range": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) ranges to exclude from your cadence. Separate the start and end date-times with a forward slash (`/`). Date-times are inclusive.\n", "format": "date-time", "type": "string" } }, "title": "Date range", "type": "object" }, { "properties": { "days_of_week": { "description": "The days of the week that you want to exclude from your schedule cadence. Days are inclusive. Airship considers `monday` the beginning of a week.", "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "minItems": 1, "type": "array" } }, "title": "Days of the week", "type": "object" } ] }, "minItems": 1, "type": "array" }, "paused": { "description": "If `true`, the schedule is paused, and will not result in sends at the regularly scheduled `cadence`.", "readOnly": true, "type": "boolean" } }, "required": [ "cadence" ], "type": "object" } }, "title": "Recurring schedule", "type": "object" } ] }, "url": { "description": "The `url` key is set by the server, and so is present in responses but not in creation requests sent from the client.", "format": "url", "readOnly": true, "type": "string" } }, "required": [ "schedule", "push" ], "title": "Schedule object", "type": "object", "x-schema-tag": "Schedules" }, "scheduleSpec": { "description": "The delivery time specified in UTC.", "oneOf": [ { "description": "Scheduled push to be delivered globally at the same moment.", "properties": { "scheduled_time": { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format).", "format": "date-time", "type": "string" } }, "title": "Scheduled time", "type": "object" }, { "description": "Deliver a message at each device's local time. This ensures that users receive your message at the same time of day across all time zones in your app's audience. This feature only works for channels that have a `timezone` tag (or Named Users containing at least one channel with a `timezone` tag). Devices in the audience that do not have a `timezone` tag will not receive your message.\n", "properties": { "local_scheduled_time": { "description": "Alternative to `scheduled_time`. The scheduled device local [date-time](/developer/rest-api/ua/introduction/#date-time-format) to send the notification.\n", "example": "2018-03-01T12:00:00", "format": "date-time", "type": "string" } }, "title": "Local scheduled time", "type": "object", "x-note": "To use Local Time Delivery for App audiences, you must have Analytic Events turned on and integrated into your application. See [Analytics and Reporting](/developer/sdk-integration/mobile/analytics/) for more information.\nA message delivered to local time includes a Delivery by Time Zone section in its message report. See the information in [View Message Detail](/guides/reports/message/#message-detail) in *Message Reports*.\n" }, { "description": "Alternative to `scheduled_time`. Uses predictive analytics to send the notification at the [optimal send time](/guides/features/intelligence-ai/predictive/optimal-send-time/) for each member of your audience.\n\n When your audience includes users without an optimal send time tag, those users will be dropped from delivery and will not receive the message. Since optimal send time is determined from user behavior over time, new users might not have an optimal send time determined for the first week or two after channel registration.\n", "properties": { "best_time": { "description": "Schedules the notification for the optimal send time.\n", "properties": { "send_date": { "description": "The date set by the user for when the push should go out, localized to the time zone for a given channel. Best-time pushes require activation of our predictive analytics toolset.\n", "format": "date", "type": "string" } }, "title": "Best time object", "type": "object" } }, "title": "Best time", "type": "object" } ], "title": "Schedule specification", "type": "object", "x-schema-tag": "Schedules" }, "scheduledBulkSendObject": { "description": "A scheduled bulk send object wraps a [bulk send object](/developer/rest-api/ua/schemas/others/#bulksendobject). It describes when the notification should be sent, an optional name for the notification, and the object defining the notification itself, which must be a bulk send object or [Templated message content](/developer/rest-api/ua/schemas/others/#templatedmessagecontent). The scheduled date must be within 60 days.", "properties": { "name": { "description": "A name for the scheduled push message.", "type": "string" }, "push": { "oneOf": [ { "$ref": "#/components/schemas/bulkSendObject" }, { "$ref": "#/components/schemas/templatedMessageContent" } ] }, "schedule": { "description": "As defined by the [Schedule object](/developer/rest-api/ua/schemas/schedules/#scheduleobject), but only the `scheduled_time` key is valid.", "properties": { "scheduled_time": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when you want to perform your Create and Send operation. Users will receive the notification as soon as possible after the specified date-time.", "format": "date-time", "type": "string" } }, "required": [ "scheduled_time" ], "type": "object" } }, "required": [ "schedule", "push" ], "title": "Scheduled bulk send object", "type": "object", "x-schema-tag": "Bulk sending" }, "scopedBatchItem": { "description": "Contains `scope` and `subscription_lists`.", "properties": { "scope": { "items": { "$ref": "#/components/schemas/scopes" }, "type": "array" }, "subscription_lists": { "$ref": "#/components/schemas/namedUserSubscriptionListsObject" } }, "required": [ "scope", "subscription_lists" ], "title": "Named User scoped batch item", "type": "object", "x-schema-tag": "Subscription Lists" }, "scopes": { "description": "The channel types where membership applies. The `app` scope includes `iOS`, `Android`, and `Amazon` channels.", "enum": [ "app", "web", "email", "sms" ], "title": "Scopes", "type": "string", "x-schema-tag": "Subscription Lists" }, "segment": { "description": "The segment ID.", "properties": { "segment": { "oneOf": [ { "format": "uuid", "type": "string" }, { "$ref": "#/components/schemas/uuidArray" } ] } }, "required": [ "segment" ], "title": "Segment selector", "type": "object", "x-inline-component": true }, "segmentObject": { "description": "A set of audience selection criteria that you can reuse as a `segment`.", "properties": { "criteria": { "description": "Defines the set of devices to send notifications to. `criteria` is a JSON expression containing the same information as the audience selector, including [Event Segmentation](/developer/rest-api/ua/schemas/event-segmentation/). See [Audience selection](/developer/rest-api/ua/schemas/audience-selection/) for more information.", "oneOf": [ { "$ref": "#/components/schemas/compoundSelector" }, { "$ref": "#/components/schemas/atomicSelector" } ], "type": "object" }, "display_name": { "description": "Human readable name for this segment. This will be used in the dashboard.", "example": [ "News but not sports" ], "type": "string" } }, "required": [ "display_name", "criteria" ], "title": "Segment object", "type": "object", "x-inline-component": true }, "sender_id": { "description": "A `sender_id` describes the sender target to apply the keyword action event to. This must be a number the app is already configured to send from. If a sender exists in multiple countries, a country can be specified by prefixing the country code with a colon, e.g., `US:12345`.\n\nThe `sender_id` is composed of two parts:\n* A `sender` stem - Required numeric string.\n* A `country_code` - Optional 2-letter ISO 3166 country code.", "title": "Sender ID", "type": "string" }, "setAttributeObject": { "description": "Add a new attribute, or edit the value of an existing attribute, for the audience.\n", "properties": { "action": { "description": "Indicate that you want to `set` an attribute on the audience.\n", "enum": [ "set" ], "type": "string" }, "key": { "description": "The attribute ID for the attribute you want to set. JSON attribute key values must be in format `#`. See [JSON attributes](/guides/audience/attributes/about/#json-attributes) in *About attributes*.", "maxLength": 64, "type": "string" }, "timestamp": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. If you don't enter a timestamp, Airship uses the current time.\n", "format": "date-time", "type": "string" }, "value": { "description": "The value that you want to set for an attribute. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. You can also set an object, which must be valid JSON or the request will fail.\n", "oneOf": [ { "type": "string" }, { "type": "number" }, { "$ref": "#/components/schemas/attributesValueObject" } ] } }, "required": [ "action", "key", "value" ], "title": "Set Attribute", "type": "object", "x-schema-tag": "Attributes", "x-weight": 5 }, "setAttributesActionItem": { "description": "Sets a channel or contact attribute when a user interacts with the notification.", "properties": { "action": { "enum": [ "set" ], "type": "string" }, "name": { "description": "The attribute name. When `value` is a JSON object, the name must be in `attributeId#instanceId` format where neither part is empty and `instanceId` does not start with a digit.", "type": "string" }, "type": { "description": "Determines whether to target a channel or contact attribute.", "enum": [ "channel", "contact" ], "type": "string" }, "value": { "description": "The attribute value. May be a string, number, or JSON object. See [JSON attributes](/guides/audience/attributes/about/#json-attributes).", "oneOf": [ { "title": "String", "type": "string" }, { "title": "Number", "type": "number" }, { "$ref": "#/components/schemas/attributesValueObject" } ] } }, "required": [ "action", "type", "name", "value" ], "title": "Set attribute action", "type": "object", "x-schema-tag": "Push" }, "shorten_links": { "default": false, "description": "If true, Airship will shorten HTTP/HTTPS links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces `short_link_click` events in the Real-Time Data Stream for each link that a user engages with.\n\nWhen this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with `&`:\n* `?ua-tag-add=tag_group:tag&another_group:tag2` — adds a tag in `tag_group` to the `channel_id`.\n* `?ua-tag-remove=tag_group:tag&another_group:tag2` — removes a tag in `tag group` from the `channel_id`.\n* `?ua-list-add=subscription_list_id` — adds the user's channel to the `subscription list`.\n* `?ua-list-remove=subscription_list_id` — removes the user's channel from the `subscription list`.\n", "type": "boolean", "x-inline-component": true, "x-schema-tag": "Push" }, "sms": { "description": "The payload for a Create and Send operation to SMS channels. When sending to SMS channels, `device_types` must be set to `sms`.", "properties": { "audience": { "oneOf": [ { "$ref": "#/components/schemas/cnsSmsAudienceObject" }, { "properties": { "bulk_id": { "description": "A unique string obtained from the [Create bulk send audience operation](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending.\n", "format": "uuid", "type": "string" } }, "required": [ "bulk_id" ], "type": "object" } ] }, "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "device_types": { "$ref": "#/components/schemas/device_types" }, "notification": { "description": "An `alert` notification or a platform override matching the value in `device types`. A notification with a platform override that does not match your `device_types` will result in a 400 error.", "properties": { "sms": { "oneOf": [ { "$ref": "#/components/schemas/smsOverrideObject" }, { "$ref": "#/components/schemas/smsOverrideWithTemplate" } ] } }, "type": "object" } }, "required": [ "audience", "device_types", "notification" ], "title": "Create and Send to SMS channels", "type": "object", "x-schema-tag": "Create and Send" }, "smsOverrideObject": { "description": "Provides override options when `sms` is one of the `device_types` specified in the payload.", "properties": { "alert": { "description": "Overrides the alert provided at the top level of the notification for SMS channels.\nThe maximum length of an SMS alert is 1,600 characters. The alert will be split into\nmultiple messages by CLX if needed.\n", "maxLength": 1600, "type": "string" }, "expiry": { "description": "The time after which Airship will stop trying to deliver an SMS message. The maximum expiry period is 48 hours; this is also the default expiry period.\n", "oneOf": [ { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format). The timestamp must be within the next 48 hours.", "example": "2018-03-01T12:00:00", "format": "date-time", "type": "string" }, { "description": "Number of seconds from now.", "maximum": 172800, "type": "integer" } ] }, "shorten_links": { "$ref": "#/components/schemas/shorten_links" } }, "title": "SMS platform overrides", "type": "object", "x-schema-tag": "Platform overrides" }, "smsOverrideWithTemplate": { "description": "Notification fields specific to SMS messages with an inline template for use in a [Create and Send](/developer/rest-api/ua/operations/bulk-sending/#createandsend) payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with `{{#operator}}` and end with `{{/operator}}`. For more information, see [Handlebars](/guides/personalization/handlebars/).\n", "properties": { "expiry": { "$ref": "#/components/schemas/expiryObject", "description": "The time after which Airship will stop trying to deliver an SMS push." }, "template": { "description": "Specify a `template_id` created in the Airship UI or use an inline template.", "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "required": [ "template_id" ], "type": "object" }, { "$ref": "#/components/schemas/inlineSmsTemplate" } ] } }, "required": [ "template" ], "title": "SMS notification with template", "type": "object", "x-schema-tag": "Platform overrides with templates" }, "smsTemplatesObject": { "description": "The SMS-specific fields for a template.", "properties": { "alert": { "description": "The SMS content.", "type": "string" } }, "required": [ "alert" ], "title": "SMS content template object", "type": "object", "x-schema-tag": "Content objects" }, "sms_id": { "description": "Selects a single SMS device. The `msisdn` must be `opted_in` to receive notifications.", "properties": { "msisdn": { "description": "The recipient phone number.", "maxLength": 128, "minLength": 1, "type": "string" }, "sender": { "description": "The sender that the app is configured to send SMS messages from.", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "sender", "msisdn" ], "title": "SMS ID selector", "type": "object", "x-inline-component": true }, "sms_sender": { "description": "A long or short code the app is configured to send from. For example, `12345`.", "properties": { "sms_sender": { "oneOf": [ { "maxLength": 16, "minLength": 1, "type": "string" }, { "items": { "maxLength": 16, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array" } ] } }, "required": [ "sms_sender" ], "title": "SMS sender selector", "type": "string", "x-inline-component": true }, "sms_with_optin": { "description": "The request included a valid `opted_in` value. Airship creates a channel that is opted in to your audience.", "properties": { "attributes": { "properties": { "ok": { "description": "If `true`, the attributes were set correctly.", "type": "boolean" } }, "type": "object" }, "channel_id": { "description": "Unique Channel ID for the SMS channel.", "format": "uuid", "type": "string" }, "ok": { "description": "If true, Airship creates a channel value with `opt_in` set to `true`.", "type": "boolean" }, "operation_id": { "$ref": "#/components/schemas/operation_id" }, "tags": { "properties": { "ok": { "description": "If `true`, the tags were set correctly.", "type": "boolean" } }, "type": "object" } }, "title": "New channel with opt-in", "type": "object", "x-inline-component": true }, "sms_without_optin": { "description": "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.", "properties": { "attributes": { "properties": { "ok": { "description": "If `true`, the attributes were set correctly.", "type": "boolean" } }, "type": "object" }, "channel_id": { "description": "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.", "format": "uuid", "type": "string" }, "ok": { "description": "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.", "type": "boolean" }, "operation_id": { "$ref": "#/components/schemas/operation_id" }, "push_id": { "description": "Identifies the message prompting the user to opt in to your audience, sent as a result of a request without an `opted_in` value.", "format": "uuid", "type": "string" }, "status": { "description": "The channel has been created but has not yet opted-in.", "enum": [ "pending" ], "type": "string" }, "tags": { "properties": { "ok": { "description": "If `true`, the tags were set correctly.", "type": "boolean" } }, "type": "object" } }, "required": [ "ok", "operation_id", "channel_id", "status", "push_id" ], "title": "New channel without opt-in", "type": "object", "x-inline-component": true }, "snippetReferences": { "description": "An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: `{{> your_snippet_name }}` to reference the snippet content within a notification or rich message.\n\nSee [Snippets](/guides/personalization/content/snippets/) to see how to create a snippet in the Airship dashboard.\n", "properties": { "snippets": { "description": "An array of snippets that you want to use to personalize your message.", "items": { "properties": { "name": { "description": "The name of the snippet that you set up in the Airship dashboard.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "required": [ "snippets" ], "title": "Snippet references object", "type": "object", "x-note": "Make sure that the location where you are using a snippet supports the content defined in the snippet. For example, an image URL or HTML will not render in a push notification since push notifications only support plain text.\n", "x-schema-tag": "Push" }, "static_list": { "description": "A `static_list` is a subset of your audience defined by a CSV file containing Channel IDs or Named Users.", "example": [ "preferred_customers" ], "properties": { "static_list": { "oneOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "$ref": "#/components/schemas/stringArray" } ] } }, "required": [ "static_list" ], "title": "Static list selector", "type": "object", "x-inline-component": true }, "stringArray": { "example": [ "hello", "world" ], "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "x-inline-component": true }, "style": { "description": "Advanced styles `big text`, `big picture`, and `inbox` are available on Android 4.3+ by adding the `style` to the platform specific notification payload on Android platforms. This object must contain a string field `type` which must be one of `big_picture`, `big_text`, or `inbox`. It may also contain `title` and `summary` override fields.", "properties": { "big_picture": { "description": "If the `type` is set to `big_picture`, then there must also be a `big_picture` string field which contains the URL for an image.", "format": "url", "type": "string" }, "big_text": { "description": "If the `type` is set to `big_text`, then a `big_text` string field must be present with the text to be shown in big text style.", "type": "string" }, "lines": { "description": "An array of strings if the `type` field is set to `inbox`.", "example": [ "line 1", "line 2", "line 3" ], "items": { "description": "If the `type` field is set to `inbox` then a `lines` field should be provided as an array of strings.", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array" }, "summary": { "description": "A string field which will override the summary of the notification.", "type": "string" }, "title": { "description": "A string field which will override the title of the notification.", "type": "string" }, "type": { "enum": [ "big_picture", "big_text", "inbox" ], "type": "string" } }, "required": [ "type" ], "title": "Android and Fire OS styles", "type": "object", "x-inline-component": true, "x-schema-tag": "Push" }, "subject": { "description": "A space-delimited set of identifiers for which subjects a token is allowed. Example: `app:`\n * `app`: May operate on the given app", "title": "Subject", "x-schema-tag": "OAuth" }, "subscriptionConditions": { "description": "Subscription conditions have two possible attributes: `list_name` and `negated`.", "properties": { "list_name": { "description": "The name of the subscription list to be matched.", "type": "string" }, "negated": { "description": "A boolean indicating the condition should match on the absence from the list.", "type": "boolean" } }, "required": [ "list_name" ], "title": "Subscription conditions", "type": "object", "x-schema-tag": "Pipeline objects" }, "subscriptionListAction": { "oneOf": [ { "description": "Alters Subscription List membership for a channel.", "properties": { "action": { "$ref": "#/components/schemas/subscriptionListMutation" }, "list_id": { "$ref": "#/components/schemas/subscriptionListId" }, "type": { "enum": [ "channel" ], "type": "string" } }, "required": [ "list_id", "type", "action" ], "title": "Channel Subscription List action", "type": "object" }, { "description": "Alters subscription list membership for a contact.", "properties": { "action": { "$ref": "#/components/schemas/subscriptionListMutation" }, "list_id": { "$ref": "#/components/schemas/subscriptionListId" }, "scope": { "$ref": "#/components/schemas/scopes" }, "type": { "enum": [ "contact" ], "type": "string" } }, "required": [ "list_id", "type", "action", "scope" ], "title": "Contact subscription list action", "type": "object" } ], "title": "Subscription List action", "type": "object", "x-inline-component": true }, "subscriptionListArray": { "example": [ "strange_facts", "cool_newsletter" ], "items": { "$ref": "#/components/schemas/subscriptionListId" }, "type": "array", "x-inline-component": true }, "subscriptionListId": { "description": "A list ID that contains only alphanumeric characters, underscores, or hyphens.", "example": "90s_rap_videos", "maxLength": 32, "minLength": 1, "title": "List ID", "type": "string", "x-schema-tag": "Subscription Lists" }, "subscriptionListMutation": { "description": "A string representing the membership mutation action to be taken for a given list.", "enum": [ "subscribe", "unsubscribe" ], "title": "Subscription List action", "type": "string", "x-schema-tag": "Subscription Lists" }, "subscriptionListObject": { "properties": { "action": { "$ref": "#/components/schemas/subscriptionListAction" }, "list_id": { "$ref": "#/components/schemas/subscriptionListId" }, "timestamp": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. Server time is used when not present.\n", "format": "date-time", "type": "string" } }, "required": [ "action", "list_id" ], "title": "Subscription List object", "x-schema-tag": "Subscription Lists" }, "subscriptionListResultObject": { "description": "Defines the subscription list result object.", "properties": { "default_opted_in": { "description": "`True` if the audience defined by `scopes` are opted in by default, otherwise `false`.", "type": "boolean" }, "description": { "description": "Description of the subscription list." }, "list_id": { "$ref": "#/components/schemas/subscriptionListId" }, "message_type": { "description": "The message type.", "enum": [ "transactional", "commercial" ], "type": "string" }, "name": { "description": "Human readable name.", "example": "A nice name readable name 1", "type": "string" }, "scopes": { "description": "An array of scopes applicable to the subscription list. Valid scopes are `app`, `web`, `email`, and `sms`.", "items": { "$ref": "#/components/schemas/scopes" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "list_id", "scopes", "default_opted_in" ], "title": "Subscription List result object", "type": "object", "x-schema-tag": "Subscription Lists" }, "subscription_list": { "description": "An single instance or array of subscription list IDs.", "example": [ "monthly_newsletter" ], "properties": { "subscription_list": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/subscriptionListArray" } ] } }, "required": [ "subscription_list" ], "title": "Subscription List selector", "type": "object", "x-inline-component": true }, "subscription_lists": { "description": "An array of Subscription List objects.", "items": { "$ref": "#/components/schemas/subscriptionListObject" }, "title": "Subscription Lists", "type": "array", "x-inline-component": true }, "suppression_state": { "description": "If an email channel is suppressed, the reason for its suppression. Email\nchannels with any suppression state set will not have any delivery to\nthem fulfilled. If a more specific reason is not known, use `imported`.\n", "enum": [ "spam_complaint", "commercial_spam_complaint", "bounce", "imported" ], "type": "string", "x-inline-component": true }, "tag": { "description": "A tag is an arbitrary bit of metadata used for targeting devices. A tag specifier may or may not have an associated group declaration, indicating a `tag group` the tag belongs to, for example, `{\"tag\": \"silver-member\", \"group\": \"loyalty\"}`. If no tag group is specified, the default `device` group is used.", "example": [ { "tag": [ "Federer fan", "Messi fan" ] }, { "group": "Loyalty", "tag": [ "silver", "ten-plus" ] } ], "properties": { "group": { "type": "string" }, "tag": { "oneOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "$ref": "#/components/schemas/stringArray" } ] } }, "required": [ "tag" ], "title": "Tag selector", "type": "object", "x-inline-component": true }, "tagArray": { "description": "An array of tags.", "example": [ "Federer fan", "Messi fan" ], "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 0, "type": "array", "x-inline-component": true }, "tagArrayBig": { "example": [ "Federer fan", "Messi fan" ], "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 1000, "minItems": 0, "type": "array", "x-inline-component": true }, "tagConditions": { "description": "Tag conditions have three possible attributes: `tag_name`, `group`, and `negated`. Tag conditions can be replaced by segmentation conditions, which offer more features. But note that the behavior of tag conditions is slightly different than a segmentation condition using tag selectors when it comes to contacts. Tag conditions evaluate against a combined set of all tags of all channels. Segmentation conditions evaluate against all the channels of a contact individually to see if at least one channel satisfies the condition.", "properties": { "group": { "description": "A tag group. Defaults to `device`.", "type": "string" }, "negated": { "description": "If true, the condition will match on the absence of a tag. If absent or false, the condition will match on the presence of a tag.", "type": "boolean" }, "tag_name": { "description": "The name of the tag the condition will match against.", "type": "string" } }, "required": [ "tag_name" ], "title": "Tag conditions", "type": "object", "x-schema-tag": "Pipeline objects" }, "tagGroupObject": { "additionalProperties": { "$ref": "#/components/schemas/tagArray", "title": "Tag group name" }, "description": "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](/reference/data-collection/device-properties/)\n``ua_`` is a reserved prefix for Airship-specific tag groups.\n\nA 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.", "example": [ { "sports fan": [ "Federer fan", "Messi fan" ] }, { "loyalty_program": [ "silver-member", "ten-plus-years" ] }, { "ua_locale_country": [ "US" ] }, { "ua_locale_language": [ "en" ] } ], "title": "Tag group object", "type": "object", "x-schema-tag": "Tags" }, "tagListMetadataObject": { "description": "Contains all user-specified data when defining a tag list in Airship. Although `add`, `remove`, and `set` are optional, one or more must be present.", "properties": { "add": { "$ref": "#/components/schemas/tagGroupObject", "description": "Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation." }, "description": { "description": "An optional description for the list.", "maxLength": 10000, "minLength": 1, "type": "string" }, "extra": { "additionalProperties": { "example": { "key": "value" }, "type": "string" }, "description": "An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters." }, "name": { "description": "The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]*$", "type": "string" }, "remove": { "$ref": "#/components/schemas/tagGroupObject", "description": "Removes the specified tags from the channel." }, "set": { "$ref": "#/components/schemas/tagGroupObject", "description": "Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed." } }, "required": [ "name" ], "title": "Tag List metadata object", "type": "object", "x-schema-tag": "Tags" }, "tagListResponseObject": { "description": "Contains information (metadata) about the tag list.", "properties": { "add": { "$ref": "#/components/schemas/tagGroupObject", "description": "Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation." }, "channel_count": { "description": "A count of resolved channel identifiers for the last uploaded and successfully processed identifier list. This will always be 0 for attribute lists.", "readOnly": true, "type": "integer" }, "created": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the list was initially created.", "format": "date-time", "readOnly": true, "type": "string" }, "description": { "description": "An optional description for the list.", "maxLength": 1000, "type": "string" }, "error_path": { "description": "If non-empty, indicates that there were errors in the processed CSV file. The value is either an empty string or a URL to download a file describing the errors.", "type": "string" }, "extra": { "additionalProperties": { "example": { "key": "value" }, "type": "string" }, "description": "An optional JSON map of up to 100 key-value (string-to-string) pairs associated with the list. Keys in this object have a 64-character maximum; values can be up to 1,024 characters." }, "last_updated": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the identifiers of the list were last updated successfully.", "format": "date-time", "readOnly": true, "type": "string" }, "name": { "description": "The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.", "maxLength": 64, "minLength": 1, "type": "string" }, "remove": { "$ref": "#/components/schemas/tagGroupObject", "description": "Removes the specified tags from the channel." }, "set": { "$ref": "#/components/schemas/tagGroupObject", "description": "Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed." }, "status": { "description": "A string value representing the state of the list.\n\n* `ready` — The list was processed successfully and is ready for sending.\n* `processing` — The list is being processed.\n* `failure` — There was an error processing the last uploaded list.\n", "enum": [ "ready", "processing", "failure" ], "readOnly": true, "type": "string" } }, "required": [ "name" ], "title": "Tag List response object", "type": "object", "x-schema-tag": "Tags" }, "tagSelector": { "description": "Defines a tag selector.", "oneOf": [ { "properties": { "group": { "description": "The tag group. If you do not specify a group, Airship uses the default `device` tag group; this group is represented by a channel's `tags` array rather than the `tag_groups` object.", "type": "string" }, "tag": { "description": "The tag.", "type": "string" } }, "required": [ "tag" ], "type": "object" }, { "description": "The device tag.", "type": "string" } ], "title": "Tag selector", "x-inline-component": true }, "tagsActionArg": { "properties": { "action": { "description": "Determines whether to add or remove the tags.", "enum": [ "add", "remove" ], "type": "string" }, "group": { "description": "The tag group. Required when `type` is `contact`. When `type` is `channel` and `group` is omitted or set to `device`, the operation targets device tags.", "type": "string" }, "tags": { "description": "The tags to add or remove.", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "type": { "description": "Determines whether to target channel or contact tags.", "enum": [ "channel", "contact" ], "type": "string" } }, "required": [ "type", "action", "tags" ], "title": "Tags action argument", "type": "object", "x-schema-tag": "Push" }, "templateObject": { "description": "A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints.", "properties": { "created_at": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when this template was created.", "format": "date-time", "readOnly": true, "type": "string" }, "description": { "description": "The description for the template.", "type": "string" }, "id": { "description": "The unique ID assigned to this template. Used to retrieve or use the template in other endpoints.", "format": "uuid", "readOnly": true, "type": "string" }, "last_used": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when this template's definition was last used. This attribute cannot template-based specified when the template is created and will only be present when template objects are provided by the template retrieval and template listing endpoints.", "format": "date-time", "readOnly": true, "type": "string" }, "modified_at": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when this template was last modified.", "format": "date-time", "readOnly": true, "type": "string" }, "name": { "description": "The name of the template.", "type": "string" }, "push": { "$ref": "#/components/schemas/templatePushObject" }, "variables": { "description": "An array of variable specifications. Variables can be customized when pushing based on the template.", "items": { "$ref": "#/components/schemas/templateVariableObject" }, "type": "array" } }, "required": [ "name", "variables" ], "title": "Template object", "type": "object", "x-schema-tag": "Personalization template objects" }, "templatePushObject": { "description": "A partial push object describing everything about a push notification, except for the `audience` and `device_types` keys (which are defined in the [Push template payload](/developer/rest-api/ua/schemas/personalization-template-objects/#pushtemplatepayload)) and the `message` key (which is incompatible with templates).", "properties": { "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "in_app": { "$ref": "#/components/schemas/inAppObject" }, "no_throttle": { "default": false, "description": "If true, the push will ignore global throttling rates that have been configured for the application, resulting in delivery as quickly as possible.", "type": "boolean" }, "notification": { "$ref": "#/components/schemas/notificationObject" }, "options": { "description": "A JSON dictionary for specifying non-payload options related to the delivery of the push.", "properties": { "expiry": { "$ref": "#/components/schemas/expiryObject" } }, "type": "object" } }, "title": "Template push object", "type": "object", "x-schema-tag": "Personalization template objects" }, "templateVariableObject": { "description": "A template variable object describes the pieces of your template to override when creating template-based pushes. These are the fields you want to customize when you send a push based on the template.", "properties": { "default_value": { "description": "A default value for the variable. If the key for this variable is not specified in a Template Selector (`substitutions`) when issuing push notifications based on this template, the push will use this value.", "type": "string" }, "description": { "description": "A description of the variable.", "type": "string" }, "key": { "description": "The key used to reference the variable inside the template push. (32 chars, starting and ending with alphanumeric characters, and consisting of alphanumeric characters and underscores).", "maxLength": 32, "minLength": 1, "type": "string" }, "name": { "description": "A friendly name for the variable.", "type": "string" } }, "required": [ "key" ], "title": "Template variables", "type": "object", "x-schema-tag": "Personalization template objects" }, "template_id": { "description": "The ID of a template created in the Airship dashboard or the API. See [Using content templates](/guides/personalization/content/templates/#using-content-templates) for more information.", "format": "uuid", "type": "string", "x-inline-component": true }, "templatedMessageContent": { "description": "Customers may use a template to specify message content instead of using static specification.\nThe request format is consistent with Template Schemes. See description [Platform Override Templates](/developer/rest-api/ua/schemas/platform-overrides-with-templates/).\nAll columns (for CSV) or keys (for JSON) not prefixed with `ua_` are considered merge fields.\nPrefixed columns/keys are not usable in template evaluation. If the value of a delivery variable\nis also needed in the template, the requester should duplicate it into an unprefixed column.\n\nNo verification is done in this API that the provided set of merge values matches the fields\nof the template. Customers using the UI will pass through a step where they'll be alerted\nthat some template field has no matching column in the uploaded CSV. Custom Create and Send\nfields are not limited to strings and can contain numbers, booleans, arrays, hierarchical\nJSON, etc.\n\nMerge fields are allowed to use nested property names in CSV upload\nheaders by using a subset of legal [Handlebars](/guides/personalization/handlebars/) template expression syntax.\n", "properties": { "template": { "oneOf": [ { "$ref": "#/components/schemas/email" }, { "$ref": "#/components/schemas/sms" }, { "$ref": "#/components/schemas/mms" }, { "$ref": "#/components/schemas/open" } ] } }, "title": "Templated message content", "type": "object", "x-schema-tag": "Bulk sending" }, "textAttribute": { "description": "An attribute object with a `TEXT` schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or Named User.", "properties": { "attribute": { "description": "The key for the text attribute that you previously defined in the Airship UI, e.g., `\"item_purchased\"`.", "maxLength": 256, "minLength": 1, "type": "string" }, "operator": { "description": "The operator used to evaluate the attribute expression.", "enum": [ "equals", "contains", "less", "greater", "is_empty" ], "type": "string" }, "value": { "description": "The string you want to match when evaluating the attribute expression, e.g., `\"jeans\"`.", "maxLength": 255, "type": "string" } }, "required": [ "attribute", "operator", "value" ], "title": "Text attribute selector", "type": "object", "x-schema-tag": "Attributes", "x-weight": 10 }, "transactional_opted_in": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive transactional\nemails. Users do not need to opt-in to receive transactional\nemails unless they have previously opted out.\n", "format": "date-time", "type": "string", "x-inline-component": true }, "transactional_opted_out": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive\ntransactional emails.\n", "format": "date-time", "type": "string", "x-inline-component": true }, "triggerRegionSelector": { "$ref": "#/components/schemas/complexEventSelector", "description": "A region selector is an event selector that describes the specific criteria\na region must fulfill in order to qualify as a match (for triggering pipelines).\n\nSupported default scope region keys are currently: `name` (string) and `region_id` (string).\n\nUnder the `source_info` scope, we support the following key: `region_id` (string).\n\nWe also have support for the arbitrary scope `attributes`, which has no key restrictions\nbecause it is user-supplied in its entirety.", "title": "Region selector", "type": "object", "x-inline-component": true }, "triggeredSelector": { "description": "A special selector used in Pipelines to indicate that the audience of the push is composed of the device or devices that activated the trigger. See [Pipeline objects](/developer/rest-api/ua/schemas/pipeline-objects/) for more information.", "enum": [ "triggered" ], "title": "Triggered selector", "type": "string", "x-inline-component": true }, "unauthorizedErrorResponseObject": { "description": "Authentication via the `Authorization` request header failed.", "properties": { "error": { "description": "Error code.", "enum": [ "invalid_client" ], "type": "string" }, "error_description": { "description": "A plain-text description of the error.", "type": "string" } }, "required": [ "error" ], "title": "Unauthorized", "type": "object", "x-inline-component": true }, "uploadCsvResponse": { "description": "The upload CSV response.", "properties": { "bulk_id": { "description": "A unique string that identifies the audience provided in the CSV for bulk sending.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "field_names": { "description": "A list of the field names found in the CSV.", "items": { "type": "string" }, "type": "array" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object", "x-inline-component": true }, "urlArray": { "items": { "format": "uri", "pattern": "^https.*:\\/\\/.+", "type": "string" }, "maxItems": 100, "minItems": 0, "type": "array", "x-inline-component": true }, "urlParametersObject": { "description": "A JSON dictionary of string-to-string key-value pairs as UTM or custom parameters. Each key and value will become a query parameter key and URL-encoded value that are automatically appended to all link URLs in an email. These parameters are used for tracking campaign performance.\n\nIf a query parameter defined in this object already exists in a link, it will not be overwritten in the link. Dynamic values are supported using [Handlebars](/guides/personalization/handlebars/), with limitations. See [URL parameters](/guides/messaging/messages/content/email/email/#url-parameters) in the *Email content* guide for more information.\n", "type": "object", "x-inline-component": true }, "uuidArray": { "example": [ "00256e0b-b02f-4f12-a77f-4c3d57078330", "f59970d3-3d42-4584-907e-f5c57f5d46a1" ], "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "x-inline-component": true }, "uuidArrayBig": { "example": [ "00256e0b-b02f-4f12-a77f-4c3d57078330", "f59970d3-3d42-4584-907e-f5c57f5d46a1" ], "items": { "format": "uuid", "type": "string" }, "maxItems": 1000, "minItems": 1, "type": "array", "x-inline-component": true }, "variantPlatformObject": { "properties": { "direct_responses": { "description": "The number of direct responses (clicks/app opens) to the variant notification on this platform as measured by the SDK.", "type": "integer" }, "influenced_responses": { "description": "The number of opens or clicks resulting from your notification (directly or indirectly).", "type": "integer" }, "sends": { "description": "The total number of audience members that accounted the variant on the specified platform.", "type": "integer" } }, "type": "object", "x-inline-component": true }, "webOverrideObject": { "description": "The `web` platform overrides determine message behaviors\nfor web notifications.\n\nSafari behaves differently from other browsers and supports only the `alert` and `title` overrides. It ignores all other `web` overrides.\n", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "alert": { "description": "Override the alert value provided at the top level, if any.", "type": "string" }, "buttons": { "$ref": "#/components/schemas/buttons" }, "extra": { "$ref": "#/components/schemas/extraObject" }, "icon": { "description": "A JSON object that describes an icon to be used with the notification.", "properties": { "url": { "description": "The URL to be used for the icon.", "type": "string" } }, "required": [ "url" ], "type": "object" }, "image": { "description": "A JSON object that describes an image to be used with the web alert.", "properties": { "url": { "description": "The URL to be used for the image.", "type": "string" } }, "required": [ "url" ], "type": "object" }, "require_interaction": { "description": "If true, a feature that requires a user to interact with the notification in order to remove it from their computer screen.", "type": "boolean" }, "time_to_live": { "$ref": "#/components/schemas/expiryObject", "description": "An integer in seconds or timestamp specifying the expiration time for the message. 0 indicates that the browser delivery service should not store the message (i.e., Now or never delivery). The maximum allowed value is 2419200 seconds (28 days). If a global expiry value has been provided, this will override it." }, "title": { "description": "A string representing the title of the notification.", "type": "string" } }, "title": "Web overrides", "type": "object", "x-note": "Safari supports the `alert` and `title` overrides. It ignores all\nother `web` overrides.", "x-schema-tag": "Platform overrides" }, "webOverrideWithTemplate": { "description": "Use a `template` with a Web-specific message. You can reference a template by ID, or use `{{handlebars}}` directly in your message.\n\nSafari behaves differently from other browsers and supports only the `alert` and `title` overrides. It ignores all other `web` overrides.\n", "properties": { "actions": { "$ref": "#/components/schemas/actionsObject" }, "buttons": { "$ref": "#/components/schemas/buttons" }, "extra": { "$ref": "#/components/schemas/extraObject" }, "icon": { "description": "A JSON object that describes an icon to be used with the notification.", "properties": { "url": { "description": "The URL to be used for the icon.", "type": "string" } }, "required": [ "url" ], "type": "object" }, "image": { "description": "A JSON object that describes an image to be used with the web alert.", "properties": { "url": { "description": "The URL to be used for the image.", "type": "string" } }, "required": [ "url" ], "type": "object" }, "require_interaction": { "description": "If true, a feature that requires a user to interact with the notification in order to remove it from their computer screen.", "type": "boolean" }, "template": { "oneOf": [ { "properties": { "template_id": { "$ref": "#/components/schemas/template_id" } }, "type": "object" }, { "properties": { "external_id": { "$ref": "#/components/schemas/external_id" } }, "type": "object" }, { "properties": { "fields": { "description": "Items in the field object are personalizable with handlebars.", "properties": { "alert": { "description": "Override the alert value provided at the top level, if any.", "type": "string" }, "icon": { "description": "A JSON object that describes a icon to be used with the web alert.", "properties": { "url": { "description": "The URL to be used for the icon.", "type": "string" } }, "required": [ "url" ], "type": "object" }, "title": { "description": "A string representing the title of the notification.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "time_to_live": { "$ref": "#/components/schemas/expiryObject", "description": "An integer in seconds or timestamp specifying the expiration time for the message. 0 indicates that the browser delivery service should not store the message (i.e., Now or never delivery). The maximum allowed value is 2419200 seconds (28 days). If a global expiry value has been provided, this will override it." } }, "title": "Web overrides with template", "type": "object", "x-schema-tag": "Platform overrides with templates" }, "webResponseReport": { "allOf": [ { "$ref": "#/components/schemas/commonSeriesReportResponse" }, { "properties": { "total_counts": { "description": "Array of total count objects, each representing counts within the given [date-time](/developer/rest-api/ua/introduction/#date-time-format) range and precision.", "items": { "properties": { "counts": { "$ref": "#/components/schemas/countsObject" }, "date": { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format) for the count period.", "example": "2018-06-02 10:00:00", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } ], "description": "The response body for web response report.", "x-inline-component": true }, "whereObject": { "description": "`where` is an object that filters on the existence of prior user activity, specified by event properties that you provide.\n", "properties": { "compare_as": { "description": "Selects the property type for comparison.", "enum": [ "text", "number", "date", "boolean" ], "type": "string" }, "operator": { "description": "The operator in question", "enum": [ "greater", "less", "equals", "greater_eq", "less_eq", "contains", "present", "range", "before", "after" ], "type": "string" }, "precision": { "description": "Used only for date values.", "enum": [ "minutes", "days", "months", "years" ], "type": "string" }, "property": { "description": "The custom event property on which to filter for inclusion in the audience. See [Event Segmentation Properties](/guides/audience/events/about/#events-reference) for properties reference.\n", "type": "string" }, "relative_to": { "description": "Used only for date values.", "enum": [ "future", "past" ], "type": "string" }, "value": { "description": "The value of the property you are filtering for in the `where` object. Use `compare_as` to select the type for comparison.\n", "oneOf": [ { "description": "A [date-time](/developer/rest-api/ua/introduction/#date-time-format), e.g., `2020-08-10T17:28:34+0000`.", "format": "date-time", "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "property", "operator", "value" ], "title": "Where object", "type": "object", "x-inline-component": false, "x-schema-tag": "Event segmentation" } }, "securitySchemes": { "basicAppAuth": { "description": "Authorization header containing the word `Basic` followed by a space and a Base64-encoded string generated from your App Key and App Secret in `appKey:appSecret` format. For example, `Basic YXBwX2tleTphcHBfc2VjcmV0`.", "scheme": "basic", "type": "http", "x-display-name": "Basic Auth (App)" }, "basicAuth": { "description": "Authorization header containing the word `Basic` followed by a space and a Base64-encoded string generated from your App Key and Master Secret in `appKey:masterSecret` format. For example, `Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0`.", "scheme": "basic", "type": "http", "x-display-name": "Basic Auth (Master)" }, "basicOauth": { "description": "Authorization header containing the word `Basic` followed by a space and a Base64-encoded string generated from your OAuth Client ID and Client Secret in `client_id:client_secret` format. For example, `Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0`. Used only for requesting OAuth tokens. See [OAuth](/developer/rest-api/ua/operations/oauth/).", "scheme": "basic", "type": "http", "x-display-name": "Basic Auth (OAuth)" }, "bearerAuth": { "description": "Authorization header containing the word `Bearer` followed by a space and a bearer token generated from the Airship dashboard. You can generate tokens for different roles. If your role does not grant you access to a feature, the endpoint will respond with a 401 status code. Tokens can be revoked at will.", "scheme": "bearer", "type": "http", "x-display-name": "Bearer Token" }, "oauth2Token": { "description": "Authorization header containing the word `Bearer` followed by a space and an OAuth 2.0 JWT bearer token provided by our authorization server. See [OAuth](/developer/rest-api/ua/operations/oauth/). Make sure your requests are using the appropriate [domain in the base URL](/developer/rest-api/ua/introduction/#servers).", "flows": { "clientCredentials": { "scopes": { "att": "Attachments", "chn": "Channels", "cnt": "Contacts", "evt": "Events", "lst": "Lists", "nu": "Named Users", "pln": "Pipelines", "psh": "Push", "rmc": "Remote Config", "rpt": "Reports", "sch": "Schedules", "tpl": "Content" }, "tokenUrl": "http://oauth2.{domain}.com/token" } }, "type": "oauth2", "x-display-name": "OAuth 2.0", "x-scope-descriptions": { "att": "Manage attachments for messages and templates.", "chn": "Manage channels and channel data.", "cnt": "Manage contacts and contact lists.", "evt": "Create custom events.", "lst": "Manage lists and list uploads.", "nu": "Manage named users and named user associations.", "pln": "Manage automated message pipelines.", "psh": "Send push notifications and scheduled messages.", "rmc": "Manage remote configuration.", "rpt": "Get report data", "sch": "Manage scheduled messages.", "tpl": "Manage content templates." } } } }, "info": { "description": "\nAirship provides a number of REST API endpoints collectively known as the Airship API\nVersion 3, in support of our messaging product lines and related features. Version 3 is the\ncurrent and only supported version of the Airship API.\n\n## API Request Format\n\nAll API requests are HTTP requests. For all requests with a body, the body may be in [JSON](https://www.json.org/json-en.html)\nformat or other formats like CSV as specified for the endpoint. The proper Content-Type for\nJSON is `application/json` and the proper content type for CSV is `text/csv`.\n\n### Date-Time Format\n\nAll date-time values are represented as a string according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) in UTC.\n\n - The string must be in the format `YYYY-MM-dd['T']hh:mm:ss['Z']` where the `T` can be replaced by a space and the `Z` is optional.\n - A `T` separator is preferred but not required. It will be included in all date-time values generated by the API. For example:\n - 2023-11-13T09:42:30Z\n - 2023-11-13T09:42:30\n - 2023-11-13 09:42:30Z\n - 2023-11-13 09:42:30\n - A trailing time zone identifier or offset should not be included.\n - UTC is implicit.\n\n### Color Format\nAll color values are represented by a string format reminiscent of CSS color values used for web programming. The format is `#rrggbb`,\na literal `#` character followed by 6 hexadecimal digits representing 3 values in the range `00` to `FF`. The values are red,\ngreen, and blue color components.\n\n## API Response Format\n\nAll API responses are HTTP responses, making use of appropriate HTTP response codes. When a body is present,\nit SHALL be in [JSON](https://www.json.org/json-en.html) format, except in certain cases where reporting data MAY be returned in CSV format.\nThe body of all JSON responses SHALL consist of a single JSON object, which SHALL contain a boolean `ok` attribute indicating overall success or failure.\nWhen a request results in a return value containing multiple entities, they SHALL be contained in an array-valued attribute, the name of which MAY vary by endpoint.\nFor example, `/api/tag` will return a list of tags in the `tags` attribute, while `/api/schedules` will return a list of schedules in the `schedules` attribute.\nThe name of the response object attribute containing the list of returned entities SHALL be contained in the Data-Attribute HTTP header.\n\n### Operation ID\nAll API calls that create or modify resources, or cause side effects, SHALL generate an operation ID. An operation ID is an opaque unique string\nthat identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs.\nFor example, the batch push API call can be used to send multiple pushes in one call. Each push has a unique push ID, but they will all share a common operation ID.\nThis enables roll-ups of multiple related operations (such as push to local time or push to language) and better end-to-end tracing in the push pipeline.\nOperation IDs are returned in the JSON body of the response, in the `operation_id` attribute of the root response object.\nAn operation ID will be generated even for error responses.\n\n### Response Codes\nThe API makes use of standard HTTP response codes, with standard HTTP semantics. Response codes in the 200 range indicate success.\nCodes in the 400 range indicate errors of a correctable nature. Codes in the 500 range indicate system errors.\n\nThis table lists general response definitions. Refer to the actual response definition per endpoint.\n\n| Response code | Description |\n|---|---|\n| **200 OK** | The payload was accepted. |\n| **201 Created** | An API request to create a new entity or entities was successful, and the entities were created. |\n| **202 Accepted** | An API request was successfully accepted into a processing queue to be processed later. |\n| **204 No Content** | An entity was successfully deleted. |\n| **400 Bad Request** | Parsing or validating the request failed. |\n| **401 Unauthorized** | Authentication information (the app key and secret) was either incorrect or missing. |\n| **403 Forbidden** | Authentication was correct, but the user does not have permission to access the requested API. This can happen if a feature is not included in the user's Airship plan. |\n| **404 Not Found** | A request was made for a non-existent entity. |\n| **405 Method Not Allowed** | A request was made using an HTTP method not supported by the endpoint. For example, sending a DELETE to /api/schedules. |\n| **406 Unacceptable** | The client requested a version of the API that cannot be satisfied, because no compatible version is currently deployed. |\n| **409 Conflict** | An entity could not be updated due to state conflict. |\n| **429 Too Many Requests** | A request was denied because the app made too many requests to an API in a short period of time. |\n\n### Validation\nAll requests must be validated. Proper validation at the API level can prevent invalid pushes from using resources in our delivery pipeline\nand educate API users about their own mistakes without involving Support. In the event of an error processing the request, the response body\nwill contain one or more [error objects](/developer/rest-api/ua/schemas/responses). Parsing errors, arising from syntactically invalid JSON, should return\nan `HTTP 400 Bad Request` response. Semantic errors, arising from requests that are syntactically valid but otherwise malformed\n(for example, missing required fields), should return an `HTTP 400` response, with a JSON body indicating details about the validation failure.\n\nSome examples of specific validation cases that cause pushes to be rejected with an `HTTP 400` error:\n- **Invalid attributes** — Any additional JSON keys that are not explicitly allowed by the spec will result in an HTTP 400 error,\n except where arbitrary keys are explicitly allowed (for example, the `extra` sections of a push payload).\n- **Unconfigured open platform** — Any open platform specified in the `device_types` array must be configured and active for the appKey.\n If the open platform is not configured, we will return an `HTTP 400`.\n- **Missing payload** — A push that specifies delivery to a platform but does not supply a payload for that platform is invalid.\n- **Device identifier/restriction mismatch** — A push that includes a device identifier in the audience selection\n but does not include the corresponding platform in the `device_types` specifier is invalid.\n- **Schedule times** — Requests to schedule pushes for times that have already passed will return an HTTP 400 response. However,\n requests to schedule local time pushes for a time that has elapsed in a local time zone will be accepted.\n- **Unsupported platform feature** — A push that includes features not supported on all platforms must explicitly target the supported platforms.\n Location is the only feature not supported across all platforms. This includes location expressions in predefined segments.\n Location pushes must specify `device_types` : [ `ios`, `android` ], or either iOS or Android explicitly.\n\n### Pagination\nSome resource collections, such as tags and segments, may have a very large number of items, necessitating iterating through them\nin chunks (or pages) if an API consumer wishes to retrieve them all.\n\n**Request Parameters**\n\nThere are two methods for pagination results:\n- `start` and `limit`\n- `page` and `page_size`\n\nUsing a non-unique identifier for the `start` parameter is unsound and will not paginate correctly. For endpoints that support sorting,\nif sorting is applied to a non-unique field, a secondary sort on a unique field must be used internally to ensure stable pagination results.\n\n- `start` — Optional string or integer. Identifies the starting element for paginating results. It can be either a unique string identifier or a zero-based offset, depending on the API.\n- `limit` — Optional integer. The maximum number of elements to return.\n- `page` — Optional integer. Specifies which page to retrieve, starting with 1.\n- `page_size` — Optional integer. The number of elements to return per page. The last page may have fewer elements.\n- `sort` — Optional string. The name of the field to sort results by. This is not necessarily supported by all endpoints.\n- `order` — Optional `asc` or `desc`. If the `sort` parameter is available, this parameter may be used to specify the direction of the sort as ascending or descending.\n\n**Link Header**\n\nCollections of entities SHALL be paginated by specifying a start point and a limit on the number of returned items as parameters of the request.\nThe response SHALL include the requested items and a link to the next page of results. A link to the previous page MAY also be included if the underlying service\nsupports it. For example, the [Segments API](/developer/rest-api/ua/operations/segments/) supports previous page links. The links SHALL be provided in the `Link` HTTP header, as per\n[RFC 5988 Web Linking](https://datatracker.ietf.org/doc/html/rfc5988.html), using the relations `next` and `prev`.\n\n**Count and Total**\n\nThe number of items in the response SHALL be returned in the custom HTTP header `Count`, as well as in the `\"count\"` field of the response object.\nThe total number of items in the collection MAY be returned in the custom HTTP header `Total-Count`, as well as in the `\"total_count\"`\nfield of the response object, if the collection is countable and the total number of items is known.\n\n## Version Syntax\n\nYou must specify the version of the API you are using with the `Accept` HTTP header.\nIf you do not specify an API version in the `Accept` header, a 406 is returned.\n\nThe content type used is a vendor-specific media type\n(see [RFC 4288 Media Type Specifications and Registration Procedures](https://tools.ietf.org/html/rfc4288)) and must be specified as: `application/vnd.urbanairship+json; version=3`.\n\n## Transport Layer Security\n\nAs of October 6, 2020, Airship supports only Transport Layer Security (TLS) versions 1.2 and 1.3 in our APIs, in accordance with [PCI Security Standards Council](https://www.pcisecuritystandards.org/) recommendations.\n\nIf your API integration uses TLS 1.0 or 1.1, [contact our Support team](https://support.airship.com) for assistance migrating to TLS 1.2 or 1.3.\n\n### Certificate Pinning\n\nCertificate chains for Airship domains cannot be considered static. You should never pin or hardcode Intermediate or Root Certificate Authorities. Airship may rotate certificate chains at any time without notice, and pinning can cause service disruptions. This applies to all Airship-owned domains, not only the REST APIs.\n\n## Delivery Speed Options\n\nThe Airship push API is designed for extremely high throughput to ensure\ndelivery to your entire audience as fast as possible. Depending on the size and/or\ncomplexity of your audience and the urgency of the message, you may find that you need to either\nslow down or speed up the delivery. To that end, we offer the following add-on\nservices: Boost and Throttling.\n\nIf you are interested in enabling Boost or Throttling, [contact Support](https://support.airship.com/).\n\n### Boost\n\nBoost optimizes your segmented messages through parallel processing. Consider adding\nBoost if your notifications are extremely time-sensitive. Boost is a paid add-on. Contact\nyour Account Manager for details.\n\n### Throttling\n\nFor less time-sensitive messages, our standard delivery speed may cause undue pressure\non your internal systems or APIs, for example, when millions of users open your app at the\nsame time. Use Throttling to tune\ndelivery to a level that doesn't put strain on those systems.\n\n### Complex segments can cause delays in processing\n\nWhen creating segments or pushes with logical expressions, keep in mind that one or more NOT statements may cause latency when sending notifications,\nas NOT operations are inherently more expensive to perform than OR or AND operations.\nFor example, `tag_a AND NOT tag_b` is basically the same speed as\n`tag_a AND tag_b`, but just `NOT tag_b` is likely to be slower than just\n`tag_b`.\n\nLatency is more significant with larger audiences. We recommend using AND statements in place of NOT statements whenever possible as a best practice.\n\n### Device changes can take a few minutes\n\nSome requests to register or unregister information about a device may take a few minutes to process before you are able to see the changes.\nKeep this in mind when performing PUT or POST requests.\n", "title": "Airship API", "version": "V3" }, "openapi": "3.0.0", "paths": { "/api/attachments": { "post": { "description": "Create attachments by `POST`ing to the attachments URI. The body of the request must be a JSON object describing and including the contents of a file to attach.\n", "operationId": "createEmailAttachment", "requestBody": { "content": { "application/json": { "example": { "content_type": "text/plain; charset=\"UTF-8\"", "data": "{{base64-encoded_data}}", "filename": "{{email_filename}}" }, "schema": { "properties": { "content_type": { "description": "The mimetype of the uploaded file including the charset parameter, if needed. Example: `\"text/plain; charset=\\\"UTF-8\\\"\"`\n", "maxLength": 100, "type": "string" }, "data": { "description": "Base64-encoded bytes of the file contents representing a maximum of 2.5 MiB of data when decoded. Padding with `=` chars is optional.\n", "type": "string" }, "filename": { "description": "The name of the uploaded file (max 255 UTF-8 bytes). Multiple files with the same name are allowed in separate requests.\n", "type": "string" } }, "required": [ "filename", "content_type", "data" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "description": "The response body for an email attachment creation request.", "properties": { "attachment_id": { "description": "The attachment ID for a newly-created attachment. Reference this ID in the `attachments` list in the [Email overrides](/developer/rest-api/ua/schemas/platform-overrides/#emailoverrideobject).", "items": { "type": "string" }, "type": "array" }, "ok": { "description": "Either `true` or `false`. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.", "type": "boolean" } }, "type": "object" } } }, "description": "The email attachment was created. The response body will contain the IDs of the created attachments." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "The application does not have the proper entitlement to create attachments." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "att" ] } ], "summary": "Create email attachment", "tags": [ "Email" ], "x-important": "* Attachments can be used for `transactional` sends only, not `commercial`.\n\n* Attachments cannot be used in Automations.\n\n* Attachment size is limited to 2.5 MB per attachment, with a 20 MB content size limit on each message, including content body and all attachments.\n\n* Attachment count is limited to 10 per email.\n\n* Sending attachments with malicious content is strictly prohibited. This is enforced in part by blocking file types with .bat and .exe extensions.\n\n* Attachments have a TTL (Time To Live) of 60 days.\n" } }, "/api/attribute-lists": { "get": { "description": "Retrieve information about all attributes lists. This call returns a list of metadata that will not contain the actual lists of users.", "operationId": "getAttributeListMetadata", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "lists": { "description": "An array of list objects.", "items": { "$ref": "#/components/schemas/listObject" }, "type": "array" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "Lists metadata retrieved successfully." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Retrieve lists", "tags": [ "Attribute Lists" ] }, "post": { "description": "Create an attributes list with a name, description, and optional metadata. After creating the list, populate it with a CSV of Text, Number, or Date attribute data using the [Upload attributes list](/developer/rest-api/ua/operations/attribute-lists/#uploadattributelist) endpoint.", "operationId": "createAttributeList", "requestBody": { "content": { "application/json": { "examples": { "snapshot": { "summary": "Snapshot Mode List", "value": { "description": "Snapshot attribute list example", "extra": { "filename": "attributesList.csv", "source": "CRM" }, "name": "ua_attributes_snapshot_my_new_list" } }, "standard": { "summary": "Standard Mode List", "value": { "description": "Standard attribute list example", "extra": { "filename": "attributesList.csv", "source": "CRM" }, "name": "ua_attributes_my_new_list" } } }, "schema": { "$ref": "#/components/schemas/attributeListMetadataObject" } } }, "required": true }, "responses": { "201": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The list was created successfully.", "headers": { "Location": { "description": "The URI of the list, used for later updates.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400", "description": "Malformed JSON payload." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g., the API may not be used to create or modify lists with a `ua_` prefixed name." }, "409": { "$ref": "#/components/responses/409", "description": "The app has reached the maximum number of allowed lists (error_code 40906). A list with that name already exists (error_code 40907). List is already processing recently uploaded CSV (error_code 40910)." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Create attributes list", "tags": [ "Attribute Lists" ] } }, "/api/attribute-lists/{list_name}/csv": { "parameters": [ { "description": "The `name` of the list you want to upload.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "put": { "description": "Upload a CSV to set Text, Number, or Date attribute values on the specified channels or Named Users.\n\nCSV guidelines:\n- The first entry in the uploaded CSV must be a header row. The first field must be one of the following identifier types: `channel_id`, `msisdn`, `email_address`, or `named_user`.\n- Only one identifier type is allowed per file unless the identifier type name matches a custom attribute schema for the associated app key.\n- You must include both `msisdn` and `sms_sender` columns when targeting SMS or MMS channel types. See example to the right.\n- Uploads must be newline-delimited identifiers (text/CSV) as described in RFC 4180, with commas as the delimiter, optionally double-quoted values, UTF-8 encoded, and with CRLF or LF line separators.\n\nRequired column headers per identifier type:\n\n| Target type | Required column headers |\n|------------------|------------------------------------------------------------------------------------------|\n| iOS | `channel_id` |\n| Android | `channel_id` |\n| Named User | `named_user` |\n| Web | `channel_id` |\n| Email | `email_address` |\n| Open Channel | `channel_id` |\n| SMS |
  • `msisdn` (numeric and no leading 0)
  • `sms_sender` (numeric, e.g., `1234`)
|\n| MMS |
  • `msisdn` (numeric and no leading 0)
  • `sms_sender` (numeric, e.g., `1234`)
|\n\nOptional Fields: Opt-in dates can optionally be set for new channels\nwhen the identifier is an `email_address` or `msisdn`.\n\n| Target type | Optional column headers |\n|-----------------|------------------------------------------------------------------------------------------|\n| SMS | `ua_opted_in` (UTC Timestamp) |\n| MMS | `ua_opted_in` (UTC Timestamp) |\n| Email |
  • `ua_transactional_opted_in` (UTC Timestamp)
  • `ua_commercial_opted_in` (UTC Timestamp)
|\n", "operationId": "uploadAttributeList", "requestBody": { "content": { "text/csv": { "schema": { "example": [ "C:/Users/someUser/Downloads/weekly_offers.csv" ], "format": "binary", "type": "string" } } }, "required": true }, "responses": { "202": { "$ref": "#/components/responses/202", "description": "The list was uploaded successfully and is now being processed." }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Bad Request. Parsing or validating the request failed.\n\n| Error code | Description |\n|---|---|\n| 40002 | CSV contains too many identifiers |\n| 40003 | CSV header contains too many columns |\n| 40013 | CSV header's first field must be an identifier |\n| 40014 | CSV header contains an unknown attribute name |\n| 40015 | CSV header contains duplicate attribute names |\n| 40017 | CSV header contains duplicate column names |\n| 40018 | CSV header does not contain required column for identifier type |\n" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "The API may only be used to create or modify lists with either a `ua_attributes_` or `ua_attributes_snapshot_` prefixed name." }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Upload attributes list", "tags": [ "Attribute Lists" ], "x-note": "A list can contain a maximum of 10 million rows and 101 columns: one identifier column and 100 attribute or internal header columns. `Content-Encoding: gzip` is supported and recommended on this endpoint to reduce network traffic.", "x-warning": "If your upload times out due to a poor connection, you must re-upload the list from scratch. Because we want to ensure that the entirety of a given list is successfully uploaded, we do not support partial list uploads." } }, "/api/attribute-lists/{list_name}/errors": { "get": { "description": "During processing, after a list is uploaded, errors can occur. Depending on the type of list processing, an error file may be created, showing a user exactly what went wrong.", "operationId": "getAttributeListErrors", "parameters": [ { "description": "The name of the list.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/listObject" } } }, "description": "The response will contain the errors found during list processing." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists or the list has not yet successfully processed an uploaded CSV." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Download list errors", "tags": [ "Attribute Lists" ] } }, "/api/bulk-send": { "post": { "description": "Send an immediate message to existing channels using a `bulk_id`. Inactive channels are dropped. Before calling this endpoint, obtain a `bulk_id` from the [Create bulk send audience](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) endpoint.\n", "operationId": "bulkSendPush", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulkSendObject" } } }, "description": "A Send a message with bulk ID payload." }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/pushAccepted" } } }, "description": "The push notification has been accepted for processing. The response contains `push_id`, `message_id`, and/or `content_url` arrays based on the type of push." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "406": { "$ref": "#/components/responses/406" }, "413": { "$ref": "#/components/responses/413", "description": "The request included a payload larger than the maximum size of 5 MiB." }, "429": { "$ref": "#/components/responses/429", "description": "There were too many similar requests in a short amount of time." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "psh" ] } ], "summary": "Send message with bulk ID", "tags": [ "Bulk Sending" ] } }, "/api/bulk-send/validate": { "post": { "description": "Accept the same range of payloads as POSTing to [`/api/bulk-send`](/developer/rest-api/ua/operations/bulk-sending/#bulksendpush), but parse and validate only, without sending any messages. Before calling this endpoint, obtain a `bulk_id` using the [Create bulk send audience](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) operation.", "operationId": "validateBulkSendPush", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulkSendObject" } } }, "description": "A single bulk send object." }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The payload was valid." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "406": { "$ref": "#/components/responses/406" }, "413": { "$ref": "#/components/responses/413", "description": "The request included a payload larger than the maximum size of 5 MiB." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "psh" ] } ], "summary": "Validate message with bulk ID", "tags": [ "Bulk Sending" ] } }, "/api/bulk/{platform_name}": { "parameters": [ { "description": "The audience channel platform. For open platforms, format the `{platform_name}` as `open/{open_platform_name}`.\n", "in": "path", "name": "platform_name", "required": true, "schema": { "enum": [ "android", "amazon", "ios", "web", "sms", "email", "open_platform_name" ], "type": "string" } } ], "post": { "description": "Upload a CSV to obtain a `bulk_id` for sending messages. The CSV can contain:\n- Channel IDs for Upload and Send endpoints: [Send message with bulk ID](/developer/rest-api/ua/operations/bulk-sending/#bulksendpush) or [Schedule message with bulk ID](/developer/rest-api/ua/operations/bulk-sending/#schedulebulksendpush)\n- Email addresses, phone numbers, or Open channel addresses for Create and Send endpoints: [Create and Send a message](/developer/rest-api/ua/operations/bulk-sending/#createandsend) or [Schedule a Create and Send message](/developer/rest-api/ua/operations/bulk-sending/#schedulecreateandsendoperations)\n\nSee [Bulk sending](/guides/audience/segmentation/bulk-sending/) for CSV formatting requirements.\n", "operationId": "bulkUploadCreateAndSendPlatform", "requestBody": { "content": { "text/csv": { "schema": { "description": "A CSV of Channel IDs, email addresses, MSISDNs, or Open channel addresses. See [Bulk sending](/guides/audience/segmentation/bulk-sending/) for CSV formatting requirements.\n", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/uploadCsvResponse" } } }, "description": "The CSV was uploaded successfully and is now being processed." }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Bad Request. Parsing or validating the request failed.\n" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] } ], "summary": "Create bulk send audience", "tags": [ "Bulk Sending" ] } }, "/api/channels": { "get": { "description": "List all channels registered to this app key, along with associated data and metadata.", "operationId": "getChannels", "parameters": [ { "description": "The default limit is 1,000 channel objects returned per request. Set the limit to 1,000 or fewer in your API calls.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 1000, "type": "integer" } } ], "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "channels": { "description": "An array of channel objects.", "items": { "$ref": "#/components/schemas/channelListingObject" }, "type": "array" }, "next_page": { "description": "If there is more than one page of results, use this link to get the next page of results.", "example": "https://go.urbanairship.com/api/channels?limit=1000&start=535ec31e-4b07-4b26-bead-a1c0e94e133c", "format": "url", "type": "string" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "Returns OK for success with the JSON response. Tags added to a channel using `/named_users/tags` are not returned from this endpoint. To view those tags, you must look up the Named User associated with the channel.", "headers": { "Link": { "schema": { "description": "Provides the URL to the current page of results. The query within the URL contains the `limit` (the number of results on the page) and `start` (the first `channel_id` in the result set) parameters.", "example": "; rel=\"next\"", "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Channel listing", "tags": [ "Channels" ], "x-note": "Tags added to a channel via the [Named Users tag endpoint](/developer/rest-api/ua/operations/tags/#modifynamedusertags) will not appear with a request to this endpoint. To view those tags, you must [look up the Named User](/developer/rest-api/ua/operations/named-users/#getnameduser) associated with the channel.\n" } }, "/api/channels/attributes": { "post": { "description": "Set or remove attributes on a channel. Aside from Airship's [default attributes](/reference/data-collection/attributes/#default-attributes), you must [define attributes in the Airship dashboard](/guides/audience/attributes/adding/) before you can set them on channels.\n", "operationId": "modifyChannelAttributes", "requestBody": { "content": { "application/json": { "example": { "attributes": [ { "action": "set", "key": "major_league", "value": "sf_giants" }, { "action": "remove", "key": "minor_league" }, { "action": "set", "key": "position", "value": "LF" } ], "audience": { "android_channel": "{{android_channel}}" } }, "schema": { "description": "Include an audience object and an array of attributes objects in your request.", "properties": { "attributes": { "$ref": "#/components/schemas/attributesObject" }, "audience": { "description": "The channel(s) you want to set or remove attributes for.", "properties": { "amazon_channel": { "$ref": "#/components/schemas/amazon_channel" }, "android_channel": { "$ref": "#/components/schemas/android_channel" }, "channel": { "$ref": "#/components/schemas/channel" }, "email_address": { "$ref": "#/components/schemas/uuidArray", "description": "The unique channel identifier used to target an email address." }, "ios_channel": { "$ref": "#/components/schemas/ios_channel" }, "sms_id": { "$ref": "#/components/schemas/sms_id" }, "web_channel": { "$ref": "#/components/schemas/uuidArray", "description": "The unique channel identifier used to target a web device." } }, "type": "object" } }, "required": [ "audience", "attributes" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, your request was successful.", "type": "boolean" }, "warning": { "description": "Alerts you if your request could not be processed. You may receive a 200 with a warning if you provide a `value` that does not match your attribute type. For example, an attribute that expects a numeric value will allow a value of \"25\" but fail if you input \"twenty-five\".\n", "type": "string" } }, "type": "object" } } }, "description": "The operation was successful." }, "400": { "$ref": "#/components/responses/400", "description": "Parsing or validating the request failed." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAppAuth": [] }, { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Set or remove attributes on channels", "tags": [ "Channels" ], "x-important": "Use the [Named Users endpoint](/developer/rest-api/ua/operations/named-users/#modifynameduserattributes) to set or remove attributes on Named Users.\n" } }, "/api/channels/email": { "post": { "description": "Create a new email channel or update an existing channel. If you provide the email address of an existing channel, the call is treated as a PUT.\nTo update the address of an existing channel, see the [Replace Email Channel](/developer/rest-api/ua/operations/email/#replaceemailchannel) endpoint.", "operationId": "registerEmailChannel", "requestBody": { "content": { "application/json": { "example": { "channel": { "address": "{{email_address}}", "commercial_opted_in": "{{today_date_time}}", "locale_country": "US", "locale_language": "en", "timezone": "America/Los_Angeles", "type": "email" } }, "schema": { "$ref": "#/components/schemas/emailChannelObject" } } }, "description": "A single email channel object." }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "description": "The response body for an email channel request.", "properties": { "attributes": { "properties": { "ok": { "description": "If `true`, the attributes were set correctly.", "type": "boolean" } }, "type": "object" }, "channel_id": { "description": "A unique string identifying the email channel.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "ok": { "description": "If `true`, the operation was successful. If `false`, other properties defined here will not necessarily be present.", "type": "boolean" }, "tags": { "properties": { "ok": { "description": "If `true`, the tags were set correctly.", "type": "boolean" } }, "type": "object" } }, "required": [ "ok" ], "type": "object" } } }, "description": "An existing email channel was found matching the address and was\nupdated.\n" }, "201": { "content": { "text/plain": { "schema": { "description": "The response body for an email channel request.", "properties": { "channel_id": { "description": "A unique string identifying the email channel.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "ok": { "description": "Either `true` or `false`. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.", "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The email channel was created.", "headers": { "Location": { "description": "The newly created email channel.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Register email channel", "tags": [ "Email" ], "x-note": "Channel creation is asynchronous, so when associating a newly created channel, both a Channel ID and a device type are required to prevent \"channel does not exist\" errors." } }, "/api/channels/email/custom-unsubscribe": { "get": { "description": "Opts-out an email address using a custom unsubscribe token. Requires [Custom Unsubscribe](/developer/api-integrations/email/custom-unsubscribe-pages/) be enabled for your project.\n\nThis endpoint is public and does not require authentication.", "operationId": "customUnsubscribeEmailChannel", "parameters": [ { "description": "The token for the unsubscribe request.", "in": "query", "name": "ua_unsubscribe_token", "required": true, "schema": { "type": "string" } }, { "description": "URL of the page to redirect to after unsubscribe. A default confirmation page will be used if not provided.", "in": "query", "name": "ua_redirect", "required": false, "schema": { "format": "uri", "type": "string" } } ], "responses": { "302": { "description": "The channel was successfully opted out and will be redirected to a confirmation page.", "headers": { "Location": { "description": "URL of the page to redirect to after unsubscribe.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" } }, "summary": "Custom unsubscribe email channel", "tags": [ "Email" ] } }, "/api/channels/email/replace/{channel_id}": { "post": { "description": "Creates a new email channel in place of the provided channel. You may\nuse this endpoint to change a contact's email address. When called with\nan email channel, this endpoint will:\n\n* Register a new channel\n* Associate the new email channel with the same user as the source channel\n* Uninstall the source channel", "operationId": "replaceEmailChannel", "parameters": [ { "description": "The email `channel_id` you want to modify.", "in": "path", "name": "channel_id", "required": true, "schema": { "example": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "channel": { "address": "{{email_address}}", "commercial_opted_in": "{{today_date_time}}", "locale_country": "US", "locale_language": "en", "timezone": "America/Los_Angeles", "type": "email" } }, "schema": { "$ref": "#/components/schemas/emailChannelObject" } } }, "description": "A single email channel object." }, "responses": { "201": { "content": { "text/plain": { "schema": { "description": "The response body for an email channel request.", "properties": { "channel_id": { "description": "A unique string identifying the email channel.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "ok": { "description": "Either `true` or `false`. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.", "type": "boolean" } }, "type": "object" } } }, "description": "The operation was successful.", "headers": { "Location": { "description": "The newly created email channel.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Replace email channel", "tags": [ "Email" ] } }, "/api/channels/email/suppress": { "post": { "description": "Suppress an existing email channel, disallowing any future delivery from being fulfilled for the channel.\n", "operationId": "suppressEmailChannel", "requestBody": { "content": { "application/json": { "example": { "address": "{{email_address}}", "reason": "spam_complaint" }, "schema": { "properties": { "address": { "description": "The email address for the channel to be suppressed.", "example": "user@example.com", "type": "string" }, "reason": { "description": "The reason for suppressing the channel. If there is no specific reason, use `imported`.", "enum": [ "spam_complaint", "commercial_spam_complaint", "bounce", "imported" ], "example": "spam_complaint", "type": "string" } }, "required": [ "address", "reason" ], "type": "object" } } } }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "Returns OK for success." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404", "description": "Returned if no channel was found associated to the specified `address`." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Suppress an email channel", "tags": [ "Email" ], "x-note": "Suppression state types that only apply to commercial messages, such as `commercial_spam_complaint`, cannot overwrite suppression state types that also apply to transactional messages." } }, "/api/channels/email/tags": { "post": { "description": "Add, remove, or set tags for a single email channel.", "operationId": "modifyEmailChannelTags", "requestBody": { "content": { "application/json": { "example": { "add": { "{{tag_group_1}}": [ "tag1", "tag2", "tag3" ], "{{tag_group_2}}": [ "tag1", "tag2", "tag3" ], "{{tag_group_3}}": [ "tag1", "tag2", "tag3" ] }, "audience": { "email_address": "{{email_address}}" } }, "schema": { "properties": { "add": { "$ref": "#/components/schemas/tagGroupObject", "description": "Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation." }, "audience": { "description": "Specifies the email address you want to perform tag operations against. Must contain a single `email_address` key.", "maxProperties": 1, "properties": { "email_address": { "description": "The email address you want to modify tags for. Accepts a single string value representing an email address.", "example": "name@example.com", "type": "string" } }, "required": [ "email_address" ], "type": "object" }, "remove": { "$ref": "#/components/schemas/tagGroupObject", "description": "Removes the specified tags from the channel." }, "set": { "$ref": "#/components/schemas/tagGroupObject", "description": "Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed." } }, "required": [ "audience" ], "type": "object" } } }, "description": "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.", "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "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." }, "400": { "$ref": "#/components/responses/400", "description": "Bad Request. Parsing or validating the request failed. If a tag is present in both the add and remove fields, a HTTP 400 response will be returned." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g., the app does not permit associations from the device. Secure tag groups require master secret to modify tags, otherwise a 403 Forbidden response is returned." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Email tags", "tags": [ "Email", "Tags" ], "x-important": "A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response.\nWe support up to 1,000 tags per channel. Adding more than 1,000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using custom events when appropriate. Please [contact Support](https://support.airship.com/) if you believe your use case requires more than 1,000 tags per channel, and they will help you find an alternative." } }, "/api/channels/email/uninstall": { "post": { "description": "**Removes an email address from Airship. Use with caution.** If the uninstalled email address opts-in again, it might generate a new channel_id. If a user generates a new `channel_id` when they opt-in again, the new `channel_id` cannot be reassociated with any opt-in information, tags, Named Users, Performance Analytics reports, or other information from the that belonged to the previously-uninstalled email channel.", "operationId": "uninstallEmailChannel", "requestBody": { "content": { "application/json": { "example": { "email_address": "{{email_address}}" }, "schema": { "properties": { "email_address": { "description": "The email address of the channel to uninstall.", "example": "name@example.com", "type": "string" } }, "required": [ "email_address" ], "type": "object" } } }, "description": "An email address of the channel to uninstall." }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "Returns OK for success." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Uninstall email channel", "tags": [ "Email" ] } }, "/api/channels/email/unsuppress": { "post": { "description": "Remove the suppression reason for an existing email channel, allowing the channel to receive emails, depending on the channel's commercial and transactional opt-in status.\n", "operationId": "unsuppressEmailChannel", "requestBody": { "content": { "application/json": { "example": { "address": "{{email_address}}" }, "schema": { "properties": { "address": { "description": "The email address for the channel to be unsuppressed.", "example": "user@example.com", "type": "string" } }, "required": [ "address" ], "type": "object" } } } }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "Returns OK for success." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404", "description": "Returned if no channel was found associated to the specified `address`." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Remove suppression from an email channel", "tags": [ "Email" ], "x-important": "Calling this endpoint will not modify commercial or transactional opt-in status to opted-in." } }, "/api/channels/email/{email}": { "get": { "description": "Returns a channel by email address. For security, email addresses are one-way hashed and aren't returned when you look up a channel by ID. Use this endpoint to find a channel belonging to a particular email address.\n\n\nYou may need to escape the `@` character in URLs using`%40`.\n", "operationId": "getEmailChannel", "parameters": [ { "description": "The email address of the channel you want to look up.", "in": "path", "name": "email", "required": true, "schema": { "example": "name@example.com", "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "channel": { "$ref": "#/components/schemas/channelListingObject" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "A channel exists for the email address" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Look up an email address", "tags": [ "Email" ], "x-note": "Emails with an `opted_out` date that is after or equal to the `opted_in` date will not be sent for that channel.\n\nA `commercial_opted_in` date is required for sending commercial emails. Transactional emails do not require a `transactional_opted_in`. This field is used in the case where a user has unsubscribed to transactional email and would like to reassert consent to receive transactional emails.\n\nThe `opt_in` property is always set to true for an email channel, so it should be ignored." }, "put": { "description": "Update an email channel. You can use this endpoint to update the subscription/unsubscription values.\n", "operationId": "updateEmailChannel", "parameters": [ { "description": "The email `channel_id` you want to modify.", "in": "path", "name": "email", "required": true, "schema": { "example": "251d3318-b3cb-4e9f-876a-ea3bfa6e47bd", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "channel": { "address": "{{email_address}}", "commercial_opted_out": "{{today_date_time}}", "type": "email" } }, "schema": { "$ref": "#/components/schemas/emailChannelUpdateObject" } } } }, "responses": { "200": { "content": { "text/plain": { "schema": { "description": "The response body for an email channel request.", "properties": { "channel_id": { "description": "A unique string identifying the email channel.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "ok": { "description": "Either `true` or `false`. Represents if the operation completed successfully or not. If false, other properties defined here will not necessarily be present.", "type": "boolean" } }, "type": "object" } } }, "description": "The email channel was updated.", "headers": { "Location": { "description": "The updated email channel.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Update an email channel", "tags": [ "Email" ], "x-important": "If you provide an `address` in this request, it must be the one that is associated with the channel you are updating. You may not update the user's email address with this endpoint." } }, "/api/channels/open": { "post": { "description": "Create a new open channel or update an existing open channel.\n", "operationId": "createOrUpdateOpenChannel", "requestBody": { "content": { "application/json": { "example": { "channel": { "address": "Number Four", "locale_country": "US", "locale_language": "en", "open": { "identifiers": { "model": "4" }, "open_platform_name": "cylon" }, "opt_in": true, "tags": [ "toaster", "caprica" ], "timezone": "America/Los_Angeles", "type": "open" } }, "schema": { "properties": { "channel": { "description": "Properties of the open channel object.", "properties": { "address": { "description": "Where notifications sent to this `channel_id` will be sent. Examples: email address, phone number. If missing, `channel_id` must be present. The `address` is one-to-one with the `channel_id`. New addresses on existing channels will overwrite old associations.", "example": "+1 5558675309", "type": "string" }, "locale_country": { "description": "The two-letter country locale short code. Will set the `ua_locale_country` tag group to the specified value.", "example": "US", "type": "string" }, "locale_language": { "description": "The two-letter language locale short code. Will set the `ua_locale_language` tag group to the specified value.", "type": "string" }, "open": { "description": "Open channel-specific properties.", "properties": { "identifiers": { "additionalProperties": { "type": "string" }, "description": "Optional object with string-to-string key:value pairs that represent non-segmentable identifiers for the channel in your delivery systems. Delivered as part of webhook payloads. If present, the value will overwrite (not union with) existing identifier records.", "example": { "baz": "lurhmann", "foo": "bar" }, "maxItems": 100, "type": "object" }, "open_platform_name": { "description": "The name of the open platform to which you are registering this channel.", "example": [ "slack" ], "type": "string" } }, "required": [ "open_platform_name" ], "type": "object" }, "opt_in": { "description": "If false, no payloads will be delivered for the channel.", "type": "boolean" }, "tags": { "description": "A list of strings used for audience targeting. When used for this endpoint, operates like the `tags { set {}}` operation; specified tags are applied, and all other tags are removed.", "example": [ "one_tag", "two_tag", "red_tag", "blue_tag" ], "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 1000, "minItems": 1, "type": "array" }, "timezone": { "description": "An IANA tzdata identifier for the time zone as a string, e.g., `\"America/Los_Angeles\"`. Will set the `timezone` tag group tag with the specified value.", "example": "America/Los_Angeles", "type": "string" }, "type": { "description": "Required string.", "enum": [ "open" ], "type": "string" } }, "required": [ "type", "opt_in", "open", "address" ], "type": "object" } }, "required": [ "channel" ], "type": "object" } } }, "description": "An open channel object." }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "channel_id": { "description": "Identifies the new open channel or the open channel you successfully updated.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "Returned if the new channel is created successfully or if an existing channel was found for the specified open_platform_name and address.", "headers": { "Location": { "description": "Used for later API calls for this channel.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Register new or update channel", "tags": [ "Open Channels" ], "x-important": "The master secret is required to update an open channel, otherwise a 401 Unauthorized response is returned.", "x-note": "A 200 status will be returned if an existing channel was found for the specified `open_platform_name` and address. Otherwise, a new channel will be created and a 200 status will be returned.\n" } }, "/api/channels/open/tags": { "post": { "description": "Manipulate a single open channel's tags. Open channels are identified by `address`, not by their `channel_id`.", "operationId": "modifyOpenChannelTags", "requestBody": { "content": { "application/json": { "example": { "add": { "my_fav_tag_group1": [ "tag1", "tag2", "tag3" ], "my_fav_tag_group2": [ "tag1", "tag2", "tag3" ], "my_fav_tag_group3": [ "tag1", "tag2", "tag3" ] }, "audience": { "address": "Number Four", "open_platform_name": "cylon" } }, "schema": { "description": "Add, remove, or set tags on a channel. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.", "properties": { "add": { "$ref": "#/components/schemas/tagGroupObject", "description": "Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation." }, "audience": { "$ref": "#/components/schemas/openChannelIdentifier" }, "remove": { "$ref": "#/components/schemas/tagGroupObject", "description": "Removes the specified tags from the channel." }, "set": { "$ref": "#/components/schemas/tagGroupObject", "description": "Assigns a list of tags exactly. Any previously set tags that are not in this current list will be removed." } }, "required": [ "audience" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 is 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." }, "400": { "$ref": "#/components/responses/400", "description": "Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Open channel tags", "tags": [ "Open Channels", "Tags" ], "x-important": "A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response.\nWe support up to 1,000 tags per channel. Adding more than 1,000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using custom events when appropriate. Please [contact Support](https://support.airship.com/) if you believe your use case requires more than 1,000 tags per channel, and they will help you find an alternative." } }, "/api/channels/open/uninstall": { "post": { "description": "Uninstall a channel needing to know its Channel ID. You cannot send notifications to, or get channel information for, an uninstalled channel.\n", "operationId": "uninstallOpenChannels", "requestBody": { "content": { "application/json": { "example": { "address": "Number Four", "open_platform_name": "cylon" }, "schema": { "$ref": "#/components/schemas/openChannelIdentifier" } } }, "description": "An `address` and the `open_platform_name` you want to uninstall the address from." }, "responses": { "202": { "$ref": "#/components/responses/202" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Uninstall open channels", "tags": [ "Open Channels" ] } }, "/api/channels/sms": { "post": { "description": "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.\n\nSMS 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.\n", "operationId": "registerSmsChannel", "requestBody": { "content": { "application/json": { "example": { "locale_country": "US", "locale_language": "en", "msisdn": "{{sms_msisdn}}", "opted_in": "2020-02-13T11:58:59", "sender": "{{sms_sender}}", "timezone": "America/Los_Angeles" }, "schema": { "properties": { "attributes": { "description": "An optional object containing the customer-provided attributes associated with the SMS channel.", "type": "object" }, "locale_country": { "description": "The ISO 3166 two-character country code. The value for this field becomes a tag in the `ua_locale_country` tag group.", "type": "string" }, "locale_language": { "description": "The ISO 639-1 two-character language code. The value for this field becomes a tag in the `ua_locale_language` tag group.", "type": "string" }, "msisdn": { "description": "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.", "maxLength": 15, "pattern": "^[0-9]*$", "type": "string" }, "opted_in": { "description": "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.", "format": "date-time", "type": "string" }, "sender": { "$ref": "#/components/schemas/sms_sender" }, "tag_operations": { "$ref": "#/components/schemas/tagGroupObject", "description": "Optionally one or more tag group objects associated with the SMS channel." }, "timezone": { "description": "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.", "type": "string" } }, "required": [ "msisdn", "sender" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/sms_with_optin" }, { "$ref": "#/components/schemas/sms_without_optin" } ] } } }, "description": "A channel with this msisdn/sender combination already exists." }, "201": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/sms_with_optin" }, { "$ref": "#/components/schemas/sms_without_optin" } ] } } }, "description": "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.", "headers": { "location": { "description": "URI of the channel, used for later registrations.", "schema": { "format": "url", "type": "string" } } } }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "errors": { "description": "Returned with 40x responses; explains reason for the unsuccessful request.", "example": "Unable to retrieve details for sender 12345 with app_key ", "type": "string" }, "ok": { "description": "If false, the request was unsuccessful.", "type": "boolean" } }, "type": "object" } } }, "description": "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." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Register SMS channel", "tags": [ "SMS" ], "x-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." } }, "/api/channels/sms/opt-out": { "post": { "description": "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.\n", "operationId": "optOutSmsChannel", "requestBody": { "content": { "application/json": { "example": { "msisdn": "{{sms_msisdn}}", "sender": "{{sms_sender}}" }, "schema": { "properties": { "msisdn": { "description": "The mobile phone number you want to opt-out of SMS messages. Must be numeric characters only, without leading zeros. 15 digits maximum.", "maxLength": 15, "pattern": "^[0-9]*$", "type": "string" }, "sender": { "$ref": "#/components/schemas/sms_sender" } }, "required": [ "msisdn", "sender" ], "type": "object" } } } }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, the operation completed successfully.", "type": "boolean" } }, "type": "object" } } }, "description": "The msisdn/channel is opted-out of SMS notifications." }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "details": { "properties": { "error": { "description": "Specific error message that explains why the request was unsuccessful.", "type": "string" } }, "type": "object" }, "error": { "description": "Returned with 40x responses; explains why the request was unsuccessful.", "type": "string" }, "error_code": { "description": "The 5-digit Airship error code, pointing to a more specific error than the HTTP status.", "type": "integer" }, "ok": { "description": "If false, the request was unsuccessful.", "type": "boolean" } }, "type": "object" } } }, "description": "The request body is not valid." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Opt-out of SMS messages", "tags": [ "SMS" ] } }, "/api/channels/sms/tags": { "post": { "description": "Add, remove, or set tags for a single SMS channel.", "operationId": "modifySmsChannelTags", "requestBody": { "content": { "application/json": { "example": { "add": { "{{tag_group_1}}": [ "tag1", "tag2", "tag3" ], "{{tag_group_2}}": [ "tag1", "tag2", "tag3" ], "{{tag_group_3}}": [ "tag1", "tag2", "tag3" ] }, "audience": { "msisdn": "{{msisdn}}", "sender": "{{sender}}" } }, "schema": { "properties": { "add": { "$ref": "#/components/schemas/tagGroupObject", "description": "Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation." }, "audience": { "description": "Specifies the MSISDN and sender you want to perform tag operations against.", "maxProperties": 1, "properties": { "msisdn": { "description": "The mobile phone number corresponding to the SMS channel. Must be numeric characters only, without leading zeros. 15 digits maximum.", "maxLength": 15, "pattern": "^[0-9]*$", "type": "string" }, "sender": { "$ref": "#/components/schemas/sms_sender" } }, "required": [ "msisdn, sender" ], "type": "object" }, "remove": { "$ref": "#/components/schemas/tagGroupObject", "description": "Removes the specified tags from the channel." }, "set": { "$ref": "#/components/schemas/tagGroupObject", "description": "Assigns a list of tags exactly. Any previously set tags that are not in this current list are removed." } }, "required": [ "audience" ], "type": "object" } } }, "description": "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.", "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "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." }, "400": { "$ref": "#/components/responses/400", "description": "Bad Request. Parsing or validating the request failed. If a tag is present in both the add and remove fields, a HTTP 400 response will be returned." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g., the app does not permit associations from the device. Secure tag groups require master secret to modify tags, otherwise a 403 Forbidden response is returned." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "SMS tags", "tags": [ "SMS", "Tags" ], "x-important": "A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response.\nWe support up to 1,000 tags per channel. Adding more than 1,000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using custom events when appropriate. Please [contact Support](https://support.airship.com/) if you believe your use case requires more than 1,000 tags per channel, and they will help you find an alternative." } }, "/api/channels/sms/uninstall": { "post": { "description": "**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.\n", "operationId": "uninstallSmsChannel", "requestBody": { "content": { "application/json": { "example": { "msisdn": "{{sms_msisdn}}", "sender": "{{sms_sender}}" }, "schema": { "properties": { "msisdn": { "description": "The mobile phone number you want to remove from the Airship system. Must be numeric characters only, without leading zeros. 15 digits maximum.", "maxLength": 15, "pattern": "^[0-9]*$", "type": "string" }, "sender": { "$ref": "#/components/schemas/sms_sender" } }, "required": [ "msisdn", "sender" ], "type": "object" } } } }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, the operation was successful.", "type": "boolean" } }, "type": "object" } } }, "description": "The SMS channel and all information associated with the msisdn is uninstalled." }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "details": { "properties": { "error": { "description": "Specific error message that explains why the request was unsuccessful.", "type": "string" } }, "type": "object" }, "error": { "description": "Returned with 40x responses; explains why the request was unsuccessful.", "type": "string" }, "error_code": { "description": "The 5-digit Airship error code, pointing to a more specific error than the HTTP status.", "type": "integer" }, "ok": { "description": "If false, the request was unsuccessful.", "type": "boolean" } }, "type": "object" } } }, "description": "The request body is not valid." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Uninstall SMS channel", "tags": [ "SMS" ] } }, "/api/channels/sms/{channel_id}": { "parameters": [ { "description": "The identifier for the SMS channel you want to update.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string" } } ], "put": { "description": "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.\n", "operationId": "updateSmsChannel", "requestBody": { "content": { "application/json": { "example": { "locale_country": "US", "locale_language": "en", "msisdn": "{{sms_msisdn}}", "opted_in": "2020-02-13T11:58:59", "sender": "{{sms_sender}}", "timezone": "America/Los_Angeles" }, "schema": { "properties": { "locale_country": { "description": "The ISO 3166 two-character country code. The value for this field becomes a tag in the `ua_locale_country` tag group.", "type": "string" }, "locale_language": { "description": "The ISO 639-1 two-character language code. The value for this field becomes a tag in the `ua_locale_language` tag group.", "type": "string" }, "msisdn": { "description": "The phone number corresponding to the `channel_id` in the request. You cannot change this value for the existing channel.", "maxLength": 15, "pattern": "^[0-9]*$", "type": "string" }, "opted_in": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) that represents when explicit permission was received from the user to receive messages.", "format": "date-time", "type": "string" }, "sender": { "description": "The sender corresponding to the `channel_id` in the request. You cannot change this value for an existing channel.", "type": "string" }, "timezone": { "description": "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.", "type": "string" } }, "required": [ "msisdn", "sender" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "True if the request was successful.", "type": "boolean" }, "operation_id": { "$ref": "#/components/schemas/operation_id" } }, "type": "object" } } }, "description": "The SMS channel was updated successfully." }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "errors": { "description": "Returned with 40x responses; explains reason for the unsuccessful request.", "example": "Unable to retrieve details for sender 12345 with app_key ", "type": "string" }, "ok": { "description": "If false, the request was unsuccessful.", "type": "boolean" } }, "type": "object" } } }, "description": "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\nor mismatching `msisdn` or `sender`, the `msisdn` is not a valid E.164 standard MSISDN, or invalid timezone/locale values are supplied.\n" }, "404": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "errors": { "description": "A plain-text explanation of the error.", "type": "string" }, "ok": { "description": "If false, your request was unsuccessful.", "type": "boolean" } }, "type": "object" } } }, "description": "Occurs when the `msisdn` and/or `sender` don't match any existing `channel_id`." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Update SMS channel", "tags": [ "SMS" ] } }, "/api/channels/sms/{msisdn}/{sender}": { "get": { "description": "Lookup an SMS channel by `msisdn` and `sender`.", "operationId": "getSmsChannel", "parameters": [ { "description": "The mobile phone number you want to look up a channel for. 15 digits maximum; may not contain leading zeroes.", "in": "path", "name": "msisdn", "required": true, "schema": { "maxLength": 15, "pattern": "^[0-9]*$", "type": "integer" } }, { "description": "A long or short code the app is configured to send from.", "in": "path", "name": "sender", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "channel": { "$ref": "#/components/schemas/channelListingObject" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "Returns an SMS channel object. An SMS channel object includes tag groups for `ua_channel_type`,\n`ua_sender_id`, and `ua_opt_in`.\n" }, "404": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "error": { "description": "Returned with 40x responses; explains why the request was unsuccessful.", "type": "string" }, "error_code": { "description": "The 5-digit Airship error code, pointing to a more specific error than the HTTP status.", "type": "integer" }, "ok": { "description": "If false, the request was unsuccessful.", "type": "boolean" } }, "type": "object" } } }, "description": "A `channel_id` does not exist for the `msisdn` and `sender`." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "SMS channel lookup", "tags": [ "SMS" ] } }, "/api/channels/subscription_lists": { "post": { "description": "Subscribe or unsubscribe channels to/from Subscription Lists.\n", "operationId": "modifyChannelSubscriptions", "requestBody": { "content": { "application/json": { "example": { "audience": { "channel": [ "{{ios_channel}}" ], "email_address": [ "tommy@example.com", "nick@example.com" ] }, "subscription_lists": [ { "action": "subscribe", "list_id": "exciting_news" }, { "action": "unsubscribe", "list_id": "animal_facts" } ] }, "schema": { "allOf": [ { "$ref": "#/components/schemas/audienceSelector100" }, { "$ref": "#/components/schemas/subscription_lists" } ], "description": "The request payload must be a JSON object with the following fields." } } } }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "Returns OK for success." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAppAuth": [] }, { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Subscribe or unsubscribe channels to/from subscription lists", "tags": [ "Channels" ], "x-important": "You must first [create a subscription list in the dashboard](/guides/audience/segmentation/audience-lists/subscription/#creating-a-list), then you can refer to its ID when subscribing users. When subscribing users, if the list has not already been created in the dashboard, then the list will be created at the same time but will not be accessible from the dashboard; the list will available for API use only.", "x-note": "If you are using a single-channel Preference Center created before October 10, 2022, that has not been [migrated to user-level](/guides/messaging/features/preference-centers/#migrating-to-a-user-level-preference-center), use the [`/api/channels/subscription_lists` endpoint](/developer/rest-api/ua/operations/channels/#modifychannelsubscriptions) to add or remove individual channels to/from your subscription list. Otherwise, use the [Scoped Named User batch operations endpoint](/developer/rest-api/ua/operations/named-users/#performnameduserscopedbatchoperations) to do so.\n" } }, "/api/channels/tags": { "post": { "description": "Add, remove, or set tags on a channel.", "operationId": "modifyChannelTags", "requestBody": { "content": { "application/json": { "example": { "add": { "{{tag_group_1}}": [ "tag1", "tag2", "tag3" ], "{{tag_group_2}}": [ "tag1", "tag2", "tag3" ], "{{tag_group_3}}": [ "tag1", "tag2", "tag3" ] }, "audience": { "android_channel": "{{android_channel}}", "ios_channel": "{{ios_channel}}" } }, "schema": { "description": "A single request body may contain add and/or remove objects or a single set object. At least one of the add, remove, or set objects must be present in a request.", "properties": { "add": { "$ref": "#/components/schemas/tagGroupObject", "description": "Adds the specified tags to the channel. Tags that are already present are not modified/removed as a result of this operation." }, "audience": { "description": "Specifies one or more channels that you want to apply tag operations to.", "properties": { "amazon_channel": { "$ref": "#/components/schemas/uuidArrayBig", "description": "The unique channel identifier for a Fire OS device." }, "android_channel": { "$ref": "#/components/schemas/uuidArrayBig", "description": "The unique channel identifier for an Android device." }, "channel": { "$ref": "#/components/schemas/uuidArrayBig", "description": "The unique channel identifier for `email`, `sms`, `open`, or `web` device types." }, "ios_channel": { "$ref": "#/components/schemas/uuidArrayBig", "description": "The unique channel identifier for an iOS device." } }, "type": "object" }, "remove": { "$ref": "#/components/schemas/tagGroupObject", "description": "Removes the specified tags from the channel." }, "set": { "$ref": "#/components/schemas/tagGroupObject", "description": "Assigns a list of tags exactly. Any previously set tags that are not in this current list will be removed." } }, "required": [ "audience" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, your request was processed normally.", "type": "boolean" }, "warnings": { "description": "Returned when some tag groups could not be updated. Contains a string indicating each tag group that could not be updated and the reason the update failed.", "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Returns OK for success. If a tag request is partially valid, i.e., at least one tag group exists and is active, a 200 is 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." }, "400": { "$ref": "#/components/responses/400", "description": "Bad Request. Parsing or validating the request failed. You will get this error if a tag is present in both the add and remove fields." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "Returned in cases when the app does not permit associations from the device. Secure tag groups require master secret to modify tags." } }, "security": [ { "basicAppAuth": [] }, { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Channel tags", "tags": [ "Channels", "Tags" ], "x-important": "A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response.\nWe support up to 1,000 tags per channel. Adding more than 1,000 tags per channel can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using custom events when appropriate. Please [contact Support](https://support.airship.com/) if you believe your use case requires more than 1,000 tags per channel, and they will help you find an alternative." } }, "/api/channels/uninstall": { "post": { "description": "Uninstalls a channel, removing it and all accompanying analytic data (including Performance Analytics) from Airship systems in accordance with data privacy law compliance.\n\nUninstallation is handled automatically by the Airship SDK and push systems. If a user decides to opt in to communications again (either by using your app or other user preferences), they will create a new channel and a new set of analytic data.\nThe value of a Channel ID may be the same as before however none of the associated metadata will persist when a user opts in again. A new Channel ID will be created if the user clears their browser’s cookies and data, deletes and reinstalls the app, etc.\n\nSee [Individual Data Privacy Rights Under Data Privacy Laws](/guides/audience/privacy/individual-data-privacy/) for more information about data privacy law compliance.", "operationId": "uninstallChannels", "requestBody": { "content": { "application/json": { "example": [ { "channel_id": "{{ios_channel}}", "device_type": "ios" }, { "channel_id": "{{android_channel}}", "device_type": "android" } ], "schema": { "items": { "description": "Specifies the Channel ID and device type you want to uninstall.", "properties": { "channel_id": { "description": "The Channel ID.", "example": "bd36e8c7-5a73-47c0-9716-99fd3d4197d5", "type": "string" }, "device_type": { "description": "The device type of the channel.", "enum": [ "ios", "android", "amazon", "web", "open" ], "type": "string" } }, "required": [ "channel_id", "device_type" ], "type": "object" }, "maxItems": 1000, "minItems": 1, "type": "array" } } } }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "Returns OK for success." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Uninstall channels", "tags": [ "Channels", "Data Privacy Laws Compliance" ], "x-note": "Channel uninstallation, like channel creation, is an asynchronous operation and may take some time to complete." } }, "/api/channels/{channel_id}": { "get": { "description": "Fetch an individual channel registered to the app key, along with associated data and metadata.", "operationId": "getChannel", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "channel": { "description": "A channel object.", "oneOf": [ { "$ref": "#/components/schemas/channelListingObject" }, { "$ref": "#/components/schemas/openChannelObject" } ] }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "Tags added to a channel using `/named_users/tags` are not returned from this endpoint. To view those tags, you must look up the Named User associated with the channel." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAppAuth": [] }, { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "chn" ] } ], "summary": "Channel lookup", "tags": [ "Channels" ], "x-note": "Tags added to a channel via the [Named Users tag endpoint](/developer/rest-api/ua/operations/tags/#modifynamedusertags) will not appear with a request to this endpoint. To view those tags, you must [look up the Named User](/developer/rest-api/ua/operations/named-users/#getnameduser) associated with the channel.\n" }, "parameters": [ { "description": "The unique channel identifier.", "in": "path", "name": "channel_id", "required": true, "schema": { "type": "string" } } ] }, "/api/contacts/associate": { "post": { "description": "Associate a channel, email address, or MSISDN with a Contact. The `contact_id` is created if it does not already exist.", "operationId": "associateContact", "requestBody": { "content": { "application/json": { "example": { "channel_id": "{{ios_channel}}", "device_type": "ios" }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/channelIdContactIdAssociation" }, { "$ref": "#/components/schemas/emailAddressContactIdAssociation" } ] } } }, "description": "Contact association requires a `channel_id`, `email_address`, or `msisdn`. Do not provide more than one identifier type in the same request. You can associate up to 100 Channel IDs to a Contact. Channel creation is asynchronous, so when associating a newly created channel, both a Channel ID and a device type are required to prevent \"channel does not exist\" errors.", "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The request was accepted. The `contact_id` is returned in the response." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "oauth2Token": [ "cnt" ] } ], "summary": "Contact association", "tags": [ "Contacts" ], "x-note": "If the `channel_id`, `email_address`, or `msisdn` is already associated with a `contact_id`, this operation will do nothing and return a 200 status code and the existing `contact_id`." } }, "/api/contacts/attributes": { "post": { "description": "Set or remove attributes on a Contact.\n\nA single request body may contain a `set` or `remove` field, or both, or a single `set` field. If both `set` and `remove` fields are present and the intersection of the attributes in these fields is not empty, then a `400` will be returned.\n\nIf an attribute request is partially valid, i.e., at least one attribute exists, Airship returns a `200` with a warning about the attributes that failed to update.\nThe attributes listed in the `warnings` string will be in CSV format.\n", "operationId": "modifyContactAttributes", "requestBody": { "content": { "application/json": { "example": { "attributes": [ { "action": "set", "key": "firstName", "timestamp": "2020-09-19 12:00:00", "value": "Gyuri" }, { "action": "remove", "key": "birthDate", "timestamp": "2020-09-19 12:00:00" }, { "action": "set", "key": "lastName", "timestamp": "2020-09-19 12:00:00", "value": "Pataki" } ] }, "schema": { "description": "Include an array of attributes objects in your request.", "items": { "$ref": "#/components/schemas/attributesObject" }, "type": "array" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contactAttributesModificationResponse" } } }, "description": "Success. If an attribute request is partially valid, i.e., at least one attribute exists,\nAirship returns a `200` with a warning string containing a CSV list of attributes that failed to update. Airship also returns a `200` with a warning if you attempt to set attributes on a `contact_id`, even if the `contact_id` does not exist.\n" }, "400": { "$ref": "#/components/responses/400" } }, "security": [ { "oauth2Token": [ "cnt" ] } ], "summary": "Set or remove attributes on a Contact", "tags": [ "Contacts" ], "x-note": "Airship returns a `200` with a warning if you attempt to set attributes on a Contact that does not exist.\n", "x-tip": "If you wish to set attributes on multiple Contact at once, we recommend\nusing [/api/channels/attributes](/developer/rest-api/ua/operations/channels/#modifychannelattributes) which\nsupports an `audience` object in the request body.\n" } }, "/api/contacts/disassociate/{contact_id}": { "post": { "description": "Disassociates channel from a Contact with the option of also opting out. You can identify a channel by MSISDN, email address, or Channel ID.", "operationId": "disassociateContact", "parameters": [ { "description": "The Contact ID to disassociate from a channel.", "in": "path", "name": "contact_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "channel_id": { "description": "The Channel ID to disassociate from the Contact.", "example": "{{channel_id}}", "format": "uuid", "type": "string" }, "channel_type": { "description": "The type of channel.", "enum": [ "sms", "email", "ios", "android", "amazon", "web", "open" ], "type": "string" }, "email_address": { "description": "The email address to disassociate from the Contact.", "type": "string" }, "msisdn": { "description": "The mobile phone number to disassociate from the Contact. Must be numeric characters only, without leading zeros. 15 digits maximum.", "maxLength": 15, "pattern": "^[0-9]*$", "type": "string" }, "opt_out": { "description": "Optional. True if the channel is to be opted out; otherwise false.", "type": "boolean" }, "sender": { "$ref": "#/components/schemas/sms_sender" } }, "required": [ "channel_type" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "channel_id": { "description": "Identifies the existing unique Channel ID.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "contact": { "description": "Identifies the existing unique Contact ID.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "The request was accepted." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "oauth2Token": [ "cnt" ] } ], "summary": "Contact disassociation", "tags": [ "Contacts" ] } }, "/api/contacts/identify/v2": {}, "/api/contacts/lookup/channel/{channel_id}": { "get": { "description": "Looks up a Contact ID for the given Channel ID.\n", "operationId": "getContactIdFromChannelId", "parameters": [ { "description": "The Channel ID for which to retrieve the associated Contact ID.", "in": "path", "name": "channel_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolveAnonymousContactsResponse" } } }, "description": "The request was accepted." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "cnt" ] } ], "summary": "Look up Contact ID by Channel ID", "tags": [ "Contacts" ] } }, "/api/contacts/lookup/named_user/{named_user_id}": { "get": { "description": "Looks up a Contact ID for the given Named User ID.\n", "operationId": "getContactIdFromNamedUserId", "parameters": [ { "description": "The URL-encoded Named User ID for which to retrieve the associated Contact ID.", "in": "path", "name": "named_user_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/identifyAnonymousContactResponse" } } }, "description": "The request was accepted." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "cnt" ] } ], "summary": "Look up Contact ID by Named User ID", "tags": [ "Contacts" ] } }, "/api/contacts/scoped/{contact_id}": { "post": { "description": "Performs one or more scoped operations on a Contact in a single request. The body is a scoped array, and each item has a scope and one or more operations. \nBehavior matches the equivalent single-operation APIs. For each scope:\n* Subscription list operations are supported. You can subscribe and/or unsubscribe the Contact to/from subscription lists for that scope, which is the same behavior as the subscription list APIs.\n* Tag operations are not supported. If `tags` is present in any scoped item, the request is rejected with 400 and an error indicating that tags are not allowed in this context.\n\nThe following apply:\n * Set operations are not supported.\n * Failure to authorize on secure tags results in a 200 and warning.\n * Failure to find any valid tag groups results in a 200 and warning.\n * Failure to find any valid attributes results in a 200 and warning.\n", "operationId": "performScopedContactBatchOperations", "parameters": [ { "description": "A string (UUID) value identifying the Contact with no leading or trailing whitespace.\n", "in": "path", "name": "contact_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "scoped": { "description": "An array of scopes, tags, and subscription lists.", "items": { "$ref": "#/components/schemas/contactsScopedBatchItem" }, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contactsScopedBatchResponse" } } }, "description": "The request was accepted.\n" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "basicAppAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "cnt" ] } ], "summary": "Scoped Contact batch operations", "tags": [ "Contacts" ], "x-important": "The path parameter `contact_id` should be URL-encoded to ensure it is handled correctly.\n", "x-note": "If you are using a single-channel Preference Center created before October 10, 2022, that has not been [migrated to user-level](/guides/messaging/features/preference-centers/#migrating-to-a-user-level-preference-center), use the [`/api/channels/subscription_lists` endpoint](/developer/rest-api/ua/operations/channels/#modifychannelsubscriptions) to add or remove individual channels to/from your subscription list.\n" } }, "/api/contacts/tags/": { "post": { "description": "Add, remove, or set tags on a Contact. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request.", "operationId": "modifyContactTags", "requestBody": { "content": { "application/json": { "example": { "add": { "{{tag_group_1}}": [ "tag1", "tag2", "tag3" ], "{{tag_group_2}}": [ "tag1", "tag4", "tag5" ] }, "audience": { "contact_id": [ "0754a3f1-6778-4f93-8d1e-e2f110973f0d", "08a5bbff-3916-4da8-ba17-8b52d69a34d8", "{{contact_id}}" ] }, "remove": { "{{tag_group_2}}": [ "tag6", "tag7" ] } }, "schema": { "properties": { "add": { "$ref": "#/components/schemas/tagGroupObject", "description": "Add the list of tags to the Contacts, but do not remove any. If the tags are already present, they are not modified." }, "audience": { "description": "The Contacts you want to associate/disassociate tags with.", "properties": { "contact_id": { "items": { "description": "The Contact IDs you want add tags to or remove tags from. A `contact_id` is always a UUID that was created by the Airship system.", "example": [ "0754a3f1-6778-4f93-8d1e-e2f110973f0d", "08a5bbff-3916-4da8-ba17-8b52d69a34d8" ], "type": "string", "uniqueItems": true }, "maxItems": 1000, "minItems": 1, "type": "array" } }, "type": "object" }, "remove": { "$ref": "#/components/schemas/tagGroupObject", "description": "Remove the list of tags from the Contacts, but do not remove any others. If the tags are not currently present, nothing happens." }, "set": { "$ref": "#/components/schemas/tagGroupObject", "description": "Set these tags for the audience. Any tags previously associated with the audience tags that are not in this current list are removed." } }, "required": [ "audience" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contactTagsResponse" } } }, "description": "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\nwarning in the response about the tag groups that failed to update. The tag groups listed in the warning will be CSV-formatted.\n" }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Parsing or validating the request failed. You will see this error if the same tag is present in both the add and remove fields." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "Secure tag groups require master secret to modify tags, otherwise a 403 Forbidden response is returned.\n" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "oauth2Token": [ "cnt" ] } ], "summary": "Contacts tags", "tags": [ "Tags", "Contacts" ], "x-important": "A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response.\nWe support up to 1,000 tags per Contact. Adding more than 1,000 tags per Contact can cause latency and service interruptions. We strongly recommend removing unused tags whenever possible, and using custom events when appropriate. Please [contact Support](https://support.airship.com/) if you believe your use case requires more than 1,000 tags per Contact, and they will help you find an alternative." } }, "/api/content/templates": { "get": { "description": "List all existing content templates. Returns an array of content template objects in the `content_templates` attribute.", "operationId": "listContentTemplates", "parameters": [ { "description": "Specifies the desired page number. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "example": 1, "type": "integer" } }, { "description": "Specifies how many results to return per page.", "in": "query", "name": "page_size", "required": false, "schema": { "example": 25, "type": "integer" } }, { "description": "Specifies the name of the field you want to sort results by. Defaults to `created_at`.", "in": "query", "name": "sort", "required": false, "schema": { "enum": [ "created_at", "modified_at" ], "example": "created_at", "type": "string" } }, { "description": "Specifies the sort order as ascending (`asc`) or descending (`desc`). Defaults to `asc`.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "asc", "desc" ], "example": "asc", "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "content_templates": { "description": "An array of content template objects.", "items": { "$ref": "#/components/schemas/contentTemplateObject" }, "type": "array" }, "count": { "description": "The number of content templates in the current response. This is effectively the page size.", "type": "integer" }, "next_page": { "description": "There might be more than one page of results for this listing. When present, use this URL to fetch the next batch of results.", "format": "url", "type": "string" }, "ok": { "description": "Success.", "type": "boolean" }, "prev_page": { "description": "Link to the previous page, if available.", "format": "url", "type": "string" }, "total_count": { "description": "The total number of content templates.", "type": "integer" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned on success, with the JSON representation of the content templates in the body of the response." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "tpl" ] } ], "summary": "List content templates", "tags": [ "Content" ] }, "post": { "description": "Create a new content template.", "operationId": "createContentTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contentTemplateObject" } } }, "description": "A single content template object.", "required": true }, "responses": { "201": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If `true`, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "template_id": { "description": "A unique string identifying the template, used to reference it when sending messages and in other operations.", "example": "0f7704e9-5dc0-4f7d-9964-e89055701b0a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The template was created.", "headers": { "Location": { "description": "The URI for the template, used for later updates or sends.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "tpl" ] } ], "summary": "Create content template", "tags": [ "Content" ] } }, "/api/content/templates/external/{type}/{external_id}": { "delete": { "description": "Delete a content template.", "operationId": "deleteContentTemplateByExternalId", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If `true`, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The template with the given external ID has been successfully deleted." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "tpl" ] } ], "summary": "Delete content template by external ID", "tags": [ "Content" ] }, "get": { "description": "Fetch a single content template using external ID.", "operationId": "getContentTemplateByExternalId", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "content_template": { "$ref": "#/components/schemas/contentTemplateObject" }, "ok": { "description": "If `true`, the operation completed successfully and returns an expected response.", "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned on success, with the JSON representation of the template in the body of the response." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "tpl" ] } ], "summary": "Look up a content template by external ID", "tags": [ "Content" ] }, "parameters": [ { "description": "The message type for the template.", "in": "path", "name": "type", "required": true, "schema": { "enum": [ "email", "sms", "open", "app", "web", "message_center" ] } }, { "description": "The customer-defined external ID of the template.", "in": "path", "name": "external_id", "required": true, "schema": { "type": "string" } } ], "put": { "description": "Create or update a content template by its external ID.", "operationId": "updateContentTemplateByExternalId", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contentTemplateObject" } } }, "description": "A partially defined content template object.", "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If `true`, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned if the template has been successfully updated." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "tpl" ] } ], "summary": "Create or update content template by external ID", "tags": [ "Content" ] } }, "/api/content/templates/{template_id}": { "delete": { "description": "Delete a content template.", "operationId": "deleteContentTemplate", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If `true`, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The template with the given ID has been successfully deleted." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "tpl" ] } ], "summary": "Delete content template", "tags": [ "Content" ] }, "get": { "description": "Fetch a single content template using UUID.", "operationId": "getContentTemplate", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "content_template": { "$ref": "#/components/schemas/contentTemplateObject" }, "ok": { "description": "If `true`, the operation completed successfully and returns an expected response.", "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned on success, with the JSON representation of the template in the body of the response." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "tpl" ] } ], "summary": "Look up a content template", "tags": [ "Content" ] }, "parameters": [ { "description": "The UUID of the template.", "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "put": { "description": "Update a content template.", "operationId": "updateContentTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contentTemplateObject" } } }, "description": "A partially defined content template object.", "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If `true`, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned if the template has been successfully updated." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "tpl" ] } ], "summary": "Update content template", "tags": [ "Content" ] } }, "/api/create-and-send": { "post": { "description": "Send messages to email addresses, MSISDNs, or Open channel addresses. Unknown identifiers are registered as new channels. This endpoint supports two audience methods:\n- `create_and_send` array: For smaller audiences, provide email addresses, MSISDNs, or Open channel addresses directly in the request.\n\n- `bulk_id`: For larger audiences, upload a CSV using the [Create bulk send audience](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) endpoint to obtain a `bulk_id`, then reference it in this request.\n\nExisting channels that are `opted_in` or have a newer `opted_in` value in the payload receive the message but are not re-registered. You cannot update `opted_in` values for existing channels through this endpoint.\n\nNote: This endpoint also accepts Channel IDs for app or web via `bulk_id`, but this works identically to [Send message with bulk ID](/developer/rest-api/ua/operations/bulk-sending/#bulksendpush).\n\n", "operationId": "createAndSend", "requestBody": { "content": { "application/json": { "example": { "audience": { "create_and_send": [ { "ua_address": "{{email_address}}", "ua_commercial_opted_in": "2020-11-29T10:34:22" } ] }, "campaigns": { "categories": [ "winter sale", "west coast" ] }, "device_types": [ "email" ], "notification": { "email": { "html_body": "

Seasons Greetings

Check out our winter deals!

Unsubscribe

", "message_type": "commercial", "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]", "reply_to": "no-reply@airship.com", "sender_address": "{{sender_email_address}}", "sender_name": "Airship", "subject": "Welcome to the Winter Sale! " } } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/email" }, { "$ref": "#/components/schemas/sms" }, { "$ref": "#/components/schemas/mms" }, { "$ref": "#/components/schemas/open" } ] } } } }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/pushAccepted" } } }, "description": "Because this operation sends messages, a successful response is nearly identical to a `/api/push` response." }, "400": { "$ref": "#/components/responses/400", "description": "You can only Create and Send to a single platform per request. Attempting to send notifications for multiple `device_types` in the same request will cause a 400 response. An invalid or missing header row will also cause a 400 response." }, "401": { "$ref": "#/components/responses/401" }, "413": { "$ref": "#/components/responses/413", "description": "The request included a payload larger than the maximum size of 5 MiB." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "psh" ] } ], "summary": "Create and Send a message", "tags": [ "Bulk Sending" ], "x-warning": "Duplicate addresses in the `create_and_send` array might receive redundant notifications or fewer notifications than expected. You should remove duplicate addresses from your request before sending a Create and Send message." } }, "/api/create-and-send/validate": { "post": { "description": "Validate a [Create and Send](/developer/rest-api/ua/operations/bulk-sending/#createandsend) payload without creating channels or sending messages. It only parses and validates your payload.", "operationId": "validateCreateAndSendPayload", "requestBody": { "content": { "application/json": { "example": { "audience": { "create_and_send": [ { "ua_address": "{{email_address}}", "ua_commercial_opted_in": "2020-11-29T10:34:22" } ] }, "campaigns": { "categories": [ "winter sale", "west coast" ] }, "device_types": [ "email" ], "notification": { "email": { "html_body": "

Seasons Greetings

Check out our winter deals!

Unsubscribe

", "message_type": "commercial", "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]", "reply_to": "no-reply@airship.com", "sender_address": "{{sender_email_address}}", "sender_name": "Airship", "subject": "Welcome to the Winter Sale! " } } }, "schema": { "discriminator": { "propertyName": "device_types" }, "oneOf": [ { "$ref": "#/components/schemas/email" }, { "$ref": "#/components/schemas/sms" }, { "$ref": "#/components/schemas/mms" }, { "$ref": "#/components/schemas/open" } ] } } } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The payload was valid." }, "400": { "$ref": "#/components/responses/400" }, "413": { "$ref": "#/components/responses/413", "description": "The request included a payload larger than the maximum size of 5 MiB." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "psh" ] } ], "summary": "Validate Create and Send payload", "tags": [ "Bulk Sending" ] } }, "/api/custom-events": { "parameters": [ { "$ref": "#/components/parameters/appKeyHeader" } ], "post": { "description": "Submit an externally-generated custom event, associated with a Channel ID or Named User, to Airship. You can use these events as custom event triggers for Automation or Sequences and can use handlebars to personalize messages using custom event properties (information in the `body.properties` object).\n", "operationId": "addCustomEvents", "requestBody": { "content": { "application/json": { "example": [ { "body": { "external_campaigns": { "categories": [ "shoes", "running", "summer_2017" ] }, "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234", "interaction_type": "url", "name": "purchased", "properties": { "brand": "Victory Sneakers", "colors": [ "red", "blue" ], "description": "Sneaker purchase", "items": [ { "price": "$ 79.95", "text": "New Line Sneakers" }, { "price": "$ 79.95", "text": "Old Line Sneakers" }, { "price": "$ 79.95", "text": "Blue Line Sneakers" } ], "name": "Hugh Manbeing", "userLocation": { "state": "CO", "zip": "80202" } }, "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1", "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a", "value": 239.85 }, "occurred": "{{yesterday_date_time}}", "user": { "named_user_id": "{{named_user_id}}" } } ], "schema": { "items": { "$ref": "#/components/schemas/customEventObject" }, "maxItems": 100, "minItems": 1, "type": "array" } } }, "description": "An array of custom event objects." }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "Success.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the API interaction. You can use the `operation_id` in support requests if something goes wrong.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "Returned on success." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "bearerAuth": [] }, { "oauth2Token": [ "evt" ] } ], "summary": "Add custom events", "tags": [ "Custom Events" ], "x-note": "* Requests complete validation before returning a response.\n* Requests are authenticated with a bearer token, which can provide access to this resource alone or to this resource and others.\n* The `name` value inside `body` must not contain any uppercase characters, or the event will be rejected with a 400 status code.\n" } }, "/api/experiments": { "get": { "description": "List experiments, sorted by `created_at` [date-time](/developer/rest-api/ua/introduction/#date-time-format) from newest to oldest. Responses are paginated. Use optional `limit` and `offset` parameters to navigate results.", "operationId": "getExperiments", "parameters": [ { "description": "Positive maximum number of elements to return per page. The default `limit` is 10 entries with a maximum of 100 entries.", "in": "query", "name": "limit", "required": false, "schema": { "example": 10, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A zero-based integer offset into the result set. If you do not use an offset, results will begin with the most recently sent experiment. If `offset` is greater than the number of queryable experiments, an empty result will be returned.", "in": "query", "name": "offset", "required": false, "schema": { "example": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of items returned in this page of results.", "type": "integer" }, "experiments": { "description": "Experiment objects sorted by either `created_at` from newest to oldest. The number of objects will never exceed the limit specified in the request.", "items": { "$ref": "#/components/schemas/experimentObject" }, "type": "array" }, "next_page": { "description": "A relative URL leading to the next page of results. If there are no more results, next_page is absent.", "nullable": false, "type": "string" }, "ok": { "description": "If true, the call was successful.", "type": "boolean" }, "total_count": { "description": "The total number of results.", "type": "integer" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned on success, with the JSON representation of the experiments in the body of the response." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] } ], "summary": "Experiment listing", "tags": [ "A/B Tests" ] }, "post": { "description": "Create an experiment. The body of the request should consist of a single experiment object. The experiment is processed and sent immediately unless a schedule is present.", "operationId": "createExperiment", "requestBody": { "content": { "application/json": { "example": { "audience": { "tag": "earlyBirds" }, "device_types": [ "ios", "android" ], "name": "Experiment 1", "variants": [ { "push": { "notification": { "alert": "message 1" } }, "schedule": { "scheduled_time": "{{sched_5m}}" } }, { "push": { "notification": { "alert": "message 2" } }, "schedule": { "scheduled_time": "{{sched_5m}}" } } ] }, "schema": { "$ref": "#/components/schemas/experimentObject" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "description": "The response body for an experiment request.", "properties": { "experiment_id": { "description": "Unique identifier for an experiment.", "example": "0f7704e9-5dc0-4f7d-9964-e89055701b0a", "format": "uuid", "type": "string" }, "ok": { "description": "If true, the experiment was successfully created. If false, the experiment was not created.", "type": "boolean" }, "operation_id": { "description": "A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "push_id": { "description": "Unique identifier for a push.", "example": "7e13f060-594c-11e4-8ed6-0800200c9a66", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The experiment was created.", "headers": { "Location": { "description": "The newly created experiment.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] } ], "summary": "Create experiment (A/B Test)", "tags": [ "A/B Tests" ], "x-important": "The A/B Tests API is unrelated to the [current version of A/B testing](/guides/experimentation/a-b-tests/messages/). For more information about this API, including its dashboard equivalent, see [Legacy message A/B tests](/guides/experimentation/a-b-tests/messages-legacy/)." } }, "/api/experiments/scheduled": { "get": { "description": "List scheduled experiments in order, from closest to the current [date-time](/developer/rest-api/ua/introduction/#date-time-format) to farthest (i.e., the experiments scheduled to occur soonest will appear at the top of the list). Responses are paginated, using optional `limit` and `offset` parameters.", "operationId": "getScheduledExperiments", "parameters": [ { "description": "Positive maximum number of elements to return per page. The default `limit` is 10 entries with a maximum of 100 entries.", "in": "query", "name": "limit", "required": false, "schema": { "example": 10, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "A zero-based integer offset into the result set. If you do not use an offset, results will begin with experiment scheduled to begin at the soonest [date-time](/developer/rest-api/ua/introduction/#date-time-format). If the `offset` is greater than the number of queryable experiments, the result set will be empty.", "in": "query", "name": "offset", "required": false, "schema": { "example": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of items in this page of results.", "type": "integer" }, "experiments": { "description": "Experiments listed by `scheduled_time` in ascending time order. The number of objects will never exceed the `limit` specified in the request.", "items": { "$ref": "#/components/schemas/experimentObject" }, "type": "array" }, "next_page": { "description": "A relative URL leading to the next page of results. If there are no more results, next_page is absent.", "nullable": false, "type": "string" }, "ok": { "description": "If true, the operation completed successfully and returns an expected result set.", "type": "boolean" }, "total_count": { "description": "The total number of results.", "type": "integer" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned on success, with the JSON representation of the experiments in the body of the response." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] } ], "summary": "Scheduled experiment listing", "tags": [ "A/B Tests" ] } }, "/api/experiments/scheduled/{experiment_id}": { "delete": { "description": "Delete a scheduled experiment. You can only delete experiments before they start; attempting to delete an experiment that has already started or completed will return an HTTP 405 response (\"Method not allowed\").", "operationId": "deleteExperiment", "responses": { "200": { "content": { "application/json": { "schema": { "description": "The response body for a pipeline's deletion request.", "properties": { "ok": { "description": "Success.", "type": "boolean" }, "operation_id": { "description": "A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned if the experiment has been successfully deleted." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "405": { "$ref": "#/components/responses/405", "description": "Experiments can only be deleted before they start; afterwards, a HTTP 405 is returned." } }, "security": [ { "basicAuth": [] } ], "summary": "Delete experiment", "tags": [ "A/B Tests" ] }, "parameters": [ { "description": "The unique identifier of the experiment.", "in": "path", "name": "experiment_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/api/experiments/validate": { "post": { "description": "Accepts the same range of payloads as `/api/experiments`, but only parses and validates the payload without creating the experiment. This does the same amount of validation as the creation endpoint, including platform-specific validation, e.g., APNs byte limit checks. While this operation ensures the experiment is technically valid, it does not guarantee that a resulting push will succeed. An experiment may validate and still fail to be delivered. For example, you may have a valid experiment with no devices in your audience.", "operationId": "validateExperiment", "requestBody": { "content": { "application/json": { "example": { "audience": { "tag": "earlyBirds" }, "device_types": [ "ios", "android" ], "name": "Experiment 1", "variants": [ { "push": { "notification": { "alert": "message 1" } } }, { "push": { "notification": { "alert": "message 2" } } } ] }, "schema": { "$ref": "#/components/schemas/experimentObject" } } }, "description": "A single experiment object.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "ok": { "description": "If true, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string that represents a single API call, used to identify the operation or side effects in reporting and troubleshooting logs.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The experiment is valid." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] } ], "summary": "Validate experiment", "tags": [ "A/B Tests" ] } }, "/api/experiments/{experiment_id}": { "get": { "description": "Look up an experiment (A/B Test).", "operationId": "getExperiment", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "experiment": { "$ref": "#/components/schemas/experimentObject" }, "ok": { "description": "If true, the operation completed successfully and returns a result set.", "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned on success, with the JSON representation of the experiment in the body of the response." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] } ], "summary": "Experiment lookup", "tags": [ "A/B Tests" ] }, "parameters": [ { "description": "The ID of the experiment you want to look up.", "in": "path", "name": "experiment_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/api/lists": { "get": { "description": "Retrieve information about all static lists. This call returns a list of metadata that will not contain the actual lists of users.", "operationId": "getStaticListsMetadata", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "lists": { "description": "An array of list objects.", "items": { "$ref": "#/components/schemas/listObject" }, "type": "array" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "Lists metadata retrieved successfully." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Retrieve lists", "tags": [ "Static Lists" ] }, "post": { "description": "Create a static list. The body of the request will contain several of the list object parameters, but the actual list content will be provided by a second call to the [upload](/developer/rest-api/ua/operations/static-lists/#updatestaticlist) endpoint. You can upload up to 100 lists per project.", "operationId": "createStaticList", "requestBody": { "content": { "application/json": { "example": { "description": "loyalty program platinum members", "extra": { "key": "value" }, "name": "platinum_members" }, "schema": { "$ref": "#/components/schemas/listMetadataObject" } } }, "required": true }, "responses": { "201": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The list was created successfully.", "headers": { "Location": { "description": "The URI of the list, used for later updates.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g., the API may not be used to create or modify lists with a `ua_` prefixed name." }, "409": { "$ref": "#/components/responses/409", "description": "The app has reached the maximum number of allowed lists (error_code 40906). A list with that name already exists (error_code 40907). List is already processing recently uploaded CSV (error_code 40910)." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Create list", "tags": [ "Static Lists" ], "x-note": "`Content-Encoding: gzip` is supported and recommended on this endpoint to reduce network traffic." } }, "/api/lists/{list_name}": { "delete": { "description": "Delete a static list.", "operationId": "deleteStaticList", "parameters": [ { "description": "The name of the list.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "$ref": "#/components/responses/204", "description": "List was deleted successfully. (This response has no payload.)" }, "401": { "$ref": "#/components/responses/401" }, "403": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "You cannot delete or modify lists with a `ua_` prefixed `name`." }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Delete a list", "tags": [ "Static Lists" ], "x-warning": "If you are attempting to update a current list by deleting it and then recreating it with new data, stop and go to the [upload endpoint](/developer/rest-api/ua/operations/static-lists/#updatestaticlist). There is no need to delete a list before uploading a new CSV file. Moreover, once you delete a list, you will be unable to create a list with the same name as the deleted list." }, "get": { "description": "Retrieve information about one static list, specified in the URL. When looking up lists, the returned information may actually be a combination of values from both the last uploaded list and the last successfully processed list. If you create a list successfully, and then you update it and the processing step fails, then the list `status` will read `failed`, but the `channel_count` and `last_modified` fields will contain information on the last successfully processed list.", "operationId": "getStaticListMetadata", "parameters": [ { "description": "The name of the list.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/listMetadataResponse" } } }, "description": "List metadata retrieved successfully." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Get single list metadata", "tags": [ "Static Lists" ] }, "put": { "description": "Update the metadata (`description`, `extras`, etc.) of a static list.", "operationId": "updateStaticListMetadata", "parameters": [ { "description": "The name of the list.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "VIP loyalty program platinum members", "extra": { "key": "value" }, "name": "platinum_members" }, "schema": { "$ref": "#/components/schemas/listMetadataObject" } } }, "description": "The body of the request will contain a list metadata object, though you can omit the `name` attribute. If present, it must match the name provided in the URL. You cannot change the name of a list; it is the primary identifier for the list.", "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The list metadata was updated successfully." }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Bad Request. Parsing or validating the request failed. error_code 40001: Attempted list rename. List renaming is not allowed." }, "401": { "$ref": "#/components/responses/401" }, "403": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g., the API may not be used to create or modify lists with a `ua_` prefixed name." }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Update list metadata", "tags": [ "Static Lists" ], "x-note": "To update the list contents, use the [list upload](/developer/rest-api/ua/operations/static-lists/#updatestaticlist) endpoint. The update endpoint is used to update a list's metadata rather than the actual list of device identifiers." } }, "/api/lists/{list_name}/csv": { "get": { "description": "Allows you to download the contents of a static list (as opposed to a `GET` `/api/lists/{list_name}`, which will return metadata about the list). The CSV output from this endpoint will only include entries originally uploaded as `ios_channel`, `android_channel`, or `amazon_channel`.\n", "operationId": "getStaticList", "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "Returns a CSV list of channels." }, "403": { "$ref": "#/components/responses/403", "description": "List is too large to download." }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists or the list has not yet successfully processed an uploaded CSV." } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Download a list of channels", "tags": [ "Static Lists" ] }, "parameters": [ { "description": "The `name` of the list you want to retrieve or update.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "put": { "description": "\nReplace the contents of an existing static list via CSV file upload. Uploads must be newline-delimited\nidentifiers (text/CSV) with commas as the delimiter.\n\nThe CSV format is two columns: `identifier_type` and `identifier`. The `identifier` is the associated identifier you wish to send to. The `identifier_type`\nmust be one of:\n\n * `named_user`\n * `ios_channel`\n * `android_channel`\n * `amazon_channel`\n * `sms_channel`\n * `email_channel`\n * `open_channel`\n * `web_channel`\n\nThe first entry in the uploaded CSV may be a header row, which will be ignored. If present,\nthe header row must contain exactly two entries, and the first column must not be an\n`identifier_type` as specified above.\n", "operationId": "updateStaticList", "requestBody": { "content": { "text/csv": { "schema": { "example": [ "C:/Users/someUser/Downloads/weekly_offers.csv" ], "format": "binary", "type": "string" } } }, "required": true }, "responses": { "202": { "$ref": "#/components/responses/202", "description": "The list was uploaded successfully and is now being processed." }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Bad Request. Parsing or validating the request failed.\n\n| Error code | Description |\n|---|---|\n| 40002 | CSV contains too many identifiers |\n| 40003 | CSV contains an entry with a column count other than 2 |\n| 40004 | CSV contains an invalid `identifier_type` |\n| 40005 | CSV contains a channel `identifier` that is not a valid UUID |\n" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "Forbidden. Authentication was correct, but the user does not have permission to access the requested API, e.g., the API may not be used to create or modify lists with a `ua_` prefixed name." }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Update list contents", "tags": [ "Static Lists" ], "x-note": "The maximum number of `identifier_type,identifier` pairs that may be uploaded to a list is 10 million. `Content-Encoding: gzip` is supported and recommended on this endpoint to reduce network traffic.", "x-warning": "If an attempt to upload a list times out due to a poor connection, you must re-upload the list from scratch. Because we want to ensure that the entirety of a given list is successfully uploaded, we do not support partial list uploads." } }, "/api/named_users": { "get": { "description": "Return a list of Named Users or look up a single Named User by `named_user_id`.", "operationId": "getNamedUser", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "oneOf": [ { "description": "Response for a single `named_user_id` query.", "properties": { "named_user": { "$ref": "#/components/schemas/namedUserResponseBody" }, "ok": { "description": "Success.", "type": "boolean" } }, "required": [ "ok" ], "title": "Named User lookup response object" }, { "description": "Response returned when performing this operation without a query.", "properties": { "named_users": { "items": { "$ref": "#/components/schemas/namedUserResponseBody" }, "type": "array" }, "next_page": { "description": "There might be more than one page of results for this listing. Follow this URL if it is present to the next page of results.", "example": "https://go.urbanairship.com/api/named_users?start=john_doe", "format": "url", "type": "string" }, "ok": { "description": "Success.", "type": "boolean" } }, "required": [ "ok" ], "title": "Named User listing response body" } ] } } }, "description": "Returns OK for success." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "nu" ] } ], "summary": "Named User listing or lookup", "tags": [ "Named Users" ] }, "parameters": [ { "description": "The `named_user_id` you want to look up. When querying a `named_user_id`, the response contains a single `named_user` object. If you do not query a specific `named_user_id`, the response returns an array of `named_users`, in which each object represents an individual Named User.", "in": "query", "name": "id", "required": false, "schema": { "example": "{{named_user_id}}", "type": "string" } } ] }, "/api/named_users/associate": { "post": { "description": "Associate a channel or email address with a Named User (`named_user_id`). If the `named_user_id` does not already exist, this operation will create it. If the `channel_id` or `email address` is already associated with the `named_user_id`, this operation will do nothing.", "operationId": "associateNamedUser", "requestBody": { "content": { "application/json": { "example": { "channel_id": "{{ios_channel}}", "device_type": "ios", "named_user_id": "{{named_user_id}}" }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/channelIdNamedUserAssociation" }, { "$ref": "#/components/schemas/emailAddressNamedUserAssociation" } ] } } }, "description": "Named User association requires a `channel_id` or `email_address`. Do not provide both in the same request. You can associate up to 100 Channel IDs to a Named User. Channel creation is asynchronous, so when associating a newly created channel, both a Channel ID and a device type are required to prevent \"channel does not exist\" errors.", "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The request was accepted but is not guaranteed to be successfully processed.\nIf the Named User has more than 1,000 channels associated with it, the request will be ignored." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "basicAppAuth": [] }, { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "nu" ] } ], "summary": "Named Users association", "tags": [ "Named Users" ], "x-warning": "If a channel has an assigned Named User and you make an additional call to associate that same channel with a new Named User, the original Named User association will be removed and the new Named User and associated data will take its place. Additionally, all tags associated to the original Named User cannot be used to address this channel unless they are also associated with the new Named User." } }, "/api/named_users/disassociate": { "post": { "description": "Disassociate a channel or an email address from a `named_user_id`.", "operationId": "disassociatedNamedUser", "requestBody": { "content": { "application/json": { "example": { "channel_id": "{{ios_channel}}", "device_type": "ios", "named_user_id": "{{named_user_id}}" }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/channelIdNamedUserDisassociation" }, { "$ref": "#/components/schemas/emailAddressNamedUserDisassociation" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The request was accepted but is not guaranteed to be successfully processed." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "basicAppAuth": [] }, { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "nu" ] } ], "summary": "Named Users disassociation", "tags": [ "Named Users" ] } }, "/api/named_users/scoped/{named_user_id}": { "post": { "description": "Supports multiple operations on a Named User within a single request for a specified `scope`. The supported operation is\n`subscription_lists`. The behavior of each of these operations are the same as their individual request counterpart.\n", "operationId": "performNamedUserScopedBatchOperations", "parameters": [ { "description": "A string value identifying the user, without leading or trailing whitespace.\nIf this value contains reserved or special characters they must be URL encoded.\n", "in": "path", "name": "named_user_id", "required": true, "schema": { "example": "john_doe", "maxLength": 128, "minLength": 1, "pattern": "^(?!\\s).{1,128}(?Seasons Greetings

Check out our winter deals!

Unsubscribe

", "message_type": "commercial", "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]", "reply_to": "no-reply@airship.com", "sender_address": "{{sender_email_address}}", "sender_name": "Airship", "subject": "Welcome to the Winter Sale! " } } }, "schedule": { "scheduled_time": "{{sched_1m}}" } }, "schema": { "properties": { "name": { "description": "A name for the schedule.", "type": "string" }, "push": { "discriminator": { "propertyName": "device_types" }, "oneOf": [ { "$ref": "#/components/schemas/email" }, { "$ref": "#/components/schemas/sms" }, { "$ref": "#/components/schemas/mms" }, { "$ref": "#/components/schemas/open" } ] }, "schedule": { "description": "Similar to other schedule objects. However, Create and Send requests support `scheduled_time` only.", "properties": { "scheduled_time": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when you want to perform your Create and Send operation. Users will receive the notification as soon as possible after the specified date-time.", "format": "date-time", "type": "string" } }, "required": [ "scheduled_time" ], "type": "object" } }, "required": [ "schedule", "push" ], "type": "object" } } }, "description": "The request is much like other Create and Send operations, with a leading `schedule` object. The standard Create and Send payload sits inside a `push` object." }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/pushAccepted" } } }, "description": "Because this operation sends messages, a successful response is nearly identical to a `/api/push` response." }, "400": { "$ref": "#/components/responses/400", "description": "You can only Create and Send to a single platform per request. Attempting to send notifications for multiple `device_types` in the same request will cause a 400 response. An invalid or missing header row will also cause a 400 response." }, "401": { "$ref": "#/components/responses/401" }, "413": { "$ref": "#/components/responses/413", "description": "The request included a payload larger than the maximum size of 5 MiB." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "psh" ] } ], "summary": "Schedule a Create and Send message", "tags": [ "Bulk Sending" ], "x-warning": "Duplicate addresses in the `create_and_send` array might receive redundant notifications or fewer notifications than expected. You should remove duplicate addresses from your request before sending a Create and Send message." } }, "/api/schedules/{schedule_id}": { "delete": { "description": "Delete a schedule resource, which will result in no more pushes being sent. If the resource is successfully deleted, the response does not include a body.", "operationId": "deleteSchedule", "responses": { "204": { "$ref": "#/components/responses/204", "description": "The delete operation was successful." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "sch" ] } ], "summary": "Delete schedule", "tags": [ "Schedules" ] }, "get": { "description": "Fetch the current definition of a single schedule resource. Returns a single schedule object.", "operationId": "getSchedule", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scheduleObject" } } }, "description": "Returned on success, with the JSON representation of the scheduled push in the body of the response." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "sch" ] } ], "summary": "List a specific schedule", "tags": [ "Schedules" ] }, "parameters": [ { "description": "The ID of a schedule.", "in": "path", "name": "schedule_id", "required": true, "schema": { "type": "string" } } ], "put": { "description": "Update the state of a single schedule resource. The body must contain a single schedule object. A PUT cannot be used to create a new schedule; it can only be used to update an existing one. A push to local time schedule cannot be updated once it has begun sending pushes to a time zone.", "operationId": "updateSchedule", "requestBody": { "content": { "application/json": { "example": { "name": "Morning People", "push": { "audience": { "tag": "earlyBirds" }, "device_types": [ "ios", "android" ], "notification": { "alert": "Good Day earlyBirds" } }, "schedule": { "best_time": { "send_date": "{{one_day_hence}}" }, "recurring": { "cadence": { "count": 1, "type": "daily" }, "end_time": "{{sched_25hours}}" } } }, "schema": { "$ref": "#/components/schemas/scheduleObject" } } }, "description": "A single schedule object." }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "Success.", "type": "boolean" }, "operation_id": { "description": "A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "schedule_urls": { "$ref": "#/components/schemas/urlArray", "description": "An array of schedule URLs.", "example": [ "https://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109" ] }, "schedules": { "description": "An array of schedule objects.", "items": { "$ref": "#/components/schemas/scheduleObject" }, "type": "array" } } } } }, "description": "Returned if the scheduled push has been successfully updated." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Returned if the local time scheduled push is in progress." }, "413": { "$ref": "#/components/responses/413", "description": "The request included a payload larger than the maximum size of 5 MiB." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "sch" ] } ], "summary": "Update schedule", "tags": [ "Schedules" ] } }, "/api/schedules/{schedule_id}/pause": { "parameters": [ { "description": "The ID of the schedule you want to pause.", "in": "path", "name": "schedule_id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Pause a recurring scheduled message, preventing Airship from sending messages on a recurring scheduled message interval. Use the `/resume` endpoint to resume a schedule. The pause operation cannot be completed for recurring schedules that have schedule end times in the past.", "operationId": "pauseSchedule", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "A pause request is empty.\n" }, "responses": { "204": { "$ref": "#/components/responses/204", "description": "The pause operation was successful." }, "400": { "description": "Returned if the schedule end time for a recurring schedule is in the past." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "description": "A description of the error.", "type": "string" }, "error_code": { "default": 500, "description": "An error code representing the HTTP status and a more specific Airship error, if known.", "example": 500, "type": "integer" }, "failed_triggers": { "items": { "properties": { "id": { "description": "The list of failed schedule triggers.", "format": "uuid", "type": "string" }, "state": { "description": "The reason that the operation failed.", "enum": [ "BLOCKED", "FAILED" ], "type": "string" } }, "type": "object" }, "type": "array" }, "ok": { "description": "If false, an error occurred.", "type": "boolean" } }, "type": "object" } } }, "description": "Occurs if a schedule fails to pause. The error includes a list of `failed_triggers`, detailing the schedule triggers that caused this operation to fail." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "sch" ] } ], "summary": "Pause a schedule", "tags": [ "Schedules" ], "x-note": "Paused schedules bear a `\"paused\": true` boolean.\n" } }, "/api/schedules/{schedule_id}/resume": { "parameters": [ { "description": "The ID of the schedule you want to resume.", "in": "path", "name": "schedule_id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Resume a recurring schedule that you previously paused, beginning with the next scheduled interval. The resume operation cannot be completed for recurring schedules that have schedule end times in the past.", "operationId": "resumeSchedule", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "A resume request is empty.\n" }, "responses": { "204": { "$ref": "#/components/responses/204", "description": "The operation was successful." }, "400": { "description": "Returned if the schedule end time is in the past." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "description": "A description of the error.", "type": "string" }, "error_code": { "default": 500, "description": "An error code representing the HTTP status and a more specific Airship error, if known.", "example": 500, "type": "integer" }, "failed_triggers": { "items": { "properties": { "id": { "description": "The list of failed schedule triggers.", "format": "uuid", "type": "string" }, "state": { "description": "The reason that the operation failed.", "enum": [ "BLOCKED", "FAILED" ], "type": "string" } }, "type": "object" }, "type": "array" }, "ok": { "description": "If false, an error occurred.", "type": "boolean" } }, "type": "object" } } }, "description": "Occurs if a schedule fails to resume. The error includes a list of `failed_triggers`, detailing the specific schedule IDs that caused the operation to fail." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "sch" ] } ], "summary": "Resume a schedule", "tags": [ "Schedules" ], "x-note": "Paused schedules bear a `\"paused\": true` boolean.\n" } }, "/api/segments": { "get": { "description": "List all segments for the application.", "operationId": "getSegments", "parameters": [ { "description": "Set the limit to 200 or fewer segment objects per request.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 200, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "next_page": { "description": "An optional relative URL which can be used to retrieve the next page of results. If no more results are available, next_page will be absent.", "type": "string" }, "segments": { "description": "An array of segments for the application.", "items": { "properties": { "creation_date": { "description": "The original creation date of segment in epoch milliseconds.", "example": 1508538390136, "type": "integer" }, "display_name": { "description": "The segment display name.", "example": "Some Segment Name", "type": "string" }, "id": { "description": "A unique identifier for the segment.", "example": "00c0d899-a595-4c66-9071-bc59374bbe6b", "type": "string" }, "modification_date": { "description": "Latest modification date of the segment in epoch milliseconds.", "example": 1508538390136, "type": "integer" } }, "required": [ "creation_date", "display_name", "id", "modification_date" ], "type": "object" }, "type": "array" } }, "required": [ "segments" ], "type": "object" } } }, "description": "Returned on success a JSON object containing segments.", "headers": { "Link": { "description": "A link to the next page of results. If present, follow this URL to the next page of segments. Also available in the `next_page` value in the response body.", "schema": { "format": "uri", "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] } ], "summary": "Segment listing", "tags": [ "Segments" ] }, "post": { "description": "Create a new segment.", "operationId": "createSegment", "requestBody": { "content": { "application/json": { "example": { "criteria": { "and": [ { "tag": "news" }, { "not": { "tag": "sports" } } ] }, "display_name": "News but not sports" }, "schema": { "$ref": "#/components/schemas/segmentObject" } } }, "description": "A single segment object.", "required": true }, "responses": { "201": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, the operation completed successfully and returns expected results.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying an API call, and can be used to identify operations in reporting and troubleshooting logs.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "segment_id": { "description": "The ID of the newly created segment.", "example": "1d154121-951f-45b9-896d-e70718b5865b", "format": "uuid", "type": "string" } }, "type": "object" } } }, "description": "The segment was created.", "headers": { "Location": { "description": "The newly created segment.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] } ], "summary": "Create segment", "tags": [ "Segments" ] } }, "/api/segments/{segment_id}": { "delete": { "description": "Remove the segment.", "operationId": "deleteSegment", "responses": { "204": { "$ref": "#/components/responses/204", "description": "The delete operation was successful." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] } ], "summary": "Delete segment", "tags": [ "Segments" ] }, "get": { "description": "Lookup a segment.", "operationId": "getSegment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/segmentObject" } } }, "description": "Returns OK for success." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] } ], "summary": "Segment lookup", "tags": [ "Segments" ] }, "parameters": [ { "description": "The segment you want to retrieve.", "in": "path", "name": "segment_id", "required": true, "schema": { "type": "string" } } ], "put": { "description": "Change the definition of the segment.", "operationId": "updateSegment", "requestBody": { "content": { "application/json": { "example": { "criteria": { "and": [ { "tag": "entertainment" }, { "not": { "tag": "sports" } } ] }, "display_name": "Entertainment but not sports" }, "schema": { "$ref": "#/components/schemas/segmentObject" } } }, "description": "A single segment object." }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "Returned if the segment has been successfully updated." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] } ], "summary": "Update segment", "tags": [ "Segments" ], "x-note": "Segmentation data is evaluated at send time. If you schedule a message that targets a segment and then edit that segment, the scheduled message automatically uses the updated segment criteria. \"Scheduled\" includes recurring messages." } }, "/api/sms/custom-response": { "post": { "description": "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](/developer/api-integrations/sms/inbound-message-handling/) for information about setting up a custom response webhook server.\n", "operationId": "createCustomSmsResponse", "parameters": [ { "$ref": "#/components/parameters/appKeyHeader" } ], "requestBody": { "content": { "application/json": { "example": { "mobile_originated_id": "28883743-4868-4083-ab5d-77ac4542531a", "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 } }, "schema": { "oneOf": [ { "properties": { "mobile_originated_id": { "$ref": "#/components/schemas/mobile_originated_id" }, "sms": { "properties": { "alert": { "description": "Your custom SMS message.", "type": "string" }, "shorten_links": { "$ref": "#/components/schemas/shorten_links" } }, "required": [ "alert" ], "type": "object" } }, "required": [ "sms", "mobile_originated_id" ], "type": "object" }, { "properties": { "mms": { "$ref": "#/components/schemas/mmsOverrideObject" }, "mobile_originated_id": { "$ref": "#/components/schemas/mobile_originated_id" } }, "required": [ "mms", "mobile_originated_id" ], "type": "object" } ] } } } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If `true`, your request was successful.", "type": "boolean" }, "operation_id": { "$ref": "#/components/schemas/operation_id" }, "push_id": { "$ref": "#/components/schemas/push_id" } }, "type": "object" } } }, "description": "The operation was successful." }, "404": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "error": { "description": "A plain-text explanation of the error.", "type": "string" }, "ok": { "description": "If false, your request was unsuccessful.", "type": "boolean" }, "operation_id": { "$ref": "#/components/schemas/operation_id" } }, "type": "object" } } }, "description": "The mobile_originated_id could not be found." } }, "security": [ { "bearerAuth": [] } ], "summary": "Custom SMS response", "tags": [ "SMS" ] } }, "/api/sms/{msisdn}/keywords": { "post": { "description": "Trigger Mobile Originated (MO) keyword interactions on behalf of an MSISDN.\n", "operationId": "triggerSmsKeywordInteraction", "parameters": [ { "$ref": "#/components/parameters/appKeyHeader" }, { "description": "The identifier for the SMS channel you want to trigger a mobile originated keyword from.", "in": "path", "name": "msisdn", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "keyword": "stop", "sender_ids": [ 54321, "1234" ] }, "schema": { "properties": { "keyword": { "description": "The keyword you want to trigger an action for. Must be an alphanumeric string with no spaces.", "type": "string" }, "sender_ids": { "description": "The [sender IDs](/developer/rest-api/ua/schemas/others/#sender_id) 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.", "items": { "$ref": "#/components/schemas/sender_id" }, "minItems": 1, "type": "array" }, "timestamp": { "description": "The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the MO keyword was sent. If absent, Airship uses the server-time of your request.", "format": "date-time", "type": "string" } }, "required": [ "keyword", "sender_ids" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If `true`, your request was successful.", "type": "boolean" } }, "type": "object" } } }, "description": "The operation was successful." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "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`.\n" } }, "security": [ { "basicAppAuth": [] }, { "basicAuth": [] }, { "bearerAuth": [] } ], "summary": "Manually trigger a keyword interaction", "tags": [ "SMS" ] } }, "/api/subscription_lists": { "get": { "description": "Provides a list of subscription lists IDs that are associated with this app key.", "operationId": "getSubscriptionLists", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "Success.", "type": "boolean" }, "subscription_lists": { "description": "An array of subscription list result objects.", "items": { "$ref": "#/components/schemas/subscriptionListResultObject" }, "type": "array" } }, "type": "object" } } }, "description": "Returns OK for success, with the list of subscription lists for the app." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Subscription lists listing", "tags": [ "Subscription Lists" ] } }, "/api/subscription_lists/named_users/{named_user_id}": { "get": { "description": "Provides the subscription lists that are associated with a given Named User.", "operationId": "getNamedUserSubscriptionLists", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "Success.", "type": "boolean" }, "subscription_lists": { "items": { "$ref": "#/components/schemas/contactSubscriptionListObject" }, "type": "array" } }, "type": "object" } } }, "description": "Returns OK for success, with the Named User subscription list IDs." }, "304": { "content": { "application/vnd.urbanairship+json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "An If-Modified-Since request header exists and the result is unchanged." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "nu" ] } ], "summary": "Named User subscription lists listing", "tags": [ "Subscription Lists" ] }, "parameters": [ { "description": "The Named User being looked up.", "in": "path", "name": "named_user_id", "required": true, "schema": { "type": "string" } } ] }, "/api/tag-lists": { "get": { "description": "Retrieve information about all tag lists. This call returns a list of metadata that will not contain the actual lists of users.", "operationId": "getTagListsMetadata", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "lists": { "description": "An array of list objects.", "items": { "$ref": "#/components/schemas/tagListResponseObject" }, "type": "array" }, "ok": { "description": "Success.", "type": "boolean" } }, "type": "object" } } }, "description": "Lists metadata retrieved successfully." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Retrieve lists", "tags": [ "Tag Lists" ], "x-note": "The tag list content will return the data provided in the [tag list creation](/developer/rest-api/ua/operations/tag-lists/#createtaglist) operation. Although `add`, `remove`, and `set` are optional, one or more must be present." }, "post": { "description": "Add tags to your contacts by creating a list and uploading CSV file with user identifiers. The body of the request contains the name, description, and optional metadata for the list. After you define a list, you populate it with a call to the [Upload Tag List](/developer/rest-api/ua/operations/tag-lists/#uploadtaglist) endpoint.", "operationId": "createTagList", "requestBody": { "content": { "application/json": { "example": { "description": "First of many tags lists!", "extra": { "filename": "tagsList.csv", "source": "CRM" }, "name": "ua_tags_my_new_list" }, "schema": { "$ref": "#/components/schemas/tagListMetadataObject" } } }, "required": true }, "responses": { "201": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The list was created successfully.", "headers": { "Location": { "description": "The URI of the list, used for later updates.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400", "description": "Malformed JSON payload." }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "The API may only be used to create or modify lists with a `ua_tags_` prefixed name." }, "409": { "$ref": "#/components/responses/409", "description": "The app has reached the maximum number of allowed lists (error_code 40906). A list with that name already exists (error_code 40907). List is already processing recently uploaded CSV (error_code 40910)." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Create a tag list", "tags": [ "Tag Lists" ], "x-important": "You must prefix tag list names with `\"ua_tags_\"`." } }, "/api/tag-lists/{list_name}": { "delete": { "description": "Delete a list. Deleting a list will not affect any previous uploads but will prevent new uploads to the deleted list. For example, this does not remove the tags associated with the previously-uploaded file from the channels in that file.", "operationId": "deleteTagList", "parameters": [ { "description": "The name of the list.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The delete operation was successful." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Delete tag list", "tags": [ "Tag Lists" ] } }, "/api/tag-lists/{list_name}/csv": { "parameters": [ { "description": "The `name` of the list you want to retrieve or update.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "put": { "description": "Upload a CSV that will set tag values on the specified channels or Named Users.\n\nThe first entry in the uploaded CSV must be a header row. The first field must be one of the following identifier types: `channel_id`, `msisdn`, `named_user`, `email_address`.\n\nOnly one identifier type is allowed per file.\n\nYou must include both `msisdn` and `sms_sender` columns when targeting SMS or MMS channel types. See example to the right.\n\nUploads must be newline-delimited identifiers (text/CSV) as described in RFC 4180, with commas as the delimiter, optionally double-quoted values, UTF-8 encoded, and with CRLF or LF line separators.\n\n| Target type | Required column headers |\n|------------------|------------------------------------------------------------------------------------------|\n| Web | `channel_id` |\n| Open Channel | `channel_id` |\n| iOS | `channel_id` |\n| Android | `channel_id` |\n| Named User | `named_user` |\n| Email | `email_address` |\n| SMS |
  • `msisdn` (numeric and no leading 0)
  • `sms_sender` (numeric)
|\n| MMS |
  • `msisdn` (numeric and no leading 0)
  • `sms_sender` (numeric)
|\n\nOptional Fields: Opt-in dates can optionally be set for new channels\nwhen the identifier is an `email_address` or `msisdn`.\n| Target type | Optional column headers |\n|-----------------|------------------------------------------------------------------------------------------|\n| SMS | `ua_opted_in` (UTC Timestamp) |\n| MMS | `ua_opted_in` (UTC Timestamp) |\n| Email |
  • `ua_transactional_opted_in` (UTC Timestamp)
  • `ua_commercial_opted_in` (UTC Timestamp)
|\n", "operationId": "uploadTagList", "requestBody": { "content": { "text/csv": { "schema": { "example": [ "C:/Users/someUser/Downloads/weekly_offers.csv" ], "format": "binary", "type": "string" } } }, "required": true }, "responses": { "202": { "$ref": "#/components/responses/202", "description": "The list was uploaded successfully and is now being processed." }, "400": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Bad Request. Parsing or validating the request failed.\n\n| Error code | Description |\n|---|---|\n| 40002 | CSV contains too many identifiers |\n| 40003 | CSV header contains too many columns |\n| 40013 | CSV header’s first field must be an identifier |\n| 40018 | CSV header does not contain required column for identifier type |\n" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403", "description": "The API may only be used to create or modify lists with a `ua_tags_` prefixed name." }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Upload tag list", "tags": [ "Tag Lists" ], "x-note": "The maximum number of rows that may be uploaded to a list is 10 million. `Content-Encoding: gzip` is supported and recommended on this endpoint to reduce network traffic.", "x-warning": "If your upload times out due to a poor connection, you must re-upload the list from scratch. Because we want to ensure that the entirety of a given list is successfully uploaded, we do not support partial list uploads." } }, "/api/tag-lists/{list_name}/errors": { "get": { "description": "During processing, after a list is uploaded, errors can occur. Depending on the type of list processing, an error file may be created, showing a user exactly what went wrong.", "operationId": "getTagListErrors", "parameters": [ { "description": "The name of the list.", "in": "path", "name": "list_name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "Returns OK for success. The response will contain the errors found during list processing." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404", "description": "No list with that name exists or the list has not yet successfully processed an uploaded CSV." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "oauth2Token": [ "lst" ] } ], "summary": "Download list errors", "tags": [ "Tag Lists" ] } }, "/api/templates": { "get": { "description": "List all existing templates. Returns an array of template objects in the `templates` attribute.", "operationId": "getTemplates", "parameters": [ { "description": "Specifies the desired page number. Defaults to 1.", "in": "query", "name": "page", "required": false, "schema": { "example": 1, "type": "integer" } }, { "description": "Specifies how many results to return per page. Has a default value of 25 and a maximum value of 100.", "in": "query", "name": "page_size", "required": false, "schema": { "example": 25, "type": "integer" } }, { "description": "Specifies the name of the field you want to sort results by. Defaults to `created_at`.", "in": "query", "name": "sort", "required": false, "schema": { "enum": [ "created_at", "modified_at", "last_used" ], "example": "created_at", "type": "string" } }, { "description": "Specifies the sort order as ascending (`asc`) or descending (`desc`). Defaults to `asc`.", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "asc", "desc" ], "example": "asc", "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "count": { "description": "The number of templates in the current response; this is effectively the page size.", "type": "integer" }, "next_page": { "description": "There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.", "example": "https://go.urbanairship.com/api/templates?page=2&page_size=1", "format": "url", "type": "string" }, "ok": { "description": "Success.", "type": "boolean" }, "prev_page": { "description": "Link to the previous page, if available.", "format": "url", "type": "string" }, "templates": { "description": "An array of template objects.", "items": { "$ref": "#/components/schemas/templateObject" }, "type": "array" }, "total_count": { "description": "The total number of templates.", "type": "integer" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned on success, with the JSON representation of the templates in the body of the response." }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] } ], "summary": "List templates", "tags": [ "Personalization" ], "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" }, "post": { "description": "Create a new template.", "operationId": "createTemplate", "requestBody": { "content": { "application/json": { "example": { "description": "Our welcome message", "name": "Welcome Message", "push": { "notification": { "alert": "Hello {{FIRST_NAME}}, this is your welcome message!" } }, "variables": [ { "default_value": "", "description": "e.g., Mr, Ms, Dr, etc.", "key": "TITLE", "name": "Title" }, { "default_value": "", "description": "Given name", "key": "FIRST_NAME", "name": "First Name" }, { "default_value": "", "description": "Family name", "key": "LAST_NAME", "name": "Last Name" } ] }, "schema": { "$ref": "#/components/schemas/templateObject" } } }, "description": "A single template object.", "required": true }, "responses": { "201": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If `true`, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "template_id": { "description": "A unique string identifying the template, used to call the template for pushing and other operations.", "example": "0f7704e9-5dc0-4f7d-9964-e89055701b0a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The template was created.", "headers": { "Location": { "description": "The URI for the template, used for later updates or sends.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] } ], "summary": "Create template", "tags": [ "Personalization" ], "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" } }, "/api/templates/push": { "post": { "description": "Send a push notification based on a template to a list of devices. The body of the request must be a single push template payload or an array of one or more push template payloads.", "operationId": "pushToTemplate", "requestBody": { "content": { "application/json": { "example": { "audience": { "ios_channel": "{{ios_channel}}" }, "device_types": [ "ios" ], "merge_data": { "substitutions": { "FIRST_NAME": "Bob", "LAST_NAME": "Smith", "TITLE": "" }, "template_id": "{{template_id}}" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/pushTemplatePayload" }, { "items": { "$ref": "#/components/schemas/pushTemplatePayload" }, "title": "Array of push templates", "type": "array" } ] } } }, "description": "A single push template payload or an array of push template payloads. Provide an override with any variable that has a `null` default value. For example, if you created a template with the variable `FIRST_NAME`, and that variable has `null` as a default value, you must provide a substitution for `FIRST_NAME` when pushing to that template.", "required": true }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "push_ids": { "$ref": "#/components/schemas/uuidArray", "description": "An array of the push IDs for this operation." } }, "required": [ "ok" ], "type": "object" } } }, "description": "The push notification has been accepted for processing." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "psh" ] } ], "summary": "Push to template", "tags": [ "Personalization" ], "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" } }, "/api/templates/push/validate": { "post": { "description": "This endpoint accepts the same range of payloads as `/api/template/push`, but only parses and validates the payload. It does not actually send a push.", "operationId": "validateTemplate", "requestBody": { "content": { "application/json": { "example": { "audience": { "ios_channel": "{{ios_channel}}" }, "device_types": [ "ios" ], "merge_data": { "substitutions": { "FIRST_NAME": "Bob", "LAST_NAME": "Smith", "TITLE": "" }, "template_id": "{{template_id}}" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/pushTemplatePayload" }, { "items": { "$ref": "#/components/schemas/pushTemplatePayload" }, "type": "array" } ] } } }, "description": "A single push template payload or an array of push template payloads.", "required": true }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "$ref": "#/components/schemas/okResponseObject" } } }, "description": "The payload was valid." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "psh" ] } ], "summary": "Validate a template", "tags": [ "Personalization" ], "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" } }, "/api/templates/schedules": { "post": { "description": "Schedule a push notification based on a template to a list of devices. Like a standard template-based push, the body of the request includes one or more push template payloads along with a schedule object determining when the template-based push should be sent.", "operationId": "scheduleTemplatedPush", "requestBody": { "content": { "application/json": { "example": [ { "audience": { "ios_channel": "{{ios_channel}}" }, "device_types": [ "ios" ], "merge_data": { "substitutions": { "FIRST_NAME": "Bob", "LAST_NAME": "Takahashi", "TITLE": "" }, "template_id": "{{template_id}}" }, "name": "Hello Bob", "schedule": { "scheduled_time": "{{sched_1m}}" } }, { "audience": { "android_channel": "{{android_channel}}" }, "device_types": [ "android" ], "merge_data": { "substitutions": { "FIRST_NAME": "Joe", "LAST_NAME": "Smith", "TITLE": "Sir" }, "template_id": "{{template_id}}" }, "name": "Hello Joe", "schedule": { "scheduled_time": "{{sched_1m}}" } } ], "schema": { "items": { "description": "A scheduled push template object defines a push by overriding the variables defined in a specific template object and the `schedule` determining when the push should be sent. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template.", "properties": { "audience": { "$ref": "#/components/schemas/audienceSelector1000", "description": "The audience for the template." }, "campaigns": { "$ref": "#/components/schemas/campaignsObject" }, "device_types": { "$ref": "#/components/schemas/deviceTypesSelector" }, "merge_data": { "description": "A template selector describing the template ID and variable substitutions to use with it.", "properties": { "substitutions": { "description": "An object containing overrides for your template's variables. The key-value pairs in this object are the value of the `key` items defined in your template, and the values you want to substitute for the `default_value` of those keys.", "type": "object" }, "template_id": { "description": "Specifies the template to override.", "example": "ef34a8d9-0ad7-491c-86b0-aea74da15161", "format": "uuid", "type": "string" } }, "required": [ "template_id" ], "type": "object" }, "name": { "description": "An optional name for the scheduled push operation.", "type": "string" }, "schedule": { "$ref": "#/components/schemas/scheduleSpec", "description": "Determines when the push is sent." } }, "required": [ "audience", "device_types", "merge_data", "schedule" ], "type": "object" }, "type": "array" } } }, "description": "An array of scheduled pushes." }, "responses": { "202": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "Success.", "type": "boolean" }, "operation_id": { "description": "A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" }, "schedule_ids": { "$ref": "#/components/schemas/uuidArray", "description": "An array of schedule IDs." }, "schedule_urls": { "$ref": "#/components/schemas/urlArray", "description": "An array of schedule URLs. The URL for each schedule is the schedules endpoint, appended with the `schedule_id` of the schedule.", "example": [ "https://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109" ] }, "schedules": { "description": "An array of schedule objects.", "items": { "$ref": "#/components/schemas/scheduleObject" }, "type": "array" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The scheduled push has been accepted for processing." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "406": { "$ref": "#/components/responses/406" } }, "security": [ { "basicAuth": [] }, { "oauth2Token": [ "psh" ] } ], "summary": "Schedule a templated push", "tags": [ "Personalization" ], "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" } }, "/api/templates/{template_id}": { "delete": { "description": "Delete a template. If the template is successfully deleted, the response does not include a body.", "operationId": "deleteTemplate", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The template with given ID has been successfully deleted." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] } ], "summary": "Delete template", "tags": [ "Personalization" ], "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" }, "get": { "description": "Fetch the current definition of a single template.", "operationId": "getTemplate", "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, the operation completed successfully and returns an expected response.", "type": "boolean" }, "template": { "$ref": "#/components/schemas/templateObject" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned on success, with the JSON representation of the template in the body of the response." }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] } ], "summary": "Look up a template", "tags": [ "Personalization" ], "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" }, "parameters": [ { "description": "A required string ID of the template.", "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "Update a template. The request body is a partially-defined template object, containing the field(s) you want to change and their updated values.", "operationId": "updateTemplate", "requestBody": { "content": { "application/json": { "example": { "description": "Our updated welcome message", "name": "Welcome Message", "push": { "notification": { "alert": "Hello {{FIRST_NAME}} {{LAST_NAME}}, this is your welcome message!" } } }, "schema": { "description": "A partially-defined template object. Provide only `variables` and `push` items that you want to update.", "properties": { "description": { "description": "The description of the template.", "type": "string" }, "name": { "description": "The name of the template.", "type": "string" }, "push": { "$ref": "#/components/schemas/templatePushObject" }, "variables": { "description": "An array of variable specifications.", "items": { "$ref": "#/components/schemas/templateVariableObject" }, "type": "array" } }, "required": [ "name" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/vnd.urbanairship+json; version=3": { "schema": { "properties": { "ok": { "description": "If true, the operation completed successfully and returns an expected response.", "type": "boolean" }, "operation_id": { "description": "A unique string identifying the operation, useful for reporting and troubleshooting.", "example": "ef625038-70a3-41f1-826f-57bc11dd625a", "format": "uuid", "type": "string" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Returned if the template has been successfully updated." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" } }, "security": [ { "basicAuth": [] } ], "summary": "Update template", "tags": [ "Personalization" ], "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" } }, "/api/user/messages/batch-delete": { "post": { "description": "Deletes multiple Message Center messages (up to 50 messages per request) completely, removing them from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.\n\nIt is not possible to delete Message Center messages generated by an automation, a recurring message, or a Sequence.\n", "operationId": "batchDeleteMessages", "requestBody": { "content": { "application/json": { "schema": { "description": "An array of message IDs, each uniquely identifying a Message Center message.", "properties": { "message_ids": { "description": "Array of Message IDs.", "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "message_ids" ], "type": "object" } } }, "description": "A request body containing an array of message IDs to be deleted." }, "responses": { "202": { "$ref": "#/components/responses/202" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] } ], "summary": "Delete multiple messages from inbox", "tags": [ "Push" ] } }, "/api/user/messages/{push_id}": { "delete": { "description": "Delete a Message Center message completely, removing it from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.\n\nThis delete call will work with either the `message_id` or the `push_id` of the accompanying push notification.\n\nThis endpoint will not work with a `group_id` from an automated message or a push to local time delivery. To delete a rich message that was part of an automated or local time delivery, you must use the relevant `push_id` from the operation.\n", "operationId": "deleteMessage", "parameters": [ { "description": "The `push_id` or `message_id` of the Rich Message you want to delete from users` inboxes.", "in": "path", "name": "push_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "202": { "$ref": "#/components/responses/202" }, "404": { "$ref": "#/components/responses/404" } }, "security": [ { "basicAuth": [] } ], "summary": "Delete message from inbox", "tags": [ "Push" ], "x-note": "For time-sensitive messages, consider including an `expiry` time as detailed in the [In-App Message Object](/developer/rest-api/ua/schemas/others/#inappobject). Setting an `expiry` value eliminates the need to manually remove messages." } }, "/token": { "post": { "description": "Request an OAuth access token with Basic Auth or an assertion. When making a request with an assertion, do not provide the Basic Auth header. See also [OAuth 2.0](/guides/getting-started/developers/api-security/#oauth-20) in the *Airship API Security* documentation.\n\nUse `oauth2.asnapius.com` for Airship's North American cloud site and `oauth2.asnapieu.com` for Airship's European cloud site when requesting an OAuth token.", "operationId": "requestOauthToken", "parameters": [ { "description": "The request must have a `Content-Type` of `application/x-www-form-urlencoded`.", "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/requestTokenBasicAuth" }, { "$ref": "#/components/schemas/requestTokenWithAssertion" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/okOauthTokenResponse" } } }, "description": "Returned on token request success.", "headers": { "Cache-Control": { "schema": { "enum": [ "no-store" ], "type": "string" } }, "Content-Type": { "schema": { "enum": [ "application/json" ], "type": "string" } }, "Pragma": { "schema": { "enum": [ "no-cache" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorResponseObject" } } }, "description": "Token not generated." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unauthorizedErrorResponseObject" } } }, "description": "Unauthorized.", "headers": { "WWW-Authenticate": { "schema": { "description": "The HTTP authentication methods that can be used to request an access token.", "type": "string" } } } }, "406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notAcceptableResponseObject" } } }, "description": "Not acceptable." } }, "security": [ { "basicOauth": [] } ], "summary": "Request token", "tags": [ "OAuth" ], "x-note": "When using the OAuth token for Airship API endpoints, make sure your requests are using the appropriate [domain in the base URL](/developer/rest-api/ua/introduction/#servers).\n\nThis example uses the OAuth token to list channels on Airship's North American cloud site: {{< highlight \"bash\" >}} curl --location 'https://api.asnapius.com/api/channels/' \\\n --header 'Accept: application/vnd.urbanairship+json; version=3;' \\\n --header 'Authorization: Bearer {OAUTH_ACCESS_TOKEN}'\n{{< /highlight >}}\n\n" } }, "/verify/public_key/{kid}": { "get": { "description": "Retrieve the public key of a key ID. Use `oauth2.asnapius.com` for Airship's North American cloud site and `oauth2.asnapieu.com` for Airship's European cloud site when verifying an OAuth public key.", "operationId": "getKeyVerification", "responses": { "200": { "content": { "application/x-pem-file": { "schema": { "description": "The PEM-formatted public key.", "type": "string" } } }, "description": "Returned on success with the public key for the given `kid`.", "headers": { "Cache-Control": { "schema": { "description": "The response contains a `Cache-Control` header which must be respected.", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "description": "The error includes as much information as possible to help you understand the reason for the failure." } } }, "description": "The requested resource doesn't exist." } }, "summary": "Verify public key", "tags": [ "OAuth" ] }, "parameters": [ { "description": "The private key ID used to sign the token. Example: `8817e96`", "in": "path", "name": "kid", "required": true, "schema": { "type": "string" } } ] } }, "servers": [ { "description": "The base URL for Airship's North American cloud site when using HTTP authentication", "url": "https://go.urbanairship.com" }, { "description": "The base URL for Airship's European cloud site when using HTTP authentication", "url": "https://go.airship.eu" }, { "description": "The base URL for Airship's North American cloud site when using OAuth authentication", "url": "https://api.asnapius.com" }, { "description": "The base URL for Airship's European cloud site when using OAuth authentication", "url": "https://api.asnapieu.com" } ], "tags": [ { "description": "Request an OAuth 2.0 token using Basic Auth or an assertion.", "name": "OAuth", "x-card-description": "OAuth 2.0 token management" }, { "description": "Send notifications or rich messages to supported channels, or validate JSON payloads.", "name": "Push", "x-card-description": "Send and validate push notifications" }, { "description": "Schedule notifications.", "name": "Schedules", "x-card-description": "Schedule notifications for delivery", "x-important": "The API prohibits batch sizes of larger than 1,000 for scheduled pushes, and batches of larger than 100 for push to local time scheduled pushes." }, { "description": "Manage Automated notifications using the `/api/pipelines` endpoints.", "name": "Automation", "x-card-description": "Automated message pipelines", "x-note": "In the dashboard UI, we refer to pipelines as *Automation* or *Automated Messages*.\n" }, { "description": "Create A/B Tests using the `/api/experiments` endpoint. An experiment or A/B test is a set of distinct push notification variants sent to subsets of an audience. You can create up to 26 notification variants and send each variant to an audience subset.", "name": "A/B Tests", "x-card-description": "Create and manage A/B test experiments", "x-important": "The A/B Tests API is unrelated to the [current version of A/B testing](/guides/experimentation/a-b-tests/messages/). For more information about this API, including its dashboard equivalent, see [Legacy message A/B tests](/guides/experimentation/a-b-tests/messages-legacy/)." }, { "description": "Use the `/templates` API to create templates and push templatized notifications.", "name": "Personalization", "x-card-description": "Create and use message templates", "x-note": "The Personalization (`/templates`) API is deprecated. Instead, [create templates in the Airship dashboard](/guides/personalization/content/templates/) or use the [Content API](/developer/rest-api/ua/operations/content/), and send using the [Bulk sending](/developer/rest-api/ua/operations/bulk-sending/) or [Automation](/developer/rest-api/ua/operations/automation/) APIs.\n" }, { "description": "Use the Content API to create content templates that can be sent in pushes and [managed in the Airship dashboard](/guides/personalization/content/templates/).", "name": "Content", "x-card-description": "Create and use content templates" }, { "description": "The Region API endpoints provide a listing and detail for all of your defined entry/exit regions, including custom shapes (polygons) and circles (point/radius).", "name": "Regions", "x-card-description": "Manage geofence regions" }, { "description": "User events that occur outside of your app can be submitted to Airship for inclusion in analytics reporting, as triggers for Automation, or for export via Connect. These events can take place on the web, e.g., your website, social media, or in your back office systems such as CRM or POS software. Any event that can be associated with a mobile app user can be submitted as an Airship custom event. The events that you submit are associated with channels and are available to use as custom event triggers.", "name": "Custom Events", "x-card-description": "Submit events from external systems" }, { "description": "Channels are Airship's unique identifiers for addressing applications on iOS, Android, Fire OS, and web devices.", "name": "Channels", "x-card-description": "Manage app and web channels" }, { "description": "Open Channels are custom communication channels that you can configure for messaging, using the same segmentation and scheduling tools available on natively-supported platforms (iOS, Android, etc.). With Open Channels, you define a new open platform, e.g., SMS, Slack, Acme™ Smart Toasters, and register the new platform with Airship.\n\n If you are sending through the [Push API](/developer/rest-api/ua/operations/push/), platform overrides for open platforms are covered in [Open Channel Overrides](/developer/rest-api/ua/schemas/platform-overrides/#openchanneloverrideobject). For open channel lookup, use the [Channel Lookup endpoint](/developer/rest-api/ua/operations/channels/#getchannel).", "name": "Open Channels", "x-card-description": "Configure custom messaging channels" }, { "description": "Register email channels, set opt-in status, and manipulate tags on email channels.", "name": "Email", "x-card-description": "Register and manage email channels" }, { "description": "Register and manage SMS channels. See [SMS Platform Information](/developer/api-integrations/sms/) to get started with SMS notifications.", "name": "SMS", "x-card-description": "Register and manage SMS channels" }, { "description": "A Named User is a proprietary identifier that maps customer-chosen IDs, e.g., CRM data, to Channels. It is useful to think of a Named User as an individual consumer who might have more than one mobile device registered with your app. For example, Named User \"john_doe_123\" might have a personal Android phone and an iPad, on both of which he has opted in for push notifications. If you want to reach John on both devices, associate the Channel (device) identifiers for each device to the Named User \"john_doe_123,\" and push to the Named User. Notifications will then fan out to each associated device.", "name": "Named Users", "x-card-description": "Map user IDs to channels" }, { "description": "Operations to assign or unassign tags for Channels and Named Users. Tags belong to tag groups and can help you organize channels using identifiers relevant to your operations. See the linked for information about, and strategies for using, tag groups.\n", "name": "Tags", "x-card-description": "Assign and manage tags", "x-note": "If you previously used the `/api/tags` endpoint to set tags, it is strongly recommended that you transition to the endpoints and methods specified in this document." }, { "description": "Segments are portions of your audience that have arbitrary metadata (e.g., tags, location data, etc.) attached. You can create, delete, update, or request information on a segment via the `/api/segments/` endpoint. Pushing to a segment is done through the `/api/push/` endpoint. See the [Audience selection](/developer/rest-api/ua/schemas/audience-selection/) section for more information.", "name": "Segments", "x-card-description": "Create and manage audience segments" }, { "description": "Set Text, Number, and Date attributes on channels or Named Users in bulk by uploading a CSV.", "name": "Attribute Lists", "x-card-description": "Set attributes in bulk by CSV upload", "x-note": "To set JSON attributes, use the [Set or Remove Attributes on Channels](/developer/rest-api/ua/operations/channels/#modifychannelattributes) or [Set or Remove Attributes on Named Users](/developer/rest-api/ua/operations/named-users/#modifynameduserattributes) endpoint, or the Airship SDKs. For more information, see [Setting and removing JSON Attributes](/guides/audience/attributes/setting/#setting-and-removing-json-attributes)." }, { "description": "With the Static List API endpoint, you can target and manage lists of devices that are defined in systems outside of Airship. Any list or grouping of devices for which the canonical source of data about the members is elsewhere is a good candidate for Static Lists, e.g., members of a customer loyalty program. In the dashboard, they are referred to as [Uploaded Lists](/guides/audience/segmentation/audience-lists/uploaded/).\n\nAirship automatically deletes a Static list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period are the creation date, when updating list contents or metadata, and when sending a message (pushing) to the list. The creation date is the initial day one of the 90-day period. Each instance of updating or sending to the list resets the timestamp to day one.\n\nAfter automatic deletion or deleting from the Airship dashboard, the list is removed from the upload history, is no longer visible in the Airship dashboard or through API calls, and is no longer available for audience segmentation.", "name": "Static Lists", "x-card-description": "Manage static device lists" }, { "description": "Target recipients of a single channel type by providing audience identifiers at send time. Bulk sending supports two methods:\n\n* **Upload and Send** targets existing channels by Channel ID across app, web, email, SMS, and Open channels. Upload a CSV of Channel IDs to the [Create bulk send audience](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) endpoint to obtain a `bulk_id`, and then send your message using the [Send message with bulk ID](/developer/rest-api/ua/operations/bulk-sending/#bulksendpush) or [Schedule message with bulk ID](/developer/rest-api/ua/operations/bulk-sending/#schedulebulksendpush) endpoint.\n\n* **Create and Send** sends to email addresses, MSISDNs, or Open channel addresses. Unknown identifiers are registered as new channels.\n\n * For smaller audiences, use the [Create and Send a message](/developer/rest-api/ua/operations/bulk-sending/#createandsend) or [Schedule a Create and Send message](/developer/rest-api/ua/operations/bulk-sending/#schedulecreateandsendoperations) endpoints to provide email addresses, MSISDNs, or Open channel addresses in an array.\n\n * For larger audiences, upload identifiers in CSV format to the [Create bulk send audience](/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) endpoint to obtain a `bulk_id`, and then send your message using the [Create and Send a message](/developer/rest-api/ua/operations/bulk-sending/#createandsend) or [Schedule a Create and Send message](/developer/rest-api/ua/operations/bulk-sending/#schedulecreateandsendoperations) endpoint.\n\n\nSee the [Bulk sending](/guides/audience/segmentation/bulk-sending/) guide for more information.\n", "name": "Bulk Sending", "x-card-description": "Send to audiences via CSV upload" }, { "description": "Report API endpoints let you retrieve information about push notifications that you have sent.", "name": "Reports", "x-card-description": "Retrieve push notification reports" }, { "description": "Manage Contacts and query for subscription lists, channels, named users, and attributes associated with a Contact.", "name": "Contacts", "x-card-description": "Manage contacts and associations" }, { "description": "Use Contact Management to record data privacy requests for your customers.", "name": "Data Privacy Laws Compliance", "x-card-description": "Handle data privacy requests" }, { "description": "Create, manage, and add or remove channels from subscription lists.", "name": "Subscription Lists", "x-card-description": "Manage email subscription lists" }, { "description": "Manage tag lists for organizing and applying tags in bulk.", "name": "Tag Lists", "x-card-description": "Manage tag lists", "x-note": "You cannot update channel information or opt-in status from these endpoints. To update channels, use the appropriate channel registration endpoints." }, { "description": "The phrases \"total audience\" and \"billable count\" are interchangeable. They both refer to the number of channels that were in an installed state at any point in a given month. A channel's billable state differs from its installed state only in that a device is billable until the last day of the calendar month in which it is uninstalled. Month boundaries are determined using UTC time zones, and all provided timestamps and dates are UTC as well. Customers can choose to be billed on their total audience. These endpoints allow them to query for the counts that we use to calculate their bill.", "name": "Billing", "x-card-description": "Query billable audience counts" } ], "x-schema-tags": [ { "description": "Event segmentation lets you target audiences based on lifecycle actions or custom events that have occurred.\n\nTo segment based on event activity, include an [Activity Object](/developer/rest-api/ua/schemas/event-segmentation/#activityobject) in your audience, and an optional [Where Object](/developer/rest-api/ua/schemas/event-segmentation/#whereobject) to filter on specific event properties.\n", "name": "Event segmentation", "x-card-description": "Target audiences by events" }, { "description": "Attributes appear on channels and Named Users. You can target an audience using attribute selectors. Available attribute types are Text, Number, Date, and JSON.\n", "name": "Attributes", "x-card-description": "Channel and user attributes", "x-tip": "Use [compound selectors](/developer/rest-api/ua/schemas/audience-selection/#compoundselector) to negate (NOT) or select a value range.\n" }, { "description": "Success and error responses typically conform to the following formats.", "name": "Responses", "x-card-description": "API response formats" }, { "description": "Override push settings and provide content for specific platforms (selected by `device_type`). The following schemas represent overrides for each platform.", "name": "Platform overrides", "x-card-description": "Platform-specific push overrides" }, { "description": "Override push settings and provide content for specific platforms (selected by `device_type`) using a `template`. Templated platform overrides automatically allow personalization using [Handlebars](/guides/personalization/handlebars/).", "name": "Platform overrides with templates", "x-card-description": "Templated platform overrides", "x-note": "The `fields` key under `template` is deprecated. This method is still supported, but has been superseded by using `{{handlebars}}` directly in the payload." }, { "description": "The following schemas represent ways to target by location, region, or geofence.", "name": "Regions", "x-card-description": "Location and geofence targeting" }, { "description": "Objects that help you select and target an audience.", "name": "Audience selection", "x-card-description": "Audience targeting and selection" }, { "description": "Schedule notifications for delivery.", "name": "Schedules", "x-card-description": "Schedule notifications for delivery" }, { "description": "Personalization template objects, including pushes to templates and template listing.\n", "name": "Personalization template objects", "x-card-description": "Template objects for personalization" }, { "description": "Schemas for [Content](/developer/rest-api/ua/operations/content/) templates and per-channel `content` payloads.\n", "name": "Content objects", "x-card-description": "Content objects for personalization" }, { "description": "Objects and samples for `/pipelines` ([Automation](/developer/rest-api/ua/operations/automation/)) endpoints.", "name": "Pipeline objects", "x-card-description": "Automation pipeline objects" }, { "description": "Objects and samples for [`/create-and-send`](/developer/rest-api/ua/operations/bulk-sending/#createandsend)\nendpoints. A full object can contain parts of schedule, template, audience, and platform override objects (for `email`, `sms`, or `open::` platforms).\n\nThe `notification` payload for Create and Send objects supports both\nstored and inline templates. Using inline templates, you can define and\npopulate variables to personalize notifications to your new channels.", "name": "Create and Send", "x-card-description": "Create and Send message objects", "x-note": "You cannot update channel information or opt-in status using Create and Send. If you want to update channels, refer to the appropriate email, SMS, or open channel endpoints." }, { "description": "A push request property specifying which [external data feeds](/guides/personalization/sources/external-data-feeds/) should be invoked and with what parameters in order to support personalization from feed content.\n", "name": "External Data Feeds references", "x-card-description": "External data feed references", "x-important": "You must first [create an external data feed in the dashboard](/guides/personalization/sources/external-data-feeds/), then you can refer to its ID as the `name` in the feed references object. The Coupons service is a type of external data feed. See [Coupons](/guides/personalization/sources/coupons/) for formatting and usage information." }, { "description": "Schemas for OAuth token requests, including scopes, assertion JWTs, and subject identifiers.", "name": "OAuth", "x-card-description": "OAuth scopes and authorization" }, null, { "description": "A Named User is a proprietary identifier that maps customer-chosen IDs, e.g., CRM data, to Channels. Schemas for managing Named Users, their associations, and updates.\n", "name": "Named User", "x-card-description": "Named User data formats" }, { "description": "Schemas for bulk sending operations, including scheduled bulk sends. Bulk sending allows you to target recipients by providing audience identifiers at send time.\n", "name": "Bulk sending", "x-card-description": "Bulk sending data formats" }, { "description": "Subscription Lists are lists of channels that can be used to target messages to specific groups of users.\n", "name": "Subscription Lists", "x-card-description": "Manage subscription lists" }, { "description": "Tags are labels that can be applied to channels and Named Users to help you organize and target your audience.\n", "name": "Tags", "x-card-description": "Manage tags" }, { "description": "Schemas for managing Contacts, including batch operations, anonymous contact resolution, and channel contact operations.", "name": "Contacts", "x-card-description": "Contact management schemas" }, { "description": "Schemas for billing-related operations, including billable audience counts and channel state information.", "name": "Billing", "x-card-description": "Billing and billable state schemas" }, { "description": "Core schemas for push notifications, including push objects, notification payloads, Message Center messages, in-app messages, and related response objects.", "name": "Push", "x-card-description": "Core push notification schemas" }, { "description": "Schemas for app configuration operations, including setting and deleting configuration values.", "name": "App config", "x-card-description": "App configuration schemas" }, { "description": "Schemas for frequency constraints and limits used in automations and messaging.", "name": "Frequency constraints", "x-card-description": "Frequency constraint schemas" }, { "description": "Schemas for channel management, including channel objects, registration, updates, and channel associations.", "name": "Channels", "x-card-description": "Channel management schemas" }, { "description": "Schemas for In-App Automation, including message objects, triggers, display components, actions, and automation configuration.", "name": "In-App Automation", "x-card-description": "In-App Automation schemas" }, { "description": "Schemas for audience limits, additional audience checks, and ban list parameters.", "name": "Audience limits", "x-card-description": "Audience limits and checks" } ] }