--- title: Task 5.1 Telegram Product Surface and Flow Map tags: [taskmaster, telegram, product, flow-map, canonical-state] created: 2026-05-24 status: draft --- # Task 5.1 Telegram Product Surface and Flow Map Source: `/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md` This map defines the first-release Telegram-native surface for Task 5.1 and keeps the financial core bound to the canonical [`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md) and Task 4 authorization/risk controls. ## 1) Channel split (first release) | Area | Bot messages | Mini App | Web/Admin-only (first release) | |---|---|---|---| | Discovery & onboarding | `/start`, `/help`, `/link`, `/settings` | Onboarding cards, link prompts, fallback CTA | Full self-serve onboarding docs | | Request browse/create | summary list + quick actions only | Full in-app list, create/edit request form | Full advanced catalog/search UI | | Offers | receive offer summary, accept/reject shortcuts | full offer list and detail, offer accept/reject | Seller negotiation detail with admin context | | Payment start | payment shortcut button + deep link payload | payment state UI + provider launch from in-app | Payment method setup, advanced failure handling | | Delivery evidence | status update nudges + evidence deep link | upload evidence from in-app flow | Full media manager + admin-side attachments | | Dispute | dispute open/summary + status check | open/respond/track dispute in app | Admin moderation, manual evidence review | | Release/Refund | only status blockers and support handoff | confirmation request + release/refund request | Execute actions through canonical payment API | | Notification settings | toggle on/off, blocked-state view | mirror of notification status and quiet mode | Full support/notification audit UI | | Support | support contact + report IDs | support request and context handoff | Admin/operator console and action audit | ## 2) Canonical state mapping (all actions) All Telegram actions must map to existing canonical states and API-side checks: - `PurchaseRequest.status`: `pending` → `received_offers` → `in_negotiation` → `payment` → `processing` → `delivery` → `delivered` → `confirming` → `completed` / `cancelled` - `Payment.escrowState`: `FUNDED` / `PARTIALLY_FUNDED` / `RELEASABLE` / `DISPUTED` / `RELEASING` / `RELEASED` / `REFUNDING` / `REFUNDED` / `FAILED` / `CANCELLED` - `Dispute.status`: `OPEN` / `UNDER_REVIEW` / `RESOLVED_*` / `CLOSED` as appropriate The only transitions that may modify funds, release eligibility, or dispute holds are those enforced by the canonical service layer from the [`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md). ## 3) Journey mapping by persona ### 3.1 Unauthenticated user - See bot start/help and public support command. - Any authenticated action routes to account-link flow. - No request write actions without auth link. ### 3.2 Unlinked Telegram user 1. Start in bot or Mini App. 2. Prompt account linking (`/link` equivalent) using signed callback token. 3. Complete account link or return to web flow. 4. After link success, deep link returns user to prior action context (request, offer, payment, or dispute). ### 3.3 Linked buyer - Browse/create requests, send offer review decision, start payment, upload delivery evidence, open disputes, monitor request state, request release/refund. - No direct fund release path: Telegram actions read state and submit intent only. ### 3.4 Linked seller - Receive offer and request notifications, update offer availability, review buyer disputes, upload shipping/proof artifacts. - No direct payout mutation from Telegram; actions remain canonical requests to existing payment/dispute endpoints. ### 3.5 Admin/support - Dedicated support context in admin view only (first release). - Telegram-origin IDs and linked wallet/payment provenance shown in existing admin interfaces. - Any manual override for Telegram-originated cases follows the same step-up/two-person policy as web flows when configured in [`Security Ownership and Launch Decision Criteria`](Security%20Ownership%20and%20Launch%20Decision%20Criteria.md). ## 4) Deep-link and context contract Deep-link entry points in order of priority: 1. `request` detail 2. `offer-review` (accept/reject) 3. `payment-start` 4. `dispute-open` / `dispute-track` 5. `delivery-evidence` 6. `account-link` Rules: - No raw IDs in clear URLs when not needed. - Use short opaque or signed context IDs. - Expire context tokens and bind to Telegram user + wallet/session. - Every context hit verifies canonical ownership/state before rendering any action. ### Example startapp routes (illustrative) - `.../startapp=request&rid=` - `.../startapp=offer&oid=` - `.../startapp=payment&pid=` - `.../startapp=dispute&did=` - `.../startapp=verify` ## 5) Release phasing | Phase | Telegram surface | Backend dependency | |---|---|---| | Phase 0 (MVP) | bot + limited Mini App for state-safe buyer/seller actions; no Telegram-only financial mutations | Payment and ledger gates already enforced | | Phase 1 | richer navigation, richer filters, deeper support surfaces | Identity linking + event fanout | | Phase 2 | admin operator actions in Telegram | Additional ops hardening and audit scope | ## 6) Acceptance traceability Directly mapped to PRD section "Task 1": - Buyer/seller/admin/support journeys and entry contexts documented: **yes** - Deep links and entry points defined with phase split: **yes** - Canonical API/state mapping in table + journey sections: **yes** - Non-native and admin surfaces identified: **yes** - Backward compatibility with existing web flows retained: **yes** ## 7) Open items for implementation 1. Finalize concrete deep-link payload schema (opaque token claim set). 2. Finalize Mini App navigation IDs and route-to-state matrix in frontend routing. 3. Confirm unsupported actions for `DISPUTED`/`FAILED` states at Telegram action layer.