Telegram Break-Point Alerts (Self-Hosted)

Disclosure: Links to Live Tennis API are affiliate links. We may earn a commission if you subscribe, at no extra cost to you. Use our link or checkout code botblog for 10% off Ultra. Live Tennis API also gave BotBlog Ultra access for testing. The how-to steps are independent. Full disclosure.

Before we start — please read this

I’m Stephane. I run BotBlog and I’m a keen tennis player. I wrote this for people who have never built an app. If a word looks scary, we explain it the first time it appears.

The GitHub repo is code only. No Live Tennis API key and no Telegram token ships with the repository. You buy your own Ultra key and create your own bot, then paste both into a local .env file that is git-ignored.

This guide is for you if:

• You trade (or watch) Betfair tennis in-play and want 0–40 / 15–40 on your phone the moment it is scored
• You can install free software, create a folder, and copy commands exactly
• You are happy to leave a terminal window open on a PC while matches are on

This guide is not:

• Betting tips, a tipster service, or financial advice
• A Betfair bot — it does not place bets and does not talk to Betfair’s API
• A replacement for the free hosted board at the desk

Pair this with the free Tennis Trader Board on a second screen. The hosted board is for when you are at the desk. This Telegram worker is for when you are away from the desk, or you want a phone ping.

Hosted board vs this DIY Telegram bot

Open-source companions: the board sample is live-tennis-scoreboard. This guide clones tennis-trader-alerts.

Hosted Live Tennis API Alerts vs this DIY bot

Live Tennis API also sells a hosted product called Break-point Alerts. That is a different job from this GitHub worker. Their page is the tap-to-connect product (no Ultra key). This guide is the self-hosted path: your Ultra key, your PC, your 0–40 / 15–40 toggles.

Use hosted Alerts if you want a tap-to-connect ping and you do not want a terminal. Use this guide if you want 0–40 / 15–40 as score states, a watchlist you control, and keys that never leave your machine. The Ultra CTA below is for the DIY worker, not for their hosted Alerts plan.

Why this is not a Flashscore or TennisTimeBot

Flashscore notifications and Telegram fan bots (TennisTimeBot, TennisAlertsBot, SiriusTennisBot, OnCourt) tell spectators the score. They are not built around Betfair tennis trading: who is serving, 0–40 / 15–40, rising-edge so a 15–40 that sits is one message, and an Ultra push when the point commits. This worker is also not a tipster channel — it does not send picks.

Tiny glossary (keep this handy)

What you need

Computer

• A Windows 10/11 PC, a Mac, or a normal Linux desktop — not a phone alone. The worker runs on the computer; Telegram is only the inbox.
• Python 3.12 or newer (the project badge is Python 3.12)
• Git, so you can clone the repo
• A text editor (Notepad, TextEdit, or VS Code)

Telegram

• The Telegram app on your phone or desktop
• A free bot token from @BotFather — no paid Telegram plan

Live Tennis API Ultra

• A paid Ultra key. Basic / free cannot open GET /ws-token.
• 10% off Ultra with code botblog at checkout (one word, lowercase)

Step 0 — Install Python and Git (do this once)

1. Python: python.org/downloads — pick 3.12 or newer. Windows: tick Add python.exe to PATH, then Install Now.
2. Check it: open PowerShell (Windows) or Terminal (Mac) and type:

   python --version
   

   On some Macs use python3 --version. You want Python 3.12.x (or newer).
3. Git: if git is not recognised, install it from git-scm.com (Windows: tick Add Git to PATH).

Windows tip: File Explorer → View → enable File name extensions so you can see .env and not save .env.txt by mistake.

Step 1 — Create a Telegram bot with @BotFather (free)

1. Open Telegram and search for @BotFather (the official one, with a blue tick).
2. Send /newbot.
3. Give it a name (what you will see in the chat list) and a username ending in bot.
4. Copy the token it replies with. It looks like 123456:ABC…. That is TELEGRAM_BOT_TOKEN.
5. Paste it into Notepad temporarily if you need — do not post it on GitHub, Discord, or social media.

What “it worked” looks like: BotFather has given you a token, and you have saved it somewhere private. You have not started any Python yet.

Step 2 — Buy a Live Tennis API Ultra key (10% off with code botblog)

The whole point of this service is that a break point hits Telegram the moment it is played. That “server pushes each point to you” model is only on Live Tennis API’s Ultra plan.

• Polling (lower tiers): you ask on a timer via REST (for example GET /matches?status=live). Between calls you are blind. The free plan is capped at 30 requests/min and 100 requests/day.
• Push (Ultra): you connect once to a WebSocket. The server sends a frame on every score commit.

Real-time push is minted through GET /ws-token, documented as plan required: ULTRA. With a lower-tier key that request is rejected (HTTP 401/403). There is no WebSocket to connect to. This worker has no polling fallback. If the key is not Ultra, the process exits.

1. Open this affiliate link.
2. At checkout, enter promo code botblog — that is 10% off the Ultra plan. One word, lowercase.
3. Choose Ultra, not the free key.
4. Copy the API key from your Live Tennis API dashboard. That is LIVE_TENNIS_API_KEY.

Subscribe to Ultra — 10% off with code botblog →

Affiliate link — code botblog. Disclosure

What “it worked” looks like: you have an Ultra key on screen, and you have not put it in GitHub.

Step 3 — Clone GitHub, venv, pip

Open GitHub

A terminal is a text window where you type a command and press Enter. It is not Notepad and not your web browser.

Windows — open PowerShell in a folder: File Explorer → click the address bar → type powershell → Enter. Or hold Shift and right-click empty space → Open PowerShell window here.

