Прив’язка чату компанії

Компанія з обліковим записом Leeri може прив’язати до нього чат Telegram. Прив’язати можна чат двох видів:

Чат	Що дає прив’язка
Особистий чат із @LeeriAMLBot	Перевірки в цьому чаті списуються з тарифу й ліміту вашого облікового запису, а не з власної безкоштовної перевірки чи пакетів Stars людини. Бот показує Списано з рахунку вашої організації у кожній відповіді.
Група або супергрупа	Група отримує сповіщення вашого облікового запису, див. Сповіщення. У групі перевірки не виконуються.

Прив’язка виконується одноразовим кодом: ваш бекенд запитує його в API, а людина вводить його в Telegram.

Створіть код прив’язки

POST /v1/telegram/link-codes потребує ключа API зі scope telegram:manage, див. Scope. Тіло запиту — порожній JSON-об’єкт. Відповідь містить код один раз.

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": []
}

Поле	Значення
code	22-символьний одноразовий код. Зберігається лише його хеш із ключем, тож показати код повторно неможливо.
deep_link	Посилання Telegram, що відкриває бота й вводить код. Дорівнює null, коли посилання на бота не налаштовано, а також у повторі запиту.
expires_at	Код спливає через 15 хвилин після створення.

• Середовище визначає ключ. Код, створений ключем sandbox, прив’язує чат у sandbox; ключем live — у live.
• Повтори безпечні. Надсилайте заголовок Idempotency-Key, див. Ідемпотентність. Повторний запит із тим самим ключем повертає той самий link_code_id, а code і deep_link дорівнюють null: код ніколи не показується двічі.
• Ставтеся до коду як до секрету, доки його не введено. Хто введе його першим, той прив’яже свій чат до вашого облікового запису.

Введіть код у Telegram

Код вводить людина в чаті, який потрібно прив’язати:

• В особистому чаті з @LeeriAMLBot надішліть /link <code> або відкрийте deep_link.
• У групі додайте @LeeriAMLBot до групи й надішліть там /link <code>. Прив’язувати й відв’язувати групу може лише адміністратор групи.

Бот підтверджує прив’язку в чаті. Він відповідає, що код недійсний чи прострочений, що чат уже прив’язано або що його прив’язано до іншої організації (спершу відв’яжіть його командою /unlink). Щоб унеможливити підбір кодів, користувач може зробити не більше 5 спроб прив’язки на годину.

Чат може бути прив’язаний лише до одного облікового запису одночасно. Прив’язаний особистий чат тарифікується на обліковий запис, тому безкоштовна перевірка й пакети перевірок там не діють; якщо в облікового запису не лишилось перевірок, бот скаже, що ліміт організації вичерпано.

Перегляньте прив’язані чати

GET /v1/telegram/links (scope telegram:manage) повертає прив’язки вашого облікового запису, найновіші першими, разом із відкликаними. Матеріал ключів він ніколи не повертає.

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"])

Кожна прив’язка має поля:

Поле	Значення
link_id	Ідентифікатор, який передають під час відкликання прив’язки.
chat_type	private, group або supergroup.
status	active, inactive або revoked.
lang	Мова, якою чат отримує повідомлення.
api_key_id	Делегований ключ особистого чату; null для групи.
linked_at, inactive_at, revoked_at	Коли прив’язку створено, коли вона стала неактивною і коли відкликана. Останні два дорівнюють null, якщо не застосовні.

Прив’язка стає inactive, коли бота видалено з групи.

Відв’яжіть чат

Припинити прив’язку може будь-яка сторона.

• З чату: надішліть /unlink. У групі це може лише адміністратор.
• Через API: DELETE /v1/telegram/links/{link_id} (scope telegram:manage). Він відкликає прив’язку й делегований ключ за нею. Ключ, який API уже закешувало, перестає автентифікувати протягом хвилини. Відкликання вже відкликаної прив’язки повертає ту саму відповідь 200, а не помилку; ідентифікатор, що вам не належить, повертає 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"}

Якщо ключ особистого чату відкликано, чат відв’язується, і бот радить людині створити новий код прив’язки.

Якщо групу видалили й додали знову

Коли бота видаляють з групи, прив’язка стає inactive, і сповіщення припиняються. Якщо бота додано назад протягом 24 годин і це була найновіша прив’язка групи, прив’язка знову стає активною без нового коду. Після цього строку або якщо в групи є новіша прив’язка, створіть новий код. Група, яку Telegram перетворює на супергрупу, зберігає свою прив’язку.

Помилки

Ключ без telegram:manage отримує 403, відсутній чи недійсний ключ — 401, а тіло, що не є порожнім об’єктом, — 400. Конверт і коди — у Помилках.