Creating Embedded Message Templates

You've defined your placements, added them to your Iterable project, designed message interfaces for them, and updated your mobile apps and websites to display messages using those interfaces.

Now, the fun part: creating and testing an embedded message template!

# In this article

# Permissions

To work with embedded message templates in Iterable, you'll need these permissions:

# Creating a template

Embedded message templates are similar to other Iterable templates. However, each embedded message template must be associated with a placement, which specifies the fields for which the template should provide data

For example, we might define a placement called "Home screen message" in our Iterable project, and give it various features: a title, a body, a media URL, a default action, and two buttons.

Then, to create a template associated with that placement:

1. If you haven't yet done so, create an embedded message placement in your Iterable project. Without a placement, you can't create a template or a campaign. For more information, read Defining Placements for Embedded Messages.

2. Navigate in Iterable to Content > Templates and click New Template > Embedded.

3. Enter a name for the template, and click Create Template.

4. Choose a placement to associate with the template.

   

5. On the template configuration page, enter values for the various configuration options required of the template by its placement. In this example, we'll make a "Daily cats!" template:

   NOTE

   Like other kinds of templates in Iterable, embedded message templates support locales.

   • Title – Another day, another cat

   • Body – Feeling stressed? No worries... time for your daily cats!

   • Media URL – https://placekitten.com/400/300 (must use https)

   • Open Action

     • Open URL - https://openverse.org/search/?q=cats

   • Button 1 – Cats!

     • Open URL – https://www.flickr.com/search/?text=cats
     • Identifier – catsButton

   • Button 2 – More cats!

     • Open URL – https://pixabay.com/images/search/cats/
     • Identifier – moreCatsButton

   Buttons and default actions can be assigned URLs or custom actions. Custom actions (such as action://joinClass/1) trigger specific functionality in your app.

As configured, the template looks like this:

# Testing a template

After creating a template, it's a good idea to test it. By testing, you can verify that the content of your template comes across as you expect, and that your apps are display it properly.

While editing a template, test it by clicking Display Test Message and choosing one of these options:

• To Yourself

  • In email-based projects, activates a test embedded message to the email address of the signed-in Iterable user, regardless of whether there is an Iterable user profile identified by that email.

  • In userID-based projects, activates a test embedded message to an Iterable user profile whose email field matches the email address of the signed-in Iterable user (since Iterable users sign in by email, not userId). If no such user profile exists, an error message displays. If multiple such user profiles exist (this can happen because email is not an identifier in userID-based projects), one and only one of them will receive the test message.

  • In hybrid projects, activates a test message to the Iterable user profile whose email matches the email address of the signed-in Iterable user (since Iterable users sign in by email, not userId). If no such user exists, an error displays.

• To an Internal List – Activates a test embedded message to each Iterable user profile included on a selected internal list. (Internal lists are defined on the Audience > Lists page.)

• To Another Address – Activates a test embedded message to various user profiles you enter after selecting this option.

  • In email-based projects, you can provide one or many email addresses, regardless of whether or not they identify existing Iterable user profiles.

  • In userID-based projects, you can provide one or many userId values that identify existing Iterable user profiles. If any provided userId does not identify an existing Iterable user profile, you'll see an error, and that userId won't receive the message — but valid profiles will.

  • In hybrid projects, you can provide one or many email and userId values that identify existing Iterable user profiles. If any provided userId or email does not identify an existing Iterable user profile, you'll see an error, and that userId or email won't receive the message — but valid profiles will.

# Verifying a test message

There are a couple of ways to verify the test message:

• Query Iterable's API to fetch all embedded messages available for the test user. Then, verify that the test message is present in the response. And, while you're there, inspect the API response to get a sense of the data payload Iterable uses when sending an embedded message to your apps.

• Sign in to your app or website as the test user, navigate to the placement associated with the message, and make sure everything looks right. This will only work if you've already updated your app or website to display embedded messages.

# API verification

To verify that your test message is available for your test user, you can use a mobile or web API key for your Iterable project to manually call the same API endpoint that your apps call to fetch embedded messages.

Calling this API can give you confidence that your test message is available for apps to download. It can also help you (and your engineers) develop an understanding of the precise data payload Iterable sends for an embedded message.

For example, to fetch embedded messages for test user user@example.com, you'd call:

GET /api/embedded-messaging/messages?email=user@example.com

For the test message described above, the response would be similar to:

{
  "placements": [
    {
      "placementId": 141,
      "embeddedMessages": [
        {
          "metadata": {
            "messageId": "",
            "placementId": 141,
            "isProof": true
          },
          "elements": {
            "title": "Another day, another cat!",
            "body": "Feeling stressed? No worries… time for your daily cats!",
            "mediaUrl": "https://placekitten.com/400/300",
            "buttons": [
              {
                "id": "catsButton",
                "title": "Cats!",
                "action": {
                  "type": "openUrl",
                  "data": "https://www.flickr.com/search/?text=cats"
                }
              },
              {
                "id": "moreCatsButton",
                "title": "More cats!",
                "action": {
                  "type": "openUrl",
                  "data": "More cats!"
                }
              }
            ],
            "text": [],
            "defaultAction": {
              "type": "openUrl",
              "data": "https://openverse.org/search/?q=cats"
            }
          },
          "payload": {}
        }
      ]
    }
  ]
}

# Verifying your test message in your app or website

You can also have the test user view the message in an app or on a website that is configured to display messages for that placement.

For example, here's the test message from above, rendered in an iOS app, using an out-of-the-box banner view (included in Iterable's iOS SDK) with no styling adjustments. In this case, the test user (user@example.com) has signed in to the app and navigated to the screen that displays messages associated with the "Home screen message" placement:

# Want to learn more?

To learn more about templates in Iterable, read Templates Overview.

# Next steps

Before creating an embedded message campaign, you'll need to define its audience. To learn how, read Defining Eligibility Lists for Embedded Messages.