Profile & Session Properties
What it is
Properties are the individual data fields that make up customer profiles and sessions in the BotBat CDP. They serve as the foundational building blocks for segmentation, personalization, analytics, and automation throughout the entire platform. Every piece of information you collect about a customer, from their name and email to custom business attributes like subscription tier or lifetime value, is stored as a property.
Profile properties are persistent attributes of a customer that remain associated with their record across all interactions. Examples include name, email, phone number, subscription plan, and lifetime value. Session properties, by contrast, capture context about a specific interaction period, such as the device type, browser, geographic location, and referrer URL. Session properties reset with each new visit and provide insight into how customers engage rather than who they are.
BotBat ships with a comprehensive set of built-in properties and gives you full control to define custom properties with specific data types, validation rules, and display settings. These properties appear throughout the platform: in the segment query builder as filterable conditions, in message templates as dynamic placeholders, in import wizards as mapping targets, and in profile detail views as readable fields.
When to use
| Scenario | Description |
|---|---|
| Extending the data model | The built-in profile fields do not cover your business needs and you want to add custom properties like "company_name," "subscription_tier," "preferred_language," or "lead_score." |
| Ensuring data quality | You need to enforce data types (string, number, boolean, date, array) and validation rules (required, regex pattern, min/max values) to maintain clean, consistent data. |
| Mapping imported data | You are importing contacts from a CSV or external system and need to map source columns to BotBat profile properties, including custom fields created on the fly. |
| Building segment conditions | You create segment conditions based on profile properties (e.g., "country = US AND subscription_tier = premium") and need to understand available properties and their data types. |
| Personalizing messages | You insert dynamic content into campaign messages using property placeholders (e.g., Hello {{firstName}}) and need to know the exact property names and expected values. |
| Analyzing session context | You want to segment or report based on interaction context such as mobile vs. desktop, direct vs. referral traffic, or geographic region. |
Steps
Step 1: Navigate to Properties
Click "Customers" in the main sidebar, then select the "Properties" tab. The view is organized into two sections: Profile Properties and Session Properties. Each property is displayed with its name, data type, scope, and whether it is built-in or custom.
Step 2: Review built-in profile properties
Browse the built-in profile properties provided by default. These properties cannot be deleted but their display names and visibility can be adjusted.
| Property | Data Type | Description |
|---|---|---|
firstName / lastName | String | Customer's first and last name. |
email | String (email format) | Primary email address used for email campaigns and identity matching. |
phoneNumber | String (E.164 format) | Primary phone number used for WhatsApp, SMS, and identity matching. |
channel | String | The channel through which the profile was created (whatsapp, sms, email, web). |
createdAt | Date | Timestamp of when the profile was first created. |
lastSeen | Date | Timestamp of the most recent event recorded for this profile. |
city / country | String | Geographic information derived from IP geolocation or explicitly provided. |
Step 3: Create a custom property
Click "New Property" and configure the following fields. Take care with data type selection, as it cannot be changed after creation.
| Field | Required | Description |
|---|---|---|
| Name | Yes | Internal identifier in camelCase with no spaces (e.g., "subscriptionTier"). |
| Display name | Yes | Human-readable label shown in the UI (e.g., "Subscription Tier"). |
| Data type | Yes | Choose from: String, Number, Boolean, Date, Array (multi-value), or Object (JSON). |
| Validation | No | Optional constraints: required flag, default value, min/max for numbers, regex pattern for strings, allowed values (enum). |
| Scope | Yes | Profile (persistent across sessions) or Session (per-session only). |
| Visibility | No | Whether the property appears in profile detail views and is available in template variables. |
Step 4: Edit an existing property
Click on any property to modify its display name, validation rules, or visibility settings. The property's internal name and data type cannot be changed after creation to prevent data corruption. If you need a different data type, create a new property and migrate the data.
Step 5: Review session properties
Switch to the Session Properties section to view properties that describe interaction context. These are populated automatically when a session is initiated.
| Property | Data Type | Description |
|---|---|---|
deviceType | String | Desktop, mobile, or tablet. |
browser | String | Browser name and version. |
operatingSystem | String | OS name and version. |
location | Object | Geolocation data including city, region, country, and coordinates. |
referrer | String | The referring URL or traffic source. |
sessionDuration | Number | Length of the session in seconds. |
Step 6: Map properties during import
When importing contacts, use the column mapping interface to match CSV columns to profile properties. If the import contains fields that do not yet exist in your schema, you can create new custom properties directly from the mapping interface without leaving the import wizard.
Step 7: Use properties in segments
In the segment query builder, property conditions appear with type-appropriate operators. Strings support "equals," "contains," and "starts with." Numbers support "greater than," "less than," and "between." Dates support "before," "after," and "in the last N days." Boolean fields offer simple true/false toggles.
Step 8: Use properties in message templates
Insert property placeholders in campaign messages using double-brace syntax: {{propertyName}}. For optional properties where a value may not exist, use a fallback: {{city|"your area"}}. The template editor provides a variable picker that lists all available properties with their data types.
Common pitfalls
| Pitfall | Why It Matters | How to Avoid It |
|---|---|---|
| Inconsistent naming conventions | Mixing camelCase, snake_case, and spaces makes properties hard to use in templates and segments. | Establish and enforce a naming convention before creating any properties. |
| Wrong data type selection | Data types are permanent. Storing phone numbers as Number or dates as String limits filtering and validation. | Plan your schema carefully and choose the correct data type on first creation. |
| Over-creating custom properties | Every custom property adds complexity to the data model and UI. | Check whether an existing property or label serves the purpose before creating a new one. |
| Ignoring validation rules | Without validation, fields contain inconsistent data (e.g., "USA," "US," "United States"). | Use allowed values (enum) for fields with a known set of options. |
| Confusing profile and session scope | Session-scoped properties reset with each visit and cannot be used for long-term segmentation. | Use profile scope for any persistent customer attribute. |
Create a "Property Dictionary" document for your team listing every custom property, its data type, allowed values, and intended use case. This prevents duplicate properties and ensures everyone uses the same fields consistently across campaigns, segments, and templates.
- Properties List
- Create Property
- Edit Property
- Session Properties
- Import Mapping
- Segment Builder
- Template Variables