Team Chat dead-letter recovery (retry a scheduled message that never sent)
Open Scheduled. Anything that never sent is listed at the top as Not sent: <reason>, with a Retry that puts it back in the queue.
On this page
What it is
When a scheduled Team Chat message cannot be delivered it is parked in the channel's dead-letter collection (scheduledMessagesDeadLetter) instead of vanishing. Three things park a message this way: the channel, workspace or your membership is gone or your account was disabled (channel-gone / not-member / workspace-deleted / author-disabled), the scheduler could not read the queued message (invalid-shape / non-instant-deliverAt), or the delivery task exhausted its retries (delivery-failed, the code the list reports for a doc that carries no dropReason).
Each of those used to look exactly like a delivered message: the queued item simply left the list, so you could not tell "sent" from "never sent". The Scheduled view now lists your own parked messages above the pending ones, with the reason, the text, the conversation and the original delivery time. Retry re-files the message into the live queue with a fresh retry budget, and the row disappears once the re-file succeeds.
Where to find it
Open Team Chat and switch the panel to Scheduled (the auxiliary view, not a channel). Parked messages appear in a section above the pending list whenever you have any, and the section stays out of the way when you have none. The list covers every workspace you belong to, so a row from another workspace can name its conversation by id rather than by name.
How it behaves
What you see
- Not sent: <reason> in place of a delivery time, so a message that never left is never mistaken for one that did.
- A notification on your devices the moment it is parked, titled Scheduled message not sent, naming the reason in plain words ("you can no longer post there", "the conversation no longer exists"). It reaches you even if you never open the Scheduled view, and the same reason is stored on the parked row as
state: 'not-sent'withreasonText, so the app and any client show the same sentence. The notice is pushed once per parked message, so a retry that parks it again does not notify you twice. - The channel or DM name and the time it was due, then the message text.
- A Retry sending button per row. While one retry runs the button shows a spinner and the other rows wait; if the re-file fails the row says so and you can try again.
- If the check itself fails (for example the callable cannot be reached), the view shows its own inline message with a Retry, and the pending list is unaffected.
How the re-file works (server side)
refileDeadLetteredScheduled (shared by the two entry points) is the whole recovery path:
- Validates the channel path (
{root}/channels/{channelId}). - Checks you are still an active org/workspace member. An account whose owner or admin role holds on both its sign-in token and its user record is exempt, because it need not belong to the org whose backlog it recovers. A workspace role alone is not enough — workspace roles are local to that workspace and never travel on the token.
- Refuses a re-file into a soft-deleted workspace during the 30-day undo window. The Admin SDK bypasses the rules' own check, so the gate re-reads the root: it refuses only a present root stamped
deletedAt. An org root carries nodeletedAt, and a hard-gone root falls through to the not-found answer. - Reads the dead-letter doc inside a Firestore transaction, validates its shape, and checks you are the author — that same account may re-file anyone's message, so an administrator can clear a backlog for people who cannot.
- Atomically moves it back to
{channelPath}/scheduledMessages/{id}; the new doc re-arms a fresh delivery task, which brings its own retry budget.
The re-file only delivers while scheduled send is running. If the scheduled-send pause switch is on, the message goes back to the live queue but no delivery task is armed for it, so it waits — silently — until someone re-arms it after turning the switch back off. Check that switch before you tell anyone their message is on its way.
The re-filed doc carries exactly the field set a client-created scheduled message has — status: 'pending' and no deliveryAttempts. The retry budget is the Cloud Task's own retryCount, never a counter on the doc.
The move is atomic (set + delete in one transaction) and idempotent: a retry of a re-file whose response was lost answers the first call's outcome instead of a 404. The relay answers { ok: true, id, created, channelId } with HTTP 201 when a new scheduled message was created and 200 with created: false when the message was already back in the queue; the callable answers the same payload without ok and without an HTTP status, since a callable has neither. The relay additionally spends one slot from the caller's per-uid daily re-file allowance and answers 429 with Retry-After once it is gone; a slot it claimed is refunded unless the message was really created, so a replay and a refused attempt are both free, and only a real create writes the operator audit row. Two entry points reach it, both gated the same way:
| Entry point | Transport | Who calls it |
|---|---|---|
teamChatRefileScheduledSend |
HTTPS relay, bearer ID token (POST /t/team-chat-refile-scheduled-send with { channelPath, deadLetterId }) |
CLI / automation, and administrator backlogs. The only road with an administrator path; an administrator re-file of another author's message leaves an audit row. |
teamChatRefileMyDeadLetteredScheduled |
Firebase callable | The app's Retry button. Author only: it never takes the operator path. |
The callable exists because the app's Content-Security-Policy only allows the callable origin (*.cloudfunctions.net), not the /t/ Hosting rewrite, so the renderer cannot reach the relay directly.
Listing your own parked messages
teamChatListMyDeadLetteredScheduled (callable) queries collectionGroup('scheduledMessagesDeadLetter').where('authorUid', '==', <your uid from the verified token>), capped at 50, soonest-due first. The uid always comes from the request's auth token, never from the request body, so a caller cannot ask for someone else's parked messages. The collection-group index this needs already ships in firebase/firestore.indexes.json.
Each item is { channelPath, channelId, id, text, deliverAt, reason }. The raw delivery error text is deliberately NOT returned: the app renders a humanized sentence per reason code, so internal Firestore messages never reach the UI.
Security model
- Firebase ID token auth; author scoping from the token's uid.
- Disabled-account gate on both callables and the relay.
- Membership, soft-delete, author and shape gates as described above, with one exemption: an account whose role is owner or admin may re-file any author's message and is not required to belong to the org. That exemption is the whole of the elevated path — it is not a separate service account, and no other role reaches it.
- A re-file arms a delivery task only while scheduled send is running; see the pause-switch note above.
- Channel path shape validation (
{root}/channels/{channelId}only).
Related
- team-chat.md — the messaging surface the re-file serves.
- Team Chat history export — the other planned Team Chat capability.
Last verified 2026-11-15