linkspect API docs linkspect.com

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

  1. Open url on a phone or computer with Telegram.
  2. Telegram opens a chat with Linkspect Alerts. Press Start.
  3. 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

  1. 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).
  2. 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

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).