Events

An event is an activity that an end user performs when interacting with your brand.

Example:

• Opening a link in your email
• Adding an item to a cart in your app
• Updating their phone number in a form on your website.

When an end user performs an action, the information about the action is saved as an event in People.

Example: When an end user interacts with a link, you can save the following information in People.

• Type of action (click or open)
• Source of the action (webpage or app)
• Time when the action was performed
• Web page in which the link was clicked

You can then use this information in different ways. Example: Send messages to end users when an event happens or analyze how many end users visit your web.

To view events, go to the Attributes, Tags and Events tab on the end user's profile page.

How to use events

The following are some examples of how to use events.

• Use event data to follow up with end users. Example: When an end user abandons items in cart, the abandoned cart event is logged. Send a follow-up email asking if they need help.
• Understand end user behavior patterns by analyzing event data.
• Use event data to recommend related products to end users. Example: If an end user purchases a mobile phone, the event item purchased is logged. Recommend accessories such as power banks and earphones.
• Use event data to segment audience. Example: Send a follow-up email only to end users who view a specific product on your website.
• Use events to personalize messages to end users.
• Use events in computed attributes. You can make calculations against event data in event aggregates and evaluate profiles when doing profile scoring.

Types of events

Events are of the following types.

• Custom events: These are the events that you create in People to track end user activity on your digital assets such as your websites, mobile apps, and other platforms and applications. Custom events are specific to your business.

• Template events: Event templates that are pre-populated with event properties, which you can customize and use for common use cases, such as e-commerce.

• Standard events: Predefined events that occur when the following happen.

  • You communicate with end users through Infobip products, such as Moments, Conversations, and Answers.
  • When person profiles (attributes, destinations, or tags) are updated.

  Standard events include People events, Channel events, and Product events.

Custom Events

These are the events that you create in People to track end user activity on your digital assets such as your websites, mobile apps, and other platforms and applications. Custom events are specific to your business.

Create a custom event

1. On the Infobip web interface (opens in a new tab), go to People > Events > Custom events tab.

2. Select Create event.

   

3. In the Event name field, enter the name of the event. Example: AddedToCart.

4. Make sure that the Event ID is unique. This field is automatically populated based on the event name. This ID is used to track the event by using the Infobip API and SDKs.

5. (Optional) In the Description field, enter the description of the event.

   

6. (Optional) Create as many properties as required.

   To add a property to an event, do the following.

   1. Select Add event property.

      

   2. In the Name field, specify the name of the property.

   3. In the Type field, select the data type of the property.

   For more information about properties, refer to the Event properties documentation.

   

Event properties

Event properties enable you to add additional information to an event.

Example: For the event adding a product to cart, you can create the following properties.

Property	Description
addedCart	Successful addition of the product to cart
productID	Unique identifier of the product
productName	Name of the producte
productPrice	Price of the product

Data types for properties

Event properties can have the following data types.

Data type	Description
Text	Use for properties that are in text format. Example: productName and productDescription.
Text	Use for properties that contain one of only two values - True or False.
Date	Use for properties that contain date values.
Number	Use for properties that are in a number format. Example: productPrice
List	Add a list as a property. Example: To pass information about an end user's shopping cart from your website to a flow in Moments, create a cartItems property of type List. In this property, add fields, such as item name, item ID, quantity, and price. You can add a maximum of 1 List property to an event. You can add a maximum of 128 fields to a List property.

Examples of properties

The following table shows examples of properties.

Event	Properties
Item Added to Cart	Item Name Item Price
Form Filled Out	Fields Filled
Flight Tickets Purchased	Travel Type
Support Ticket Closed	Ticket Id Closure Date

Test send an event

1. On the Infobip web interface (opens in a new tab), go to People > Events > Web SDK tab.

2. In the Try it out section, select an event and a person profile related to it.

3. Select Send event.

   

The event is added to the person's profile page.

Currently, you cannot set values for list properties in test events.

Track custom events on your platform

You can track custom events through the following.

• Web SDK
• API
• Mobile SDK

Web SDK

