Add /gifer: convert a replied-to GIF into a Telegram video sticker

Reply to any GIF with /gifer and it's converted to a WEBM/VP9 video
sticker (Telegram's only animated-sticker path a raster GIF can
actually reach — TGS is vector-only) and added to the user's pack,
creating one first if needed.

Encoding runs through ffmpeg (new Dockerfile dependency), retrying
down a CRF/fps ladder until the output fits Telegram's 256KB video
sticker cap, and reports a real failure rather than delivering
something Telegram would reject if nothing fits. Live-tested against
real GIFs before writing any app code: a moderately complex 400x400
animated GIF encoded to ~120KB at good quality, comfortably inside
budget.

Two real bugs caught by live end-to-end testing (not just mocked unit
tests) against the actual running app with real ffmpeg:
- Telegram's docs state video/animated stickers can't be uploaded via
HTTP URL (unlike static ones) — the relay Worker now fetches the
converted bytes itself and re-uploads via multipart/form-data instead
of just handing Telegram a URL.
- An input-side `-t 3` trimmed how much of the source ffmpeg READ, but
the fps filter could then round that up to one extra frame in the
output, overshooting the 3s cap (3.067s observed). Moved -t to an
output-side option, which cuts the encoded stream at exactly 3.0s.

Converted bytes are cached in a new TelegramConvertedSticker table
(claimed and deleted on first fetch, like every outbox table) since —
unlike every other sticker this app delivers — they're a one-off, not
regenerable from a short URL parameter.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Dockerfile

@@ -2,6 +2,13 @@ FROM python:3.11-slim
 
 WORKDIR /app
 
+# ffmpeg — GIF-to-video-sticker conversion (notify/gif_sticker.py, the
+# /gifer command). Only the libvpx-vp9 encode path is actually used; the
+# Debian package pulls in a full build rather than a minimal one, which is
+# an acceptable image-size tradeoff for not having to compile it ourselves.
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
 COPY backend/requirements.txt backend/requirements.txt
 RUN pip install --no-cache-dir -r backend/requirements.txt
 

backend/db/models.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import datetime
 import uuid
 
-from sqlalchemy import Boolean, DateTime, Float, ForeignKey, Integer, JSON, String, Text, UniqueConstraint
+from sqlalchemy import Boolean, DateTime, Float, ForeignKey, Integer, JSON, LargeBinary, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from db.session import Base
@@ -252,6 +252,26 @@ class TelegramOutboxStickerAdd(Base):
     created_at: Mapped[datetime.datetime] = mapped_column(DateTime(timezone=True), default=_now)
 
 
