Introduction
Apache Kafka is an open-source, distributed event streaming platform used for high-performance data pipelines, streaming analytics, and mission-critical applications.MoEngage and Kafka
This integration enables you to stream events from Kafka topics directly to MoEngage via Connected Sources. This allows raw event data to flow from Kafka to MoEngage in near real time. With this integration, you can:- Stream real-time events: Send events from Kafka topics to MoEngage with sub-second latency for immediate campaign triggering and user profile updates.
- Scale across environments: Deploy across multiple environments, including Systemd, Docker, Docker Compose, and Kubernetes, for production-grade reliability.
Use cases
Integrating Kafka with MoEngage supports the following use cases:- Real-time purchase triggers: When a customer completes a purchase captured in Kafka, instantly stream the order event to MoEngage to trigger personalized thank-you emails, product review requests, and cross-sell campaigns based on items purchased and order value.
- Abandoned cart recovery: Stream cart abandonment events from your e-commerce platform through Kafka to MoEngage to automatically trigger reminder emails with personalized recommendations and time-sensitive discount codes.
- User activity tracking: Capture high-volume user interactions like page views, feature usage, and content engagement in Kafka topics. Stream them to MoEngage to build behavior profiles and trigger contextual in-app messages or push notifications.
Integration
The integration follows an architecture in which your Kafka events are sent directly to MoEngage in JSON format.
Prerequisites
- An active Kafka cluster with bootstrap servers accessible from your deployment environment.
- Python 3.7 or higher is installed in your deployment environment.
- Kafka events are formatted according to the standard JSON schema.
- An understanding of your Kafka message structure and authentication requirements.
Step 1: Get the MoEngage endpoint
Contact the MoEngage Support team to obtain a dedicated Kafka integration endpoint. Note the values for the following fields for the next steps:| Field | Description | Sample value |
|---|---|---|
MOENGAGE_PARTNER_NAME | Enter your MoEngage partner identifier. | — |
MOENGAGE_DATA_CENTER | Enter your MoEngage Data Center number (for example, 01, 02, or 03). For more information, see Data Centers in MoEngage. | 02 |
MOENGAGE_CONFIG_NAME | Enter the unique MOENGAGE_CONFIG_NAME provided by the MoEngage team. | 15fc62d8-efbd-42c7-aad5-... |
MOENGAGE_APP_ID | Your MoEngage workspace ID. To find your credentials:
| 7IYSTOK1CLO9A1XDO... |
MOENGAGE_API_SECRET | The MoEngage Data API secret key. To find your credentials:
| pIfghD6guNHTvwgZz... |
Step 2: Set up the Kafka connector
The following sections provide a sample script to push data from your Kafka topic to your dedicated MoEngage endpoint. You can modify the script based on your data structure and attribute mapping.Step 2.1: Standard event format
MoEngage provides a standard JSON format for Kafka events. Ensure your Kafka messages follow this structure:Sample Event
| Field | Type | Required | Description |
|---|---|---|---|
customer_id | String | Yes | The unique identifier for the user (used as the primary key in MoEngage). |
email | String | No | The user’s email address. |
phone | String | No | The user’s phone number, including the country code (for example, +1234567890). |
first_name | String | No | The user’s first name. |
last_name | String | No | The user’s last name. |
updated_at | String | Yes | The timestamp in epoch milliseconds (for example, "1759752209000"). |
user_attributes | Object | No | Additional user profile attributes (for example, city, subscription_tier, and custom fields). |
event_attributes | Object | Yes | Event-specific data. The event_name field is mandatory. |
event_attributes.event_name | String | Yes | The name of the event (for example, Purchase Completed, Page Viewed). |
Flexible schemaYou can add custom fields to the
user_attributes and event_attributes objects. MoEngage automatically captures and stores these fields. Only customer_id, updated_at, and event_attributes.event_name are mandatory.Step 2.2: Basic setup
Python dependencies Install the required Python packages for Kafka consumption and HTTPS communication:Shell
| Package | Version | Purpose |
|---|---|---|
confluent-kafka | 2.3.0+ | The Kafka consumer client. |
requests | 2.31.0+ | The HTTP client for the MoEngage API. |
python-dotenv | 1.0.0+ | An environment variable management. |
.env file to securely store your configuration.
Do not commit this file to version control.
Environment Configuration
| Variable | Required | Description |
|---|---|---|
KAFKA_BOOTSTRAP_SERVERS | Yes | A comma-separated list of Kafka broker addresses. |
KAFKA_TOPICS | Yes | A comma-separated list of topics to consume. |
KAFKA_GROUP_ID | Yes | The consumer group ID for offset management. |
KAFKA_SECURITY_PROTOCOL | No | PLAINTEXT, SASL_SSL, or SSL (default: PLAINTEXT). |
LOG_LEVEL | No | INFO, DEBUG, WARNING, or ERROR (default: INFO). |
Step 2.3: Create the consumer script
Create a file namedkafka_consumer.py. This script consumes messages from Kafka and posts them to the MoEngage API.
kafka_consumer.py
Step 3: Test script
Before you deploy to production, verify that the integration works correctly.Testing prerequisitesEnsure your Kafka topics contain test events in the standard JSON format before you run the consumer script.
3.1. Run the consumer script locally
Shell
Sample Logs
3.2. Verify data in the MoEngage UI
- In the MoEngage UI, navigate to Settings > Data Management > Events.
- Search for your event names (from
event_attributes.event_name). - Check the Users section to confirm profiles are created/updated.
- Navigate to Segment > Search Users.
- Search for the customer using Customer ID, Email address, or Phone number.
- Verify that events appear with correct attributes and timestamps in the User Profile.
Data processing delayEvents may take 1 to 2 minutes to appear in the MoEngage dashboard due to processing queues. If events don’t appear after 10 minutes, check the console logs for API errors and verify your credentials.
Step 4: Deploy to production
Choose a deployment method based on your infrastructure. MoEngage supports the following deployment options.- Systemd Service
- Docker
- Docker Compose
- Kubernetes
Systemd Service (Linux)
To run the consumer as a persistent background process on a Linux server, follow the steps below to configure:1. Create service fileCreate the service file using nano:Rate Limits
To maintain platform stability, MoEngage limits ingestion of Kafka data to a maximum of 500 requests per second (RPS) per workspace. If your workspace exceeds this limit, MoEngage returns an HTTP429 (Too Many Requests) status code.
Handle 429 responses in your consumer script by backing off and retrying, so events are not dropped when the limit is reached. The sample script already retries on server errors; extend the same logic to cover rate-limit responses.
Troubleshooting
Common issues and solutions
| Issue | Possible cause | Solution |
|---|---|---|
| 401 Unauthorized Error | The MoEngage credentials are incorrect. | Verify MOENGAGE_APP_ID and MOENGAGE_API_SECRET. Check for extra spaces in the .env file. |
| 400 Bad Request Error | The data does not match standard JSON format. | Verify Kafka events match the required schema. Ensure customer_id, updated_at, and event_attributes.event_name are present. |
| Consumer not connecting to Kafka | These are incorrect bootstrap servers or authentication. | Verify KAFKA_BOOTSTRAP_SERVERS and test connectivity with telnet broker1 9092. Check SASL credentials if using authentication. |
| Events not appearing in MoEngage | These are missing required fields or wrong configName. | Check console logs for API response. Ensure all required fields are present. Verify MOENGAGE_CONFIG_NAME matches the credentials provided by MoEngage. |
| Consumer lag increasing | These processes are slower than the ingestion rate. | Scale horizontally by adding more consumer instances. Each instance will process different partitions. |
| JSON Decode Error | This is non-JSON data in the Kafka topic. | Verify Kafka topic contains valid JSON messages. Check for binary data or malformed JSON. |
| Module Not Found Error | This is a Python dependency that is not installed. | Run pip install -r requirements.txt. Verify Python version is 3.7+. |