Rings, Telegram and the phone line

A ring is one visitor asking for one flat. This chapter follows it from the tap on the bell page to the door opening, and explains what happens when nobody answers.

How a ring flows

1. The checks. The door must be enabled and the flat must not be disabled or off this door's list. Then the rate limits: three rings per visitor per door in five minutes, one ring per flat every thirty seconds, twenty rings per door an hour (all adjustable in Settings). A refused ring gets a friendly page and a "Ring refused" line in the log.
2. Quiet hours. Inside the building's quiet hours (or when a resident has turned quiet hours on for the flat, and no resident has turned them off) a ring is refused with a polite page. A Deliveries ring is not refused: it becomes a message-only ring so the courier can leave a note.
3. The ring is created and the snapshot stored, if the visitor allowed the camera and no resident of the flat has turned snapshots off.
4. Telegram, at once. Every resident of the flat with a linked chat gets "Front door: someone is ringing Flat 12" (or "a delivery for", "a tradesperson for"), as a photo message when there is a snapshot, with two buttons: Open door and Not now.
5. The phone legs, at once. Every resident with a mobile and calls switched on gets a call leg. The PBX rings them all in parallel.
6. The visitor page shows Ringing with the countdown and follows the ring live (server-sent events, with a plain refresh as the fallback). Cancel ends the ring.

Answering by phone: keypress confirm

A leg that answers hears the whisper from Settings, by default "[building] [door] for flat [number]. Press 1 to talk, 2 to open the door, or hang up." Only a keypress counts as an answer:

• 1 bridges the visitor's audio to that phone: the ring shows Talking.
• 2 releases the door and ends the call: the ring shows Door open, "Opened by a resident of Flat 12" (the name is kept off the visitor's screen).
• Hanging up declines that leg only; the others keep ringing.

Voicemail, a divert and a switched-off phone all "answer" without pressing anything, so that leg is dropped after the confirm timeout (eight seconds by default) and the rest keep ringing. That is what makes the ordinary mobile a safe handset. The keypress must come from a leg that belongs to a resident of the rung flat; the dial code on its own never opens anything.

Answering on Telegram

Tapping Open door releases the door, marks the ring opened, and edits every resident's message to "Opened by Priya at 14:02". Not now declines. A tap from a chat that is not a resident of that flat is ignored and logged. A late tap on a ring that is already handled gets "Already handled".

First answer wins

Whichever leg or chat answers first decides the ring. Everyone else's call is cancelled and their Telegram message is updated. The ring records who answered and how (telegram, call, API) and the log gets a "Door opened" or "Not now" line with the resident's name.

No answer: messages left at the door

When the door's ring timeout passes (45 seconds by default) the ring becomes No answer, the Telegram messages are edited to say so, and the visitor gets the message form: a text box, or Record a voice message in the browser. The message is delivered to the residents on Telegram (a voice note when ffmpeg is installed on the server, otherwise an audio file) and by email, sits in the flat's bell log, and is kept for the audio retention period, seven days by default.

The phone line

A visitor who cannot scan calls the number on the poster, keys in the door's dial code and then the flat number. The PBX asks Doorcom to resolve that into a ring (POST /pbx/resolve), which creates a ring of kind "phone" for the same flat, with the same residents' legs, the same quiet hours and the same per-flat and per-door limits (the per-visitor limit does not apply, as there is no visitor cookie). Everything after that is the same as a scanned ring. When the caller hangs up without an answer the PBX can record a message and post it as audio, which is delivered like a web message.

Retention and privacy

• Snapshots and voice messages are purged after the days set in Settings (seven by default); issue photos after 365 days.
• A visitor is identified only by a hashed cookie-and-address key used for the rate limits; nothing else about them is kept.
• A visitor's page can only see its own ring; the URL of another ring shows nothing.
• Door pages send no-store and noindex headers.

Where to look when something is wrong

• Bell log in the panel: every ring, open, decline, timeout, message, refusal (with the reason: visitor, apartment or door limit, quiet hours) and test release. Filter by door, flat, kind and date; export CSV.
• Bell log, Calls (/log/calls): each phone leg with its result (ringing, no answer, busy, unconfirmed, declined, talked, opened), for checking trunk costs.
• The resident's own bell log in the portal.