User Guide
Everything you need to set up, configure, and run your campaign on UchaguziOS v6.0. Follow the step-by-step guides below with real screenshots from the platform.
Up and running in 5 steps
From sign-in to your first campaign message — under 15 minutes.
Sign In
Access your campaign dashboard at your unique campaign URL
Import Voters
Upload your supporter database via CSV with column mapping
Add Your Team
Create user accounts and assign roles for each team member
Launch Comms
Create SMS/WhatsApp campaigns targeting voter segments
Monitor & Win
Track real-time KPIs, AI predictions, and election day results
Five roles, one unified platform
Every user sees exactly what they need — nothing more, nothing less.
Administrator
Full platform access. Manages tenants, billing, user provisioning, system configuration, and security policies. The only role with access to the Audit & Observability module.
Campaign Manager
Day-to-day campaign operations. Coordinates volunteers, manages communications, reviews analytics, oversees donor engagement, and monitors field activities.
Field Officer
Manages field operations including route planning, GPS tracking of volunteers, incident reporting, and on-ground coordination during campaign activities.
Volunteer
Completes assigned tasks, performs check-ins at designated locations, submits survey responses, and participates in door-to-door mobilization.
Polling Agent
Election-day specialist. Monitors assigned polling stations, tracks voter turnout in real-time, reports incidents, and enters provisional results.
Chapters
Getting Started
The Executive Dashboard is your command centre — a role-based intelligence hub that surfaces the most critical KPIs for your campaign. Upon login, Administrators see a high-level overview including supporter growth trends, volunteer activation rates, donation progress against targets, and real-time communication delivery metrics. The dashboard auto-adapts based on your assigned role, ensuring every team member sees the data most relevant to their responsibilities.
Executive Dashboard — Role-based KPIs, supporter trends, and campaign health metrics at a glance
Step-by-Step Instructions
Sign In & Role Selection
Navigate to your campaign URL and sign in with your administrator credentials. Use the role selector dropdown in the sidebar to switch between Administrator, Campaign Manager, and other roles. The interface dynamically reconfigures to show only the modules and data accessible to the selected role.
Pro Tip: Assign the minimum role necessary for each user. Use role switching for testing rather than granting elevated permissions.
Campaign Configuration
Set up your campaign profile including name, candidate details, election dates, budget parameters, and geographic coverage level (county, constituency, ward, or national). Configure constituency mapping to link your campaign to specific IEBC constituency codes for polling station alignment.
Team Onboarding
Add team members through the User Management module. Assign roles (Administrator, Campaign Manager, Field Officer, Volunteer, or Polling Agent), link them to campaign tenants, and optionally assign geographic constituencies. Invitation emails with credentials are dispatched automatically.
Key Features
Supporter Management
The Supporters module is the backbone of your voter outreach strategy. It provides a centralized database for managing all voter contacts with advanced segmentation, import/export capabilities, and detailed contact profiles. Supporter data drives every other module — from communication targeting to GIS mapping to AI predictions — making data quality and completeness critical.
Supporters Module — Centralized voter database with advanced filtering, segmentation, and CSV import
Step-by-Step Instructions
Importing Supporters via CSV
Navigate to the Supporters module and click "Import". Upload a CSV file with columns for name, phone number, constituency, ward, and voter registration number. The system validates data integrity, flags duplicates, and provides a preview before committing. Supports up to 50,000 records per batch.
Pro Tip: Always validate CSV files against the expected schema before upload. Larger datasets should be split into multiple batches of 50,000 records.
Manual & Phone Entry
For individual registrations during field engagements, use the phone entry form or SMS shortcode capture. Field officers can add supporters directly from their mobile devices during door-to-door canvassing.
Segmentation & Filtering
Create dynamic segments based on constituency, ward, registration status, engagement level, or custom tags. Segments power targeted communication campaigns and are used by the AI engine for voter profiling and turnout prediction.
Key Features
Communications Hub
The Communications Hub unifies SMS, WhatsApp, USSD, and email outreach into a single management interface. Campaign managers can compose messages using multi-language templates (English, Swahili, Kalenjin), schedule delivery for optimal engagement windows, and track per-recipient delivery status in real-time. Automated campaigns can be triggered by workflow rules, enabling hands-off voter engagement at scale.
Communications Hub — Multi-channel message campaigns with delivery tracking and template management
Step-by-Step Instructions
Creating a Message Campaign
Open the Comms Hub and click "New Campaign". Select your channel (SMS, WhatsApp, Email, or multi-channel), choose a template or compose a custom message, then select your target audience segment. Schedule immediate delivery or set a future date/time.
Pro Tip: Schedule SMS campaigns for 10:00–12:00 and 17:00–19:00 for optimal open rates based on Kenyan mobile usage patterns.
Template Management
Create reusable message templates with variable placeholders (e.g., {{name}}, {{ward}}). Templates support multiple languages and are version-controlled. The system includes pre-built templates for common campaign scenarios: rally invitations, donation appeals, and election day reminders.
Delivery Tracking & Analytics
Monitor delivery status in real-time: sent, delivered, read, and failed. View per-campaign analytics including open rates, response rates, and opt-out counts. Failed deliveries are automatically queued for retry based on configurable rules.
Key Features
Volunteer Management
The Volunteers module manages the complete volunteer lifecycle from recruitment through activation to performance tracking. Campaign managers can vet new registrations, assign volunteers to geographic areas, link them to Field Officers for supervision, and track task completion rates. The module integrates with the Operations and Routes modules to coordinate field activities seamlessly.
Volunteers Module — Recruitment queue, geographic assignments, and task completion tracking
Step-by-Step Instructions
Volunteer Recruitment & Vetting
New volunteer registrations enter a review queue visible to Campaign Managers. Review each application, verify contact details, and approve or reject. Approved volunteers are automatically assigned onboarding materials via email/SMS and receive login credentials.
Geographic Assignment
Assign approved volunteers to specific constituencies and wards based on coverage needs. Each volunteer is linked to a Field Officer for supervision. The assignment view shows coverage gaps using colour-coded ward maps.
Task Assignment & Tracking
Create tasks and assign them to individual volunteers or volunteer groups. Tasks can include door-to-door canvassing, rally preparation, survey distribution, or election day duties. Track completion rates, check-in frequency, and performance metrics per volunteer.
Key Features
Election Day Operations
The Election Day module is your real-time command centre on voting day. It provides live vote tallying from polling stations across your coverage area, with automated Form 34A/34B reconciliation that catches discrepancies instantly. Agents check in via mobile, results are entered and verified, and the system projects outcomes with confidence intervals — giving your campaign a critical head start on results verification.
Election Day Module — Live vote tallying, agent deployment status, and Form 34A/34B reconciliation
Step-by-Step Instructions
Agent Deployment & Check-In
Before voting begins, verify that all polling agents have checked in via the mobile app. The deployment view shows coverage status across all assigned stations — green for checked-in, amber for pending, and red for no response. Contact unresponsive agents immediately through the integrated communication tools.
Pro Tip: Deploy backup agents for high-priority stations. The system can auto-assign the nearest available agent if a primary agent fails to check in by the deadline.
Live Vote Tallying
As voting concludes at each station, agents enter provisional results through the mobile app. Results appear in real-time on the tally dashboard with automatic aggregation at ward, constituency, and county levels. The system cross-references against registered voter counts to flag anomalies.
Form 34A/34B Reconciliation
The automated reconciliation engine compares agent-submitted results against official IEBC Form 34A and 34B data. Discrepancies are flagged with severity levels and supporting evidence. Critical mismatches trigger immediate alerts to administrators and legal teams for rapid response.
Key Features
Polling Station Management
The Polling module maintains a comprehensive registry of all polling stations within your campaign coverage area, aligned with official IEBC data. Each station record includes the station name, IEBC code, constituency, ward, registered voter count, and geographic coordinates. This data powers the GIS mapping, election day operations, and route planning modules.
Polling Module — Station registry, agent assignments, and real-time turnout tracking
Step-by-Step Instructions
Station Registry Setup
Import or manually configure your polling station registry. Each station requires: station name, IEBC official code, constituency, ward, registered voter count, and GPS coordinates. The system validates against IEBC data formats and flags any mismatches.
Agent-to-Station Assignment
Assign polling agents to specific stations with defined time-slot coverage requirements. The assignment view optimizes for geographic proximity and workload balance. Agents can be assigned to multiple stations if coverage gaps exist.
Turnout Tracking
On election day, track real-time voter turnout by station. The turnout view displays hourly progression charts, comparison against historical data, and projected final turnout. Low-turnout stations trigger automated alert rules for targeted mobilisation efforts.
Key Features
Donations & Fundraising
The Donations module provides end-to-end fundraising management with native M-Pesa STK Push and Paybill integration. Track every contribution from pledge to receipt, manage donor relationships with a built-in CRM, and generate IEBC-compliant financial reports. The module supports multiple payment channels including M-Pesa, bank transfers, and cash recording.
Donations Module — M-Pesa integration, donor CRM, pledge tracking, and financial reporting
Step-by-Step Instructions
Setting Up M-Pesa Integration
Configure your Safaricom M-Pesa Paybill or Till Number in the Finance settings. The system supports both STK Push (for initiated payments) and Paybill (for donor-initiated payments). Test the integration with a small transaction before going live.
Pro Tip: Enable automatic receipt generation for all M-Pesa transactions. Donors receive instant SMS confirmation, improving trust and repeat donation rates.
Donor Relationship Management
Maintain detailed donor profiles including contact information, donation history, pledge commitments, and communication preferences. Segment donors by contribution level for targeted engagement. Track pledge fulfilment rates and send automated reminders as due dates approach.
Financial Reporting
Generate comprehensive financial reports categorized by IEBC spending limits. Reports include income statements, expenditure breakdowns by category, donor analysis, and compliance summaries. All data is exportable for regulatory submission.
Key Features
GIS Mapping
The GIS Map module provides interactive geographic visualization of your entire campaign footprint. View supporter distribution, polling station locations, volunteer coverage, and incident reports on a unified map built on OpenStreetMap. The module supports Kenya's complete administrative hierarchy: 47 counties, 290 constituencies, and 1,450+ wards with demographic data layers.
GIS Map Module — Interactive geographic visualization with supporter heat maps and polling station coverage
Step-by-Step Instructions
Map Navigation & Layers
Open the GIS Map module and use the layer selector to toggle data overlays: supporters (density heat map), polling stations (markers with turnout data), volunteer locations (GPS dots), and incident reports (severity-coloured pins). Zoom to county, constituency, or ward level using the administrative boundary selector.
Supporter Heat Mapping
Enable the supporter density layer to visualize where your voter base is concentrated. The heat map uses a gradient from transparent (low density) through yellow to deep red (highest density). Use this data to identify under-penetrated areas that need additional outreach.
Polling Station Coverage Analysis
Overlay polling station locations with agent assignment status. The coverage view highlights stations without assigned agents (red), partially covered (amber), and fully staffed (green). This view is critical for election day readiness planning.
Key Features
Security & Access Control
The Security module provides enterprise-grade protection for your campaign data. Role-based access control (RBAC) enforces granular permissions across all 38+ modules, two-factor authentication (TOTP) adds a critical second layer of login security, and comprehensive audit logging creates an immutable record of every platform action. These tools ensure compliance with the Kenya Data Protection Act 2019.
Security Module — RBAC enforcement, 2FA configuration, and comprehensive audit trail
Step-by-Step Instructions
Role-Based Access Control
Every user is assigned one or more of the five platform roles. Each role maps to a predefined permission set controlling module access, data visibility, and action permissions. The permission matrix ensures users see only the tools and data relevant to their responsibilities.
Pro Tip: Enable 2FA enforcement for all Administrator accounts. Review the Login Analytics dashboard daily during peak campaign periods. Suspend inactive accounts after 30 days of no login activity.
Two-Factor Authentication
Enable TOTP-based 2FA for specific roles or all users. Compatible with standard authenticator apps (Google Authenticator, Authy). Administrators can enforce 2FA at the role level — recommended for all Administrator and Campaign Manager accounts.
Audit Trail Review
Every user action is automatically logged with timestamp, user identity, action type (CREATE, READ, UPDATE, DELETE), affected resource, and IP address. Filter logs by user, action type, time range, or resource. Before/after state changes are captured for update operations.
Key Features
Audit & Observability
The Audit & Observability module is the administrator's mission control for platform health. It provides seven distinct monitoring sub-sections covering system audit, failed jobs, queue monitoring, API health, login analytics, security alerts, and tenant usage. This module is exclusively available to Administrator-role users and is critical during high-traffic periods like election day.
Audit & Observability — Seven monitoring sub-sections for complete platform health visibility
Step-by-Step Instructions
System Audit Review
Access the chronological log of all platform activity. Filter by action type, user, time range, or resource. Visual breakdowns show the distribution of successful versus failed actions. Trend analysis charts display activity patterns over configurable time windows, helping identify operational anomalies.
Failed Jobs & Queue Monitoring
Monitor asynchronous operations that did not complete successfully: overdue tasks, undelivered messages, and stalled imports. Each failed job shows the error message, retry count, and a manual retry button. The queue dashboard displays current depth, processing rate, and priority distribution of pending tasks.
Pro Tip: During election day, monitor the queue dashboard continuously. Message delivery spikes can cause backlog — set up alert rules for queue depth thresholds.
Security Alerts & Incident Response
Review aggregated security events in the unified incident feed. Each alert includes severity classification (Low, Medium, High, Critical), an automated risk score, and recommended remediation actions. Critical alerts trigger immediate push notifications to all administrators on duty.
Key Features
AI Intelligence Engine
The AI Intelligence module leverages machine-learning models to deliver predictive insights that give your campaign a strategic advantage. It analyses supporter data, communication engagement patterns, and historical election data to predict voter turnout, identify swing voters, segment demographics with high precision, and generate win-probability forecasts at ward and constituency levels.
AI Intelligence Module — Turnout prediction, swing voter identification, and win-probability forecasting
Step-by-Step Instructions
Turnout Prediction
The AI engine generates turnout probability scores for each ward and constituency based on historical data, current engagement metrics, and demographic factors. Predictions are updated daily and displayed on interactive charts. High-risk low-turnout areas are automatically flagged for targeted intervention.
Swing Voter Identification
Using behavioural signals (communication engagement, event attendance, survey responses), the AI identifies voters who are most likely to be persuaded. These swing voter segments can be directly exported to the Communications Hub for targeted outreach campaigns.
Win-Probability Forecasting
The forecasting dashboard displays win-probability estimates at ward, constituency, and county levels. Scenario simulation allows campaign managers to model "what-if" outcomes based on different turnout assumptions, voter persuasion rates, and opponent performance projections.
Key Features
Workflows & Route Planning
The Workflows and Routes modules work together to automate campaign operations and optimise field coordination. Workflow automation reduces manual overhead by triggering actions based on system events, while route planning ensures volunteers and field officers follow the most efficient paths for canvassing and distribution activities.
Workflows Module — Drag-and-drop automation rules with execution logging and monitoring
Step-by-Step Instructions
Creating Workflow Automation Rules
Navigate to the Workflows module and click "New Rule". Define a trigger event (e.g., "New supporter imported"), set conditions (e.g., "Ward equals Westlands"), and specify actions (e.g., "Auto-assign to nearest volunteer", "Send welcome SMS"). Rules execute in real-time and are logged for audit purposes.
Route Planning for Field Operations
Open the Routes module and create a new route. Add stops (supporter addresses, polling stations, distribution points) and the system calculates the optimal route based on distance, travel time, and priority. Routes can be assigned to individual volunteers or field teams.
Pro Tip: Generate routes the evening before field activities and distribute via SMS to assigned volunteers. Include estimated travel times and stop priorities.
Monitoring & Execution Logs
Track workflow execution history and route completion status in real-time. The workflows dashboard shows trigger counts, success/failure rates, and execution latency. Route tracking displays volunteer GPS positions against planned paths.
Key Features