The Web SDK enables you to capture events from your website. To learn how to add the Web SDK code to your website and use it to track custom events, refer to the guidelines and the Web SDK documentation.

Events API

API is considered a secure way to send events to Infobip from other systems.

When you use API, you can send events only for person identifiers that already exist in People. If you send an event for a person identifier that does not exist in People, you get an error.

For details about the implementation, refer to the guidelines and the developer guide (opens in a new tab).

Mobile SDK

Use the mobile SDK to capture events from mobile apps.

You can capture the following types of events.

• Standard app events are enabled for all Moments users who have Mobile SDK implemented in their mobile app. You do not need to perform any additional actions to track these events. Example: application installed.

  Refer to the Channel Events section to see the list of available mobile app events.

• Custom events are the events that you create and configure, to track end user activities. You can track custom events by using Mobile SDK. Example: send a custom event by using Mobile SDK when an end user adds items to a shopping cart, purchases an item, or finishes the steps in an onboarding process.

Learn about how to set up mobile events tracking on the following.

• iOS (opens in a new tab)
• Android and Huawei (opens in a new tab) SDKs
• React Native (opens in a new tab) plugin
• Cordova (opens in a new tab) plugin 
• Flutter (opens in a new tab) plugin

Guidelines

When a custom event is sent through a call to the Web SDK or Events API, there must be a 1:1 mapping between the event and the event schema.

The following guidelines apply.

• If a call contains more properties than defined in the schema, the call is rejected.
• If a call contains fewer properties than defined in the schema, the properties that are not included in the call have a value of NULL in the event.
• If a call contains properties that do not match the schema, the call is rejected. Example: The property in the event schema is in uppercase but the property in the event call is in lowercase.
• If the property value is a string, add it within quotation marks. If it is not, do not use quotation marks.
• Even if the event does not have properties, you must send the JSON body. In this case, send an empty JSON body. Example: {{}}

Template Events

Event templates are pre-populated with event properties, which you can customize and use for common use cases, such as e-commerce.

The templates contain both mandatory fields and optional properties.

The following table shows a list of template events. To see this list of events templates in the web interface, go to People > Events > Template events tab.

Template name	Purpose	Properties
itemViewed	This event shows the details of an item viewed by a profile.	itemID: Number. Mandatory duration: Number. Optional
itemPurchased	This event shows the details of a purchase made by a profile.	itemID: Number. Mandatory amount: Number. Optional price: Number. Optional profit: Number. Optional
ratingAdded	This event shows the rating that a profile gave to an item.	itemID: Number. Mandatory rating: Decimal. Optional
addedToCart	This event shows details of an item that a profile added to a cart.	itemID: Number. Mandatory amount: Number. Optional price: Number. Optional
addedToFavourites	This event indicates that a specific item was bookmarked by a profile	itemID: Number. Mandatory
viewPortionSet	This event indicates partial view of an item, such as a video or article, by a profile in a session.	itemID: Number. Mandatory portion: Decimal. Optional* sessionID: String. Optional** * Portion indicates the viewed portion of an item. It is a numerical value between 0.0 (item not viewed) and 1.0 (viewed item fully). The viewed portion depends on the position at which the item was viewed. Example: If the end user opens a video at 50%, but only views 10% after that, then the portion is 0.1, and not 0.6. ** The ID of the session in which the end user viewed the item. The default value is null.

Standard Events

Standard events are generated when end users interact with your services through Infobip products such as Moments, Conversations, and Answers.

These events are available in all elements that support events in these products. Example: In Moments, you can use events in elements such as triggers.

Enable or disable a standard event

To use events in Infobip products, you need to enable the events in People.

To enable or disable an event, do the following.

1. On the Infobip web interface (opens in a new tab), go to People > Events.
2. Go to the required event category (People events or Product events).
3. To track an event, select the check box next to the event.
4. To stop tracking an event, deselect the check box next to the event.
5. To save the changes, select Activate.

Types of standard events

Standard events include the following:

• People Events
• Channel Events
• Product Events

People Events

People events are triggered when there are changes to a person profile. The changes could be one of the following.

