Get alerts in Telegram
Your monitors can post their events to a Telegram
chat or group: one short message when a site gets blocked or unblocked by an
operator, or added to a public block list. Setting it up takes a minute and
needs no programming. Telegram is one more channel next to webhooks and
GET /v1/events; it changes nothing about them.
The bot is called Linkspect Alerts. It only posts alerts: it does not make monitors, show results or have menus. It never asks for your API key. Never paste a key into a chat.
1. Get a link
We send you a one-time link together with your API key. You can also make one yourself with your key:
curl https://api.linkspect.com/v1/telegram/links \
-H "Authorization: Bearer $LINKSPECT_KEY" \
-H "Content-Type: application/json" -d '{}'
The answer has two links: url for a private chat with the bot,
and group_url for a group. Each link works once, for one chat, for
14 days.
2. Link a private chat
- Open
urlon a phone or computer with Telegram. - Telegram opens a chat with Linkspect Alerts. Press Start.
- The bot answers: This chat is now linked to Linkspect. It gets a message for each event of all your monitors.
2. Or link a group
- Open
group_url. Telegram asks which group to add the bot to. Pick the group and confirm. You must be allowed to add members there (usually a group admin). - The bot posts the same confirmation in the group.
The bot reads only commands meant for it. It does not read the group's other messages.
What a message looks like
Blocked: example.com
Poland · Play (mobile)
How: The operator's resolver sends the name to Play's block page.
Check: chk_01M751N53GVGR0SN3T9GWTHAHC
Each message gives the site, the country, the operator and whether it is
home or mobile internet, how the site is blocked (the first sentence of the
result's explanation) and the check ID, for GET
/v1/checks/{id}. A lifted block reads Block lifted:, a new
entry on a public list On a block list: with the operators'
deadline. Every event type of the monitors page has
its message. Link previews are off, so Telegram never opens the monitored
site itself.
Messages from a test key start with [TEST] and end with
Test key: a fixture result, not a measurement. To try it, link a
chat with a test key's link and make a test monitor of
https://flip.fixtures.linkspect.com/ with "interval":
"15m" (see Test keys and fixtures).
Only some monitors or events
A link covers every monitor of the key's account and kind, also monitors you make later. To limit it, name them when you make the link:
curl https://api.linkspect.com/v1/telegram/links \
-H "Authorization: Bearer $LINKSPECT_KEY" \
-H "Content-Type: application/json" \
-d '{"monitor_ids": ["mon_01M74XBRM09VB42AVD9J8VC107"],
"event_types": ["cohort.blocked", "cohort.unblocked"]}'
Opening a new link in a chat that is already linked replaces its monitors and event types.
Stop the alerts
- In a private chat, send
/stop. - In a group, a group admin sends
/stop@and the bot's name, as the bot's confirmation message shows it. - Or with the API:
GET /v1/telegram/chatslists the linked chats,DELETE /v1/telegram/chats/{id}unlinks one.
If you block the bot or remove it from the group, we stop sending at once.
The chat then shows status: "disabled" with the reason, and the
event telegram.disabled appears in GET /v1/events
(and in your other linked chats). To get alerts there again, open a new
link.
Delivery
A chat gets its messages one at a time, in the order of the events. When
Telegram asks us to slow down, we wait as long as it says. When Telegram
fails, we try again after 1, 5 and 15 minutes, then 1, 2, 4, 8 and 8 hours.
GET /v1/telegram/chats/{id}/deliveries shows each message and
its attempts. An account may link up to 10 chats per kind of key (test or
live).