Skip to main content

Introduction

iEMA Bot is an open-source platform for running Experience Sampling Method (ESM) and Ecological Momentary Assessment (EMA) research studies. It provides a complete infrastructure for delivering surveys to participants, collecting responses, integrating with wearable devices, and administering cognitive assessments — all configurable through YAML files and a REST API.

Key Features​

  • Multi-frontend delivery — Reach participants via a Telegram bot or a Progressive Web App (PWA), using the same survey definitions and logic for both.
  • YAML-defined surveys — Define surveys declaratively with support for branching (show_if), randomization, composite surveys (combining multiple survey modules), and multiple question types (Likert, choice, text, photo, voice, time, and more).
  • Flexible scheduling — Deliver surveys on cron-based schedules via APScheduler, trigger them on-demand through the REST API, or fire them automatically in response to wearable device events using the rules engine.
  • Cognitive assessments — Administer validated cognitive tasks (e.g., reaction time, memory) powered by m2c2kit, with results collected automatically.
  • Wearable integration — Connect participant wearable devices from Fitbit, Oura, and Withings. Receive webhook data, run daily syncs, and trigger event-driven surveys based on incoming health data.
  • REST API — Automate study management with a full API for triggering surveys, managing participants, exporting responses (JSON and CSV), and configuring schedules.
  • Web push notifications — Send push notifications to PWA participants when surveys are available.

Who Is This For?​

  • Researchers running EMA/ESM studies who need a self-hosted, customizable platform for survey delivery and data collection — particularly those who want to leverage prioritized push notifications through messaging apps (Telegram), context-aware survey triggers from wearable and nearable devices, or a conversational chat-based UI for higher participant engagement.
  • Developers looking to extend the platform with new question types, wearable integrations, or frontend interfaces.

Architecture​

The platform runs three services in a single process: a Telegram bot (long-polling), an APScheduler instance for timed survey delivery, and a FastAPI HTTP server for the REST API and PWA backend.

Next Steps​

  1. Installation — Clone the repo and install dependencies.
  2. Configuration — Configure environment variables for your study.
  3. Set up your frontend:
    • Telegram Setup — Run the Telegram bot and enroll your first participant.
    • Web App Setup — Build the PWA and register your first participant.

You can run both frontends simultaneously — they share the same survey definitions, database, and scheduling engine.