• Person activity: Activity done by the end user. Example: logged in.
• Standard attributes: Changes to standard attributes.
• Custom attributes: Changes to custom attributes.

You can create personalized messages based on these profile updates.

Person activity

Use cases for Person activity events

• Track anonymous visitor website visits: Follow the end user's journey from being an anonymous visitor through to lead and conversion.
• Targeted offering: If a person visits your mortgage page 5 times in a month, send them an email about mortgage offers and advice.
• Promotional code for a specific category: When an end user looks at the Shoes page 3 times within a week, send them a message with a promotional code for shoes.
• Reactivation: Start a reactivation campaign that includes end users who have not visited your webpage in the last 45 days.
• Abandoned cart: Send a communication after an end user visits your Search tickets page, then goes to the Select ticket page, but does not go to the Checkout page.
• Survey for active customers: If an end user has more than 100 page views in 30 days, send them a survey.

Track Person activity events on your website

To track Person activity events on your website, add a JavaScript-based Web SDK to your website. See Web SDK for more information.

Types of Person activity events

• Session started
• Page view
• Session ended
• Person created
• Person merged

Session started

This event logs when an end user visits your website.

Each Session started event contains the following properties that are automatically filled by the Web SDK.

Property	Description
Session ID	Unique session identifier
Session start	Time when the session started. Format is DD/MM/YYYY HH:MM:ss
Session type	Web
UTM parameters	utm_source utm_medium utm_campaign utm_term utm_content If the Session type is Web and no UTM tags are set in the page request, then utm_source is set to direct.

Page view

This event logs when an end user views your web page. Use this event to engage end users based on these views. Example: If an end user views your Shoes page 3 times in a week, send them a message with a promotional code for shoes.

Each Page view event contains the following properties that are automatically filled by the Web SDK.

Property	Type	Description
pageTitle	String	The title of the current page.
url	String	The URL of the page that was loaded for the PageView. This property value can have a maximum of 1,500 characters. If the URL exceeds this limit, the property value is truncated to 1,500 characters.
domain	String	The domain portion of the request URL.
path	String	The path portion of the URL. This value should start with the slash (/) character.
deviceType	String	The type of device that is used to load the page: This property can have the following values. unknown mobile tablet desktop spider TV console
timestamp	DateTime	Time (date, hour, minute, second) when the interaction occurred.
browserName	String	The browser name, such as Chrome or Firefox This information is obtained from the User-Agent header of an HTTP request.
browserVersion	String	The reported software version of the browser. This information is obtained from the User-Agent header of an HTTP request.
browserOS	String	The reported operating system that the browser is running on. Example: Windows or Linux. This information is obtained from the User-Agent header of an HTTP request.
referrer	String	The Referrer HTTP request header contains an absolute or partial address of the page making the request.
browserLanguage	String	Browser language.
websiteLanguage	String	Website language.

Session ended

This event logs when an end user stops being active on a website.

Each session ended event contains the following properties that are automatically filled by the Web SDK.

Property	Description
Session ID	Unique session identifier
Session End	Time when the session ended. Format is DD/MM/YYYY HH:MM:ss
Session Length	Session End - Session Start. In seconds.
Session Type	Web
UTM parameters	utm_source utm_medium utm_campaign utm_term utm_content If the Session type is Web and no UTM tags are set in the page request, then utm_source is set to direct.

Person created

This event logs when a person profile is created.

Person Merged

This event logs when person profiles are merged.

Standard Attributes

Track changes to standard attributes in profiles.

You can track the following standard attributes.

• Name changes in person profile: Changes to a person's first, middle, and last names.
• Location changes in person profile: Changes to address, city, and country.
• Other changes in person profile: Example: Date of birth.
• Tag changes: Tag is added or removed from a profile.
• Contact information: Addition or removal of channels over which the person can be contacted.

Contact Information

The following contact information events are available in a person profile.

Contact Information Type	Events
Email	Email address added Email address changed Email address deleted
Push	Push contact added Push contact changed Push contact deleted These push destination events provide information about the end user's activities on mobile apps. These events are generated by Mobile SDK and are displayed in person profiles in People.
Facebook	Facebook contact added Facebook contact changed Facebook contact deleted
SMS/Voice/MMS	Phone number added Phone number changed Phone number deleted
Other contact information	Contact information changed

