Tutorial de bot de películas para Telegram
Este tutorial crea un bot de Telegram con grammY en Node.js. Envía /movie fight club y el bot responde con el póster, el año, la duración y la nota desde amodb. Lee ambas credenciales de variables de entorno, reintenta ante un 429 con Retry-After, guarda respuestas en memoria y se detiene si rechazan la clave. Lleva unos 20 minutos.
Qué vas a construir
Vas a construir un bot de Telegram que responde a /movie fight club con el póster, el título, el año, la duración y la nota. Necesitas Node.js 20.6 o superior, un token de bot de BotFather dentro de Telegram y una clave de amodb. El bot usa grammY y el fetch integrado, así que basta un paquete de npm. Calcula unos 20 minutos.
Paso 1: obtén dos credenciales
Elige un plan en precios. El plan fija cuántas solicitudes por minuto puede enviar tu bot. Crea una clave en el panel de tu cuenta, de 32 caracteres hexadecimales. Después abre un chat con BotFather en Telegram, envía /newbot, responde las dos preguntas y copia el token que imprime.
Pon ambos valores en un archivo .env y añade ese archivo a .gitignore:
BOT_TOKEN=YOUR_BOT_TOKEN
AMODB_KEY=YOUR_API_KEYPaso 2: crea el proyecto
El ajuste type activa la sintaxis import y el await de nivel superior. La página de autenticación muestra las formas de la clave en el encabezado y en api_key.
mkdir movie-bot && cd movie-bot
npm init -y
npm pkg set type=module
npm install grammyPaso 3: responde al primer comando
grammY coloca el texto posterior a un comando en ctx.match. Empieza con una función auxiliar que envía el encabezado Bearer y un comando que busca.
import { Bot } from 'grammy';
const bot = new Bot(process.env.BOT_TOKEN);
async function getJson(path, params) {
const url = new URL('https://api.amodb.dev/3' + path);
for (const [name, value] of Object.entries(params)) url.searchParams.set(name, value);
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
return res.json();
}
bot.command('movie', async (ctx) => {
const found = await getJson('/search/movie', { query: ctx.match, language: 'en-US' });
await ctx.reply(found.results[0]?.title ?? 'No movie found.');
});
bot.start();Paso 4: construye la respuesta con un póster
Toma el primer resultado de la búsqueda, cárgalo con append_ y construye un pie de foto. La URL del póster es https:/ más poster_path. Telegram descarga la foto por sí mismo, y img.amodb.dev no necesita clave. Un pie de foto admite como máximo 1024 caracteres, así que el código recorta la sinopsis.
Cada fuente de ratings es un objeto con value y votes, o null. Cuando imdb es null, el pie de foto recurre al vote_average agregado. La página de puntuaciones explica las cinco fuentes.
function buildCaption(movie) {
const year = (movie.release_date || '').slice(0, 4) || 'year unknown';
const imdb = movie.ratings?.imdb;
const rating = imdb
? `IMDb ${imdb.value}`
: movie.vote_average ? `TMDB ${movie.vote_average.toFixed(1)}` : 'not known';
const lines = [`${movie.title} (${year})`, `Rating: ${rating}`];
if (movie.runtime) lines.push(`Runtime: ${movie.runtime} min`);
if (movie.overview) lines.push('', movie.overview.slice(0, 600));
return lines.join('\n').slice(0, 1024);
}Paso 5: gestiona errores y límites de solicitudes
Deja que los manejadores lancen errores y captura todo en un solo lugar. Sin bot.catch, grammY detiene el bot cuando un manejador lanza un error.
| Caso | Causa | Reacción del bot |
|---|---|---|
| 401 | Clave ausente, incorrecta o suspendida | Lo registra, avisa al chat y termina. Todos los comandos fallarían. |
| 429 | Superaste tus solicitudes por minuto | Espera Retry-After segundos, con un tope de 30, reintenta dos veces y luego pide al usuario que lo intente más tarde. |
results vacío | Ningún título coincide con la consulta | Responde que no se encontró ninguna película. |
| Tiempo agotado o error de red | fetch lanza un error | Responde con una breve disculpa y registra el error. |
| Foto rechazada | Telegram no puede obtener la imagen | Envía el pie de foto como texto. |
El bucle de abajo está dentro de getJson. AmodbError es una pequeña subclase de Error con un campo status, que aparece en el listado final.
Cada comando cuesta dos solicitudes, así que el plan de 20 solicitudes por minuto atiende unas 10 búsquedas nuevas por minuto. Consulta límites de solicitudes y errores para ver los detalles.
for (let attempt = 0; ; attempt++) {
const res = await fetch(id, { headers, signal: AbortSignal.timeout(10_000) });
if (res.status === 429 && attempt < 2) {
const seconds = Math.min(Number(res.headers.get('retry-after')) || 5, 30);
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
continue;
}
if (!res.ok) throw new AmodbError(res.status);
return res.json();
}Paso 6: guarda las respuestas en caché
La comprobación del límite de solicitudes se ejecuta antes del caché perimetral, así que solo un caché dentro de tu propio bot ahorra solicitudes. Guarda un Map de URL a datos y una hora de caducidad. Usa las duraciones del perímetro: 10 minutos para la búsqueda y 6 horas para los detalles. Un tope de tamaño evita que un bot que lleva mucho tiempo en marcha crezca sin límite.
Las líneas del caché también están dentro de getJson.
const hit = cache.get(id);
if (hit && hit.expires > Date.now()) return hit.data;
// ...after a successful fetch:
if (cache.size > 500) cache.delete(cache.keys().next().value);
cache.set(id, { data, expires: Date.now() + ttlMs });Paso 7: el bot completo
Guarda esto como bot.js.
import { Bot } from 'grammy';
const { BOT_TOKEN, AMODB_KEY } = process.env;
if (!BOT_TOKEN || !AMODB_KEY) {
console.error('Set BOT_TOKEN and AMODB_KEY first.');
process.exit(1);
}
const API = 'https://api.amodb.dev/3';
const IMG = 'https://img.amodb.dev/t/p/w500';
const headers = { Authorization: `Bearer ${AMODB_KEY}` };
const cache = new Map();
class AmodbError extends Error {
constructor(status) {
super(`amodb returned ${status}`);
this.status = status;
}
}
async function getJson(path, params, ttlMs) {
const url = new URL(API + path);
for (const [name, value] of Object.entries(params)) url.searchParams.set(name, value);
const id = url.toString();
const hit = cache.get(id);
if (hit && hit.expires > Date.now()) return hit.data;
for (let attempt = 0; ; attempt++) {
const res = await fetch(id, { headers, signal: AbortSignal.timeout(10_000) });
if (res.status === 429 && attempt < 2) {
const seconds = Math.min(Number(res.headers.get('retry-after')) || 5, 30);
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
continue;
}
if (!res.ok) throw new AmodbError(res.status);
const data = await res.json();
if (cache.size > 500) cache.delete(cache.keys().next().value);
cache.set(id, { data, expires: Date.now() + ttlMs });
return data;
}
}
function buildCaption(movie) {
const year = (movie.release_date || '').slice(0, 4) || 'year unknown';
const imdb = movie.ratings?.imdb;
const rating = imdb
? `IMDb ${imdb.value}`
: movie.vote_average ? `TMDB ${movie.vote_average.toFixed(1)}` : 'not known';
const lines = [`${movie.title} (${year})`, `Rating: ${rating}`];
if (movie.runtime) lines.push(`Runtime: ${movie.runtime} min`);
if (movie.overview) lines.push('', movie.overview.slice(0, 600));
return lines.join('\n').slice(0, 1024);
}
const bot = new Bot(BOT_TOKEN);
bot.command('start', (ctx) =>
ctx.reply('Send /movie and a title, for example /movie fight club.'));
bot.command('movie', async (ctx) => {
const title = ctx.match.trim();
if (!title) return ctx.reply('Usage: /movie fight club');
await ctx.replyWithChatAction('typing');
const found = await getJson('/search/movie', { query: title, language: 'en-US' }, 10 * 60_000);
const hit = found.results[0];
if (!hit) return ctx.reply(`No movie found for "${title}".`);
const movie = await getJson(
`/movie/${hit.id}`,
{ language: 'en-US', append_to_response: 'ratings' },
6 * 60 * 60_000,
);
const caption = buildCaption(movie);
if (!movie.poster_path) return ctx.reply(caption);
try {
await ctx.replyWithPhoto(IMG + movie.poster_path, { caption });
} catch {
await ctx.reply(caption);
}
});
bot.catch(async ({ ctx, error }) => {
console.error('Update failed:', error);
if (error instanceof AmodbError && error.status === 401) {
console.error('amodb rejected AMODB_KEY (401). Fix the key and restart.');
await ctx.reply('The bot key was rejected. The owner has to fix it.').catch(() => {});
process.exit(1);
}
const text = error instanceof AmodbError && error.status === 429
? 'Too many requests right now. Try again in a minute.'
: 'The movie service did not answer. Try again later.';
await ctx.reply(text).catch(() => {});
});
await bot.api.setMyCommands([{ command: 'movie', description: 'Find a movie by title' }]);
process.once('SIGINT', () => bot.stop());
process.once('SIGTERM', () => bot.stop());
bot.start({ onStart: (me) => console.log(`Running as @${me.username}`) });Inícialo con el archivo .env y luego envía /movie fight club a tu bot en Telegram.
node --env-file=.env bot.jsCon /movie fight club, el primer resultado de la búsqueda es la película 550. El bot envía su póster, https:/, con este pie de foto:
El bot usa long polling, así que no necesita una dirección pública. Mantén el proceso en marcha con la herramienta que ya uses para servicios.
Fight Club (1999)
Rating: IMDb 8.8
Runtime: 139 min
A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy. Their concept catches on, with underground "fight clubs" forming in every town, until an eccentric gets in the way and ignites an out-of-control spiral toward oblivion.Próximos pasos
- Añade
/trendingcon la llamadatrending/movie/weekde tendencias y listas. - Deja que los usuarios elijan uno de cinco resultados con un teclado en línea, usando más de la respuesta de búsqueda.
- Envía tráilers con el endpoint de vídeos y tráilers.
- Crea el mismo comando para Discord.