project.bot.status_changed

Dispatch site not yet wired. Subscribe an endpoint now and deliveries will land automatically once the firing site ships.

When this fires

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

Required ability

project:view-any — 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": "prj_01HX...",
  "data": {
    "project_id": "prj_01HX...",
    "bot_id": "bot_01HX...",
    "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 ULID	Project this event belongs to.
`data.project_id`	string ULID	Mirrors top-level `project_id`.
`data.bot_id`	string ULID	bot identifier.
`data.status`	enum: `healthy` \| `degraded`	New health state.
`data.reason`	string	Short machine code describing the cause; absent when transitioning back to `healthy`.

Caveats

DEFERRED — the dispatch site is not wired yet. The event is reserved so subscriptions taken now stay valid once it ships.
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.