Custom Attributes

Track changes to custom attributes in profiles.

Channel Events

These events are specific to the channel that is used to communicate with the end user. Use channel events to track the status of your messages and how customers react to them.

By default, all channel events are active. So, you do not need to make any changes during configuration.

The following table shows the events that are supported by the channels.

Channel	Event name
Email	Sent Delivered Opened Clicked Unsubscribed Complained
Mobile push	Sent Delivered Opened
In-app message	Sent Delivered Seen Clicked
SMS	Sent Delivered Clicked
WhatsApp	Sent Delivered Opened Clicked
Viber	Sent Delivered Opened Clicked
Messenger	Sent Delivered Opened Clicked
Mobile App	Personalize Depersonalize Install Uninstall App Launch
Voice	Voice Call Initiated Voice Call Answered Voice Call Not Answered Voice Busy Voice Call Answered By Machine Voice Inbound Call Answered Call Forwarded Busy Call Forwarded Not Answered Voice IVR Played Voice IVR Information collected Voice User Hang Up
LINE	Sent Link Clicked
MMS	Sent Delivered

Product Events

These events are for specific Infobip products.

• Moments: The product events show when a person entered or exited a specific communication campaign. This event happens based on customer attributes and activity, and in accordance with your settings.

• Answers: The product events show when an end user started or ended a specific chatbot session, and if the session failed to start. These events are added to end users' Person profiles in People. When an end user starts a session with your chatbot, the following happens.

  • If a profile exists for the end user, the events are added to the profile.
  • If a profile does not exist, a new profile of type Customer is automatically created in People. The product events are then added to this profile.

• Conversations: The product events show when an end user created or closed a conversation. These events are created only if a Person profile exists in People for the end user.

• Forms: You can track the Submit Form event if the processing rules (opens in a new tab) are enabled for the form. You can then use this information to send the requested information to the form submitter.

Use events to personalize messages

The following is an example of how to use an event from your app to personalize messages to end users.

1. In People, either identify an existing event that you want to use or create a custom event.
2. Integrate the event in your app. The app can now send the event to the Infobip platform.
3. In Moments, create a flow that is triggered by the event.
4. Map the data in the event to flow variables.
5. Use the flow variable to personalize the message to the end user.

Use events to segment your audience

Use events to create audience segments based on end user behavior. You can then organize your communication based on the segments. Example: You can decide whether to send a message based on the event or check the number of times an end user called your contact center.

You can create segments on the Segments page in People. When creating segments, combine events and attributes for more relevant segmentation.

In the following example, the selected attribute is Country and the event is Tag added.

Use events in Moments

In Moments, you can use events in the People real-time event trigger and the Wait for event element.

People real-time event trigger

Trigger a flow campaign based on custom events that you have defined previously in People, or based on predefined (standard) events.

Example: To send a message to all end users who add items to cart, in your communication flow, use the People real-time event trigger with the custom event Item Added to Cart.

Wait for event element

If you want to use events at a later stage of the communication flow, use the Wait for event element.

Example: In the Wait for event element, select Checkout Finished as the event to wait for. Enter the amount of time for which the element needs to wait for this event to occur.

Use events in People analytics

Use events in the following.

• Events Segmentation: Use events to create the audience segment that you want to analyze.
• Funnel Analytics: Select an event to use as a step in a funnel.

Example: Select Funnel analytics, and then select the standard events that you want to use.

Use events in external systems

To use events data in external systems, use the People API (opens in a new tab) to export the events as compressed files to your Amazon Web Services (AWS) S3 bucket.

Use Events Export API (opens in a new tab) to do the following.

• Submit an export event request (opens in a new tab) (Post)
• Check the status of your export request (opens in a new tab) (Get)
• Asynchronous cancellation of an export request (opens in a new tab) (Del)
• Get a list of event definitions (opens in a new tab) (Get)

Process

Set up AWS S3 bucket

Refer to the Amazon AWS documentation (opens in a new tab) to learn how to set up an AWS S3 bucket.

