project.bot.status_changed

Fires on a transition, not on a schedule. Subscriby probes every project bot hourly; you get one event when the bot breaks and one when it recovers, never an event per probe.

When this fires

Fires when a project's bot transitions into or out of a degraded state — Telegram API failures, rate-limit, token revoked.

Required ability

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

Payload

{
  "id": "evt_01HX...",
  "type": "project.bot.status_changed",
  "created_at": "2026-05-18T10:05:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "bot_id": "5e93b1d7-4a20-4c68-8f51-9b0d27e6a34c",
    "status": "degraded",
    "reason": "telegram_api_unauthorized"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `project.bot.status_changed` 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.project_id`	string UUID	Mirrors top-level `project_id`.
`data.bot_id`	string UUID	bot identifier.
`data.status`	enum: `healthy` \| `degraded`	New health state.
`data.reason`	string	Short machine code describing the cause — one of `telegram_api_unauthorized`, `telegram_api_not_found`, `telegram_api_rate_limited`, `telegram_api_error`. Absent when transitioning back to `healthy`.

Caveats

A transport failure on our side (DNS, connect timeout) does not mark a bot degraded. Only an answer from Telegram that refuses the token counts, so a network incident here does not fire this event for every creator at once.
Health transitions are not the same as connect / disconnect. A degraded bot is still attached to the project; see project.bot.disconnected for explicit removal.

project.bot.connected — when a bot is first attached.
project.bot.disconnected — when a bot is removed.
Project events overview — back to family overview.