Reference · the tools · timers
add_timer
Add a timer
What it does
Have the box post a message to a gateway topic at a time: repeating (cron, five fields: minute hour day-of-month month day-of-week -- "30 7 * * 1-5" is weekdays at 7:30) or once (at). With no tz, repeating times follow the person's current zone, so 9:00 stays 9:00 when they travel; name a tz to pin one to it. It posts and nothing else: a session subscribed to the topic does the work (subscribe_topic), so set that up too if nobody subscribes yet. "Brief me at 7:30 on weekdays" is cron "30 7 * * 1-5" to a topic like `briefing`. If it says no zone is known, ask the person and set it with time_zone. Missed while the box was down, it fires late within its catch-up (30 minutes by default) and otherwise skips that time.
What it needs to know
- topic
- The gateway topic it posts to.
- message
- What it posts: what the subscribed session should do or know.
- cron · optional
- Repeating: five-field cron.
- at · optional
- Once: "2026-10-22 15:00" in tz, or an ISO time with its offset.
- tz · optional
- An IANA zone to pin it to, e.g. America/Los_Angeles. Omit to use the person's current zone: a repeating timer keeps following it.
- name · optional
- What to call it: "morning briefing".
- catch_up_minutes · optional
- How late it may still fire after the box was down. Default 30.
- data · optional
- Optional JSON it posts alongside.
- box · optional
- Which box: its name and account, "home.frank" or "jordan.northwind", or just "home" when only one of your boxes is called that. Omit it for your current box (switch_box changes it; list_boxes says which it is).
- session_box · optional
- The box this session runs on, if it runs on one of yours: its name, as the on-box instructions give it ("frankh90.hemlane"). With it, a call that names no box is checked against your current box.
Where it lands
On one of your boxes: the one named in box, or your default box when none is named.