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.

.js Telegram Actualizado el Ver en Markdown

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:

Shell
BOT_TOKEN=YOUR_BOT_TOKEN
AMODB_KEY=YOUR_API_KEY

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

Shell
mkdir movie-bot && cd movie-bot
npm init -y
npm pkg set type=module
npm install grammy

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

JavaScript
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_to_response=ratings y construye un pie de foto. La URL del póster es https://img.amodb.dev/t/p/w500 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.

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

CasoCausaReacción del bot
401Clave ausente, incorrecta o suspendidaLo registra, avisa al chat y termina. Todos los comandos fallarían.
429Superaste tus solicitudes por minutoEspera Retry-After segundos, con un tope de 30, reintenta dos veces y luego pide al usuario que lo intente más tarde.
results vacíoNingún título coincide con la consultaResponde que no se encontró ninguna película.
Tiempo agotado o error de redfetch lanza un errorResponde con una breve disculpa y registra el error.
Foto rechazadaTelegram no puede obtener la imagenEnví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.

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

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

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

Shell
node --env-file=.env bot.js

Con /movie fight club, el primer resultado de la búsqueda es la película 550. El bot envía su póster, https://img.amodb.dev/t/p/w500/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg, 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.

Text
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 /trending con la llamada trending/movie/week de 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.