Send in-app messages

 This feature is in beta

We’re confident in the core feature and don’t expect to introduce any breaking changes before we formally release it—but we still have a bit more work to do and a few more questions to answer. Start using it today and Share your feedback to help us build the best possible feature for you!

How it works

Before you begin, make sure that you’ve incorporated our SDKs in your app and added the updated JavaScript snippet to your website depending on the platforms you want to support. People can’t receive in-app messages until they have a version of your app with the appropriate version of our SDK:

You can send in-app messages as a part of any campaign or broadcast workflow. When you set up a message, you’ll select and populate a message. The message provides the general design of your message—colors, static text, etc. When you populate the message as a part of your workflow, you’ll customize:

the in-app message composer
the in-app message composer

When does someone receive an in-app message?

People receive your in-app message as soon as they’re identified by your app or website, as long as the message hasn’t expired. By default, messages expire after 1 year, but you can change the expiration period to make sure that people don’t receive messages that are no longer relevant. You can also set page rules to determine the pages people must visit before they’ll see your message. Page rules can help you send targeted, relevant messages.

If a person has multiple devices, they’ll receive your message on their first eligible device.

graph LR a[app user triggers
in-app message]-->d{is the app open?} d-->|yes|f[user gets message] d-->|no|e[hold message
until app opens] e-->g{did the message
expire?} g-->|no, wait for user
to open the app|d g-->|yes|h[user doesn't
get the message]

 What happens if a person doesn’t have a version of your app that supports in-app messages?

If you send a message to a person who hasn’t updated their app to a version supporting in-app messages, your message will appear as sent, but will never be opened. If you want to filter out people who can’t yet receive your messages, you can set up a segment to target people with an appropriate version of the SDK.

In-app messages and unsubscribes

In-app messages ignore the standard unsubscribe attribute. People can’t unsubscribe from in-app messages unless you give them that option—through a custom subscription center with a custom attribute that you use in segmentsA segment is a group of people in your audience that you want to target with campaigns, messages, etc. You can join groups of people manually, or by attribues and event data. to prevent your messages from going to people.

You don’t want to abuse this privilege and cause your audience to ignore your messages or delete your app. When you set up in-app messages, be conscious of the frequency of the messages you send. To make sure that you don’t over-message your audience, you might:

  • Set up page rules to ensure that your messages are relevant to the pages your audience visits.
  • Set up delays between in-app messages in a campaign.
  • Filter people out of campaigns if they received messages or other campaigns within the same time frame.

Send an in-app message

Before you can use an in-app message in a workflowA series of actions (messages, attribute updates, etc) that people progress through as a part of a campaign or broadcast., you need to create it under Settings > Workspace Settings > In-App Settings. If you haven’t already created a message, you’ll need to do that first.

  1. Drag In-App Message into your workflow.
  2. Select your message, give it a Name, and then click Add Content.
  3. Set your message settings:
    • To: the value you use to identify people who use your app or your website. Contact your app or web developer if you’re not sure.
    • Priority: negotiates between multiple messages with the same Page Rule.
    • Position: determine where the message appears on the screen.
    • Page Rule: determine the page(s) a person must be on to see your message.
    • Display and Position: Select where you want your message to appear in your app or on your website. See Display and Position for more information about positioning your message.
      set your in-app message settings
      set your in-app message settings
  4. Pick the Message you want to send. Learn more about crafting in-app messages.
  5. Fill in your message Content, customizing your message for recipients. These fields are represented by $<fieldTitle> in your preview, and will update as you fill them in. Remember, you can use liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}. in these fields!
    populate your in-app message content
    populate your in-app message content
  6. Click Save Changes.

Targeting your audience: the “To” field

When you set up a message, the To field is the identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace.—email or ID—that your app uses to identify people in When a person in your campaign or broadcast is identified by the value in the To field, they’ll receive your message. If your app doesn’t identify people using the value you select, we won’t deliver your message to the person. Your messages will appear as Sent, but never Opened or Clicked.

Message expiration

By default, in-app messages expire 365 days after they’re sent. If someone doesn’t open your app for a full year, they won’t get your message.

However, many messages are more time-sensitive. For example, you wouldn’t want to send someone an expired coupon code. To prevent people from receiving old messages, make sure that you change the Expiration for your message.

Message Priority

Priority determines the order of messages sent to a person. If you send multiple messages before the next time a person opens their app, we’ll display messages in the priority order—highest to lowest.

