Message Personalization Composer

Message Personalization Templates let you send a templated message to many users, personalized with the values that are specific to each user, e.g., first name, flight number, order status. If you’ve ever used a mail merge feature to create holiday card labels, you are already familiar with this concept.

First a developer creates the template. Any user can view saved templates and edit the content. This page will take you through the required steps to create a personalization template. After setting up the basic descriptive information for your template, you will define the merge fields, into which the user-specific data will be populated when sending your message. Your final step will be to reference your template in your Push API call.

Thanks for reading, {{name}}; we’re very excited to have {{your_company}} as a customer!

Templates can only be created by a Team member with the Owner, Administrator, or Full Access role. Templates should be created via the UI only, not the API. Push messages referencing a template are not editable in the UI composer.

Create a New Template

Choose your app from the Urban Airship dashboard, then click the Messages dropdown menu, and select Templates. From the Templates dashboard, click the New Template button.

Your steps are tracked in the progress header. Your current step turns green when complete, showing you are ready to proceed. Completed steps display a green checkmark icon. A red (!) icon appears if you need to fix anything in order to proceed. Click a step name to move ahead or to go back and edit.

In the Content and Review steps, your selected conditions are displayed in a Summary on right side of the window. The Help tab displays information relevant to the current step. Hover over composer sections to expose a (?) icon. Click the icon, and the Help tab will update with that topic.

Template Info

Define the template name and merge fields.

After saving the merge fields created during this step, no fields may be added, removed, or changed. However, you may duplicate and modify any saved template. See Saved Templates.

  1. Enter a Name that will help you identify your template in your list of all saved templates, and enter a brief Description defining its purpose.

  2. Click the Add a Merge Field button to Create the merge fields you will use for this integration. These fields determine the available options when composing your message text.

    Fill out the required fields, then click the Add button to add the new merge field to the template, or cancel to discard.

    • Key may contain only alphanumeric characters and internal single underscores, and must be at least two characters in length. Required field.
    • Friendly Name is required.
    • Description is optional.


    • Key = gate, Friendly Name = Gate Location
    • Key = flight, Friendly Name = Flight Number
    • Key = air_code, Friendly Name = Airport Code

  3. The Advanced Usage box appears after creating your first merge field. Check the box to add your merge fields as extras in the notification payload. See Advanced Usage below for more information.

  4. Click the Save button once you are satisfied with your merge fields, then Confirm. The next screen is an overview of your new template. Save the template ID listed here.

Advanced Usage

The Advanced Usage option will take the merge fields that you define and add them as extras in the nofification payload. If you are unsure about whether to choose this option, contact your developer.

See iOS Notification Payload and Android Notification Payload for details about extras on iOS and Android in the API.

