Telegram Pages
Understand Telegram account, channel and bot control records.
Telegram Pages can represent an account, channel or bot where control is established through the appropriate Telegram-native method. The backend reads the canonical identifier from authenticated provider data; typed handles are not accepted as ownership proof.
The telegram_account_score operation costs 5 credits and returns the score for that Telegram subject.
Redirect configuration
Telegram OpenID redirect URIs must match exactly, including www, scheme, path and trailing-slash behavior. Production and local development callback URLs must each be registered with the Telegram application when both environments are supported.
Public route
/tg-account/{handle}The readable handle is not the ownership anchor. The backend stores the provider-issued Telegram identifier and Page kind so authentication cannot create a second Page for the same canonical subject.
Account, channel and bot differences
| Kind | Required authority | What must not be assumed |
|---|---|---|
| Account | Telegram account authentication | Control of channels or bots owned by that account |
| Channel | Provider-native administrator proof | Ownership based only on a public channel username |
| Bot | Bot-control verification appropriate to the integration | Control based on knowing the bot username |
The Page labels the identity kind and verification method. If only account authentication is implemented, channel and bot registration remain unavailable rather than falling back to a typed handle.
Score operation
const response = await fetch('https://www.clawdbase.ai/api/clawdbase/operations/run', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CLAWDBASE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
operation: 'telegram_account_score',
subject: '@channel_name',
channel: 'api',
idempotency_key: 'telegram-channel-name-01',
}),
})The operation requires scores:read and costs 5 credits after eligible free calls. Its result belongs to the selected Telegram subject and never overwrites an associated Creator, Agent or Skill score.
Failure states
An incorrect redirect URI fails before Clawdbase receives authoritative identity data, so no Page should be created. Expired state, nonce mismatch, missing canonical ID and insufficient channel/bot authority also terminate the flow. Return the user to the registration or Console Pages surface with an actionable error and retry control.
See Telegram registration and Telegram integration for the full setup.