You can avoid competing messages using Page Rule triggers. Page rules cause messages to appear when a person visits specific pages in your app or website, helping you deliver messages that are relevant to the pages your audience visits.

Page Rule

Page rules determine the pages a person must visit in your app or website to see a message. They help you target messages, so they’re more relevant to the places your audience visits, and the things they do. We determine the “page” differently, depending on whether you’re sending your message to a mobile app or website.

  • Mobile Apps (iOS and Android): the page is the same as the name value that you send in screen events.
  • Websites: the page is the URL (window.location.href) unless you pass page calls with a different name parameter.

If your website is a single page application you must send page calls to tell what “page” a person is on.

You might use page rules to point out new features within specific areas of your app or new products on your website. Page rules also help avoid conflicting messages. If you send two messages of the same priority without page rules, one is likely to be dropped; if you set a page rule for at least one message, it’s much more likely that your audience will see both messages—after triggering the page rule(s).

If you send a message without a page rule, it appears on whatever a person is on or opens their app to.

set in-app page rules to determine the page your message appears on
set in-app page rules to determine the page your message appears on

Positioning your message

The Display and Position settings help you determine where your message appears to users. Pick your Display option and then pick the position for your message.

Some options are exclusive to web in-app messages, and won’t work on mobile devices. For example, using an Overlay option effectively limits your message to your website visitors, because mobile apps won’t display the message.

Display settingiOSAndroidWeb
1For mobile apps, you have to handle inline positioned elements with your own code, or they won’t be displayed. Consult Gist’s documentation for more information.
set your message's display setting
set your message's display setting

Modal positioning works for both mobile and web apps. You can position your message on at the top, in the center, or at the bottom of your audience’s screen.

Overlay positioning is specific to web in-app messages. Your message appears in the location you select, relative to your audience’s browser. For example, on a wide-screen monitor, a bottom-right positioned message will appear in the bottom right.

Inline positioning is generally for your website, though you can write code to handle inline positioning for your mobile apps. With inline positioning, you provide the id of an element that you want to replace with your message. For example, if you wanted to highlight a new button on your website, you could place an empty placeholder element with an ID directly below the new button and use your message to replace to the empty element and highlight to your button.

For mobile apps, you have to handle inline positioning with your own code, or your message won’t be displayed.

 We don’t retry messages that can’t be displayed on apps

Apps don’t handle website-only display methods. If you set up your message with a website-only display setting, and don’t use page rules to limit your message to your website, anybody who logs into your app before your website won’t see your message; will not retry your message either.

We’re working to change this behavior. In the meantime, you can limit your message to web or mobile only using page rules.

Limit your message to web or mobile audiences

By default, when you set up an in-app message, a person can receive the message in your app or on your website. We’re actively working on a way to select the platform(s) you want to limit your in-app message to. But, in the meantime, if you want to limit a message to your app or your website, you can use page rules.

A page rule determines the page or pages a person needs to visit to see your message. If you set a page rule to a page or screen that doesn’t exist, we’ll never display your message on that medium. You can use this behavior to your advantage to ensure that a message only appears on a particular channel—web, iOS, Android, or some combination.

For example, if you want to display your message on your website’s /docs/in-app/ page, you can set a page rule /docs/in-app/. For your iOS and Android channels, simply set a screen that doesn’t exist, like 404. Because the page doesn’t exist, your message will never appear to app users; it’ll only appear to people who go to your website’s /docs/in-app/ page.

Segmenting an audience of app users

When you set up your campaign, you may also want to make sure your segment includes, or filters for, people who have a version of the SDKs supporting in-app messages. If someone in your audience doesn’t have a version of your app that supports in-app messages, they’ll never receive your in-app messages. Messages intended for them will be sent, but never opened, which can produce inaccurate metrics.

Our SDKs have implemented in-app messages in different versions. So, if you create segments or filters for this purpose, you should group platform AND cio_sdk_version conditions:

Set up a segment to look for people who have the correct cio_sdk_version
Set up a segment to look for people who have the correct cio_sdk_version

 Use filters for event triggered campaigns

If you send an in-app message as a part of an event-triggered campaign, you might want to use a segment to exclude people who don’t have versions of your app supporting in-app messages.

Test your in-app message

When you set up a message as a part of a campaign, you can send a test to make sure that your message looks and behaves the way you expect it to.

Click Send test… and enter the email or ID—corresponding to your message’s To field—of the person you want to send a test to.

paste your device token to send a test
paste your device token to send a test

If your test looks good, then you’re all set to send! If not, you can edit your message and send more tests to check your work.

Copied to clipboard!