Events for In-App Messages and Mobile Inbox

As users interact with in-app messages and your app's mobile inbox, Iterable can capture various events that describe the actions they're taking. You can use these events to:

• Determine how users are interacting with your in-app message campaigns.
• Segment users and filter journeys.
• Trigger journeys.
• Trigger system webhooks.

This document describes the in-app message and Mobile Inbox events Iterable can capture, how to capture them, and how to use them.

# Table of contents

# APIs for capturing in-app message events

Iterable's mobile SDKs and web SDK automatically capture the events described in this document (however, the web SDK does not yet provide a mobile inbox, and does not capture mobile inbox-related events).

It's also possible to capture these events by making calls to Iterable's API:

• POST /api/inApp/target
• POST /api/events/trackInAppDelivery
• POST /api/events/trackInAppClose
• POST /api/events/trackInAppOpen
• POST /api/events/trackInAppClick
• POST /api/events/inAppConsume

Other in-app message and Mobile Inbox APIs include:

• GET /api/inApp/getMessages
• POST /api/inApp/cancel

# Event definitions

This section describes the various events Iterable can capture for in-app messages and Mobile Inbox.

# In-browser message events

There are no events specific to in-browser messages (in-app messages that target a website instead of a mobile app). They're standard in-app message events, with platform set to Web, deviceId set to the browser user agent associated with the event, and appPackageName is set to your app's package name.

# In-app click

An in-app click event indicates that a user tapped a link or button in an in-app message.

Fields:

• campaign — An object containing various fields that describe the campaign associated with the event (object)
• campaignId — The ID of the campaign associated with the message (long)
• clickedUrl — The URL of the clicked link/button (string, if available)
• createdAt — When the event occurred (date)
• deviceInfo — An object containing various fields that describe the device and app associated with the event (object)
  • deviceId — The device's unique identifier, or a browser user agent (string)
  • platform — iOS, Android, or Web (string)
  • appPackageName — The package name of the app (string)
• email — The email address of the recipient (string)
• eventType — inAppClick (string)
• expiresAt — The expiration date and time for the message associated with the event (date)
• inboxSessionId — The ID of the inbox session in which this event occurred. Not present if there's not an inbox session associated with the event.
• messageContext — An object containing various fields that describe the message associated with the event (object)
  • location — The location from which the event was initiated: in-app, inbox or a custom value (string).
  • saveToInbox — Whether or not the message associated with the event was configured to use the inbox (boolean)
  • silentInbox — Whether or not the message associated with the event was configured to send directly to the inbox (boolean)
• messageId — The ID of the message associated with the event (string)
• templateId — The ID of the template associated with the message (long)

# In-app close

An in-app close event indicates that a user closed an in-app message by tapping a button or link in the message's content or by tapping a back button (or an auto-generated close button on an in-browser message, if your web SDK implementation is configured to add one).

Fields:

• campaign — An object containing various fields that describe the campaign associated with the event (object)
• campaignId — The ID of the campaign associated with the message (long)
• clickedUrl — The URL (if any) of the button/link the user clicked to close the in-app message.
• closeAction — The type of action that initiated the close: link (for buttons or links), back (for a back button), other or a custom value (string)
• createdAt — When the event occurred (date)
• deviceInfo — An object containing various fields that describe the device and app associated with the event (object)
  • deviceId — The device's unique identifier, or a browser user agent (string)
  • platform — iOS, Android, or Web (string)
  • appPackageName — The package name of the app (string)
• email — The email address of the recipient (string)
• eventType — inAppClose (string)
• expiresAt — The expiration date and time for the message associated with the event (date)
• inboxSessionId — The ID of the inbox session in which this event occurred. Not present if there's not an inbox session associated with the event.
• messageContext — An object containing various fields that describe the message associated with the event (object)
  • location — The location from which the event was initiated: in-app, inbox or a custom value (string).
  • saveToInbox — Whether or not the message associated with the event was configured to use the inbox (boolean)
  • silentInbox — Whether or not the message associated with the event was configured to send directly to the inbox (boolean)
