Telegram Targets for CAP Alerts in multi-channel-relay

This multi-channel-relay slice adds a Telegram downstream target for relayed CAP messages.

This is a deliberately small capability. It does not make Telegram an alerting authority, and it does not change the CAP message into the source of truth. The relay still accepts a structured CAP alert, preserves the accepted alert state, and then delivers a concise notification to the configured target. Telegram is one possible last-mile destination for teams, test channels, or operational groups that already use it.

The useful question for this change was narrower:

Can a CAP-producing or CAP-adjacent workflow publish one accepted alert into a context, preserve the CAP object, and also send a human-readable summary into a Telegram channel with an auditable delivery record?

The current answer is yes.

What changed

multi-channel-relay already had the shape needed for this: contexts, targets, target-level filters, asynchronous delivery jobs, and delivery receipts. The Telegram work adds another target kind to that model rather than creating a separate notification path.

The target is configured inside a relay context. In the current implementation it is a TELEGRAM_POST target using the platform API delivery mechanism. The target owns the Telegram destination configuration, while the context continues to own the operational boundary: which publisher can submit alerts, which targets are enabled, and where delivery history is inspected.

The message sent to Telegram is intentionally a summary, not the whole CAP XML. It is derived from CAP fields that are useful to a person scanning a channel:

• event
• severity
• urgency
• certainty
• area text
• expiry time
• preserved CAP URL, when one is available

That keeps the Telegram message readable while leaving the CAP object available for downstream systems and for audit.

Why this belongs in the target model

Telegram delivery is not special from the relay’s point of view. It is another downstream destination considered from the same accepted alert state.

That matters because the same CAP alert may need several outcomes:

• preserve the CAP XML to object storage
• publish an Atom or RSS feed entry
• post a notification into a team channel
• call a webhook for a workflow system
• skip one target when the configured filter does not match

Putting Telegram in the same target model means the operator can reason about it alongside the other destinations. A context can publish every accepted alert to a feed while sending only selected alerts to a more interruptive channel. It also means Telegram delivery can share the same operational diagnostics as other targets.

Delivery receipts

The context alert view now shows the accepted alert, CAP Store state, and target delivery state together.

That combined view is important. If a Telegram message is missing, the operator should not have to infer what happened from the downstream application. They need to see whether the relay accepted the alert, whether CAP preservation succeeded, whether the Telegram target was selected, and whether the downstream delivery was recorded as delivered, skipped, failed, or pending.

This is the part that makes the feature more than a bot integration. The relay is preserving the audit trail around the delivery attempt: which alert was accepted, when it was stored, which target was considered, and when that target accepted the delivery.

A guidance-feed test case

The screenshots use the guidance context. In that test setup, flood-hub-guidance-feed generates CAP from flash-flood guidance changes and publishes those CAP messages to multi-channel-relay.

That is a useful test case because it exercises the whole path:

1. Generate a CAP message from a guidance event.
2. Publish it to the relay with context-scoped machine credentials.
3. Preserve the CAP XML through CAP Store.
4. Publish a feed target for machine-readable downstream consumption.
5. Send a Telegram summary for human inspection.
6. Confirm the result through target-level delivery receipts.

The test should still be read with the same caveat as the guidance-feed work itself. This is not a claim that the upstream guidance has become an authoritative public warning feed. It is a controlled implementation test of CAP-shaped processing, preservation, relay delivery, and operator audit.

What remains cautious

Telegram is useful for visibility, but it should be treated carefully in emergency alerting workflows.

The relay currently sends a concise backend-rendered message. That is a good first version because the wording path is controlled and inspectable. It is not yet a full notification policy system. There is still work to do around message variants, localisation, rate limits, error presentation, retry behaviour, target filtering, and the operational rules for deciding which alerts should reach interruption-heavy channels.

There is also a governance question. Many organisations can benefit from relaying CAP messages into team tools, but the boundary between internal situational awareness and public alerting must remain clear. Telegram delivery should carry the provenance of the accepted CAP alert and link back to the preserved CAP object wherever possible.

Why it is useful now

The immediate value is practical observability.

An implementation partner can now publish a CAP message once and inspect three views of the result: the preserved CAP URL, the feed output, and the Telegram notification. If one of those downstream paths fails, the context alert history gives a place to start the investigation.

That is the direction multi-channel-relay is taking: not one bespoke integration per channel, but a context-owned relay for CAP messages where targets, filters, delivery mechanisms, and receipts are visible together.