The WebEngage Knowledge Base Developer Hub

Welcome to the WebEngage Knowledge Base developer hub. You'll find comprehensive guides and documentation to help you start working with WebEngage Knowledge Base as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Basics of CSV Uploads

Users

Any user profile data on WebEngage has attributes that define a user, such as First Name, Last Name, Date of Birth, Gender, Score, Membership Type and so on.

Among the attributes above, there are certain attributes that are predefined by WebEngage such as First Name, Last Name etc. These are called System Attributes. The second set of attributes you see above such as Score, Membership Type etc. are defined by you. These are called Custom Attributes.

Please refer to Users for more details on the system and custom attributes.

Any User CSV file you upload on WebEngage will have a mix of system and custom attributes that define each user. Let’s look at a tabular representation of a sample User CSV file. If you notice the first row in the table below, you will see that this CSV file has a mix of system attributes (user_id, email, phone, first_name, last_name) and custom attributes (score, membership_type).

user_idemailphonefirst_namelast_namescoremembership_type
2123414[email protected]+1 925 336 0294AdamSmith20Gold
2384708[email protected]+65 9039 1135JohnKnowles10Silver

In addition to defining specific user attributes as system attributes, WebEngage has also assigned the relevant data types to these system attributes (e.g. system attribute email is of String data type). When you are preparing your User CSV file, you need to ensure that you use these same attribute names and data types to represent your user data.

Please note that you cannot change the name of these system attributes or the corresponding data types.

Following is the list of system attributes and their data types that have been defined by WebEngage and is available for use in CSV file uploads.

List of System Attributes for Users CSV File Upload

System Attribute NameData TypeDescription
user_idStringUser ID
first_nameStringFirst name
last_nameStringLast name
birth_dateDateBirth date in YYYY-MM-DD format
genderStringGender - value can only be one of male, female, other
companyStringCompany
countryStringCountry
cityStringCity
regionStringRegion
localityStringLocality
postal_codeStringPostal Code
emailStringEmail ID
phoneStringPhone number of the user in E.164 format
eg. +551155256325, +917850009678
hashed_emailStringEncrypted email address for use with a private ESP (Email Service Provider). This can be a maximum of 512 characters. See PII hashing for more details
hashed_phoneStringEncrypted email address for use with a private SSP (SMS Service Provider). This can be a maximum of 512 characters. See PII hashing for more details
email_opt_inBooleanIf this is set to false, Email campaigns will not be sent to the user
sms_opt_inBooleanIf this is set to false, SMS campaigns will not be sent to the user
push_opt_inBooleanIf this is set to false, Push campaigns will not be sent to the user
whatsapp_opt_inBooleanIf this is set to false, WhatsApp campaigns will not be sent to the user

In addition to these system attributes, you can define various custom attributes (and their corresponding data types) that represent a user. If you have integrated the WebEngage SDK in your mobile apps or website, you might have already defined these custom attributes.

You can check the custom attributes you have already defined on your WebEngage dashboard under the Data Management > User attributes list section.

When preparing your User CSV file, you can choose to use the already existing custom attributes, or you could choose to add new custom attributes. Do note that once these custom attributes are recorded in WebEngage, you will not be able to change their name. Therefore, please be careful whenever you add new custom attributes.

Please take note of the following limitations when creating new custom attributes:

  • Values of an attribute can only be of one of the following data types: Boolean, Number, String, and Date. Map and Array data types are not allowed for CSV uploads.

  • A user profile can have a maximum of 25 custom attributes per data type for the following data types: Boolean, Number, String, Date (i.e. 25 custom attributes of Number data type, 25 custom attributes of String data type etc.).

  • The maximum length of a String data type for an attribute is 1000 characters.

  • The maximum length of an attribute name is 50 characters.

  • The name of your user attribute should not begin with we_.

🚧

CSV Uploads Are Only for Known Users

Please note that CSV Uploads for Users can be used only to add or update details of known users. You will not be able to add or update the details of any unknown users through CSV uploads.

