30

Send in-app messages

How it works

Before you begin, make sure that you’ve incorporated our SDKs in your app or website depending on the platforms you want to support. People can’t receive in-app messages unless they visit your website or use a version of your app that incorporates 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:

• Text fields: 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}}. to personalize the message for your audience
• Expiry: this determines how long a message will wait for a person to open your app or visit your website (and visit the right page)
• Page rule: the page that a person has to look at to see your message
• Display and Position: where your message will appear on your audience’s screen

Once the message is sent, people will receive your in-app message as soon as they’re identified in your app or website, as long as the message hasn’t expired. By default, messages expire after 30 days, 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.

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 Content > In-App Messages. 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 Rules.
   • Position: determine where the message appears on the screen.
   • Page Rules: 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.

     

     
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!

   

   
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 Customer.io. 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 30 days after they’re sent. If someone doesn’t open your app within the expiration period after the message is sent, 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. You can set your message to expire

• At a specific date and time
• At a relative time after the message is sent (for example, 10 days after the message is sent)
• Or using 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}}. to configure the expiration date based on an event property, profile attribute, trigger variable, or snippet relative to the send time of the message.

The maximum expiration window is 60 days.

Persistent messages

By default, in-app messages only show once—the message disappears after the customer clicks, taps, or refreshes the page.

You can check the Persist Message option to show your message across multiple sessions and page views. Persisted messages continue being displayed until the expiration date or until the customer clicks Close or the icon. Make sure your messages include a Close button or an icon so that customers can permanently dismiss your message.

If you use our Web SDK, you’re all set to send persistent messages. For mobile devices, you must use the versions below or later to take advantage of this feature. Persistent messages are available starting in:

• Android 3.7.0
• iOS 2.8.4
• React Native 3.2.0
• Flutter 1.3.0

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 Rules

Page rules determine the platform a person must be on and the page(s) or screen(s) a person must visit on your website or app to see a message. They help you send messages that are relevant to the places your audience visits and the things they do.

By default, your audience will see your message on the first page or screen they visit. Click Add Rule to add a page rule. Click it again to add multiple rules. We evaluate multiple rules with a logical OR: if a person visits any page in your page rules, they’ll see your message.

When you add a rule, you’ll set the platform and then the page(s) or screen(s) a person must visit to see your message. You can use wildcards (*) in rules to match multiple pages. You can also 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}}. to set a page rule based on an event property, profile attribute, trigger variable, and so on.

A “page” means something different for your mobile apps and website:

• Mobile Apps (iOS and Android): the page is the same as the name value that you send in screen events. For example, billing* would cover all screens in your app that begin with “billing”.
• Websites: the page is the URL (window.location.href) unless you pass page calls with a different name parameter. For example, https://example.com/*/billing would cover paths on your website like your in-app billing page https://example.com/ui/billing or documents about billing under https://example.com/docs/billing.

If your website is a single page application you must send page calls to tell Customer.io 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 and you can even 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}}. to set a dynamic value (like {{event.product_url}}). Page rules also help avoid conflicting messages. If you send two messages of the same priority without page rules, they’ll appear one after the other; if you set a page rule for at least one message, it’ll distribute the messages across your app, and only show when your audience is on a page matching the rule.

Keep in mind: page rules are case sensitive. If you’re targeting your mobile app, make sure your page rules match the casing of the name in your screen events. If you’re targeting your website, your page rules should always be lowercase.

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.

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 only for web in-app messages. 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.

Custom message width

By default, the max width of a message is 414px, a common breakpoint for mobile devices. This might not be wide enough for certain messages—especially ones that you display on your website.

If you need more space, you can set a custom Message Max-Width (px) for your in-app message. This expands messages to the set value, while still being responsive (100% of width) when the screen size is smaller than the max-width value.

Custom background overlay color and opacity

When you use the modal display position for your in-app message, we display your message on top of a background overlay. The overlay has a default hex color of #000000 (black) with a 20% opacity.

You can change the Overlay Color and Opacity values to better fit your brand when you configure your in-app message’s display settings.

Limit your message to web or mobile audiences

By default, when you set up an in-app message, your audience can see your message in your app or on your website—anywhere you’ve integrated in-app notifications. You can limit your message to specific message channels using page rules.

