SMS Notification Tutorial

An SMS notification is a message that you can send to an MSISDN (phone number) over the SMMP protocol to devices that have opted in for a specific sender ID (long or short code). SMS messages appear in recipients' native SMS clients.

See the SMS Notification Reference for options and settings details.

Resources:

 Tip

You can save this message as a Composer Favorite — a reusable message with preset settings and content. You can use Composer Favorites instead of recreating commonly used messages. See: Use Composer Favorites.

  1. Click Create and select Message.

  2. (Optional) Add a message name and/or flag the message as a test.
    1. Click   in the header.
    2. Enter the name.
    3. Enable Test.
    4. Click outside the box to close it.

    See also: Name a Message and Flag a Message as a Test.

  3. Define your message Audience.

    1. Select the SMS channel. When SMS is the only enabled channel, the composer is reduced to only fields and settings relevant to SMS notifications.

    2. Select the group of users you want to send your message to.
      • All Users: Sends the message to your entire audience.
      • Target Specific Users: Create a recipient group based on segmentation data. See: Target Specific Users.
      • Test Users: Predefined recipient groups. After choosing Test Users, select from the Test Groups dropdown menu that appears. See: Test Groups.
      • Upload Users: Upload a list of users just before sending the message. Select this option if you want to include merge fields in your message. See: Upload Users.
       Important

      If you are using merge fields in your HTML, you must select Upload Users.

       Note

      If your project has multiple senders, you can target specific users belonging to a Sender ID to determine the sender that the message comes from and ensure that your message only goes to members of your audience subscribed to that sender.

    3. Click Content in the header to move on.

  4. Add your message Content.

    1. Select Text Message (SMS). You will only see this option if your project is also configured for MMS. Otherwise, you will go directly to the text-entry screen.

    2. Enter your message text. The character count and the total number of SMS notifications update as you type.
      • Include merge fields or Dynamic ContentVariable message content using handlebar syntax that you populate at send time. Use dynamic content to personalize messages for each member of your audience. if you selected Upload Users for your audience. The character and notification counts do not account for the varying lengths of merge values, so they should only be used as an estimate when using merge fields.

      • If your message includes links, you can enable or disable Link ShorteningConverts HTTP/HTTPS URLs in your SMS messages to unique, shortened URLs for your recipients. The shortened URLs reduce the total number of characters that links consume and produce ‘click’ tracking metrics for your SMS messages. . When enabled, the message and character counts reflect your message with shortened link URLs.

      • If your message includes links and Shorten Links is enabled, click Set Tags to add or remove tags for members of your audience who engage with your link. Tag actions add query parameters to your URL, but users will still see the shortened URL in your SMS messages.

       Note

      If you create a new tag when adding tag actions, it will belong to the device group for associated SMS channels.

    3. Click Delivery in the header to move on.

  5. Set Delivery options for your message.

    1. Select a delivery type.

      Send now Send the message immediately after review.
      Schedule

      Choose an exact time of day to send the message.

      1. Enter a date in YYYY-MM-DD format and select the time and time zone.

      2. (Optional) Select Delivery By Time Zone to deliver messages at the specified time in your audience’s time zone(s). For example, a push notification scheduled for 9 a.m. will arrive for people on the east coast at 9 a.m. Eastern Time, in the midwest an hour later at 9 a.m. Central Time, then on the west coast two hours after that, at 9 a.m. Pacific Time.

         Note

        A message delivered by time zone includes a Delivery by Time Zone section in its message report. See: View Message Detail.

         Tip

        The API equivalent of Delivery By Time Zone is Push to Local Time.

      Recurring

      Send the message periodically at specified intervals. You may want to send recurring messages for things like payment reminders. You can pause, resume, and cancel recurring messages in Messages Overview.

       Note

      Segmentation data is evaluated at send time. For example, if your recurring message targets an audience list whose members change over time, each recurring message is sent to the current version of the list when the message is sent.

       Note

      Recurring messages that include multi-language localized content cannot be edited.

      1. Specify the delivery interval by number of hours/days/weeks/months/years. If you selected weeks, also specify which days of the week to send the messsage.

      2. Set the initial date. This is the first day Airship will send your message.

      3. Set the initial time. This is the time of day Airship will send each message.

      4. (Optional) Specify when to stop sending the message.

        1. Enable End date.
        2. Enter a date.
        3. Select the time and time zone.
      5. (Optional) Specify dates or days of the week when the message should not be sent. If you selected the hours interval for delivery, you can also specify which hours of the day should be excluded.

        If the scheduled send falls during an excluded period, Airship waits to send the message until the next available valid send time. For example, if you scheduled delivery weekly on Thursdays but added Thanksgiving Day as an exclusion, the next send would be the Thursday after Thanksgiving.

        1. Enable Do not send.
        2. Click Add date exclusion, enter a date, and repeat for additional dates.
        3. Click Add day exclusion and select days.
        4. Click Add time exclusion and set start and end times.

    2. Set Optional Features.

    3. If your message includes External Data FeedsA connection to an external API. When you send a message, Airship uses a response from that API to personalize messages. , you must configure each feed listed in External data feed options.

      Failure behavior Determine how your message is handled if the feed fails. Select Abort sending the message or Send message without this data.
      Default value for [var]

      This displays the default value for each message-level variable used in your data feed’s request URL. You set the default value when you Add a data feed in your project’s settings.

      You can change the value to override the default for this message only.

    4. Click Review in the header to move on.

  6. Review your message.

    1. If you want to make changes, click the associated step in the header, make your changes, then return to Review.

    2. (Optional) Send a test message and verify its appearance and behavior on each channel the message is configured for.

      The message is sent to your selected recipients immediately, and it appears as a test in Messages Overview.

      1. Click Send Test.
      2. Enter at least one named user or Test GroupA reusable audience group that can be used as a recipient for test messages. Messages you send to a test group appear as tests in Messages Overview. and select from the results.
      3. Click Send.
    3. If you chose Upload Users in the Audience step, click Upload & Send and select your file. Uploaded merge field names will be verified against the merge fields set in the Content step.

    4. Click Send Message or Schedule Message.

