Ping

Ping reads your message, takes the first link in it and downloads what is behind that link. Everything else is a word you can put anywhere in the same message, in any order, because it looks for the words rather than parsing a command.

A link on its own gives you the media. A tweet with a video gives you the video. A post with several photos comes back as one album instead of five separate messages. Add mp3 and you get audio.

Add card and you get a picture of the post instead of what was in it.

A card is a drawing of the post rather than a screenshot of one. Nothing opens a browser and nothing takes a picture of a screen.

For tweets, the text, the media, the counts and the date come from the endpoint that the official embed widget uses. It is public, so there is no login and no account involved. Instagram goes through gallery-dl, which does need your own cookies. TikTok goes through yt-dlp, which does not need anything.

The drawing itself is done by Satori. You give it a tree of elements with flexbox rules on them and it hands back an SVG. resvg turns that SVG into a PNG at twice the size, and the PNG is what arrives in the chat. Because it is a layout engine rather than a template, a long tweet and a short one both come out looking right.

A tweet is often only half of what is being shared, so the card draws the other half too.

If the tweet is a reply, the card puts the tweet it answers above it with the thread line running down the left, the way X shows it. If it quotes another post, the quoted post gets its own box inside the card. If it is a reply to a tweet that itself quotes something, all three appear in one picture, each one set in a narrower column than the one above so the nesting is easy to follow.

A still card of a video post is a still of a video, which is only half useful. Adding mp4 to a card message gives you an mp4 instead, where the clip plays inside the card while the header, the text, the likes and the caption stay put around it.

The awkward part is knowing where in the finished picture the video belongs, because that position depends on how the layout turned out. So the layout answers the question itself. Where the video should go, it puts a solid rectangle in one colour that nothing else in the card uses. Once Satori has produced the SVG, the code finds the rectangle with that fill and reads its position and size straight off it. Then ffmpeg scales the clip to that box, crops it to fit, and lays it over the still card for as long as the clip runs. The measurement is never done twice, so a card whose layout shifts cannot get a video in the wrong place.

One tweet can hold up to four videos: its own, its quote's, the one it replies to, and that tweet's quote. Ping plays the first one it finds, in that order. If you want a different one, say which: quote, parent or og.

Instagram cards are built the same way as tweets: header, media, actions, likes, caption, date, with the clip dropped into the media slot.

TikTok is built the other way round, because the video is the whole frame there and the interface sits on top of it. So the card is rendered on a transparent background, and ffmpeg puts the clip underneath it rather than inside it. The rail, the caption and the sound line end up over the video, which is where they are on TikTok.

The account is a real WhatsApp account, so it can see every chat the number is in. Two settings decide what it acts on.

PING_DMS covers direct messages, and is one of anyone, self for your own chat with yourself, or off. PING_GROUPS covers groups, and is one of mention, all or off. It ships on mention, which means the bot sits quietly in a group until someone tags it.

It also ignores anything sent before it started. WhatsApp delivers a backlog when a device reconnects, and without that check a restart would download every link from the last hour again.

WhatsApp links a device by QR code, which is easy on your laptop and annoying on a server. The first version printed the QR into the container logs, so relinking meant opening a shell on the box with a phone in the other hand.

Now the bot serves one page of its own. Set LINK_TOKEN to a secret and it listens on /link?token=..., giving the container a domain is enough to reach it. The page shows the current QR, refreshes itself every five seconds, and says “Linked” once the scan goes through. Without a token it serves nothing and falls back to the logs.

WhatsApp unlinks devices on its own sometimes. When that happens while the bot is running, it clears the dead session and goes back to showing a QR by itself, so relinking is opening a URL rather than redeploying anything. The one thing to get right is keeping the session folder on a volume, because a fresh container without it means pairing again after every deploy.

It needs Bun, yt-dlp, gallery-dl and ffmpeg on the machine, or the Docker image, which has all four in it already. Copy .env.sample, run the container, open the link page once, and it is yours.

Instagram needs your cookies to download anything, and YouTube asks for them too when the request comes from a datacentre address. There is a script that takes a cookies.txt export, throws away every line that is not Instagram or YouTube, and encodes what is left into the env file. Use a throwaway Google account for the YouTube half, because cookies used from a server IP can get an account flagged.

The repo is at github.com/echoeyecodes/wa-ping-downloader.