HailMe Platform docsOpen cabinet →

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

Project checkboxes reveal configuration or preparation steps. They never turn these readiness statements into delivery permission.

OTP convergence

The mobile backend retains the released phone-auth API, user accounts and sessions. New HailMe phone challenges now use the platform's first-party LIVE v2 service: platform-generated ordinary SMS codes, or the existing Twilio Verify service for applicable US traffic. The old implementation and provider settings remain available for rollback and for challenges created before the switch. Cooldowns, Android SMS Retriever formatting, country rules, reviewer access, response DTOs, attempts and expiry remain compatible. The operator runbook is `docs/platform/hailme-phone-otp.md` in the repository.

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.

The compatibility rollout used old-mobile HTTP contracts against cloud TEST/FAKE, isolated database copy rehearsals, encrypted backups, a closed LIVE release, credential-isolation checks without sends, and explicit owner approval before switching new challenges. A separately approved one-SMS acceptance then confirmed delivery and sign-in from installed HailMe 1.3.3. Keep the legacy implementation and provider settings for explicit rollback. No mobile user table is copied into the platform. The cabinet's own email OTP uses its internal system-delivery path, without an HTTP call back into its own login service.

The earlier `/v1/hailme/phone-otp/challenges` bridge remains isolated TEST/FAKE and accepts synthetic subjects only. It does not become a real provider route. The separately scoped `/v1/hailme/phone-otp/v2/challenges` service owns durable LIVE challenges and provider attempts, with a five-minute lifetime/cooldown and ten admissions per phone per hour. The backend preserves challenge ownership and ambiguous create/check IDs in Redis. A separate TEST observer may read fake codes; no LIVE key may have that scope.

Production selects `HAILME_PHONE_OTP_MODE=PLATFORM`, audience `ALL`, and a dedicated LIVE read/write key for HailMe only. Daily/monthly caps are 1000/30000. Existing users and sessions stay in the mobile system. Commercial multi-channel OTP remains a separate implementation plan; email, Telegram, WhatsApp and Signal OTP are not enabled by this phone cutover. The separate Gateway pilot does not add a Telegram choice to an old mobile version or enable new countries.

WhatsApp

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.

The protocol module sends approved utility and copy-code authentication template payloads to a fixed Graph API host, sanitizes errors, never retries an ambiguous send, and authenticates status callbacks over the original bytes. It is packaged but not constructed by TEST/FAKE runtime composition. The WhatsApp guide documents the accepted simulation and remaining work: encrypted per-project credentials, durable claims and callback persistence, template synchronization, admission, limits, cost snapshots and operator rollback. The checkbox reveals requirements; it does not collect a token, register a number or authorize delivery.

Official sources: Meta developer hub, Cloud API documentation.

Telegram

For ordinary phone verification use Telegram Gateway, with explicit recipient choice. It delivers to Telegram's Verification Codes chat and requires no bot invitation or pre-binding. The bot adapter below serves opt-in notifications; it is not the phone OTP route.

The TEST/FAKE lab and BYOC adapter are implemented; follow the Telegram guide. Bot identities and webhooks are configured for the isolated own-bot pilot and HailMe's production control plane. Global production outbound remains disabled. The requirements below apply before broader customer delivery or Telegram OTP activation.

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 bot adapter supports transactional text; ordinary phone OTP uses the separate Gateway 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.

Telegram has a separate integration guide. It covers synthetic opt-in, templates, common API, budgets, fee waivers, journal and rollback. A configured real bot or healthy webhook is not a grant of production outbound or OTP permission.

RCS staging laboratory

RCS TEST/FAKE supports synthetic service notifications and verification, project budgets, fee exemptions and the common journal. Google approval and a real provider implementation are separate future gates. No real RCS delivery is enabled.