Push Templates let you send messages personalized with 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.

The template can include a push notification, in-app message, or combine the two. Learn more in Message and Workflow 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!

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.

Navigation

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

Immediately under the progress header is an arrow tab. Click the tab to expose Summary and Help.

Your selected conditions are displayed in the Summary. The Help tab displays information relevant to the current step. Click the (?) icon in any step and the Help tab will open with that topic.

Steps

Open your project from the dashboard, then click Messages and select Templates.

Then click the New Push Template button.

If your account is provisioned for Email Templates, both Push and Email Templates will be listed in a menu on the left side of the page.

Template Info

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.
     
     Examples:
     
     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 Delivery 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.

Content

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

   Available message types are reduced to those supported by all the platforms 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 }}.“
   Note

   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.

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

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

Duplicate

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 progress header to make changes, then complete the Content and Review & Save steps.