How Messages and Passes Work

Learn how Airship gets messages and wallet passes to your users.

See also: Intro to Messages and the Mobile Wallet feature guide.

How Messages Work

Before you can send messages, you need:

  1. An app or website integrated with the Airship SDK. The SDK enables communications with mobile devices and web browsers. However:

    • SMS and email notifications do not require an app or website.
    • Notifications sent to Open Channels do not require SDK integration, but your webhook server must be able to process and interpret a JSON payload.
  2. A container for your messages. This is the project. You will create a project for each app or website you want to communicate with.

  3. An audience of your app’s or website’s opted-in users.

    • Apple News notifications are sent to Apple News subscribers. The Apple News audience management is not handled via Airship.

With those things in place, then:

  1. You create a message.

  2. Your app or website interprets the message via the Airship SDK, displaying or delivering it to users.

    • SMS, email, and Apple News notifications are interpreted by a native client, and do not use or require the SDK.
  3. Users see your message.


To take advantage of Airship, you must have an app, website, or another medium, e.g, SMS, email, etc., that you want to use to communicate with your users.

Apps and Websites

Your app or website must include the Airship SDK. The SDK is the mechanism for registering your users as channels in Airship, making them eligible to receive non-SMS messages. The SDK also interprets message payloads that you send to your users and tracks user trends within your app.

The SDK also enables Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. , Channel CoordinationA group of strategies you can use to target users where they are most likely to receive your message. , and predictive features: Predictive ChurnAnalyzes your audience for users that exhibit behaviors indicating they are likely to become inactive, and tags the users as High, Medium, or Low Risk. and Optimal Send TimeAn algorithm that determines the best hour for optimal engagement activity — when each individual member of your audience is most likely to receive and act on your message. iOS, Android, and Amazon platforms only. .

SMS, Email, and Open Channels

You do not need to use the Airship SDK for SMS, email, or open channels. However, these channels typically require you to use the API to register new channels and perform other features.

SMS and email are native messaging channels; you can register users via the API, but you don’t need to do anything special to communicate with your users via SMS or email.

However, while email and SMS channels are convenient mediums and easy to set up, they do not provide the orchestration and predictive features that help you better understand your user base. Data and analytic features generally require the SDK.

Open channels are platforms that are not natively supported by the Airship SDK. To use Airship with open channels, your open platform, e.g., chatbot, Slack integration, must be able to accept and interpret a JSON payload. Typically you will enable the delivery of the payload via a webhook server. See: Open Channels.

Your Project

Almost everything you do with Airship, including creating messages, happens inside a project. A project is essentially Airship’s representation of your app or website. A project:

  • Is a record for your app, website, and any other channels you use to communicate with your audience.

  • Stores your message history, message templates, audience and analytic data, channel configuration, and default message configuration settings.

  • Contains the keys required to talk to various notification services.

You make use of all Airship features from within a project or using your project’s app key. Each of your apps or websites requires an individual Airship project, which will have separate application keys and audiences. See: The SDKs and APIs: Authentication.

You create projects in the DashboardThe Airship web interface located at or .

Your Audience

Your audience is the set of users that you want to send messages to.

Channels and Channel IDs

The underlying representation of an audience member is a channel, which is represented by a unique identifier, the channel ID. A channel contains all the necessary information that you (and the Airship service) need to communicate with your users, including but not limited to: metadata used for targeting, associations with other Airship or third-party identifiers, opt-in/opt-out status, orchestration data, and more.

To target a channel directly, use the channel_id which you will find in the channel object. The channel ID is a UUID representing an individual device, e.g., smartphone, browser, email address, etc.

Channel IDs are the atomic units of an audience and are assigned upon initial registration of a user. In the case of app and web users, our SDK creates the channel automatically. For email, SMS, and open channels, you must use our channel registration API to generate an addressable channel.

In most cases, however, it’s not necessary to know the channel ID for each user in order to target either an individual user or groups of users. We have a number of other ways to group and target users such as tags, tag groups, audiences lists, segments, etc. See Segmentation for details about other targeting mechanisms.

Selecting an Audience

In most cases, you won’t concern yourself with individual channel IDs. You will instead select an audience based on things your channel IDs have in common. First you’ll select which channels to address: Android, iOS, SMS, etc. Then you’ll either select your entire audience, or just a section of your audience, based on tags, segments, and other identifying characteristics.

This is represented in the dashboard as:

  • All Users sends the message to your entire audience.

  • Target Specific Users lets you create a recipient group based on segmentation data. See: Segmentation.

  • Test Users are predefined recipient groups. After choosing Test Users, select from the Test Groups dropdown menu that appears. See: Test Groups.

  • Upload Users lets you upload a list of users just before sending the message. See: Message Composer Tutorial: Upload Users.


Airship groups channel IDs by tag, named user, segments, audience lists, and more. In addition to your own tags, Airship’s predictive features group users based on how they use your app, their time zone, and other data reported by the SDK. You can use these grouping mechanisms to target specific sections of your audience.