In the UI we support the notion of extras as Custom Keys, which are supported in our message composers. See the Content: Optional Features section for each composer:


  1. Choose between sending a Push Notification or an In-App Message. After you make your selection you have the option to combine both message types. Click the Continue button to confirm your choice(s).

    Or choose Silent Push Notification to send a push without notification text.

    • Push Notifications alert users from outside of your app to key information (news, offers, features, etc.), and drive them back to engage with your app.

    • In-App Messages are banner notifications that appear inside of your app. Use them to engage with users as they browse your app, and reach users who have not opted in to push.

  2. Enter the text that will display in your message. Type {{ to enable the merge field selector, allowing you to see what fields are available, then click your choice. As you type, a preview will display.

    Example for notification about airline flight information: “Heads up! Your flight {{ flight }} has had a gate change. Your new gate is {{ gate }} at {{ air_code }}.“

    Optionally set a Default Value for each field or check the box for Allow Empty. These settings are used when a value is not sent through your integration. Take care to craft your message so that your default values will make sense in the case they are needed.

    Continuing the previous example, these would be appropriate default values:

    • Flight Number: Click the checkbox for Allow Empty so that no value will be displayed if the flight number is not sent.
    • Gate Location: “available on the departure board”
    • Airport Code: “your airport”

    Below the text box is a color-coded indicator, warning when your message may be truncated on some devices.

    • Green: Full length of message will appear in most cases
    • Orange: Message may be shortened on some devices
    • Red: Message will be shortened on all devices

    Best practice is to make your message as brief as possible, though some customers find success when a message truncates, teasing their audience to learn more.

    If you chose to combine a Push Notification and In-App Message, you have the option of using the Push Notification text as the In-App Message’s alert text. If you’d prefer to use a different message, select the radio button for Write alternative, and enter your text in the box that appears below.

  3. Direct the user’s next step after they tap or swipe your message. The Message Actions listed in the dropdown menu differ depending on which message type you chose, and if you chose to combine message types. See the Message Actions topic guide for more information.

    Action for Push Notification only:

    Action for In-App Message only:

    Action for combined Push Notification and In-App Message only:

    • Home Screen (combined) opens the app’s Home Screen for a Push Notification, and dismisses the In-App Message.

    Actions common to both Push Notification and In-App Message:

    • Deep Link opens to a configured screen within your app or on the web.
    • Web Page opens to a web page or any valid-device level URL such as App Store or app protocol links.
    • Share prompts the user to share the message on social networks.

  4. Click the Set a tag button.

    You may remove an existing tag, or set and remove tags.

    Type ahead to find tags that exist in the system, or create a new tag.

    Tags let you dynamically track user interactions for follow-on retargeting campaigns by setting one or more tags when the user interacts with this push. For example, if you set a tag “responded-campaign1” then you can target them with another message at a later date, knowing they are active users. Alternatively, you can re-engage them with an automated message if they are inactive for a period of time.

Optional Features

Available options are dependent on which message types and platforms are selected.


Add one or two Buttons to bring even more interactivity to your messaging. Buttons prompt a user to take specific actions within or outside of the applications. There are up to 35 predefined Notification buttons to choose from, depending on your SDK version. Trigger any Urban Airship message action when a button is clicked. See Settings: Configuration: Notification Buttons.

Enable via toggle, click Select buttons, either page through or type to narrow your search, and click the button(s) of your choice.

Custom Keys

Set Custom Keys, also known as key/value pairs, which allow you to pass extra data through your Push Notification payload for use by custom code in your app. Common uses of custom keys include passing additional campaign identifiers for analytics, passing user profile information to the device, controlling the look and feel of the app, providing image links, etc.

Enable via toggle, make your platform selection from the dropdown menu, then enter the key and value. Click the Add Another button for additional keys.

By default, a custom key is sent to Push Notifications on all platforms, but you can choose platform-specific keys as well if you your message is going out to more than one platform, e.g., one imageURL for iOS and another imageURL for Android.


Enter a Title to create a heading that appears above the notification text on:

  • iOS Notification Center
  • Apple Watch Looks
  • Android and Amazon Notification Area/Drawer

Enable via toggle, then type the title in the text field.


Add a Summary line, supplemental text displayed with the primary notification message. Enable via toggle, then type the line in the text field.

  • iOS: Summary appears below the push notification title. See iOS 10 documentation. iOS 10 only.

  • Android and Amazon: Summary appears below the main notification text in most cases. This is the only visible text other than the title when Android Picture is visible in expanded mode, as the main notification text is suppressed. See Android documentation.


Add Media to your notification. Toggle to enable.

  1. Enter the URL for the media to be displayed with the push notification. Image, animated gif, audio, and video are supported. See API reference for allowed file types and requirements. Ensure the URL will be accessible by your mobile audience. HTTPS is required.

  2. Check the box to Hide iOS thumbnail. By default, a thumbnail of the media is displayed in the message alert.

  3. Add Media Specific Content on iOS 10 devices. By default, iOS 10 devices will receive the Same push notification as pre-iOS 10 devices. If you would like to send a different message to iOS 10 devices, select the Write Alternative radio button to display the iOS 10 Push Notification box, and enter the alternative text.

Alternate Title and Summary fields will appear here only if the initial Title and Summary fields preceding Media have been enabled and filled out.

Android and Amazon

Enter the URL for the media to be displayed with the push notification. Only static images are supported. See API reference for "style". Ensure the URL will be accessible by your mobile audience. HTTPS is required.

If the iOS platform is enabled along with Android and/or Amazon, the URL field is labeled Picture for Android. The Picture for Android field is removed if a URL for a static image is entered in the initial URL field.

Upload Media

If your account has CDN enabled, you have the option to Upload media rather than entering a URL. Select the radio button for Upload, click the Upload Media button, and select the media file. Maximum file size is 2 MB.

Supported Media

  • Images: JPEG, GIF, PNG
  • Audio: AIFF, WAV, MP3, M4A
  • Video: AVI, MPEG, MPEG2, MP4

Contact Support if you are interested in enabling CDN media hosting.

iOS Only


Update the recipient device’s app Badge, the red numeric display on the app icon that typically indicates its number of unread messages.

By default you automatically increment the existing badge number, but alternatively you can specify the exact number, e.g., +3, +12, -3.

Enable via toggle, then select either Increment by 1 or Specify. Specify requires a value in the text field.


Play a custom Sound when the message is received. The file must be bundled with your app by your app developer.

Enable via toggle, then enter the name of the sound file, e.g., “default” or “beep.caf”.

Review & Save

Confirm your choices, and preview per platform.

  1. Review the information on the left side of the screen, and click through the images in the previewer. The platform and display type are dynamically updated above.

    If you would like to make changes, click Content in the progress header, edit, then return to Review & Save.

  2. Click the Save Template button at the bottom of your window.

    You will be taken back to your Templates dashboard, where your new template will be listed.

Saved Templates

The Templates dashboard contains a table listing your saved templates. The Ready column displays a Yes for templates that are available for use. Any template with a No status requires further setup before it may be used.

When you select a template in the list, its Name, ID, and Description are shown in the Template Info box in the upper right side of the screen, and a preview of the message is below.

Edit Info or Delete

Select a template in the list, then click the pencil icon in the Template Info box.

Either make changes and click the Save button, click cancel to discard, or click Delete Template. There is no confirmation step for deleting a template.


Select a template in the dashboard list, then click the Duplicate Message (plus sign) icon in the Template Info box. The next screen takes you to the Template Info step of creating a new template, but every field is pre-filled and editable. Continue with the Content and Review & Save steps, and be sure to give it a name differentiating it from the template you duplicated.

Edit Content

Select a template in the list, then click the Edit Content button in the center of the preview.

The next screen takes you to the Content overview. Click Content in the progress header to make changes, then complete the Content and Review & Save steps.

Send a Message to Your Template

Sending to a template via the UI is not supported at this time. Head over to Push to Template to send your first push to template.