Events

Events in WebEngage are of the following types. Please refer to Events for more details.

  • System Events: These events are automatically captured by WebEngage as soon as the SDK integration is done such as App Install, App Uninstall etc.

  • Campaign Events: These events are automatically captured by WebEngage, based on the actions your users perform on the campaigns they receive through WebEngage such as Email Open, Email Click etc.

  • Custom Events: These events are sent by you to WebEngage, based on the actions performed by your users, on your mobile app and/or website. Some examples of these events are: Purchased, Searched, Added to Wishlist and so on. You can check the various custom events you are already sending to WebEngage under the Data Management > Events section of your dashboard.

🚧

Only CSV Files with Custom Events Can Be Uploaded

Please note that you can upload Events CSV file for Custom Events only. The file can contain data about an already existing custom event or a new custom event. Any new custom events created through CSV files will be visible on your list of events section in the WebEngage dashboard under Data Management > Events list section.

A custom event has attributes that describe the details of the event - who did the event, where did the event happen, what time did the event happen etc. Just like User attributes, attributes of a Custom Event are of two types:

  • System Attributes: These are predefined by WebEngage, and they automatically capture certain details about the event such as time of the event, who did the event, the location where the event happened etc.

  • Custom Attributes: These attributes and their data types are defined by you. For example, a Purchase event could have custom attributes like Item ID, Item Price, Item Category etc.

Any Events CSV file you upload on WebEngage will have a mix of system and custom attributes that define each custom event. Let’s look at a tabular representation of a sample Events CSV file. If you notice the first row in the table below, you will see that this CSV file has a mix of system attributes (event_name, user_id, event_time) and custom attributes (product, price, category).

event_nameuser_idevent_timeproductpricecategory
add_to_cart21234142018-01-21 10:23:21iPhone XS$800Phone
add_to_cart23847082018-05-18 22:20:00Inspiron 6000$549Laptop

In addition to defining specific event attributes as system attributes, WebEngage has also assigned the relevant data types to these system attributes (e.g. system attribute event_name is of String data type). When you are preparing your Events CSV file, you need to ensure that you use these same attribute names and data types to represent your data. Note that you cannot change the name of these system attributes or the corresponding data types.

Following is the list of system attributes and their data types that have been defined by WebEngage and have to be mandatorily used in uploads of Events CSV files.

List of System Attributes for Events CSV File Upload

System Attribute NameData TypeDescription
event_nameStringName of the event
user_idStringUser ID of the user that performed the event
event_timeDateTime at which the the event occurred in ISO format

🚧

System Attributes Not Included for Events CSV Uploads

There are other system attributes as well such as Country, City, OS, Browser etc. These are not covered in the list above because you will not be able to use these system attributes in your CSV files.

In addition to these system attributes, you can define various custom attributes (and their corresponding data types) that represent a custom event. If you have integrated the WebEngage SDK in your mobile apps or website, you might have already defined these custom attributes. You can check the custom attributes of custom event you have already defined on your WebEngage dashboard under the Data Management > Events section of your dashboard.

When preparing your Events CSV file, you can choose to use the already existing custom attributes, or you could choose to use new custom attributes. Do note that once these custom attributes are recorded in WebEngage, you will not be able to change their name. Therefore, please be careful whenever you add new custom attributes.

Please take note of the following limitations when you’re creating new custom attributes:

  • Values of an attribute can only be of one of the following data types: Boolean, Number, String, and Date. Map and Array data types are not allowed for CSV uploads.

  • A custom event can have a maximum of 25 custom attributes per data type for the following data types: Boolean, Number, String, Date (i.e. 25 custom attributes of Number data type, 25 custom attributes of String data type etc.).

  • The maximum length of an event name is 50 characters.

  • The maximum length of a String data type for an attribute is 1000 characters.

  • The maximum length of an attribute name is 50 characters.

  • The name of your event or event attribute should not begin with we_.

Updated 8 months ago


So, what's next?

Upload Process

Basics of CSV Uploads


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.