You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> An open-source Python bot that automatically scrapes the internet for opportunities for Nigerian students — scholarships, fellowships, internships, bootcamps, and more. It updates a shared Google Spreadsheet and emails a **weekly digest**to subscribers every Sunday.
3
+
> An open-source Python bot that automatically finds scholarships, fellowships, and internships for Nigerian students. It updates a shared Google Spreadsheet, sends a weekly email digest, and delivers opportunities directly to WhatsApp campus groups and a Telegram channel.
ScoutBot emails a curated digest of the **latest** student opportunities every **Sunday at 10AM Lagos time**.
18
20
19
21
**[→ Fill the ScoutBot Subscription Form](https://docs.google.com/spreadsheets/d/1dFcnVvQjWkuYhN1rplICTY0j88KgvGqQ3FzYId2ru4s/edit?gid=1666713039#gid=1666713039)**
20
22
21
23
No app, no login, no fee. Fill the form once and you're on the list.
22
24
23
-
📋 [View the live opportunity spreadsheet →](https://docs.google.com/spreadsheets/d/1pLCEvDI1btjtOe1H3VgzCqpC6R0nRsEtnTwQhY6BqmU/edit)
24
-
25
25
---
26
26
27
-
##What ScoutBot Does
27
+
### 2 — WhatsApp Campus Delivery (filtered by level)
28
28
29
-
- 🔍 **Scrapes 8+ live feeds daily** — Google News RSS (Nigeria + International), YouthHubAfrica
30
-
- 🔗 **Direct application links only** — every link is extracted from the article's "Apply Now" button; items with no findable apply link are dropped before entering the sheet
31
-
- 📊 **Writes to two separate tabs**: Nigeria 🇳🇬 and International 🌍 — never mixed
32
-
- 🤖 **AI quality scoring** — every new item scored 1–10 by Gemini 2.0 Flash; items scoring below 5 are dropped
33
-
- 🧹 **Auto-cleans daily** — entries removed when closed, past deadline, or older than 23 days
34
-
- 📧 **One email per week** — Sunday digest with only opportunities added in the last 7 days
(drop known) (score 1–10) (write to Nigeria/International tab)
47
-
(drop < 5)
48
-
(add AI blurb)
49
-
```
52
+
> 📌 **Telegram link update in progress** — reach out to [@tsouk88](https://github.com/tsouk88) (the Telegram integration author) or open an issue for the current invite link.
53
+
54
+
---
50
55
51
-
**The AI does two things:**
52
-
1.**Scores** each opportunity 1–10 for relevance to Nigerian students — items below 5 are dropped silently
53
-
2.**Generates a 2-sentence blurb** that appears in the weekly email so subscribers instantly know if an opportunity is for them
56
+
📋 [View the live opportunity spreadsheet →](https://docs.google.com/spreadsheets/d/1pLCEvDI1btjtOe1H3VgzCqpC6R0nRsEtnTwQhY6BqmU/edit)
54
57
55
-
**Why Gemini and not GPT-4 or Claude?**
56
-
Gemini 2.0 Flash is available on a free API tier with 1,500 requests/day — enough for ScoutBot's daily volume (typically 5–15 new items) with zero cost.
- 🔍 **Scrapes 21+ direct org pages daily** — checks PTDF, NDDC, NNPC, MTN Foundation, Tony Elumelu Foundation, Commonwealth Scholarships, Chevening, Fulbright, World Bank, AfDB, AU, UNDP, UNICEF, British Council, and more
63
+
- 🔗 **Direct org application links only** — every link goes to the actual organisation's apply page, never a news aggregator or redirect URL
64
+
- 📊 **Two separate tabs**: Nigeria 🇳🇬 and International 🌍 — never mixed
65
+
- 📱 **WhatsApp campus delivery** — campus leads register their group; opportunities arrive filtered by academic level
66
+
- 📣 **Telegram channel** — real-time posts as new opportunities are discovered
67
+
- 🧹 **Auto-cleans daily** — entries removed when closed, past deadline, or older than 23 days
68
+
- 📧 **One email per week** — Sunday digest with only opportunities added in the last 7 days, sent to 500+ subscribers
- ☁️ **Runs entirely on GitHub Actions** — no server, no Replit dependency, works 24/7 independently
59
71
60
72
---
61
73
62
-
## Opportunity Lifecycle
74
+
## Accomplishments We're Proud Of
63
75
64
-
```
65
-
Day 0: Opportunity posted on the web
66
-
Day 0–3: Spider picks it up (MAX_POST_AGE_DAYS = 3)
67
-
→ follows article to find direct "Apply Now" link
68
-
→ Gemini scores it 1–10
69
-
→ if score ≥ 5: written to Google Sheet
70
-
Day 7: Included in Sunday weekly email digest
71
-
Day 23: Hard-removed from sheet by cleanup.py (STALE_DAYS = 23)
72
-
```
76
+
-**500+ email subscribers** acquired organically through student WhatsApp groups and word-of-mouth — zero paid promotion
77
+
-**WhatsApp campus delivery system** — built from scratch by [@olamidefasogbon](https://github.com/olamidefasogbon): a full distribution bridge that joins WhatsApp groups, filters opportunities by level, and broadcasts automatically
78
+
-**Subscriber web portal** with real-time registration, QR code generation, and live ScoutBot status indicator
79
+
-**Telegram integration** — built by [@tsouk88](https://github.com/tsouk88), extending delivery to a third channel with zero extra infrastructure
80
+
-**Zero cost infrastructure** — entire stack runs free: GitHub Actions, Gmail SMTP, Google Sheets API
81
+
-**All links are direct org URLs** — no news.google.com, no redirects; every row in the sheet links to the actual application page
73
82
74
83
---
75
84
76
85
## How It Works
77
86
78
87
```
79
88
Every day at 07:00 WAT (GitHub Actions — scoutbot.yml):
→ scores each with Gemini → writes to Nigeria / International tab
82
-
2. python run.py --cleanup → removes entries older than 23 days or with past deadlines
89
+
1. scrapy crawl opportunities → checks 21+ org pages for open opportunities
90
+
→ extracts direct apply URLs
91
+
→ deduplicates against existing sheet entries
92
+
→ writes to Nigeria / International tab
93
+
94
+
2. python run.py --cleanup → removes entries older than 23 days or past deadline
83
95
84
96
Every Sunday 10:00 WAT (GitHub Actions — digest.yml):
85
-
3. python run.py --notify → sends weekly digest (last 7 days only) to all subscribers
97
+
3. python run.py --notify → sends weekly email digest (last 7 days) to all subscribers
98
+
99
+
After each scrape (broadcast_daemon.py):
100
+
4. WhatsApp distribution bridge → sends new items to registered campus groups (filtered by level)
101
+
5. Telegram notification → posts new items to Telegram channel
86
102
87
103
1st of every month 07:30 WAT (GitHub Actions — admin-report.yml):
88
-
4. python admin_report.py → sends monthly stats report to project lead
104
+
6. python admin_report.py → monthly stats report to project lead
89
105
```
90
106
91
107
---
92
108
93
109
## Why ScoutBot Exists
94
110
95
-
Opportunities for Nigerian students are scattered across dozens of websites with no single reliable source. ScoutBot runs quietly in the background, finds new opportunities as they appear, extracts direct application links, scores them with AI, and delivers them straight to people's inboxes — once a week, clean and fresh.
96
-
97
-
**This is a bot, not a web app.** No dashboard, no login page, no frontend — just an automated Python system that works independently of any platform.
111
+
Opportunities for Nigerian students are scattered across dozens of websites with no single reliable source. Most are announced on corporate press offices, government portals, or international org pages that students rarely check. ScoutBot checks all of them automatically, every day, and pushes the results to wherever students already are — their WhatsApp group, their Telegram feed, or their inbox once a week.
98
112
99
113
---
100
114
@@ -104,10 +118,17 @@ Opportunities for Nigerian students are scattered across dozens of websites with
104
118
ScoutBot/
105
119
├── scoutbot/
106
120
│ ├── spiders/
107
-
│ │ └── opportunities_spider.py ← All scraping + RSS + apply link extraction
├── admin_report.py ← Monthly stats email to project lead
@@ -116,7 +137,6 @@ ScoutBot/
116
137
├── requirements.txt
117
138
├── .env.example ← Copy to .env and fill in credentials
118
139
├── docs/
119
-
│ ├── AI_IMPLEMENTATION.md ← Full Gemini AI pipeline documentation
120
140
│ └── VOLUNTEER_ROLES.md ← Step-by-step guide for all volunteer roles
121
141
├── .github/
122
142
│ └── workflows/
@@ -125,34 +145,52 @@ ScoutBot/
125
145
│ ├── admin-report.yml ← Monthly 07:30 WAT stats report
126
146
│ ├── welcome.yml ← Monthly welcome email to new subscribers
127
147
│ └── pytest.yml ← CI tests on every push/PR
128
-
├── CHANGELOG.md ← Full project history
148
+
├── CHANGELOG.md
129
149
├── CONTRIBUTING.md
130
-
├── CODE_REFERENCE.md
131
150
└── ENGINEERING.md
132
151
```
133
152
134
153
---
135
154
155
+
## Opportunity Sources
156
+
157
+
ScoutBot checks **21 organisation pages directly** every day — no news aggregators, no redirects:
158
+
159
+
| Nigeria | International |
160
+
|---------|---------------|
161
+
| PTDF (ptdf.gov.ng) | Commonwealth Scholarship |
162
+
| NDDC (nddc.gov.ng) | Chevening Scholarship |
163
+
| NNPC Group | Fulbright Program |
164
+
| Shell/SNEPCo | Mastercard Foundation |
165
+
| MTN Foundation | World Bank |
166
+
| Tony Elumelu Foundation | African Development Bank |
167
+
| Dangote Foundation | African Union |
168
+
| Access Bank | UNDP Nigeria |
169
+
| YouthHub Africa | UNICEF |
170
+
| NDIC (SIWES) | UN Fellowship, British Council NG |
171
+
172
+
Plus **scholars4dev.com** RSS as a supplementary feed when it has qualifying items.
173
+
174
+
---
175
+
136
176
## 🤝 Volunteer — Help Us Grow ScoutBot
137
177
138
-
ScoutBot is maintained by a small founding team and open-source contributors. Several roles are open to volunteers — no application required to get started.
178
+
ScoutBot is maintained by a small founding team and open-source contributors. Several roles are open to volunteers — no application required.
139
179
140
180
**[→ Full volunteer guide: docs/VOLUNTEER_ROLES.md](./docs/VOLUNTEER_ROLES.md)**
141
181
142
-
| Role | Time/week | Skills needed | How to start |
- 🤝 **Volunteer** — see the [volunteer guide](./docs/VOLUNTEER_ROLES.md) for non-coding roles
273
+
- 🤝 **Volunteer** — see the [volunteer guide](./docs/VOLUNTEER_ROLES.md)
242
274
243
275
**Ready to code?** Start with issues labelled [`good first issue`](https://github.com/TechHub-Extensions/ScoutBot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
244
276
@@ -257,7 +289,7 @@ Every merged contribution is permanently credited in [CONTRIBUTORS.md](./CONTRIB
0 commit comments