+class TelegramConvertedSticker(Base):
+    """One-shot storage for a GIF converted to a video sticker (the
+    /gifer command, notify/gif_sticker.py) — unlike every other sticker
+    delivery in this app (generated: deterministic from a prompt+seed;
+    copied: an existing Telegram file_id), a converted GIF's output
+    bytes aren't re-derivable from a short URL param, so they have to
+    sit somewhere until Telegram's relay Worker fetches them. Claimed
+    exactly like the outbox tables: GET /telegram/sticker.webm (main.py)
+    deletes the row after serving it once. Telegram also further
+    requires video stickers to be uploaded via multipart/form-data
+    rather than passed as a URL directly (unlike static ones) — see the
+    Worker's uploadStickerBytes — so this row is fetched by the Worker
+    itself and re-uploaded, not handed to Telegram as a URL."""
+    __tablename__ = "telegram_converted_stickers"
+
+    token: Mapped[str] = mapped_column(String(64), primary_key=True)
+    webm_bytes: Mapped[bytes] = mapped_column(LargeBinary)
+    created_at: Mapped[datetime.datetime] = mapped_column(DateTime(timezone=True), default=_now)
+
+
 class TelegramAiCooldown(Base):
     """Per-DM cooldown gate for the natural-language Q&A path (see
     notify/telegram_ai.py) — the only bot feature that costs a real

backend/main.py

@@ -71,6 +71,7 @@ from db.models import (
     ScannerSymbol,
     Signal,
     SignalSubscription,
+    TelegramConvertedSticker,
     TelegramOutboxAudio,
     TelegramOutboxButtonMessage,
     TelegramOutboxMessage,
@@ -83,7 +84,7 @@ from db.models import (
 from db.session import get_session, init_db
 from indicators.technical import compute_indicators
 from news.sentiment import get_news_sentiment, fetch_article_text, is_served_article_url
-from notify import charts, image_gen, md, telegram_commands, voice, witty
+from notify import charts, gif_sticker, image_gen, md, telegram_commands, voice, witty
 from notify.email import send_email
 from notify.telegram import (
     TELEGRAM_BOT_TOKEN,
@@ -1069,6 +1070,10 @@ class TelegramWebhookBody(BaseModel):
     # The text/caption of whatever this message replies to, from ANY
     # sender — not just the bot or a sticker (separate fields above).
     replied_message_text: Optional[str] = None
+    # Present only when this message replies to a GIF (Telegram's
+    # `animation` type) — the /gifer command's input, Worker-downloaded
+    # and base64-encoded the same way voice/document/photo bytes are.
+    replied_animation_file_b64: Optional[str] = None
 
 
 @app.post("/telegram/webhook")
@@ -1108,7 +1113,7 @@ async def telegram_webhook(
         body.voice_file_b64, body.document_file_b64, body.document_mime_type,
         body.photo_file_b64, body.caption,
         body.replied_sticker_file_id, body.replied_sticker_is_animated, body.replied_sticker_is_video,
-        body.message_id, body.replied_message_text,
+        body.message_id, body.replied_message_text, body.replied_animation_file_b64,
     )
     await session.commit()
     if not deliver_now:
@@ -1381,6 +1386,37 @@ async def telegram_sticker_photo(source_url: str = Query(...), exp: int = Query(
     return Response(content=sticker, media_type="image/webp")
 
 
+@app.get("/telegram/sticker.webm")
+async def telegram_sticker_webm(
+    token: str = Query(...), exp: int = Query(...), sig: str = Query(...),
+    session: AsyncSession = Depends(get_session),
+):
+    """Fetched by the relay Worker itself (NOT Telegram directly — see
+    the Worker's uploadStickerBytes: video stickers can't be handed to
+    Telegram as a URL, only via multipart upload, unlike every other
+    sticker this app delivers). Unlike sticker.webp/sticker-photo.webp
+    above, this can't regenerate its content on demand — a converted
+    GIF's bytes are a one-off, not derivable from a short URL param — so
+    they're looked up from TelegramConvertedSticker (written by
+    /gifer, notify/telegram_commands.py::cmd_gifer) and the row is
+    deleted once served, the same claim-by-delete contract as every
+    outbox table in this app."""
+    if not _TELEGRAM_RELAY_SECRET:
+        raise HTTPException(status_code=403, detail="Not configured")
+    if int(time.time()) > exp:
+        raise HTTPException(status_code=403, detail="Expired sticker link")
+    if not hmac.compare_digest(sig, gif_sticker.sign_gif_sticker_token(token, exp)):
+        raise HTTPException(status_code=403, detail="Invalid signature")
+
+    row = await session.get(TelegramConvertedSticker, token)
+    if not row:
+        raise HTTPException(status_code=404, detail="Sticker not found or already claimed")
+    webm_bytes = row.webm_bytes
+    await session.delete(row)
+    await session.commit()
+    return Response(content=webm_bytes, media_type="video/webm")
+
+
 def _signal_dict(s: Signal) -> dict:
     return {
         "id": s.id, "symbol": s.symbol, "direction": s.direction, "timeframe": s.timeframe,

backend/notify/gif_sticker.py

@@ -0,0 +1,131 @@
+"""GIF -> Telegram video sticker conversion, powering the /gifer command
+(notify/telegram_commands.py). Telegram's "video sticker" format is the
+only way to turn a raster GIF into an animated sticker at all — the other
+animated format, "animated" (.TGS), is a vector Lottie animation with no
+meaningful GIF-to-TGS conversion path. Video stickers must be WEBM/VP9,
+silent, at most 3 seconds, with one side exactly 512px, and — the binding
+constraint — at most 256KB.
+
+Live-tested against real GIFs before building this (not just trusting
+Telegram's docs): a moderately complex 400x400 animated GIF (continuous
+color, no flat regions) encoded to 117KB at good quality (CRF 30) once
+scaled to 512px/15fps/3s — comfortably inside budget. Only adversarial
+content (literal random noise, far outside what any real GIF's own
+256-color palette can produce) fails to fit even at the lowest quality
+tried here — hence the honest "couldn't convert" failure path below
+rather than ever silently delivering something over Telegram's limit
+(which it would just reject).
+
+ffmpeg is shelled out to directly (see the Dockerfile) rather than using
+a Python video library — there's no meaningfully-maintained pure-Python
+GIF->VP9/WEBM encoder, and ffmpeg is the standard tool for this exact job.
+
+Unlike every other sticker delivery in this app (generated: deterministic
+from a prompt+seed; copied: an existing Telegram file_id), a converted
+GIF's output bytes are a one-off — not re-derivable from a short URL
+param — so they're cached in TelegramConvertedSticker (db/models.py)
+until the relay Worker fetches and claims them via GET
+/telegram/sticker.webm. Telegram also requires video stickers to be
+uploaded via multipart/form-data rather than passed as a URL (unlike
+static ones) — see the Worker's uploadStickerBytes — so this row is
+fetched by the Worker itself and re-uploaded, not handed to Telegram
+directly."""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import hmac
+import logging
+import os
+import tempfile
+from typing import Optional
+
+logger = logging.getLogger("pulsar.notify.gif_sticker")
+
+GIF_STICKER_TOKEN_TTL_SECONDS = 300  # same reasoning as image_gen.py's STICKER_TOKEN_TTL_SECONDS
+_TELEGRAM_RELAY_SECRET = os.getenv("TELEGRAM_RELAY_SECRET", "")
+
+_MAX_OUTPUT_BYTES = 256 * 1024  # Telegram's hard cap for video stickers
+_MAX_DURATION_SECONDS = 3  # Telegram's hard cap for video stickers
+_FFMPEG_BIN = os.getenv("FFMPEG_BIN", "ffmpeg")
+_ENCODE_TIMEOUT_SECONDS = 20  # guards against a malformed/corrupt GIF hanging the encoder
+
+# Tried in order at 15fps; the first one to land under _MAX_OUTPUT_BYTES
+# wins. Real GIFs (already palette-limited to 256 colors, unlike true
+# video) fit comfortably well before the end of this ladder — confirmed
+# live, see this module's docstring. The final fps=10 pass is a last-ditch
+# attempt for genuinely high-entropy content the 15fps ladder couldn't fit.
+_CRF_LADDER_15FPS = [28, 32, 36, 40, 45, 50, 55, 60]
+_CRF_LADDER_10FPS_FALLBACK = [55, 63]
+
+# Telegram requires one side to be exactly 512px; the other scales down
+# proportionally. -2 keeps the scaled dimension even (required by yuv420p
+# chroma subsampling) — ffmpeg's scale filter rounds down to the nearest
+# even number when given -2 as a dimension.
+_SCALE_FILTER = "scale='if(gte(iw,ih),512,-2)':'if(gte(iw,ih),-2,512)'"
+
+
+def sign_gif_sticker_token(token: str, exp: int) -> str:
+    msg = f"{token}|{exp}".encode()
+    return hmac.new(_TELEGRAM_RELAY_SECRET.encode(), msg, hashlib.sha256).hexdigest()
+
+
+async def _run_ffmpeg(input_path: str, output_path: str, fps: int, crf: int) -> bool:
+    """Runs one encode attempt; returns whether ffmpeg exited 0. Doesn't
+    itself check the output size — the caller does, since a successful
+    encode over budget just means "try a lower-quality pass next", not a
+    real failure."""
+    # -t as an OUTPUT option (after -i), not an input one — an input-side
+    # -t trims how much of the source is READ, but the fps filter can then
+    # round that up to an extra whole frame in the output, overshooting
+    # the 3s cap (confirmed live: input-side -t produced a 3.067s file for
+    # a fps=15 encode). Output-side -t cuts the encoded stream itself at
+    # exactly 3.0s regardless of frame boundaries.
+    args = [
+        _FFMPEG_BIN, "-y", "-i", input_path,
+        "-vf", f"{_SCALE_FILTER},fps={fps}",
+        "-pix_fmt", "yuv420p",
+        "-c:v", "libvpx-vp9", "-b:v", "0", "-crf", str(crf),
+        "-an", "-t", str(_MAX_DURATION_SECONDS), "-f", "webm", output_path,
+    ]
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *args, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+        )
+        _, stderr = await asyncio.wait_for(proc.communicate(), timeout=_ENCODE_TIMEOUT_SECONDS)
+    except (asyncio.TimeoutError, FileNotFoundError, OSError):
+        logger.warning("ffmpeg encode failed to run (crf=%d fps=%d)", crf, fps, exc_info=True)
+        return False
+    if proc.returncode != 0:
+        logger.warning("ffmpeg exited %s (crf=%d fps=%d): %s", proc.returncode, crf, fps, stderr.decode(errors="replace")[-500:])
+        return False
+    return True
+
+
+async def convert_gif_to_webm_sticker(gif_bytes: bytes) -> Optional[bytes]:
+    """Returns WEBM bytes fitting Telegram's video-sticker limits (3s,
+    512px one side, <=256KB), or None if no quality level tried gets
+    under budget (or ffmpeg itself isn't available/fails outright) —
+    callers should show a real "couldn't convert this one" reply rather
+    than attempting delivery, since Telegram would just reject an
+    oversized upload anyway."""
+    if not gif_bytes:
+        return None
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        input_path = os.path.join(tmpdir, "input.gif")
+        output_path = os.path.join(tmpdir, "output.webm")
+        with open(input_path, "wb") as f:
+            f.write(gif_bytes)
+
+        for fps, ladder in ((15, _CRF_LADDER_15FPS), (10, _CRF_LADDER_10FPS_FALLBACK)):
+            for crf in ladder:
+                if not await _run_ffmpeg(input_path, output_path, fps, crf):
+                    return None  # a real ffmpeg failure, not just "too big" — no point retrying
+                size = os.path.getsize(output_path) if os.path.exists(output_path) else 0
+                if 0 < size <= _MAX_OUTPUT_BYTES:
+                    with open(output_path, "rb") as f:
+                        return f.read()
+
+    logger.warning("gif->webm conversion never fit under %d bytes even at lowest quality", _MAX_OUTPUT_BYTES)
+    return None

backend/notify/telegram.py

@@ -104,6 +104,7 @@ async def handle_incoming_update(
     replied_sticker_is_video: bool = False,
     message_id: int | None = None,
     replied_message_text: str | None = None,
+    replied_animation_file_b64: str | None = None,
 ) -> bool:
     """Processes one Telegram message relayed by the Worker. /start <code>
     (the linking handshake) and bare /start (welcome message) stay here
@@ -173,6 +174,14 @@ async def handle_incoming_update(
     are separate fields above) — lets "@PulsarBot what does this mean?"
     as a reply to someone else's message actually see what "this" is.
 
+    replied_animation_file_b64 is set only when this message replies to
+    a GIF (Telegram's `animation` message type) — the /gifer command's
+    input, already downloaded and base64-encoded by the Worker the same
+    way voice/document/photo bytes are (same reason: this backend can't
+    fetch it itself). Unlike those three, `text` stays as-is here (it's
+    the literal "/gifer" command text) rather than being replaced by
+    anything derived from the bytes.
+
     Returns True if whatever this queued should be claimed and returned
     synchronously in the webhook's own HTTP response (see main.py's
     /telegram/webhook) rather than left for the async outbox poll — see
@@ -236,5 +245,5 @@ async def handle_incoming_update(
     from notify import telegram_commands
     return await telegram_commands.dispatch(
         session, chat_id, text, from_id, chat_type, reply_to_bot_username, is_voice_input, image_data_url,
-        replied_sticker, message_id, replied_message_text,
+        replied_sticker, message_id, replied_message_text, replied_animation_file_b64,
     )

backend/notify/telegram_commands.py

@@ -791,6 +791,74 @@ async def cmd_kang(session: AsyncSession, chat_id: str, from_id: Optional[str],
     return True
 
 
+async def cmd_gifer(
+    session: AsyncSession, chat_id: str, from_id: Optional[str], replied_animation_file_b64: Optional[str],
+) -> bool:
+    """Direct GIF-to-video-sticker command — reply to a GIF with /gifer
+    and it's converted and added to your pack. Special-cased in
+    dispatch() below rather than living in _COMMANDS, same reason as
+    /kang: needs replied_animation_file_b64, which no other command
+    handler takes.
+
+    Unlike /kang (which just reuses an existing sticker's file_id, no
+    conversion needed), this one does real work — ffmpeg encoding — so
+    it's noticeably slower than every other command here. Still handled
+    synchronously within this request rather than deferred to the outbox
+    poll: the conversion has already happened by the time this function
+    would return either way, so there's no reason to make the user wait
+    on ANOTHER outbox poll cycle on top of that."""
+    if not replied_animation_file_b64:
+        await send_telegram_message(session, chat_id, md.escape("Reply to a GIF with /gifer to add it to your pack as a video sticker."))
+        return True
+    if not from_id:
+        await send_telegram_message(session, chat_id, md.escape("Couldn't identify who's asking."))
+        return True
+
+    import base64
+    try:
+        gif_bytes = base64.b64decode(replied_animation_file_b64)
+    except Exception:
+        gif_bytes = b""
+    if not gif_bytes:
+        await send_telegram_message(session, chat_id, md.escape("Couldn't read that GIF."))
+        return True
+
+    from notify import gif_sticker
+    webm_bytes = await gif_sticker.convert_gif_to_webm_sticker(gif_bytes)
+    if webm_bytes is None:
+        await send_telegram_message(
+            session, chat_id,
+            md.escape("Couldn't convert that GIF into a sticker that fits Telegram's size limit — try a shorter or simpler one."),
+        )
+        return True
+
+    import secrets
+    from db.models import TelegramConvertedSticker, TelegramStickerSet
+    token = secrets.token_urlsafe(24)
+    session.add(TelegramConvertedSticker(token=token, webm_bytes=webm_bytes))
+    exp = int(time.time()) + gif_sticker.GIF_STICKER_TOKEN_TTL_SECONDS
+    sig = gif_sticker.sign_gif_sticker_token(token, exp)
+    sticker_url = f"{_PULSAR_WEB_URL}/telegram/sticker.webm?token={token}&exp={exp}&sig={sig}"
+    emoji = "\U0001F642"
+
+    from notify import telegram_ai
+    tracked = await session.get(TelegramStickerSet, from_id)
+    if tracked:
+        telegram_ai.queue_sticker_delivery(session, chat_id, from_id, "sticker_add", {
+            "set_name": tracked.set_name, "title": f"Pulsar Stickers ({from_id})",
+            "sticker_url": sticker_url, "emoji": emoji, "sticker_format": "video",
+        })
+        return True
+
+    set_name = f"pulsar_u{from_id}_by_{TELEGRAM_BOT_USERNAME}"
+    session.add(TelegramStickerSet(from_id=from_id, set_name=set_name))
+    telegram_ai.queue_sticker_delivery(session, chat_id, from_id, "sticker_create", {
+        "set_name": set_name, "title": f"Pulsar Stickers ({from_id})",
+        "sticker_url": sticker_url, "emoji": emoji, "sticker_format": "video",
+    })
+    return True
+
+
 async def cmd_space(session: AsyncSession, chat_id: str, args: str, from_id: Optional[str], chat_type: str) -> bool:
     from notify import space
     apod = await space.get_apod()
@@ -1097,6 +1165,7 @@ async def dispatch(
     replied_sticker: Optional[dict] = None,
     message_id: Optional[int] = None,
     replied_message_text: Optional[str] = None,
+    replied_animation_file_b64: Optional[str] = None,
 ) -> bool:
     """Returns True if the caller (main.py's webhook route) should
     synchronously claim and return whatever this command just queued,
@@ -1130,6 +1199,8 @@ async def dispatch(
     # reason: different inputs than the general case).
     if cmd == "/kang":
         return await cmd_kang(session, chat_id, from_id, replied_sticker)
+    if cmd == "/gifer":
+        return await cmd_gifer(session, chat_id, from_id, replied_animation_file_b64)
 
     handler = _COMMANDS.get(cmd)
     if handler is not None:

backend/tests/test_gif_sticker.py

@@ -0,0 +1,119 @@
+import time
+
+import pytest
+
+from db.models import TelegramConvertedSticker
+from notify import gif_sticker
+
+
+# ---------- convert_gif_to_webm_sticker ----------
+
+@pytest.mark.asyncio
+async def test_convert_returns_none_for_empty_bytes():
+    assert await gif_sticker.convert_gif_to_webm_sticker(b"") is None
+
+
+@pytest.mark.asyncio
+async def test_convert_returns_bytes_from_first_attempt_under_budget(monkeypatch):
+    calls = []
+
+    async def fake_run_ffmpeg(input_path, output_path, fps, crf):
+        calls.append((fps, crf))
+        with open(output_path, "wb") as f:
+            f.write(b"x" * 1000)  # well under budget
+        return True
+
+    monkeypatch.setattr(gif_sticker, "_run_ffmpeg", fake_run_ffmpeg)
+    result = await gif_sticker.convert_gif_to_webm_sticker(b"fake gif bytes")
+    assert result == b"x" * 1000
+    # Only the first (highest-quality) rung of the ladder should have run.
+    assert calls == [(15, gif_sticker._CRF_LADDER_15FPS[0])]
+
+
+@pytest.mark.asyncio
+async def test_convert_retries_down_the_ladder_until_under_budget(monkeypatch):
+    attempt = {"n": 0}
+
+    async def fake_run_ffmpeg(input_path, output_path, fps, crf):
+        attempt["n"] += 1
+        # First two attempts stay oversized, third finally fits.
+        size = gif_sticker._MAX_OUTPUT_BYTES + 1 if attempt["n"] < 3 else 500
+        with open(output_path, "wb") as f:
+            f.write(b"y" * size)
+        return True
+
+    monkeypatch.setattr(gif_sticker, "_run_ffmpeg", fake_run_ffmpeg)
+    result = await gif_sticker.convert_gif_to_webm_sticker(b"fake gif bytes")
+    assert result == b"y" * 500
+    assert attempt["n"] == 3
+
+
+@pytest.mark.asyncio
+async def test_convert_returns_none_when_ffmpeg_fails_outright(monkeypatch):
+    async def fake_run_ffmpeg(input_path, output_path, fps, crf):
+        return False
+
+    monkeypatch.setattr(gif_sticker, "_run_ffmpeg", fake_run_ffmpeg)
+    assert await gif_sticker.convert_gif_to_webm_sticker(b"fake gif bytes") is None
+
+
+@pytest.mark.asyncio
+async def test_convert_returns_none_when_nothing_ever_fits_budget(monkeypatch):
+    async def fake_run_ffmpeg(input_path, output_path, fps, crf):
+        with open(output_path, "wb") as f:
+            f.write(b"z" * (gif_sticker._MAX_OUTPUT_BYTES + 1))
+        return True
+
+    monkeypatch.setattr(gif_sticker, "_run_ffmpeg", fake_run_ffmpeg)
+    assert await gif_sticker.convert_gif_to_webm_sticker(b"fake gif bytes") is None
+
+
+def test_sign_gif_sticker_token_is_deterministic_and_tamper_evident():
+    exp = int(time.time()) + 300
+    sig1 = gif_sticker.sign_gif_sticker_token("tok123", exp)
+    sig2 = gif_sticker.sign_gif_sticker_token("tok123", exp)
+    assert sig1 == sig2
+    assert sig1 != gif_sticker.sign_gif_sticker_token("tokABC", exp)
+    assert sig1 != gif_sticker.sign_gif_sticker_token("tok123", exp + 1)
+
+
+# ---------- GET /telegram/sticker.webm ----------
+
+@pytest.mark.asyncio
+async def test_sticker_webm_endpoint_returns_bytes_and_claims_row(client, db_session):
+    db_session.add(TelegramConvertedSticker(token="claim-me", webm_bytes=b"FAKEWEBMBYTES"))
+    await db_session.commit()
+
+    exp = int(time.time()) + 60
+    sig = gif_sticker.sign_gif_sticker_token("claim-me", exp)
+    resp = await client.get("/telegram/sticker.webm", params={"token": "claim-me", "exp": exp, "sig": sig})
+    assert resp.status_code == 200, resp.text
+    assert resp.headers["content-type"] == "video/webm"
+    assert resp.content == b"FAKEWEBMBYTES"
+
+    # Claimed exactly once — a second fetch finds nothing.
+    resp2 = await client.get("/telegram/sticker.webm", params={"token": "claim-me", "exp": exp, "sig": sig})
+    assert resp2.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_sticker_webm_endpoint_rejects_bad_signature(client):
+    exp = int(time.time()) + 60
+    resp = await client.get("/telegram/sticker.webm", params={"token": "whatever", "exp": exp, "sig": "wrong"})
+    assert resp.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_sticker_webm_endpoint_rejects_expired_token(client):
+    exp = 1
+    sig = gif_sticker.sign_gif_sticker_token("whatever", exp)
+    resp = await client.get("/telegram/sticker.webm", params={"token": "whatever", "exp": exp, "sig": sig})
+    assert resp.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_sticker_webm_endpoint_404s_for_unknown_token(client):
+    exp = int(time.time()) + 60
+    sig = gif_sticker.sign_gif_sticker_token("never-existed", exp)
+    resp = await client.get("/telegram/sticker.webm", params={"token": "never-existed", "exp": exp, "sig": sig})
+    assert resp.status_code == 404

backend/tests/test_telegram_commands.py

@@ -1,3 +1,4 @@
+import base64
 import datetime
 
 import pandas as pd
@@ -11,6 +12,7 @@ from db.models import (
     Signal,
     SignalModel,
     SignalSubscription,
+    TelegramConvertedSticker,
     TelegramGroupSignalSubscription,
     TelegramStickerSet,
     User,
@@ -60,6 +62,7 @@ async def _clean_scan_tables(db_session):
     await db_session.execute(delete(TelegramGroupSignalSubscription))
     await db_session.execute(delete(WittyRemark))
     await db_session.execute(delete(TelegramStickerSet))
+    await db_session.execute(delete(TelegramConvertedSticker))
     await db_session.commit()
     yield
 
@@ -782,6 +785,100 @@ async def test_kang_copies_replied_sticker(client, db_session):
     assert row is not None
 
 
+@pytest.mark.asyncio
+async def test_gifer_requires_a_replied_animation(client):
+    resp = await client.post(
+        "/telegram/webhook", params=RELAY_HEADERS,
+        json={"chat_id": "g1", "text": "/gifer", "from_id": "g1", "chat_type": "private"},
+    )
+    assert resp.status_code == 200
+    body = resp.json()
+    assert "reply to a gif" in body["messages"][0]["text"].lower()
+
+
+@pytest.mark.asyncio
+async def test_gifer_converts_and_creates_sticker(client, db_session, monkeypatch):
+    from notify import gif_sticker
+
+    async def fake_convert(gif_bytes):
+        assert gif_bytes == b"raw gif bytes"
+        return b"FAKEWEBMBYTES"
+
+    monkeypatch.setattr(gif_sticker, "convert_gif_to_webm_sticker", fake_convert)
+
+    b64 = base64.b64encode(b"raw gif bytes").decode()
+    resp = await client.post(
+        "/telegram/webhook", params=RELAY_HEADERS,
+        json={
+            "chat_id": "g2", "text": "/gifer", "from_id": "g2", "chat_type": "private",
+            "replied_animation_file_b64": b64,
+        },
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert len(body.get("sticker_creates", [])) == 1
+    created = body["sticker_creates"][0]
+    assert created["sticker_format"] == "video"
+    assert "sticker.webm?token=" in created["sticker_url"]
+
+    row = await db_session.get(TelegramStickerSet, "g2")
+    assert row is not None
+
+    from db.models import TelegramConvertedSticker
+    all_rows = (await db_session.execute(select(TelegramConvertedSticker))).scalars().all()
+    assert len(all_rows) == 1
+    assert all_rows[0].webm_bytes == b"FAKEWEBMBYTES"
+
+
+@pytest.mark.asyncio
+async def test_gifer_adds_to_an_existing_pack(client, db_session, monkeypatch):
+    from notify import gif_sticker
+
+    db_session.add(TelegramStickerSet(from_id="g3", set_name="pulsar_u3_by_bot"))
+    await db_session.commit()
+
+    async def fake_convert(gif_bytes):
+        return b"FAKEWEBMBYTES"
+
+    monkeypatch.setattr(gif_sticker, "convert_gif_to_webm_sticker", fake_convert)
+
+    b64 = base64.b64encode(b"raw gif bytes").decode()
+    resp = await client.post(
+        "/telegram/webhook", params=RELAY_HEADERS,
+        json={
+            "chat_id": "g3", "text": "/gifer", "from_id": "g3", "chat_type": "private",
+            "replied_animation_file_b64": b64,
+        },
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert len(body.get("sticker_adds", [])) == 1
+    assert body["sticker_adds"][0]["set_name"] == "pulsar_u3_by_bot"
+
+
+@pytest.mark.asyncio
+async def test_gifer_reports_failure_when_conversion_never_fits(client, monkeypatch):
+    from notify import gif_sticker
+
+    async def fake_convert(gif_bytes):
+        return None
+
+    monkeypatch.setattr(gif_sticker, "convert_gif_to_webm_sticker", fake_convert)
+
+    b64 = base64.b64encode(b"raw gif bytes").decode()
+    resp = await client.post(
+        "/telegram/webhook", params=RELAY_HEADERS,
+        json={
+            "chat_id": "g4", "text": "/gifer", "from_id": "g4", "chat_type": "private",
+            "replied_animation_file_b64": b64,
+        },
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body.get("sticker_creates", []) == []
+    assert "couldn't convert" in body["messages"][0]["text"].lower()
+
+
 @pytest.mark.asyncio
 async def test_space_queues_photo(client, monkeypatch):
     from notify import space

cloudflare/telegram-relay-worker.js

@@ -109,6 +109,18 @@ export default {
     const isPhotoMessage = !!(message && Array.isArray(message.photo) && message.photo.length > 0);
     const isMediaMessage = isVoiceMessage || isDocumentMessage || isPhotoMessage;
 
+    // /gifer replies to an earlier GIF (Telegram's `animation` message
+    // type) rather than attaching one to the current message — unlike
+    // voice/document/photo above, THIS message is plain command text, so
+    // this doesn't fold into isMediaMessage. Gated on the command name so
+    // an unrelated reply to a GIF doesn't trigger an expensive download
+    // for nothing.
+    const repliedAnimation = message?.reply_to_message?.animation;
+    const isGiferCommand = !!(
+      repliedAnimation && typeof message.text === "string" &&
+      message.text.trim().split(/\s+/)[0].split("@")[0].toLowerCase() === "/gifer"
+    );
+
     // Ignore anything that isn't a plain text message, an analyzable
     // voice/document/photo, or a tapped inline-keyboard button
     // (channel_post, other unsupported content, etc.) — the backend's
@@ -122,6 +134,20 @@ export default {
     let voiceFileB64 = null;
     let documentFileB64 = null;
     let photoFileB64 = null;
+    let animationFileB64 = null;
+    if (!callbackQuery && isGiferCommand) {
+      const result = await fetchTelegramFileAsBase64(env, repliedAnimation.file_id);
+      if (result === "TOO_LARGE") {
+        await sendTelegramMessage(env, {
+          chat_id: String(message.chat.id),
+          text: escapeMarkdownV2(
+            `That GIF's too large for me to process right now (over ${Math.round(MAX_MEDIA_BYTES / (1024 * 1024))} MB) — try a shorter one.`
+          ),
+        });
+        return new Response("ok", { status: 200 });
+      }
+      if (result) animationFileB64 = result;
+    }
     if (!callbackQuery && isMediaMessage) {
       // Telegram only gives a file_id in the update. The backend CANNOT
       // resolve/download this itself — HF Spaces' free tier reliably
@@ -210,6 +236,10 @@ export default {
           // above). Lets "@PulsarBot what does this mean?" as a reply to
           // someone else's message actually see what "this" refers to.
           replied_message_text: message.reply_to_message?.text || message.reply_to_message?.caption || null,
+          // Set only for /gifer replying to a GIF — see isGiferCommand
+          // above. Already-downloaded bytes, same reasoning as
+          // voice/document/photo: the backend can't fetch this itself.
+          replied_animation_file_b64: animationFileB64,
         };
 
     const forwardToBackend = async () => {
@@ -459,6 +489,33 @@ async function drainOutbox(env) {
   await Promise.all(stickerAdds.map((s) => addStickerToSet(env, s)));
 }
 
+// Telegram: "Animated and video stickers can't be uploaded via HTTP URL"
+// (confirmed against the Bot API's InputSticker docs) — unlike static
+// stickers, which Telegram fetches directly from sticker_url the same
+// way sendPhoto/sendAudio do here. Only applies when sticker_url is
+// actually a URL we're pointing Telegram at — copy_sticker_to_pack's
+// file_id passthrough (an existing Telegram file, any format) was never
+// a URL fetch to begin with, so it's unaffected either way.
+function needsMultipartUpload(sticker_url, sticker_format) {
+  return (sticker_format === "video" || sticker_format === "animated") && /^https?:\/\//i.test(sticker_url || "");
+}
+
+/** Fetches the sticker bytes ourselves (from our own backend — see
+ * GET /telegram/sticker.webm, main.py) so they can be re-uploaded to
+ * Telegram as multipart/form-data instead of just handed over as a URL. */
+async function fetchStickerBytes(url) {
+  const resp = await fetch(url);
+  if (!resp.ok) throw new Error(`sticker source fetch failed: ${resp.status}`);
+  return await resp.arrayBuffer();
+}
+
+function buildStickerUploadForm(baseFields, sticker_url, emoji, sticker_format, bytes) {
+  const form = new FormData();
+  for (const [key, value] of Object.entries(baseFields)) form.append(key, String(value));
+  form.append("sticker0", new Blob([bytes], { type: sticker_format === "video" ? "video/webm" : "application/x-tgsticker" }), "sticker0");
+  return form;
+}
+
 async function createStickerSet(env, { chat_id, from_id, set_name, title, sticker_url, emoji, sticker_format }) {
   try {
     // `sticker` as a URL string OR an existing file_id — both work
@@ -469,16 +526,29 @@ async function createStickerSet(env, { chat_id, from_id, set_name, title, sticke
     // sticker actually is — only ANIMATED (TGS) or VIDEO (WEBM) originals
     // need that declared correctly, a mismatch here is what Telegram
     // would reject the request over.
-    const resp = await fetch(`https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/createNewStickerSet`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        user_id: from_id,
-        name: set_name,
-        title,
-        stickers: [{ sticker: sticker_url, format: sticker_format || "static", emoji_list: [emoji] }],
-      }),
-    });
+    let resp;
+    if (needsMultipartUpload(sticker_url, sticker_format)) {
+      const bytes = await fetchStickerBytes(sticker_url);
+      const form = buildStickerUploadForm(
+        {
+          user_id: from_id, name: set_name, title,
+          stickers: JSON.stringify([{ sticker: "attach://sticker0", format: sticker_format, emoji_list: [emoji] }]),
+        },
+        sticker_url, emoji, sticker_format, bytes,
+      );
+      resp = await fetch(`https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/createNewStickerSet`, { method: "POST", body: form });
+    } else {
+      resp = await fetch(`https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/createNewStickerSet`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          user_id: from_id,
+          name: set_name,
+          title,
+          stickers: [{ sticker: sticker_url, format: sticker_format || "static", emoji_list: [emoji] }],
+        }),
+      });
+    }
     if (!resp.ok) {
       console.error("createNewStickerSet failed:", chat_id, set_name, resp.status, await resp.text());
       return;
@@ -501,15 +571,28 @@ async function createStickerSet(env, { chat_id, from_id, set_name, title, sticke
 
 async function addStickerToSet(env, { chat_id, from_id, set_name, title, sticker_url, emoji, sticker_format }) {
   try {
-    const resp = await fetch(`https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/addStickerToSet`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        user_id: from_id,
-        name: set_name,
-        sticker: { sticker: sticker_url, format: sticker_format || "static", emoji_list: [emoji] },
-      }),
-    });
+    let resp;
+    if (needsMultipartUpload(sticker_url, sticker_format)) {
+      const bytes = await fetchStickerBytes(sticker_url);
+      const form = buildStickerUploadForm(
+        {
+          user_id: from_id, name: set_name,
+          sticker: JSON.stringify({ sticker: "attach://sticker0", format: sticker_format, emoji_list: [emoji] }),
+        },
+        sticker_url, emoji, sticker_format, bytes,
+      );
+      resp = await fetch(`https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/addStickerToSet`, { method: "POST", body: form });
+    } else {
+      resp = await fetch(`https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/addStickerToSet`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          user_id: from_id,
+          name: set_name,
+          sticker: { sticker: sticker_url, format: sticker_format || "static", emoji_list: [emoji] },
+        }),
+      });
+    }
     if (resp.ok) {
       // Same visibility gap as createStickerSet above — an added sticker
       // is otherwise silent, and if the user hasn't added the pack yet