Message Personalization Tutorial

Push templates can include a push notification, in-app message, or both combined. Learn more in Message and Composer Types.

First you create the template. Any user can view saved templates and edit the content. 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. This page takes you through the required steps to create the template.

Your final step will be to reference the 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 dashboard only, not the API. Push messages referencing a template are not editable in the dashboard.


You may also use SMS notifications with push templates. See: SMS: Personalization Templates.

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.


You can configure the default appearance of your In-App Messages in Settings » Configuration » In-App Message Design. This includes button text and message color, screen position, and more.


  1. Open your messaging project and go to Messages » Templates.
  2. Click View Push Templates, and then click Create Push Template.

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 custom keys. See Advanced Usage below.
  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 as the data as custom keys in the notification payload. In the API, custom keys are added via the extra platform override. See Optional Features: Custom Keys for more information.

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.


  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. Click the Continue button to confirm your choice.

    Available message types are reduced to those supported by all the channels enabled for your project.

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

    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.

  3. Optionally set a Default Value for each field or check the box for Allow Empty. This section appears after you entered text that includes a merge field. 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. 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 Reference: Actions.

  5. Optionally Set a tag.

  6. Set Optional Features.

  7. Click Review & Save in the header to move on.

Review & Save

  1. Review the device preview and message summary.
    If you would like to make changes, click Content in the header, edit, then return to Review & Save.

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

    You will return to the list of Push Templates, where your new template will be listed. Click the template's row to see its ID in the Template Info box in the upper right side of the screen. You'll use that ID when sending your message.

Next Steps

Send a Message Using a Template

Sending templated messages via the dashboard is not supported at this time. Head over to API: Push to Template.

Saved Templates

Messsages » Templates lists 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 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 from the 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 header to make changes, then complete the Content and Review & Save steps.