rclabs · lab notebookentry Nº 008

Lights from Telegram, through Alexa

Objective
A private Telegram bot on a Cloudflare Worker that switches my home lights. Alexa has no public API for that, so the bot fires Voice Monkey routine triggers and Alexa Routines do the switching.
Date
· 4 min read
Apparatus
cloudflareworkerstelegramalexahomeshipped
Observer
RC · Berlin

Atom Home is a small Worker I run for myself. There is no public demo, because the only thing it does is turn my lights on and off.

My lights are already in the Alexa app: bedroom, work and kitchen. I wanted to switch them from Telegram, from anywhere, without opening the Alexa app or talking to an Echo. The catch is that Amazon has no public API that lets an outside program switch an Alexa smart-home device. Anything that claims to does it by logging in with your Amazon password, which I did not want to depend on.

The path

What Alexa does allow is a routine that starts when a smart-home device changes state. Voice Monkey is an Alexa skill that gives you virtual “routine trigger” devices and an HTTP API to fire them. So the bot never touches a light. It fires a trigger, and a routine I made in the Alexa app does the rest.

 Telegram (my phone)
      |
      |  HTTPS webhook + secret-token header
      v
 Cloudflare Worker  (home.rclabs.in/tg/webhook)
      |  - checks the secret header, else 403
      |  - owner lock: one chat id, everyone else ignored
      |  - device names -> trigger ids in Workers KV
      |
      |  POST /trigger  (Voice Monkey v3 API)
      v
 Voice Monkey virtual trigger device
      |
      |  "When this happens: Smart Home -> Alexa Voice Monkey v3 -> <trigger>"
      v
 Alexa Routine
      |
      v
 the actual lights

The Worker is about 200 lines of plain JavaScript with no dependencies. It has one KV namespace for the saved triggers and the owner, the Workers AI binding, and three secrets: the Telegram bot token, the Voice Monkey token and the webhook secret. None of those are in the code or the repo.

Who gets to talk to it

A Telegram bot is public by default. Anyone who finds its username can message it. Two checks keep this one private.

The first is at the door. When I register the webhook I give Telegram a secret, and Telegram sends it back on every call in a header. The Worker compares it before it reads the body:

if (req.headers.get("X-Telegram-Bot-Api-Secret-Token") !== env.WEBHOOK_SECRET) {
  return new Response("forbidden", { status: 403 });
}

The second is the owner lock. Before I set the webhook, I sent the bot /start and read it once with getUpdates. That gave me my own chat id, which went into KV as the owner. Only after that did I register the webhook. Every update from any other chat returns early with no reply, so a stranger gets silence rather than an error that confirms the bot exists. The Worker always answers Telegram with a 200 so a failure on my side doesn’t turn into a retry loop.

Scenes, not toggles

Voice Monkey’s free plan gives three routine triggers. An Alexa routine also can’t toggle. Each one does one fixed thing when it fires. So instead of “bedroom on” and “bedroom off” for three rooms (six triggers), I made three scenes:

  • All Lights On
  • All Lights Off
  • Work Mode: work light on, bedroom and kitchen off

Each scene is one trigger in Voice Monkey and one routine in the Alexa app. The routines have to be made by hand in the app; Amazon gives no way to create them from outside.

The bot

The commands are short:

  • /add <name> <device-id> saves a trigger under a name
  • /remove <name> deletes it
  • /list shows saved triggers as inline buttons
  • /run <name> fires one
  • /vmdevices lists the trigger devices on the Voice Monkey account
  • /help

Typing the exact name, like work mode, runs it. For anything looser, like “switch everything off”, a free Workers AI model (@cf/meta/llama-3.1-8b-instruct) is asked to pick one saved name or say NONE. Its answer must match a saved name exactly, and even then it never fires anything. It only replies “Did you mean all lights off?” with a Run button. A wrong guess costs one tap, not a dark kitchen.

const ans = norm(out.response);
pick = names.find((n) => n === ans) || null;   // must be a saved name
// then: "Did you mean <pick>?" with a ▶️ Run button

Firing a trigger is one POST to Voice Monkey with the token and the device id. Its error codes (unknown device, bad token, throttled, quota used) are mapped to plain sentences so the bot tells me what went wrong instead of a status number.

What broke

Error 1010 on the webhook. rclabs.in has Browser Integrity Check on. Telegram’s webhook calls don’t look like a browser, so Cloudflare blocked them with error 1010 before they ever reached the Worker. The fix is one rule that turns Browser Integrity Check off for /tg/webhook only. The rest of the zone keeps it, and that path is still guarded by the secret header.

A mangled token. On the first deploy one of the secrets went in damaged, so the Worker had the right shape and the wrong token. I re-set the secrets through the Cloudflare secrets API and tested the bot end to end again rather than trusting the deploy output.

Toggles that aren’t. I first thought in terms of “lights on” and “lights off” per room. That plan didn’t survive the three-trigger limit and the no-toggle routines. Scenes fit both.

What stuck

Use the door the vendor left open. There’s no API for switching Alexa devices, but routines with smart-home triggers are a supported feature. Building on that is slower to set up and much less likely to break than scraping a login.

Lock first, then open. Capturing the owner chat before the webhook existed meant there was never a window where a stranger’s message reached the handler.

Let the model suggest, not act. A small free model is good enough to map “kill the lights” to a name. It’s not good enough to be trusted with the switch, so it isn’t.

Recorded byRCBerlin · 10 Oct 2026
Witnessed byyou, just nowquestions or corrections: rcsekar.v3@gmail.com