---
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=<opaque>`
- `.../startapp=offer&oid=<opaque>`
- `.../startapp=payment&pid=<opaque>`
- `.../startapp=dispute&did=<opaque>`
- `.../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.