Mac: Terminal from Spotlight.

Copy these commands from the project README. Run them one at a time.

Mac / Linux

git clone https://github.com/stephanepatteux/tennis-trader-alerts.git
cd tennis-trader-alerts

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

cp .env.example .env

Windows PowerShell (same clone; activate and copy use Windows paths)

git clone https://github.com/stephanepatteux/tennis-trader-alerts.git
cd tennis-trader-alerts

python3 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt

copy .env.example .env

If Activate.ps1 is blocked, the README’s Windows line is:

.venv\Scripts\activate

When activate works, the prompt starts with (.venv). If python3 fails on Windows, try py -m venv .venv then python -m venv as in our dashboard beginner guide.

What “it worked” looks like: a tennis-trader-alerts folder, a .venv folder inside it, pip finished without an error, and a new .env file sitting next to .env.example.

Step 4 — Put two secrets in .env

Open .env in a text editor. Paste your two secrets. No quotes. No spaces around =.

LIVE_TENNIS_API_KEY=paste_your_ultra_key_here
TELEGRAM_BOT_TOKEN=paste_your_botfather_token_here

Optional but recommended — lock the bot to you so strangers cannot /start and burn your Ultra quota. Message @userinfobot, copy your numeric Id, and set:

TELEGRAM_ALLOWED_CHATS=123456789

Replace 123456789 with your id. You can list more than one chat, comma-separated. Anyone already saved in data/rules.json keeps access.

.env is git-ignored. Never commit it. Never bake keys into a Docker image. The Ultra key is sent as Authorization: Bearer to Live Tennis API; the Telegram token is used only for Bot API calls.

What “it worked” looks like: two filled lines in .env, still on your PC only. The example file .env.example stays empty of real keys — that is correct.

Step 5 — python -m app (what success looks like)

With (.venv) still showing, run:

python -m app

Leave that terminal open. Ctrl+C stops it.

You should see log lines including:

Telegram bot menu started
Connected source=livetennisapi-ultra users=0 bot=on

users=0 means nobody has /started yet. bot=on means the Telegram token was accepted. If .env was missing a key, the process exits with a clear error (exit code 2). Fix .env and run python -m app again.

python -m app --dry-run still needs the Ultra key (it must consume the live feed) but logs alerts instead of sending them. Tests need no keys:

pytest

What “it worked” looks like: the process stays running. It does not return you to the prompt. Do not close the window.

Step 6 — /start and pick 0–40 + 15–40

1. In Telegram, search for your bot (the name you gave BotFather).
2. Tap Start or send /start.
3. Use the persistent keyboard: ⚙️ Menu, Status, Pause, Resume.
4. Toggle 0–40 and 15–40 (you can also use 30–40, Any BP, Deuce, Tiebreak).
5. Optionally filter ATP/WTA, clay/hard/grass, and add a player watchlist (➕ Player, then type a name; tap ✕ name to remove).

Commands also appear in Telegram’s bot command list: /menu /status /on /off /help. /off pauses without wiping filters.

What 0–40 and 15–40 Telegram alerts actually send

0–40 is three break points against the server. 15–40 is two. The message names the players, tour, surface, sets / games / points, and who is serving. Rising-edge: the bot fires when that score newly appears, not on every point it sits. It does not place a Betfair bet and it is not a tip. Why traders watch 15–40 is in the 15–40 tennis trading strategy guide — this ping is only the score state.

The menu works immediately. Telegram alerts only fire when a live ATP/WTA game actually hits that score. Rising-edge: a 15–40 that sits for three points is one message, not three.

What “it worked” looks like: you can open ⚙️ Menu and see 0–40 / 15–40 toggles. You may wait until a live match actually reaches that score before a ping arrives. That is expected.

Everyday use — starting again tomorrow

1. Open PowerShell or Terminal in the tennis-trader-alerts folder
2. Activate the toolbox:
   • Windows: .venv\Scripts\Activate.ps1 (or .venv\Scripts\activate)
   • Mac: source .venv/bin/activate
3. python -m app
4. Leave it running. Your Telegram filters are stored in data/rules.json on this PC — you do not need to rebuild them unless you want to.

That is the whole daily routine. Stop with Ctrl+C.

Keep the Tennis Trader Board open on a second screen when you are at the desk. Filters and pins are explained in the board guide.

If something goes wrong

These are the failures the project actually documents — not a guess list.

Full operations notes (reconnect, rules reload, Docker) live in the repo docs/OPERATIONS.md. Beginners can ignore Docker until this path works on the desktop.

Next steps

1. Keep the free Tennis Trader Board on a second screen while this worker pings the phone
2. Board guide — filters, pins, P1 odds gap
3. 15–40 tennis trading strategy — why that score state is watched (not a signal from this bot)
4. Break-point playbook — 0–40, 30–40, deuce, tiebreak
5. Live Tennis API for exchange bots — licences, costs, and what a betting bot would still need (this Telegram worker is not that)
6. 15–40 hold-rate match tape — after a ping, count whether the server actually held on completed matches
7. BF Bot Manager tennis — if you want a bot that can place Betfair bets (this Telegram worker cannot)
8. Build a personal scoreboard — another Python beginner path if you want a browser board on your PC

Source: github.com/stephanepatteux/tennis-trader-alerts (MIT). Board sample: live-tennis-scoreboard.

Disclaimer: This Telegram worker and all content on BotBlog are for educational and informational purposes only. Not financial or betting advice. Not a tipster. Live scores are informational only. They are not tips and do not place bets for you. This post contains affiliate links to Live Tennis API. Full disclosure.