Send an MMS Notification

You can send multi-media messages (MMS) to your SMS audience. MMS messages include a fallback, ensuring that users who can’t view the original MMS message still receive a message that makes sense.

When sending an MMS message, you can provide the URL for your image or upload it to Airship. If you do not upload to Airship, you should use image assets you control and a dedicated media host to prevent delivery errors. Do not use images hosted on a site where others could change or remove the images you want to use in your messages.

MMS messages must be:

  • .gif, .jpeg, .jpg, or .png format.
  • Hosted over HTTP or HTTPS (for media not hosted by Airship).
  • Smaller than 2 MB for .jpeg and .jpg.
  • Smaller than 1 MB for .png and .gif.
 Note

We recommend that you use images 650 KB or smaller to improve deliverability. In general, you should use the smallest possible image size to ensure that your audience receives messages quickly, regardless of connection quality.

See the SMS Notification Reference for options and settings details.

  1. Click Create and select Message.

  2. (Optional) Add a message name and/or flag the message as a test.
    1. Click   in the header.
    2. Enter the name.
    3. Enable Test.
    4. Click outside the box to close it.

    See also: Name a Message and Flag a Message as a Test.

  3. Define your message Audience.

    1. Select the SMS channel. When SMS is the only enabled channel, the composer is reduced to only fields and settings relevant to SMS notifications.

    2. Select the group of users you want to send your message to.
      • All Users: Sends the message to your entire audience.
      • Target Specific Users: Create a recipient group based on segmentation data. See: Target Specific Users.
      • Test Users: Predefined recipient groups. After choosing Test Users, select from the Test Groups dropdown menu that appears. See: Test Groups.
      • Upload Users: Upload a list of users just before sending the message. Select this option if you want to include merge fields in your message. See: Upload Users.
       Important

      If using merge fields in your message, you must select Upload Users.

       Note

      If your project has multiple senders, you can target specific users belonging to a Sender ID to determine the sender that the message comes from and ensure that your message only goes to members of your audience subscribed to that sender.

    3. Click Content in the header to move on.

  4. Add your MMS message Content.

    1. Select Image Message (MMS).

    2. Provide the Media for your message.
      • URL: Enter the address of your image, beginning with HTTP or HTTPS and ending with the image extension.

      • Upload: Click Upload Media and select your image.

    3. Configure MMS Options.
      1. (Optional) Enter a Subject and/or Text Message to accompany your image, including merge fields if you selected Upload Users for your audience. The subject appears in bold, but it might not appear if you are sending from a toll-free number.

      2. Enter SMS Fallback Text. Users who cannot receive your MMS message will receive this text along with the image URL.

      3. If the text fields in your message include links, you can enable or disable Link ShorteningConverts HTTP/HTTPS URLs in your SMS messages to unique, shortened URLs for your recipients. The shortened URLs reduce the total number of characters that links consume and produce ‘click’ tracking metrics for your SMS messages. . When enabled, the message and character counts reflect the length of your message with shortened link URLs.

       Note

      There is no guarantee as to the order in which media and text appear to users. Media and text send separately.

    4. Click Delivery in the header to move on.

  5. Select Delivery options for your message.

    1. Select a delivery type.

      Send now Send the message immediately after review.
      Schedule

      Choose an exact time of day to send the message.

      1. Enter a date in YYYY-MM-DD format and select the time and time zone.

      2. (Optional) Select Delivery By Time Zone to deliver messages at the specified time in your audience’s time zone(s). For example, a push notification scheduled for 9 a.m. will arrive for people on the east coast at 9 a.m. Eastern Time, in the midwest an hour later at 9 a.m. Central Time, then on the west coast two hours after that, at 9 a.m. Pacific Time.

         Note

        A message delivered by time zone includes a Delivery by Time Zone section in its message report. See: View Message Detail.

         Tip

        The API equivalent of Delivery By Time Zone is Push to Local Time.

      Recurring

      Send the message periodically at specified intervals. You may want to send recurring messages for things like payment reminders. You can pause, resume, and cancel recurring messages in Messages Overview.

       Note

      Segmentation data is evaluated at send time. For example, if your recurring message targets an audience list whose members change over time, each recurring message is sent to the current version of the list when the message is sent.

       Note

      Recurring messages that include multi-language localized content cannot be edited.

      1. Specify the delivery interval by number of hours/days/weeks/months/years. If you selected weeks, also specify which days of the week to send the messsage.

      2. Set the initial date. This is the first day Airship will send your message.

      3. Set the initial time. This is the time of day Airship will send each message.

      4. (Optional) Specify when to stop sending the message.

        1. Enable End date.
        2. Enter a date.
        3. Select the time and time zone.
      5. (Optional) Specify dates or days of the week when the message should not be sent. If you selected the hours interval for delivery, you can also specify which hours of the day should be excluded.

        If the scheduled send falls during an excluded period, Airship waits to send the message until the next available valid send time. For example, if you scheduled delivery weekly on Thursdays but added Thanksgiving Day as an exclusion, the next send would be the Thursday after Thanksgiving.

        1. Enable Do not send.
        2. Click Add date exclusion, enter a date, and repeat for additional dates.
        3. Click Add day exclusion and select days.
        4. Click Add time exclusion and set start and end times.

    2. Set Optional Features.

    3. If your message includes External Data FeedsA connection to an external API. When you send a message, Airship uses a response from that API to personalize messages. , you must configure each feed listed in External data feed options.

      Failure behavior Determine how your message is handled if the feed fails. Select Abort sending the message or Send message without this data.
      Default value for [var]

      This displays the default value for each message-level variable used in your data feed’s request URL. You set the default value when you Add a data feed in your project’s settings.

      You can change the value to override the default for this message only.

    4. Click Review in the header to move on.

  6. Review your message.

    1. Review the device preview and message summary. Click the arrows to page through the MMS and SMS fallback previews. You can also select a preview directly from the dropdown menu. If you would like to make changes, click the associated step in the header, make your changes, then return to Review.
    2. (Optional) Send a test message and verify its appearance and behavior on each channel the message is configured for.

      The message is sent to your selected recipients immediately, and it appears as a test in Messages Overview.

      1. Click Send Test.
      2. Enter at least one named user or Test GroupA reusable audience group that can be used as a recipient for test messages. Messages you send to a test group appear as tests in Messages Overview. and select from the results.
      3. Click Send.
    3. If you chose Upload Users in the Audience step, click Upload & Send and select your file. Uploaded merge field names will be verified against the merge fields set in the Content step.

    4. Click Send Message or Schedule Message.

