Event Tracking

What it is

Events represent individual customer actions tracked by the BotBat CDP. Every meaningful interaction, whether it is a page view, a message sent, a link clicked, a form submitted, a purchase completed, or any custom event you define, is recorded as an event tied to a customer profile and session. Events are immutable records; once written, they cannot be modified, ensuring a trustworthy audit trail of customer behavior.

Events are the behavioral data layer that powers dynamic segments, automation rules, conversion goals, and campaign analytics. While profile properties tell you who a customer is, events tell you what they have done. This distinction is critical because behavioral data enables far more precise targeting and personalization than demographic data alone. A segment based on "clicked a pricing link in the last 7 days" is significantly more actionable than one based on "job title is Manager."

Each event consists of a type (the action category), a timestamp, a set of properties (contextual details about the action), and references to the associated profile and session. Events are stored in reverse chronological order and can be queried by type, date range, profile, or any combination of these filters.

Built-in event types

The CDP ships with several built-in event types that are tracked automatically when you integrate BotBat with your channels and website. You can also define custom event types for business-specific actions.

Event type	Description	Common properties
page_view	Recorded when a customer visits a page on your tracked website or web app.	url, page_title, referrer, duration
message_sent	Recorded when a message is sent to a customer through any channel.	channel, campaign_id, template_id, message_id
message_delivered	Recorded when a sent message is confirmed as delivered to the customer's device.	channel, campaign_id, message_id, delivered_at
message_read	Recorded when the customer opens or reads a delivered message.	channel, campaign_id, message_id, read_at
link_clicked	Recorded when the customer clicks a tracked link in a message or on your website.	url, campaign_id, link_label, channel
form_submitted	Recorded when the customer submits a tracked form.	form_id, form_name, fields
session_started	Recorded when a new interaction session begins for a customer.	channel, source, device_type
custom	Any event type you define for business-specific tracking.	Varies based on your schema definition.

When to use

• Analyzing customer behavior: When you want to understand what actions customers are taking across your channels. The Events tab provides a centralized log of all activity, making it possible to identify patterns such as which pages drive the most engagement or which campaign links get the most clicks.

• Building behavioral segments: When you need to create audience segments based on actions rather than static properties. Event-based segment conditions let you target profiles by event occurrence, frequency, recency, or specific event property values. For example, "customers who completed a purchase with an amount greater than $100 in the last 14 days."

• Triggering automations: When you want rules or workflows to fire in response to specific customer actions. Events serve as trigger conditions for automation rules. For example, you could create a rule that sends a follow-up WhatsApp message 24 hours after a customer submits a contact form.

• Tracking campaign engagement: When you need to measure campaign effectiveness by examining which events were generated as a result. The chain of message_sent, message_delivered, message_read, and link_clicked events provides a complete delivery and engagement funnel for each campaign.

• Debugging delivery issues: When you need to trace the exact sequence of events for a specific customer to diagnose why a message was not delivered or a workflow did not trigger as expected. The event timeline on a profile provides the definitive record of what happened and when.

• Defining custom events: When your business requires tracking actions beyond the built-in event types, such as "subscription_renewed," "cart_abandoned," or "support_ticket_opened." Custom events must be registered with a schema before they appear in the UI dropdowns.

Steps

1. Navigate to Events: Click "Customers" in the main sidebar, then select the "Events" tab to view the event log. The default view shows recent events across all profiles in reverse chronological order.

2. Browse the event list: Each row in the event list displays the event type, associated profile name, timestamp, and originating channel. Scroll through the list to get a high-level view of recent activity, or use filters to narrow down to specific events.

3. Filter by event type: Use the event type dropdown to filter for specific actions such as "page_view," "message_sent," "link_clicked," "form_submitted," or any custom event type you have defined. This is the fastest way to find events of a particular category.

4. Filter by date range: Set a start and end date to narrow the event list to a specific time period. This is especially useful for analyzing behavior around campaigns, product launches, or promotional events. You can combine date range filters with event type filters for maximum precision.

5. Filter by profile: Enter a profile name, email, or ID to see all events for a specific customer. This is equivalent to viewing the Timeline tab on a profile detail page, but accessible directly from the Events tab.

6. View event details: Click on any event row to expand the detail panel. This shows the full event payload including all properties, the session context (session ID, channel, duration), and the profile snapshot at the time of the event. The detail panel is essential for debugging because it reveals exactly what data was captured.

7. Use events in segments: When creating or editing a segment in the Segments tab, add a condition of type "Event" to target profiles based on event occurrence, frequency, recency, or specific event property values. The segment query builder provides autocomplete for event types and properties.

8. Use events in rule conditions: When creating an automation rule, select an event type as the trigger condition. The rule will fire whenever a matching event is recorded for any profile. You can add additional conditions to narrow when the rule triggers, such as requiring specific event property values.

Custom event registration

Before a custom event type can be used in segment conditions, rule triggers, or the event type filter dropdown, it must be registered with a schema. The schema defines the event type name, a description, and the expected properties with their data types.

Field	Required	Description
Event type name	Yes	A unique identifier using lowercase and underscores (e.g., cart_abandoned).
Display name	Yes	A human-readable label shown in the UI (e.g., "Cart Abandoned").
Description	No	A brief explanation of when this event is generated.
Properties	Yes	A list of expected properties, each with a name, data type (string, number, boolean, date), and whether it is required.

Unregistered events are still recorded in the event log if they arrive via the API, but they will not appear in dropdown menus and cannot be used as segment or rule conditions until registered.

Common pitfalls

• Not filtering before searching: The event log can contain millions of records. Always apply at least one filter (event type, date range, or profile) before browsing. Attempting to scroll through unfiltered events leads to slow load times and makes it nearly impossible to find what you need.

• Confusing event types with event properties: The event type (e.g., "link_clicked") categorizes the action at a high level. Event properties (e.g., "url," "campaign_id") provide the contextual details. When building segment conditions, use the event type to select the category, then add property conditions to refine the match. Using only the event type without property filters often results in overly broad matches.

• Missing custom event registration: Custom events must be registered with a defined schema before they appear in dropdowns and can be used in segment conditions or rule triggers. If you are sending custom events via the API but cannot find them in the UI, check whether the event type has been registered.

• Overlooking event timestamps: Events are recorded in UTC. When filtering by date range or analyzing behavior patterns, account for timezone differences between your team's location and your customers' locations. A customer action at 11 PM in their timezone might appear as the next day in UTC.

• Ignoring session context: Events that arrive without session context (orphaned events) may indicate integration issues with your tracking setup. If you notice events appearing without session IDs, review your tracking implementation to ensure sessions are being created and associated correctly.

tip

When debugging why a segment is not matching expected profiles, go to the Events tab and filter for the specific event type and profile. Verify that the events exist, have the correct properties, and fall within the time window your segment condition specifies. This step resolves the majority of "why isn't my segment working" questions.

• Event Tracking
• Event List
• Filter Events
• Event Details
• Custom Event Registration