Channels and the path to one platform
The target is one communications boundary: application backends ask HailMe Platform to deliver notifications and OTP. Provider secrets, rate limits, attempts, costs and delivery evidence belong to that boundary. User accounts, sessions and business authorization remain in the application.
What exists now
- SMS and push: implemented adapters and real first-party HailMe integration; external customer activation is separate. TEST uses FAKE.
- Platform cabinet email OTP: already generated and delivered inside the platform using its protected system sender.
- HailMe Verify: separate TEST/FAKE service for synthetic SMS/email, including limits, idempotency, billing and affiliation rules.
- Telegram: isolated TEST/FAKE lab; real BYOC supports an explicitly scoped one-message owner pilot; general delivery remains disabled.
- Application email and WhatsApp: preparation; no general customer transport is admitted yet.
- Signal: feasibility research; no supported business transport has been established.
Project checkboxes reveal configuration or preparation steps. They never turn these readiness statements into delivery permission.
OTP convergence
The existing HailMe phone OTP currently remains in the mobile backend. It has two paths: local generation/Redis verification for ordinary SMS, and Twilio Verify for applicable US traffic. Existing cooldowns, Android SMS Retriever formatting, country rules, reviewer access, response DTOs, attempts and expiry must survive migration.
Do not turn ordinary OTP into a delayed generic notification or silently replace Twilio Verify with an unregistered US SMS sender. Keep each challenge bound to its original verification owner for its whole TTL. Admission must check provider acceptance, ambiguity and idempotency before exposing success; an UNKNOWN delivery must not fall back and send a second code automatically.
Migration order: implement and test a platform-owned compatibility gateway for both legacy OTP paths; verify on isolated copies with old mobile contracts; prepare scope/config/limits and monitoring; perform one approved owner test; then switch new challenges while draining existing ones. Keep the legacy implementation and provider settings for explicit rollback. No mobile user table is copied into the platform. The platform cabinet's own email OTP must use an internal system-delivery path, without an HTTP call back into its own login service.
The HailMe phone compatibility gateway is now implemented for isolated TEST/FAKE: /v1/hailme/phone-otp/challenges. It reuses Verify billing, idempotency, expiry and fee policies; a dedicated profile preserves the mobile five-minute cooldown and ten-per-hour request cap. Only a first-party HailMe TEST service key and an HMAC-derived synthetic subject are accepted. The backend persists challenge ownership and ambiguous create/check operation IDs in Redis. A separate observer key reads the fake code for acceptance; the backend key cannot. Real phone destinations and LIVE execution are rejected.
Production deployment of this code is dark: HAILME_PHONE_OTP_MODE remains LEGACY and no TEST key is installed there. Actual US Twilio Verify and ordinary SMS transport cutover remains a separately validated LIVE extension; the current TWILIO_VERIFY profile simulates provider ownership and does not call Twilio. No mobile identity database or existing sessions are moved. See phone-otp-test.md for deployment and rollback.
Preferred first adapter: customer's own Meta WhatsApp Business Platform / Cloud API account. Prepare Business portfolio, WABA, sending-number ID, scoped access material and approved message templates. Authentication templates are relevant for OTP. Capture recipient consent and category/locale; preserve provider message IDs and signed callback deduplication. Customer-initiated windows and template rules must be checked against the pinned Meta API version at implementation, not assumed from SMS behavior.
Backend work before activation: encrypted per-project credentials, template synchronization/approval states, admission checks, callback verification, status mapping, rate/backoff policy, cost snapshots and no-duplicate handling after ambiguous acceptance. A checkbox currently shows this checklist; it does not collect a token or register a number.
Official sources: Meta developer hub, Cloud API documentation.
Telegram
Preferred first adapter: Bot API with one customer's bot identity per connection. The user must initiate/link a private chat before normal bot delivery. A phone number or a username is not a secure substitute for a bound chat ID. Use short-lived, single-use opaque linking tickets bound to an authenticated application user; do not include a service key or PII in the start link. Handle unlinking and blocks.
Authenticate webhooks with the documented secret-token header, deduplicate update_id and apply per-chat/global limits. Avoid logging bot-token-bearing API URLs. Do not enable paid broadcasts by default. Bot acceptance is not evidence that someone read the notification. The first adapter should support explicit transactional text only; OTP requires accepted recipient-binding and channel policy.
Official sources: Bot introduction, features and deep links, Bot API, limits.
Signal
No supported commercial bot/business API route has been established in this project. An unofficial bridge is not equivalent to an official delivery provider. Before implementing anything, decide the support model, account/device custody, permitted operation, recipient opt-in, operational reliability and recovery process. No Signal account, bridge or third-party binary is installed or linked here. Do not offer a delivery SLA or use Signal as an OTP fallback at this stage.
Primary reference: Signal documentation. This is a feasibility boundary, not a claim that the Signal cryptographic protocol is a hosted business API.
Common adapter contract
Every future channel must use the same project/environment scope, immutable operation ID, credential-version snapshot, budget admission, durable provider-attempt claim and UNKNOWN reconciliation. New channel names do not become accepted values in /v1/notifications until the complete admission, provider, journal, billing and SDK contract exists. Rejected unsupported channels must not create a wallet hold or provider call.
Provider receipts need authentication and deduplication. Templates, body text, recipients, coordinates, OTPs and secrets never enter diagnostic logs. Fake acceptance must be labelled FAKE. Affiliated fee policy applies to platform fees; third-party charges remain separate.