Set up S3 bucket permissions

Use AWS Identity and Access Management (IAM) to create a role that is used by the Events Export application to access the S3 bucket.

The role requires the following policies:

• S3 access policy to allow access to your S3 bucket.
• Trust policy to allow the Events Export application user to obtain a temporary session using the AWS Security Token Service. You can retrieve this code from the Events Export (opens in a new tab) page of the Infobip web interface.

After you set the required permissions, your S3 bucket is ready to accept exported files from Infobip.

Export the events

Submit an export event request following the schema defined on Submit an export event request (opens in a new tab).

After the request is complete, files containing events are exported to a designated S3 bucket. You can specify the directory path of the S3 bucket in which to save the files.

Each file is compressed to .gzip format. Filename format is
<requestid>-events-<starttime(yyyymmddhhmmsssss)>-<endtime(yyyymmddhhmmsssss)>.json.gz</endtime(yyyymmddhhmmsssss)></starttime(yyyymmddhhmmsssss)></requestid>.

When the file is uncompressed, it contains a maximum of 50,000 rows. Each row contains 1 event in JSON format.

Event schema

Each event has the following fields.

• Mandatory fields that present in all events.
• Additional properties that are specific to each event.

Mandatory fields

Field name	Value format	Example	Notes
definitionId	String	personEnteredFlow	Definition(type) of the event. See Get list of event definitions (opens in a new tab) endpoint.
eventId	String	fent_100000000270199_1_1647967373262	Unique ID of the event.
sessionId	String	61bc52b9ba3ae43407dbb246	Unique ID of the web session for events that are tracked by using People Web SDK In all other cases, this value is NULL.
personId	String	2342	Unique internal ID of the profile for which the event is registered.
externalPersonId	String	CS26_342	External ID of the profile for which the event is registered. If the profile does not exist, this value is NULL.
occuredTime	String	2022-09-14T15:00:35.495+0000	Timestamp of when the system receives the event, in ISO-8601 format.

Event specific fields

Each event might have one or more properties that contain additional information about the activity. The properties vary from one event type to another.

To view the properties of a standard event, add the event ID to the following base URL: https://portal.infobip.com/people/events/definitions/ (opens in a new tab) (opens in a new tab).

Example: Enter https://portal.infobip.com/people/events/definitions/emailLinkClicked (opens in a new tab) (opens in a new tab) to see the list of properties of the standard event, Email Link Clicked.

Events export can provide additional properties for events produced by Moments. Example: campaignName. You can export this information and use in external systems. The following table shows a list of these properties.

Field name	Value format	Example	Notes
campaignName	String	Communication name 56	The name of the campaign, if this data exists
elementName	String	Send email	The name of the flow element, if this data exists
campaignStart	String	2022-06-14T10:54:30.033+0000	The start date and time of the campaign, if this data exists
flowElementId	String	10000005271386-12	The ID of the flow element, if this data exists

To enable this functionality, set the enrichWithMomentsInfo parameter to True when submitting an export event request (opens in a new tab).

Data retention for events

People events follow the data retention policies for Infobip products and services. Events are stored only for a limited period. Custom retention options are available on request. The retention policy applies to all event types.

This section explains how data retention policy affects the way you use People events in segments, reports, flow triggers, and computed attributes.

For more information, refer to Data retention policy.

How data retention works

When you use an event condition to filter search results, query a segment, or calculate computed attributes, the system only has access to the events that are within the event data retention period on your Infobip account. If the event condition exceeds this period, a warning message is displayed. In this case, consider adjusting the condition such that it is within the retention period.

Exceptions

Event filters and conditions that are used in segments or triggers in active flows and event-based computed attributes (profile scores and event aggregates) are not affected by data retention. The system temporarily saves the necessary information about the matching events to keep these filters functional even when the original events are deleted according to the retention policy.

Example: A flow is waiting for 3 product orders over a period of 9 months. By the time the third order arrives, some of the events might have been deleted because of data retention. But the trigger still works because the required event information is temporarily saved. 

The saved event data is lost when the flow stops or the computed attribute is deactivated.