Vincular un chat de empresa

Una empresa con una cuenta de Leeri puede vincular un chat de Telegram a ella. Se pueden vincular dos tipos de chat:

Chat	Qué hace el vínculo
Chat privado con @LeeriAMLBot	Las verificaciones de ese chat se facturan al plan y a la cuota de su cuenta, no a la verificación gratuita ni a los paquetes de Stars de la persona. El bot muestra Cargado a tu organización en cada respuesta.
Grupo o supergrupo	El grupo recibe las alertas de su cuenta, vea Alertas. En un grupo no se ejecutan verificaciones.

El vínculo se hace con un código de un solo uso que su backend solicita a la API y que una persona introduce en Telegram.

Crear un código de vinculación

POST /v1/telegram/link-codes requiere una clave de API con el scope telegram:manage, vea Scopes. El cuerpo es un objeto JSON vacío. La respuesta incluye el código una sola vez.

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

Campo	Significado
code	Un código de un solo uso de 22 caracteres. Solo se guarda un hash con clave, por lo que no se puede volver a mostrar.
deep_link	Un enlace de Telegram que abre el bot y canjea el código. Es null cuando no hay enlace del bot configurado y en una repetición.
expires_at	El código caduca 15 minutos después de crearse.

• El entorno lo determina la clave. Un código creado con una clave sandbox vincula el chat en sandbox; con una clave live, en live.
• Las repeticiones son seguras. Envíe una cabecera Idempotency-Key, vea Idempotencia. Repetir la solicitud con la misma clave devuelve el mismo link_code_id, con code y deep_link en null: el código nunca se muestra dos veces.
• Trate el código como un secreto hasta que se canjee. Quien lo canjee primero vincula su chat a su cuenta.

Canjear el código en Telegram

Quien canjea el código lo hace en el chat que se va a vincular:

• En un chat privado con @LeeriAMLBot, envíe /link <code> o abra el deep_link.
• En un grupo, añada @LeeriAMLBot al grupo y envíe allí /link <code>. Solo un administrador del grupo puede vincular o desvincular un grupo.

El bot confirma el vínculo en el chat. Responde que el código no es válido o ha caducado, que el chat ya está vinculado o que está vinculado a otra organización (desvincúlelo primero con /unlink). Para impedir que se adivinen códigos, un usuario puede hacer como máximo 5 intentos de vinculación por hora.

Un chat solo puede estar vinculado a una cuenta a la vez. Un chat privado vinculado se factura a la cuenta, por lo que la verificación gratuita y los paquetes de verificaciones no se aplican en él; si la cuenta no tiene verificaciones, el bot indica que se agotó la cuota de la organización.

Consultar los chats vinculados

GET /v1/telegram/links (scope telegram:manage) enumera los vínculos de su cuenta, los más recientes primero, incluidos los revocados. Nunca devuelve material de claves.

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

Cada vínculo tiene:

Campo	Significado
link_id	El identificador que se pasa para revocar el vínculo.
chat_type	private, group o supergroup.
status	active, inactive o revoked.
lang	El idioma en que el chat recibe sus mensajes.
api_key_id	La clave delegada de un chat privado; null para un grupo.
linked_at, inactive_at, revoked_at	Cuándo se creó el vínculo, pasó a inactivo y se revocó. Los dos últimos son null cuando no corresponden.

Un vínculo pasa a inactive cuando el bot se elimina del grupo.

Desvincular un chat

Cualquiera de las partes puede terminar un vínculo.

• Desde el chat: envíe /unlink. En un grupo solo puede hacerlo un administrador.
• Desde la API: DELETE /v1/telegram/links/{link_id} (scope telegram:manage). Revoca el vínculo y la clave delegada que hay detrás. Una clave que la API ya tenía en caché deja de autenticar en menos de un minuto. Revocar un vínculo ya revocado devuelve el mismo 200, no un error; un identificador que no es suyo devuelve 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"}

Si se revoca la clave de un chat privado, el chat se desvincula y el bot indica a la persona que cree un nuevo código de vinculación.

Si se elimina un grupo y se vuelve a añadir

Cuando el bot se elimina de un grupo, el vínculo pasa a inactive y las alertas se detienen. Si el bot se vuelve a añadir en un plazo de 24 horas y era el vínculo más reciente del grupo, el vínculo vuelve a estar activo sin un código nuevo. Pasado ese plazo, o si el grupo tiene un vínculo más reciente, cree un código nuevo. Un grupo que Telegram convierte en supergrupo conserva su vínculo.

Errores

Una clave sin telegram:manage recibe 403, una clave ausente o no válida 401, y un cuerpo que no es un objeto vacío 400. El sobre y los códigos están en Errores.