registration and publication

application fields

application IDs are opaque stable strings. the display name is not an account username and cannot claim the official system identity. names and descriptions use existing text-safety checks. developers retain user-authored capitalization. one verified human account owns each application in v1; team ownership and transfers are outside v1.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25{
  "id": "app_example",
  "name": "Helpful bot",
  "description": "A private helper.",
  "icon_asset_id": "asset_example",
  "owner_id": "user_developer",
  "support_url": "https://example.org/support",
  "privacy_url": "https://example.org/privacy",
  "visibility": "private",
  "status": "draft",
  "revision": "1",
  "published_revision": null,
  "install_policy": "either",
  "permissions": {
    "commands": "required",
    "bot.messages.ephemeral": "required"
  },
  "bot_user_id": "bot_example",
  "banner_asset_id": null,
  "enabled": true,
  "commands": [],
  "install_url": null,
  "created_at": "2026-10-20T07:00:00Z",
  "updated_at": "2026-10-20T07:00:00Z"
}

configuration and validation

permissions accept only disabled, optional or required; omission means disabled. install_policy is account, either or chat. invalid keys, incompatible required dependencies, duplicate commands or missing publication fields reject the whole draft with field errors. avatar uploads use the existing image-validation rules. tokens are shown only when created. a bot token can register commands but cannot change permissions, visibility, invite lists or install policy; those changes require the owner’s dashboard session.

publishing a revision

publish atomically freezes the name/icon metadata, commands, install policy and permission request at an immutable revision. publication runs validation but no admin approval, submission or review queue. the stable install link resolves the latest published revision on sometimes. the authorization screen binds its confirmation to that exact revision; concurrent publication returns configuration_changed and refreshes the screen before consent. uploaded executable packages are not part of this hosting model.

drafts, unpublishing and disabling

saving a draft does not affect published installations. unpublish removes new installation access and keeps existing approved revisions running. disable stops all runtime operations, disconnects event/media sessions and hides commands immediately; enabling resumes only installations whose user, scope and private eligibility remain valid. delete is irreversible after dashboard confirmation, revokes credentials and installations and tombstones bot attribution on existing public content. suspension or deletion of the developer also disables the application. uninstall removes private bot state and credentials for that installation but preserves ordinary messages and immutable provenance; it never deletes user-authored chat content as a side effect.

private bots

private installation requires the owner or an invite-list account ID at both prompt display and consent commit. resolve a typed handle to an account before saving so username changes do not transfer an invitation. removing an invite revokes that user’s installations immediately. switching public to private revokes installations for everyone outside the new invite list except the owner. eligibility loss uses the same revocation path as uninstall; adding someone back does not silently reinstall.

developer dashboard routes

these dashboard routes use the verified owner’s existing same-origin session and CSRF protection, never the bot token. writes require If-Match for the current application revision except initial creation. lists use the pagination contract. secret creation returns the token once; later reads expose only token metadata. use the dashboard to publish permissions, manage invites and rotate credentials; the bot token cannot perform these owner actions.

scroll the table horizontally to see all columns.