Tags are plain-text identifiers for channel_ids. Some tags are assigned by Airship as the SDK gathers relevant, identifying information from the SDK, e.g., time zone, locale, etc. But, in many cases, you can assign tags to users arbitrarily or based on actions within your app and in response to messages. For example, you might use tags to determine where a customer is in a particular engagement funnel — not opening notifications, opening notifications, acting on notifications, etc. See: Tags.

Named Users

A named user is set of channel_ids that represent a single user. For example, if a user logs into your website and app, a named user groups those channels into a single entity, so you can better understand a customer’s behavior.

Named users are typically assigned by the SDK. You don’t have use an external system or otherwise figure out which channel IDs belong to which people; we do that for you. Named users have most of the same characteristics as channel IDs; you can assign tags to them, select audiences of named users, etc. Named users are the atomic unit for Airship’s analytic features. You have to use named users to take advantage of the system’s predictive features. See: Named Users.

Audience Lists

Use audience lists to create recipient groups based on either your own uploaded data or automatically generated lifecycle information.

  • Lifecycle lists are automatically generated by Airship and capture app open, uninstall, notification, and dormancy information. Lifecycle List auto-generation may be disabled.

  • Uploaded lists are created by you, static, updatable, and can be reused.These are known as static lists in the API.

    Unlike tags and named users, which are set in response to client or can otherwise change without your direct intervention, static lists retain a list of users until you decide to change the list. Use an Uploaded list to generate a point-in-time audience.

  • Inline lists are created by you at the time of sending a message for that message only, and any previously unregistered address will be registered as a new channel at send time. They are not stored for reuse. Inline lists are used with SMS, Email, and Open channels only.

See: Audience Lists.


A segment is a grouping of audience members selected by unique or shared identifiers. Multiple identifiers can be combined within a segment. See: Segmentation and Segment Builder Tutorial.

Create Messages

You can create and send messages via the API or the dashboard. In the dashboard you choose composers, which provide various message types, delivery rules, automation, and other options you can employ for your messages. Learn more in Message and Composer Types.

How Passes Work

A pass is the product of a link generated from a template contained within a mobile wallet project:

In general, the process of getting a pass to your audience is as follows.


  1. Create your project.
  2. Design the pass. This is the template.
  3. Generate a URL that points to the pass. This is the pass link.
  4. Distribute the pass link to recipients.

The recipients:

  1. Open the pass link and view the pass.
  2. Install the pass to their Apple Wallet or Google Pay digital wallets.

Create and Design

The first step of creating a pass is creating a project that will store the templates for that pass type. Projects can contain both Apple Wallet and Google Pay templates for a single pass type.

You must then design a template for your pass. The template holds the design, field information, and default field values for your pass. If designing passes to support both Apple Wallet and Google Pay users, you will design two templates, one for each platform.

You will then create a link to the pass that users can tap or click to install the pass. Android pass URLs can also be provided in a Save to Google Pay button. This pass URL can either be platform-specific — for either iOS or Android users — or you can create an Adaptive Link.

Adaptive links are the preferred pass-creation method. An Adaptive Link detects the recipient’s platform and installs the appropriate pass. Instead of sending an Apple Wallet pass URL to one recipient group and a Google Pay pass URL to another (or both URLs to all recipients), you can associate the two templates using an Adaptive Link, then distribute that single Adaptive Link to all intended recipients.


While you can use a Wallet project to create passes, you cannot distribute passes via a Wallet project. Since the pass is essentially a URL, you can send the pass however you would send any URL, such email or SMS. See the various pass distribution methods.

It’s important to remember that you are sending a link to install a pass, not attachment to a message body. You should send a pass over a medium that you expect to reach your audience and persist, in case a user decides to dismiss a notification alert and install the pass at a later time.

If you are also an Airship messaging customer, you can include the pass URL with all our message types. Depending on the message type you choose, you can link to the pass:

  • When the user taps or clicks the notification.
  • When the user taps a button.
  • From the body of the message.


A user receives the pass URL, opens the URL, and then has the option to install the pass. The user only needs to install the pass once. They can then open the pass from Apple Wallet, Google Pay, or an app that relies on the respective Apple and Google APIs.

Update Content

After a user installs a pass, you can seamlessly update the pass as event information, gift card balance, loyalty points, and other information changes, so that your users are always up to date.

By updating an already-installed pass, you can ensure that your customers never miss their gates, and that they take advantage of the loyalty programs that bring them back to your business.

You can optionally continue to update content and appearance of a pass that has already been installed by a recipient. See: Publish Tutorial.

Get Started


To get messages to your users, you need:

  • An Airship account.
  • An app or website.
  • A project to contain your messages.

Follow the steps in the messaging project tutorials to get started.


Try sending messages now, using our 1st Flight app. No development required!


To get passes into the hands (devices!) of your users, you need:

  • An Airship account.
  • A certificate for Apple Wallet or Google Pay.
  • A project to contain your certificate, templates, pass URLs, and other settings and information.
  • A template to generate your passes from.

The Wallet Getting Started Guide walks you through the whole process, with links to individual tutorials for each step.