Link a company chat

A company with a Leeri account can link a Telegram chat to it. Two kinds of chat can be linked:

Chat	What linking does
Private chat with @LeeriAMLBot	Checks made in that chat are billed to your account's plan and quota, not to the person's own free check or Stars packs. The bot shows Billed to your organisation in every answer.
Group or supergroup	The group receives your account's alerts, see Alerts. No checks are run in a group.

Linking is done with a one-time code that your backend requests from the API and a person redeems in Telegram.

Create a link code

POST /v1/telegram/link-codes needs an API key with the telegram:manage scope; see Scopes. The body is an empty JSON object. The response carries the code once.

curl

curl -s -X POST https://api.leeri.ai/v1/telegram/link-codes \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

const response = await fetch('https://api.leeri.ai/v1/telegram/link-codes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const { data } = await response.json();
console.log(data.code, data.deep_link, data.expires_at);

Python

import os
import requests

response = requests.post(
    "https://api.leeri.ai/v1/telegram/link-codes",
    headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
    json={},
    timeout=30,
)
data = response.json()["data"]
print(data["code"], data["deep_link"], data["expires_at"])

{
  "status": "ok",
  "data": {
    "link_code_id": "0192e0d4-0000-7000-8000-000000000001",
    "code": "EXAMPLE0CODE0EXAMPLE00",
    "deep_link": "https://t.me/LeeriAMLBot?start=l_EXAMPLE0CODE0EXAMPLE00",
    "expires_at": "2026-01-01T12:15:00.000Z"
  },
  "errors": []
}

Field	Meaning
code	A 22-character single-use code. Only a keyed hash of it is stored, so it cannot be shown again.
deep_link	A Telegram link that opens the bot and redeems the code. It is null when no bot link is configured, and on a replay.
expires_at	The code expires 15 minutes after it is created.

• The environment follows the key. A code created with a sandbox key links the chat in sandbox; a live key links it live.
• Replays are safe. Send an Idempotency-Key header, see Idempotency. Repeating the request with the same key returns the same link_code_id, with code and deep_link set to null: the code is never shown twice.
• Treat the code as a secret until it is redeemed. Anyone who redeems it first links their chat to your account.

Redeem the code in Telegram

Whoever redeems the code does it in the chat that is to be linked:

• In a private chat with @LeeriAMLBot, send /link <code>, or open the deep_link.
• In a group, add @LeeriAMLBot to the group and send /link <code> there. Only a group administrator can link or unlink a group.

The bot confirms the link in the chat. It answers that the code is not valid or has expired when it cannot be redeemed, that the chat is already linked, or that it is linked to a different organisation (unlink it first with /unlink). To stop code guessing, a user can make at most 5 link attempts per hour.

A chat can be linked to one account at a time. A linked private chat is billed to the account, so the free check and the check packs do not apply there; if the account has no checks left, the bot says the organisation's quota is exhausted.

List linked chats

GET /v1/telegram/links (scope telegram:manage) lists your account's links, newest first, including revoked ones. It never returns key material.

curl

curl -s https://api.leeri.ai/v1/telegram/links \
  -H "Authorization: Bearer $LEERI_API_KEY"

Node.js

const response = await fetch('https://api.leeri.ai/v1/telegram/links', {
  headers: { Authorization: `Bearer ${process.env.LEERI_API_KEY}` },
});
const { data } = await response.json();
for (const link of data) console.log(link.link_id, link.chat_type, link.status);

Python

import os
import requests

response = requests.get(
    "https://api.leeri.ai/v1/telegram/links",
    headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
    timeout=30,
)
for link in response.json()["data"]:
    print(link["link_id"], link["chat_type"], link["status"])

Each link has:

Field	Meaning
link_id	The id to pass when revoking the link.
chat_type	private, group or supergroup.
status	active, inactive or revoked.
lang	The language the chat receives its messages in.
api_key_id	The delegated key behind a private chat; null for a group.
linked_at, inactive_at, revoked_at	When the link was made, went inactive and was revoked. The last two are null when not applicable.

A link goes inactive when the bot is removed from the group.

Unlink a chat

Either side can end a link.

• From the chat: send /unlink. In a group only an administrator can.
• From the API: DELETE /v1/telegram/links/{link_id} (scope telegram:manage). It revokes the link and the delegated key behind it. A key the API has already cached stops authenticating within a minute. Revoking a link that is already revoked answers the same 200, not an error; an id that is not yours answers 404.

curl

curl -s -X DELETE https://api.leeri.ai/v1/telegram/links/$LINK_ID \
  -H "Authorization: Bearer $LEERI_API_KEY"

Node.js

const response = await fetch(`https://api.leeri.ai/v1/telegram/links/${linkId}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.LEERI_API_KEY}` },
});
console.log((await response.json()).data); // { link_id, status: "revoked" }

Python

import os
import requests

response = requests.delete(
    f"https://api.leeri.ai/v1/telegram/links/{link_id}",
    headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
    timeout=30,
)
print(response.json()["data"])  # {"link_id": ..., "status": "revoked"}

If the key behind a private chat is revoked, the chat is unlinked and the bot tells the person to create a new link code.

If a group is removed and added again

When the bot is removed from a group the link goes inactive and alerts stop. If the bot is added back within 24 hours and that was the group's most recent link, the link becomes active again without a new code. After that window, or if the group has a newer link, create a new code. A group that Telegram upgrades to a supergroup keeps its link.

Errors

A key without telegram:manage answers 403, a missing or invalid key 401, and a body that is not an empty object 400. See Errors for the envelope and the codes.