pass.holder_queued

When this fires

A holder tapped their invite link for a dated window that has not opened yet. Telegram holds the join request, and Subscriby records that they are queued — they will be admitted automatically the moment the window opens, whether or not they are at their phone.

This is the moment a buyer stops being a risk, and it is the one thing about a pass that a creator can still act on beforehand.

Bought is not the same as queued

A purchase and a queued request are different events with different follow-up. Someone who bought but never tapped is relying on noticing a message on the day; someone queued needs nothing at all. Everything in the product that nudges a pass holder — the reminder ladder, the creator's roll call, the manual Send Reminders button — targets the first group and skips the second.

Required ability

project-subscription:view — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "pass.holder_queued",
  "created_at": "2026-09-17T18:42:10Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
    "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
    "plan_kind": "pass",
    "window_id": "3d5a8c72-b016-4e94-8fa7-61c209d4e738",
    "source_plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
    "starts_at": "2026-09-20T13:00:00+00:00",
    "ends_at": "2026-09-21T03:00:00+00:00"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `pass.holder_queued` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	string UUID	Project this event belongs to.
`data.subscription_id`	string UUID	The purchase the queued request belongs to.
`data.subscriber_id`	string UUID	The project user who tapped.
`data.plan_id`	string UUID	The plan that was bought. On a series this is the series plan.
`data.plan_kind`	string	`pass` or `pass_series`. Tells you whether this is one purchase's only date or one leg of a season.
`data.window_id`	string UUID	The window they queued for.
`data.source_plan_id`	string UUID	The plan the window belongs to. Equal to `plan_id` on a pass; a source plan on a series.
`data.starts_at`	ISO 8601 timestamp	Window start, always UTC.
`data.ends_at`	ISO 8601 timestamp	Window end, always UTC.

Caveats

This fires per join request, not per purchase. A season-ticket holder queues separately for each of their dates, so one series purchase produces at least one of these per date they tap — often spread over weeks, because the link for the next date is sent in the message that ends the previous one. A plan with more than one Telegram resource produces one per resource they tap, all carrying the same window_id.
It does not fire when someone taps a link for a window that is already open. That is an immediate admission, not a queued request, and arrives as member.resource_added.
A holder who never taps produces no event at all. Absence is the signal — see pass.holder_missed for the other end of that.
Re-queuing does re-emit. The handler re-stamps join_requested_at and fires this event again on every chat_join_request it receives, so treat subscription_id + window_id as the idempotency key on your side.

pass.holder_missed — a holder whose window closed without them joining.
pass.window_opened — the moment held requests are approved.
member.resource_added — the per-resource grant that follows.
Pass events overview — back to family overview.