By default, all the page rule boxes are unchecked, and your audience will see your message on the first page or screen they visit on your website or app.

When you check a box, you automatically exclude un-checked channels. For example, if you want to send a message to your web visitors but not iOS or Android devices, you can check the Web box.

When you select a channel, you must enter a page rule; an empty rule is invalid. You can, however, use a wildcard (*) to show your message on the first page or screen people. You can set a specific page URL or use a path with a wildcard to limit the pages or screens people must visit to see your message.

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:

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.

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.

In-App FAQs

Can I stop an in-app message after it’s sent?

In most cases, you can’t stop messages after they’re Sent. You’ll want to set an Expiration period for your messages to make sure that your messages expire when they’re no longer useful.

However, if you’re willing to stop a campaign, you can use the Exit Immediately option to cancel in-app messages that have been sent but not opened. Note that stopping messages in this way only works for in-app messages. You can’t stop other kinds of messages in this same way.

You will cancel in-app messages that have been “Sent” but not “Opened” when you:

• Delete an in-app action from a campaign workflow. This recalls any unopened messages associated with the action.
• Delete a campaign containing in-app messages. This recalls any unopened in-app messages sent by the campaign.
• Stop a newsletter that was in-progress. This recalls any unopened in-app messages sent by the newsletter.
• Delete a newsletter. This recalls any unopened in-app messages sent by the newsletter.
• Delete an API Triggered broadcast containing an in-app message. This recalls any unopened in-app messages sent by the broadcast.
• Disable in-app messaging for your workspace. This recalls any unopened in-app messages for the entire workspace.

How do in-app messages handle unsubscribes?

In-app messages ignore our standard unsubscribed attribute. People can’t unsubscribe from in-app messages unless you give them that option through a custom subscription center with an attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. that you use with segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. to prevent your messages from going to people.

Abusing in-app messages can cause your audience to ignore your messages or delete your app. When you set up in-app messages, be conscious of the frequency and relevance 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/screens your audience visits.
• Set up delays between in-app messages in campaigns.
• Filter people out of campaigns if they received messages or other campaigns within the same time frame.

What happens if a person doesn’t have a version of my 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 Customer.io SDK.

Why are my messages delayed? How do I send real-time in-app messages?

When a message is “sent” from Customer.io, our SDKs fetch them and store them on the device, and they’ll show in real time when customers match the the page rule(s) specified in the message. But event-triggered messages aren’t sent until a person performs an event, meaning that our SDKs don’t prefetch them. The round-trip traffic between the device-side event, starting a campaign, and fetching a message results in a delay between when a person triggers a message and when it appears in your app.

If you want messages to appear in real-time, you can trigger your messages in advance using any other campaign or broadcast, so that your messages are stored locally. If you use page rules you can display messages immediately based on your audience’s activities in your app rather than waiting for an event trigger your message.

1. Use a campaign or broadcast to trigger the message(s) to your target audience. Set up each in-app message with a custom page rule determining it will appear.
2. When a user opens your app, all in-app messages with the Sent status will be retrieved and saved in the device’s local storage, waiting for the user to visit the right page or screen.
3. When the user goes to the page/screen defined in a message’s page rule, they’ll immediately trigger the in-app message, retrieving it from local storage. If your use case doesn’t have a target page, use a custom page or screen view instead to force the in-app message to show. This call is processed client-side and cause the in-app message to show immediately.

In the long term, we plan to extend the prefetching functionality to events so that we automatically store event-triggered messages on devices and they’re ready to display when the event is triggered. In the interim, use page rules for real-time display.

Can I use page rules for in-app messages on my website even if I don’t send page events?

Yes! If you don’t send page events, we’ll use window.location.pathname to determine the page that a person is on. This means that page rules will always work for in-app messages on your website, even if you don’t log page events.

How do I send in-app messages to a specific platform?

By default your message will appear on the first page or screen your audience visits in any platform where you support in-app messages—web, iOS, or Android.

When you add a page rule, you automatically exclude platforms not covered by your rule. Click Add page rule when you setup your message to select the platform you want to send your message to. When you set up a page rule, you can enter a page path or screen name—or you can simply set contains * to send your message on any page or screen on that platform.