Message Personalization Tutorial

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.

What You’ll Do

In this tutorial, you will:

  1. Define the template name and merge fields.
  2. Choose a message type and enter its content.
  3. Direct the users’ next step after they tap or swipe the message.
  4. Preview and save the template.

Features and options are explained along the way.


As you create a new template, these page elements are available to guide and assist.

Progress Header

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.

Summary and Help

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.


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

Template Info

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 and a brief Description defining its purpose. The name should be specific enough to help you identify the template in your list of all saved templates,
  2. Click the Add a Merge Field button. 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. Optionally check the box for Advanced Usage. This box appears after creating your first merge field. Checking the box adds 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.

  5. Click Content in the header to move on.

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, Android Notification Payload, and Web Notification Payload for details about extras in the API.

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


  1. Choose between sending a Push Notification or an In-App Message, or choose Silent Push Notification to send a push without notification text. After you make your selection you have the option to combine message types, then click the Continue button to confirm your choice(s).

  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. A preview will display as you type. 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 }}.“

  3. 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 example in Template Info, 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”
  4. If you chose to combine a Push Notification and In-App Message, an In-App Message Text section appears below the message truncation indicator. By default, the In-App Message’s alert text is the same as the Push Notification 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.
  5. Select a Message Action from the dropdown menu.

    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: Message Actions: Availability.

  6. Optionally Set a tag.
  7. Set Optional Features.
  8. Click Review & Save in the header to move on.

Review & Save

  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 the window.

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

Next Steps

Send a Message to a 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.

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 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.