• messageId — The ID of the message associated with the event (string)
• templateId — The ID of the template associated with the message (long)

# In-app delete

An in-app delete event indicates that a user deleted an inbox-enabled in-app message by swiping it in the inbox or clicking a delete button/link (with URL iterable://delete) in its content.

Fields:

• campaign — An object containing various fields that describe the campaign associated with the event (object)
• campaignId — The ID of the campaign associated with the message (long)
• createdAt — When the event occurred (date)
• deleteAction — How the message was deleted: inbox-swipe (the message was deleted with a swipe in the inbox), or delete-button (the user tapped a button or link having URL iterable://delete) or a custom value.
• deviceInfo — An object containing various fields that describe the device and app associated with the event (object)
  • deviceId — The device's unique identifier, or a browser user agent (string)
  • platform — iOS, Android, or Web (string)
  • appPackageName — The package name of the app (string)
• email — The email address of the recipient (string)
• eventType — inAppDelete (string)
• expiresAt — The expiration date and time for the message associated with the event (date)
• inboxSessionId — The ID of the inbox session in which this event occurred. Not present if there's not an inbox session associated with the event.
• messageContext — An object containing various fields that describe the message associated with the event (object)
  • location — The location from which the event was initiated: in-app, inbox or a custom value (string).
  • saveToInbox — Whether or not the message associated with the event was configured to use the inbox (boolean)
  • silentInbox — Whether or not the message associated with the event was configured to send directly to the inbox (boolean)
• messageId — The ID of the message associated with the event (string)
• templateId — The ID of the template associated with the message (long)

# In-app delivery

An in-app delivery event indicates that an in-app message arrived on a user's device. It does not mean that the user viewed the message.

Fields:

• campaign — An object containing various fields that describe the campaign associated with the event (object)
• campaignId — The ID of the campaign associated with the message (long)
• createdAt — When the event occurred (date)
• deviceInfo — An object containing various fields that describe the device and app associated with the event (object)
  • deviceId — The device's unique identifier, or a browser user agent (string)
  • platform — iOS, Android, or Web (string)
  • appPackageName — The package name of the app (string)
• email — The email address of the recipient (string)
• eventType — inAppDelivery (string)
• expiresAt — The expiration date and time for the message associated with the event (date)
• messageContext — An object containing various fields that describe the message associated with the event (object)
  • saveToInbox — Whether or not the message associated with the event was configured to use the inbox (boolean)
  • silentInbox — Whether or not the message associated with the event was configured to send directly to the inbox (boolean)
• messageId — The ID of the message associated with the event (string)
• templateId — The ID of the template associated with the message (long)

# In-app open

An in-app open event indicates that an in-app message was displayed, either because it appeared on arrival or because the user selected it in the inbox.

Fields:

• campaign — An object containing various fields that describe the campaign associated with the event (object)
• campaignId — The ID of the campaign associated with the message (long)
• createdAt — When the event occurred (date)
• deviceInfo — An object containing various fields that describe the device and app associated with the event (object)
  • deviceId — The device's unique identifier, or a browser user agent (string)
  • platform — iOS, Android, or Web (string)
  • appPackageName — The package name of the app (string)
• email — The email address of the recipient (string)
• eventType — inAppOpen (string)
• expiresAt — The expiration date and time for the message associated with the event (date)
• inboxSessionId — The ID of the inbox session in which this event occurred. Not present if there's not an inbox session associated with the event.
• messageContext — An object containing various fields that describe the message associated with the event (object)
  • location — The location from which the event was initiated: in-app, inbox or a custom value (string)
  • saveToInbox — Whether or not the message associated with the event was configured to use the inbox (boolean)
  • silentInbox — Whether or not the message associated with the event was configured to send directly to the inbox (boolean)
• messageId — The ID of the message associated with the event (string)
• templateId — The ID of the template associated with the message (long)

# In-app send

An in-app send event indicates that Iterable sent an in-app message to a user. It does not mean that the user received the message.

Fields:

• campaign — An object containing various fields that describe the campaign associated with the event (object)
• campaignId — The ID of the campaign associated with the message (long)
• channelIds — The IDs of the channels associated with the in-app message.
• contentId — The ID of the template revision for the message associated with the event (long)
• createdAt — When the event occurred (date)
• email — The email address of the recipient (string)
• eventType — inAppSend (string)
• expiresAt — The expiration date and time for the message associated with the event (date)
• messageContext — An object containing various fields that describe the message associated with the event (object)
  • saveToInbox — Whether or not the message associated with the event was configured to use the inbox (boolean)
  • silentInbox — Whether or not the message associated with the event was configured to send directly to the inbox (boolean)
• messageId — The ID of the message associated with the event (string)
• messageTypeIds — The IDs of the message types associated with the in-app message.
• templateId — The ID of the template associated with the message (long)

# In-app send skip

An in-app send skip event indicates that Iterable did not send an in-app message to an intended recipient, for any of various reasons.

Fields:

• campaign — An object containing various fields that describe the campaign associated with the event (object)
• campaignId — The ID of the campaign associated with the message (long)
• createdAt — When the event occurred (date)
• email — The email address of the recipient (string)
• eventType — inAppSendSkip (string)
• messageId — The ID of the message associated with the event (string)
• reason — A string that describes why Iterable did not send the message to the intended recipient; for example, DuplicateMarketingMessage (string)

# Inbox message impression

An inbox message impression event captures the number of unique times a specific message appeared in the message list during a single inbox session (period when the inbox was open). It's useful for understanding how many times a user had the opportunity to notice a particular message in the inbox during a single inbox session.

Fields:

• campaign — An object containing various fields that describe the campaign associated with the event (object)
• campaignId — The ID of the campaign associated with the message (long)
• createdAt — When the event was created; close to the end of the session (date)
• deviceInfo — An object containing various fields that describe the device and app associated with the event (object)
  • deviceId — The device's unique identifier, or a browser user agent (string)
  • platform — iOS or Android (string)
  • appPackageName — The package name of the app (string)
• email — The email address of the recipient (string)
• eventType — inboxMessageImpression (string)
• expiresAt — The expiration date and time for the message associated with the event (date)
• impressionCount — The number of times the message appeared in the inbox list during the inbox session associated with this event (long)
• inboxSessionEnd — The date and time when the inbox session ended (date)
• inboxSessionId — The ID of the inbox session associated with this event.
• inboxSessionStart — The date and time when the inbox session started (date)
• messageContext — An object containing various fields that describe the message associated with the event (object)
  • saveToInbox — Whether or not the message associated with the event was configured to use the inbox (boolean)
  • silentInbox — Whether or not the message associated with the event was configured to send directly to the inbox (boolean)
• messageId — The ID of the message associated with the event (string)
• templateId — The ID of the template associated with the message (long)
• totalDuration — The total number of seconds the message was visible in the inbox during the inbox session associated with this event.

# Inbox session

An inbox session event indicates that an app displayed the mobile inbox and captures how long it was open. The time span for this event starts when the inbox appears on the screen and ends when the user navigates away, minimizes the app, or closes the app. Tapping on a message in the inbox to view its content does not end the inbox session.

Fields:

• createdAt — When the event was created; close to the end of the session (date)
• deviceInfo — An object containing various fields that describe the device and app associated with the event (object)
  • deviceId — The device's unique identifier (string)
  • platform — iOS or Android (string)
  • appPackageName — The package name of the app (string)
• email — The email address of the recipient (string)
• endTotalMessageCount — The number of messages in the inbox at the end of the inbox session. May differ from startTotalMessageCount since messages can be added or deleted during a session (long)
• eventType — inboxSession (string)
• inboxSessionEnd — The date and time when the inbox session ended (date)
• inboxSessionId — The ID of this inbox session.
• inboxSessionStart — The date and time when the inbox session started (date)
• startTotalMessageCount — The number of messages in the inbox at the start of the inbox session (long)
• uniqueImpressionCount — The number of unique messages that made an impression during the inbox session (long)

# Click, close, and delete events

Iterable's mobile SDKs sometimes capture multiple events when users tap a single button or link in the content of an in-app message:

• All button and link taps create in-app click events.

• Close button taps (URL iterable://dismiss) create in-app click and in-app close events.

• Delete button taps (URL iterable://delete) create in-app click, in-app close and in-app delete events.

• Swiping to delete a message in a mobile inbox only creates an in-app delete event.

# Using in-app message and Mobile Inbox events

Iterable provides various ways to make use of in-app message and Mobile Inbox events, as described below.

# Campaign analytics

Use campaign analytics to learn how users are interacting with your in-app messages.

To view the analytics for an in-app message campaign, navigate to Messaging > Campaigns and open the (active) campaign in question. Use the drop-down menu initially labeled No Metrics Selected to pick the metrics you'd like to view.

Available in-app message and Mobile Inbox analytics include:

• Average order value
• In-app click rate
• Revenue
• Total in-app clicks
• Total in-app closes
• Total in-app deletes
• Total in-app deliveries
• Total in-app holdouts
• Total in-app opens
• Total in-app sends
• Total in-app send skips
• Total inbox impressions
• Total purchases
• Total unsubscribes
• Unique in-app clicks
• Unique purchases
• Unique unsubscribes

# Segmenting users and filtering journeys

In-app message and Mobile Inbox events can be used to segment users or filter them in a journey.

For example:

• This screenshot shows a segmentation query that searches for users that have five or more inbox message impressions for a particular messageId:

  

• This screenshot shows a journey filter on users that have deleted any messages from their inbox by searching for In-App Delete events with messageContext.location set to inbox:

  

The following in-app message and Mobile Inbox events can be used to segment users and filter journeys:

• In-app click
• In-app close
• In-app delete
• In-app delivery
• In-app open
• In-app send
• In-app send skip
• Inbox message impression
• Inbox session

# Triggering journeys

In-app message and Mobile Inbox events can be used to trigger journeys for particular users.

To do this, navigate to Content > Journeys and open the necessary journey. Edit the journey's Start tile and select the appropriate entry source:

The following in-app message and Mobile Inbox events can trigger journeys:

• In-app click
• In-app close
• In-app delete
• In-app delivery
• In-app open

# Triggering system webhooks

Inbox and in-app events can be used to trigger system webhooks to send data to external systems.

To do this, navigate to Integrations > System Webhooks and create or edit a webhook. Select the in-app or Mobile Inbox events that should trigger the webhook:

The following in-app message and Mobile Inbox events can trigger system webhooks:

• In-app click
• In-app close
• In-app delete
• In-app delivery
• In-app open
• In-app send
• In-app send skip

# Further reading

User guides:

• In-App Messages and Mobile Inbox
• Sending In-App Messages

Developer documentation:

• Iterable's iOS SDK
• Iterable's Android SDK
• Iterable's React Native SDK
• In-App Messages Overview
• In-App Messages on iOS
• In-App Messages on Android
• Tracking Events with Iterable's Mobile SDKs
• Setting up Mobile Inbox on iOS
• Setting up Mobile Inbox on Android
• Customizing Mobile Inbox on iOS
• Customizing Mobile Inbox on Android
• Animating In-App Messages with CSS
• Image Carousels in In-App Messages
• Testing and Troubleshooting In-App Messages
• In-App Messages Without the SDK
• API Overview and Sample Payloads
• API Overview