In-App Messages: Getting Started

In app messages let you incorporate dynamic, personalized content into your app or website with very little development or engineering and help you continue conversations across channels. By personalizing messages based on the activities your audience performs in- or outside your app, you can maintain highly relevant interactions with your audience.

 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!

What is an in-app message?

An in-app message is a message sent to a user inside your app or on your website. It’s distinct from a push notification in that a user must be in your app or on your website to receive it. They can’t get your message if they don’t open your app or login to your site.

How it works

When you send an in-app message, the message waits in a queue until your recipient opens your app or website on one of their devices. When the person opens your app or visits your website, they’ll see your message. We log events based on the person’s response to your message—whether tap it or click an action link in the message.

You’ll target your message message to your audience by their ID or email—rather than by device or browser. In-App messages go to the first device or browser that you identify a person from. After a person receives your message, they won’t receive it on another device or browser session (unless they enter a campaign again or you re-broadcast your message).

sequenceDiagram Participant a as App User Participant b as SDK Participant c as c->>c: Trigger in-app message c-->>b: If app isn't open, hold
until user opens app a->>b: User opens app b->>c: Identify User c->>b: Send in-app message b->>a: User sees
in-app message

Before you begin

Your setup path might change depending on whether you’re a developer integrating with or a marketer who wants to send messages. Use the chart below to better understand what you, or other members of your team, must to do before you can send in-app messages.

Before you can send an in-app message, you’ll need to:

  1. Enable in-app messaging in your workspace
  2. Set up your branding and in-app messages
  3. Use your messages in campaigns or broadcasts
  4. Set up your app and/or website:
flowchart LR a{Where do
I start?} a-->|I'm a marketer|f{Are SDKs already
integrated?} f-->|yes|g[Create in-app messages] a-->|I'm a developer|b[Integrate SDK and/or
Javascript Snippet] f-.->|no, contact
a developer|b g-->c[Send messages] b-->g

Enable in-app support

Enabling in-app support generates your in-app organization ID and service key. You’ll use these values to enable in-app support in our mobile SDKs and JavaScript snippet.

  1. Go to Settings > Workspace Settings and click Get Started next to In-App.
  2. Click Enable in-app.
set up in-app messages and get keys
set up in-app messages and get keys

Set up branding

Before you create messages, you’ll set your Branding rules—the colors, fonts, and padding options that you want to use across all of your messages. Branding settings help you create messages that look like a part of your app or website, and ensure consistency across your messages.

Go to the Branding tab under Settings > Workspace Settings > In-App Settings to set or change your in-app branding rules.

Set up branding rules for your messages
Set up branding rules for your messages

 Branding changes take effect immediately

Changes to your branding settings affect all of your messages, even messages that are in-flight!

Set up your mobile app

If you haven’t already, you need to enable in-app support.

  1. Incorporate the in-app notifications SDK, so that your app can receive notifications from
  2. Identify the device user. In general, this means that your app requires people to log in, or otherwise make themselves known to you to receive an in-app message. You cannot send anonymous in-app messages.

Set up your website

After you’ve enabled the in-app message channel, you need to add our JavaScript snippet to do two things:

  1. Add the JavaScript snippet to your website and update it to include the data-in-app-org-id and data-use-in-app properties shown below.
  2. Identify people on your website—either when they login or otherwise make themselves known to you (by email or ID).

If you’ve already added the JavaScript snippet to your website, you’ll need to add a line containing your organizationId to the snippet, highlighted in the sample below.

Otherwise, copy the snippet below and paste it to your pages immediately before the closing </body> tag. Then, add your workspace’s API credentials (replacing YOUR_SITE_ID) and your ORGANIZATION-ID.

<script type="text/javascript">
    var _cio = _cio || [];
    (function() {
        var a,b,c;a=function(f){return function(){_cio.push([f].
        var t = document.createElement('script'),
            s = document.getElementsByTagName('script')[0];
        t.async = true;    = 'cio-tracker';
        t.setAttribute('data-site-id', 'YOUR_SITE_ID');
        t.setAttribute('data-use-array-params', 'true');
        t.setAttribute('data-in-app-org-id', 'ORGANIZATION-ID');
        t.setAttribute('data-use-in-app', 'true');
        t.src = '';
        //If your account is in the EU, use:
        //t.src = ''
        s.parentNode.insertBefore(t, s);

 Send page events from your single page app

If you want to take advantage of page rules from a single page application, you’ll need to send page calls to tell the SDK what “pages” people are on.

Identify your website visitors

You must identify people before you can send them messages. You can do this by adding the _cio.identify beneath the JavaScript snippet.

// Send this when a user logs in or you otherwise identify them. 

    // Required attributes — you must include email or ID
    email: '',

    // Strongly recommended when you first identify someone
    created_at: 1339438758,   // Timestamp in representing when the user
                              // first signed up in Unix format.

    // Example event attributes (properties you'll reference with liquid)
    first_name: 'Cool',
    last_name: 'Person',
    plan_name: 'premium'

When you send _cio.identify, you must send at least one identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace.. Depending on your workspace settings, this may be either an id (the unique identifier the maps a person to your backend systems) or email address.

You can also send in additional attributesA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages. that are of value to you. In the above example we send first_name, last_name and plan_name attributes. You can use these attributes to segment your audience or to personalize messages for people.

 Send created_at when you first identify someone

The created_at attributeA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages. is useful for date-based campaign triggers, starter campaigns, and it can help you understand how long someone’s been in You should only pass this value with your first-ever identify calls, or you’ll overwrite your audience’s created_at value.

Copied to clipboard!
Is this page helpful?