Send a Templated SMS or MMS Notification

You must use the Upload Users option to send a notification using a template. You should have the user list that you want to upload ready before you begin this tutorial.

If your template includes handlebars, your user list can also include the data that you want to pass into your message when you upload users. For more information, see Handlebars and Dynamic Content.

  1. Click Create and select Message.

  2. (Optional) Add a message name and/or flag the message as a test.
    1. Click   in the header.
    2. Enter the name.
    3. Enable Test.
    4. Click outside the box to close it.

    See also: Name a Message and Flag a Message as a Test.

  3. Define your message Audience.

    1. Select the SMS channel.

    2. Select Upload Users. You will upload your user list just before sending the message.

    3. Click Content in the header to move on.

  4. Add your message Content.

    1. Select Text Message Template (SMS) or Image Message Template (MMS).

    2. Select the template you want to use and click Continue with Selected Template.
    3. (MMS templates only) Provide the Media for your message.
      • URL: Enter the address of your image, beginning with HTTP or HTTPS and ending with the image extension.

      • Upload: Click Upload Media and select your image.

    4. Click Delivery in the header to move on.

  5. Set Delivery options for your message.

    1. Select a delivery type.

      Send now Send the message immediately after review.
      Schedule

      Choose an exact time of day to send the message.

      1. Enter a date in YYYY-MM-DD format and select the time and time zone.

      2. (Optional) Select Delivery By Time Zone to deliver messages at the specified time in your audience’s time zone(s). For example, a push notification scheduled for 9 a.m. will arrive for people on the east coast at 9 a.m. Eastern Time, in the midwest an hour later at 9 a.m. Central Time, then on the west coast two hours after that, at 9 a.m. Pacific Time.

         Note

        A message delivered by time zone includes a Delivery by Time Zone section in its message report. See: View Message Detail.

         Tip

        The API equivalent of Delivery By Time Zone is Push to Local Time.

      Recurring

      Send the message periodically at specified intervals. You may want to send recurring messages for things like payment reminders. You can pause, resume, and cancel recurring messages in Messages Overview.

       Note

      Segmentation data is evaluated at send time. For example, if your recurring message targets an audience list whose members change over time, each recurring message is sent to the current version of the list when the message is sent.

       Note

      Recurring messages that include multi-language localized content cannot be edited.

      1. Specify the delivery interval by number of hours/days/weeks/months/years. If you selected weeks, also specify which days of the week to send the messsage.

      2. Set the initial date. This is the first day Airship will send your message.

      3. Set the initial time. This is the time of day Airship will send each message.

      4. (Optional) Specify when to stop sending the message.

        1. Enable End date.
        2. Enter a date.
        3. Select the time and time zone.
      5. (Optional) Specify dates or days of the week when the message should not be sent. If you selected the hours interval for delivery, you can also specify which hours of the day should be excluded.

        If the scheduled send falls during an excluded period, Airship waits to send the message until the next available valid send time. For example, if you scheduled delivery weekly on Thursdays but added Thanksgiving Day as an exclusion, the next send would be the Thursday after Thanksgiving.

        1. Enable Do not send.
        2. Click Add date exclusion, enter a date, and repeat for additional dates.
        3. Click Add day exclusion and select days.
        4. Click Add time exclusion and set start and end times.

    2. Set Optional Features.

    3. If your message includes External Data FeedsA connection to an external API. When you send a message, Airship uses a response from that API to personalize messages. , you must configure each feed listed in External data feed options.

      Failure behavior Determine how your message is handled if the feed fails. Select Abort sending the message or Send message without this data.
      Default value for [var]

      This displays the default value for each message-level variable used in your data feed’s request URL. You set the default value when you Add a data feed in your project’s settings.

      You can change the value to override the default for this message only.

    4. Click Review in the header to move on.

  6. Review your message.

    1. Review the device preview and message summary. If you would like to make changes, click the associated step in the header, make your changes, then return to Review.
    2. (Optional) Send a test message and verify its appearance and behavior on each channel the message is configured for.

      The message is sent to your selected recipients immediately, and it appears as a test in Messages Overview.

      1. Click Send Test.
      2. Enter at least one named user or Test GroupA reusable audience group that can be used as a recipient for test messages. Messages you send to a test group appear as tests in Messages Overview. and select from the results.
      3. Click Send.
    3. Click Upload & Send and select the CSV file containing your list of users and merge fields. Uploaded merge field names will be verified against the merge fields set in the Content step.

    4. Click Send Message or Schedule Message.

Upload Users

In the Audience step when sending a message, you can use the Upload Users feature to send your message to a CSV list of recipients. When uploading a list of SMS, email, or open channels, Airship both registers new users found in your list and sends your message.

 Tip

You can take advantage of this feature using our Create-and-send API to register and send messages to new email, SMS, or open channel users.

See Upload Users CSV Format for information about formatting your CSV. The first column of your CSV must contain the channel ID or address (email, MSISDN, etc.) for a new user. For SMS, the second column should be the Sender IDThe alphanumeric code that your SMS messages come from — like a phone number or name. Your audience subscribes to each individual sender ID they want to receive messages from. . Your CSV can contain additional columns with information that you use to personalize a message using HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. — e.g., {{name}}.

To use the Upload Users feature:

  1. In the Audience step, select the channel you want to send your message to and then click Upload Users. You cannot use the Upload Users feature if you select more than one channel.

  2. In the Review step, click Upload and Send.

  3. Click Choose File and select the file that contains your list of users.

  4. Click Send Message.