When a bot command needs to access a third-party service on behalf of a Telegram user — like reading their Gmail inbox or sending emails — it uses OAuth. AIBotBuilder gives you fine-grained control over two independent dimensions of every OAuth provider attached to a command.
This guide explains both dimensions in depth, walks through complete Gmail examples for every scenario, and shows you exactly how to configure them in the platform.
Before reading this guide, you should be familiar with:
Traditional OAuth setups only ask one question: "Which API permissions does this app need?" AIBotBuilder adds a second, equally important question: "Which Telegram users are allowed to connect their account?"
What can the command do?
Controls the API permissions requested when a user authorizes. A narrow scope limits what the command can access in the user's account.
Gmail Example
gmail.readonly — can read emails but not send or delete
Who can authenticate?
Controls which Telegram users are allowed to go through the OAuth flow and connect their third-party account to this command.
Gmail Example
owner_only — only the bot owner can link their Gmail
Consider a /check_inbox Gmail command on a public bot with 500 users:
gmail.readonly, so even if something goes wrong, no emails can be sent or deleted. But all 500 users can still connect.gmail.readonly and a whitelist of 10 team members. Now only those 10 people can authorize, and they can only read — not modify — emails. Maximum security.Token Scope determines the OAuth scopes (permissions) that are requested when a Telegram user clicks "Authorize". It controls what your command's code can actually do with the user's third-party account.
Request only the scopes your command needs. This is the most restrictive and most secure option.
When the user authorizes, the OAuth consent screen shows only the permissions your command actually uses. The resulting token is scoped to exactly those permissions — nothing more.
Gmail Example
A /check_inbox command configured with command_specific scope would request only https://www.googleapis.com/auth/gmail.readonly. The command can list and read emails, but cannot send, delete, or modify anything.
Request all scopes configured on the OAuth provider. This gives the command broader access.
When the user authorizes, the consent screen shows every scope that the OAuth provider is configured with. The resulting token has all those permissions available.
Gmail Example
If your Gmail OAuth provider is configured with https://mail.google.com/ (full access), a command using full_provider scope gets complete Gmail access — read, send, delete, manage labels, everything.
An important detail: tokens with different scopes are stored separately. If a user authorizes a command_specific command and then a full_provider command, they get two distinct tokens. The narrow token cannot be used by the broad command, and vice versa.
| Command | Token Scope | Permissions Granted | Token Used |
|---|---|---|---|
/check_inbox |
command_specific | gmail.readonly | Token A (read-only) |
/send_email |
command_specific | gmail.send | Token B (send-only) |
/manage_labels |
full_provider | mail.google.com (full) | Token C (full access) |
Each user may need to authorize separately for commands with different token scopes, even if they use the same OAuth provider. This is by design — it ensures the principle of least privilege is enforced per command.
Authentication Policy determines which Telegram users are allowed to go through the OAuth authorization flow for a given command. Even if a user tries to use the command, they'll be blocked from connecting their account if the policy doesn't include them.
Any Telegram user who interacts with your bot can authorize their third-party account. No restrictions.
Best for: Public bots where every user needs their own account access (e.g., each user reads their own Gmail).
Only the bot owner (you) can authorize. All other users are blocked from connecting their account. The command runs using your token for all users.
Best for: Automated or admin commands where you want a single authorized account (e.g., a bot that sends email notifications from your Gmail on behalf of the bot, not from each user's Gmail).
Only users you explicitly add to the allowed list can authorize. Everyone else is blocked.
Best for: Team bots or bots with paid tiers where only specific users should have OAuth access (e.g., only 5 team members can connect their Gmail).
All users can authorize except those on the blocked list. This is an open-by-default policy with specific exclusions.
Best for: Public bots where you need to block specific abusive users from connecting their accounts while keeping the bot open to everyone else.
For the whitelist and blacklist policies, you manage a list of Telegram users. The platform displays each user with their first name, last name, and username for easy identification. Users are matched by their unique Telegram user ID internally.
Where do these users come from?
The list of available users is populated from Telegram users who have interacted with your bot. When a user sends /start or any message to your bot, they're recorded. You can then select from these known users when configuring a whitelist or blacklist.
Let's walk through five practical scenarios using Gmail bot commands. Each scenario demonstrates a different combination of Token Scope and Authentication Policy, so you can see exactly how the two dimensions work together.
For all scenarios, assume you have a Gmail OAuth provider configured on AIBotBuilder (either the built-in system provider or your own custom provider).
Command
/check_inbox
What it does
Shows the user their 5 most recent unread emails
Token Scope
command_specific
Auth Policy
any_user
Scenario: You run a public productivity bot. Any Telegram user can connect their Gmail to see their unread messages. Since the command only reads emails, you don't want the token to have send or delete permissions.
/check_inbox:any_user — the user is allowed to proceed. ✅command_specific — Google's consent screen shows "View your email messages and settings" (gmail.readonly). No send or delete permissions are shown.🛡️ Security benefit: Even if a bug in your command code tried to call the Gmail send endpoint, the API would reject it because the token only has gmail.readonly permission.
Command
/send_email
What it does
Sends an email from the user's Gmail account
Token Scope
command_specific
Auth Policy
any_user
Scenario: Same public bot, but this command lets users compose and send an email. The token needs send permission, but you still keep it as narrow as possible.
/send_email.any_user — allowed. ✅/check_inbox (gmail.readonly), but that token is not reused. This command requires gmail.send scope, so a separate authorization is needed.command_specific — Google's consent screen shows "Send email on your behalf" (gmail.send).💡 Key insight: The same user now has two separate tokens for the same Gmail provider — one for reading and one for sending. Neither token can do what the other does. This is the Token Scope isolation in action.
Command
/daily_digest
What it does
Sends a daily summary of your inbox to the Telegram chat
Token Scope
command_specific
Auth Policy
owner_only
Scenario: You want a scheduled command that runs every morning at 8 AM and sends you a summary of yesterday's emails. You're the only one who should be able to connect Gmail for this command — other users on the bot shouldn't be prompted to authorize at all.
/daily_digest for the first time.owner_only — you are the bot owner, so you're allowed. ✅/daily_digest:owner_only — the user is not the bot owner. ❌ The bot sends a message like "This command's OAuth authorization is restricted to the bot owner."⚠️ Important: With owner_only, the command always uses the bot owner's token. Other users who run the command see data from your Gmail, not theirs. Use this pattern for automation, not for multi-user commands.
Command
/team_inbox
What it does
Shows unread emails for authorized team members
Token Scope
command_specific
Auth Policy
whitelist
Scenario: You have a company bot in a Telegram group. The bot serves 200 employees, but only 5 customer-support agents should be able to connect their shared Gmail inboxes. You don't want the other 195 employees to accidentally authorize their personal Gmail.
/team_inbox command with Gmail as a required OAuth provider.command_specific (gmail.readonly).whitelist./team_inbox → Policy check passes (she's on the whitelist) → She authorizes and sees her emails. ✅/team_inbox → Policy check fails → Bot responds: "You are not authorized to use OAuth for this command." ❌💡 Tip: You can modify the whitelist at any time after creation by editing the command's OAuth constraints in the command detail view. Adding or removing users takes effect immediately.
Command
/send_email
What it does
Sends email from user's Gmail (same as Scenario 2)
Token Scope
command_specific
Auth Policy
blacklist
Scenario: Your public bot has a /send_email command open to all users. You notice that a specific user is abusing the command to send spam. Instead of restricting the entire bot, you block just that user from the OAuth flow.
/send_email → Policy check passes (they're not blocked) → They can authorize and send email. ✅/send_email → Policy check fails (they're on the blacklist) → Bot responds: "You are not authorized to use OAuth for this command." ❌🛡️ Note: Blacklisting blocks the user from new authorizations and from using the command with existing tokens. It's an immediate, effective way to revoke access for specific users.
| Command | Token Scope | Auth Policy | Who can authorize? | Gmail permissions |
|---|---|---|---|---|
/check_inbox |
command_specific | any_user | Everyone | Read only |
/send_email |
command_specific | any_user | Everyone | Send only |
/daily_digest |
command_specific | owner_only | Bot owner | Read only |
/team_inbox |
command_specific | whitelist | 5 agents | Read only |
/send_email |
command_specific | blacklist | Everyone except blocked | Send only |
Understanding the flow helps you debug issues and make informed design decisions. Here's the step-by-step process when a user runs a command that requires OAuth.
The user sends a command (e.g., /check_inbox) to the bot in Telegram.
The bot checks which OAuth providers this command requires and loads the constraints (token_scope and auth_policy) for each provider.
Before checking tokens or prompting authorization, the bot evaluates the auth_policy:
any_user → always passesowner_only → checks if the user's Telegram ID matches the bot ownerwhitelist → checks if the user's Telegram ID is in allowed_user_idsblacklist → checks if the user's Telegram ID is NOT in blocked_user_idsIf the check fails, the command stops and the user gets an access-denied message.
The bot checks if the user already has a valid token with the correct scope. Tokens are stored per (user, provider, command, scope). A gmail.readonly token won't satisfy a gmail.send requirement.
If no matching token exists, the bot sends an authorization button. The OAuth request includes only the scopes dictated by the token_scope setting.
After authorization, the token is stored with its scope metadata. Future runs of the same command skip authorization and use the stored token directly.
The command code runs with the scoped token injected. It can only access API endpoints allowed by the token's scope.
When you create a new command with the "Generate Command with AI" dialog, you can configure both dimensions for every OAuth provider you attach.
In the command creation dialog, check "Requires System Supplied OAuth Login" and/or "Requires Custom OAuth Login". Select the providers your command needs (e.g., Gmail).
For each selected provider, a Token Scope dropdown appears with two options:
Below the Token Scope, you'll see the Authentication Policy selector with four options:
If you chose Whitelist or Blacklist, a user picker appears showing all Telegram users who have interacted with your bot. Select the users to include or exclude.
Click "Generate" to create the command. The OAuth constraints are saved alongside the command and take effect immediately.
You can change both the Token Scope and Authentication Policy at any time after a command is created.
⚠️ Re-authorization required: If you change the Token Scope from full_provider to command_specific (or vice versa), users who previously authorized will need to re-authorize because the new scope requires a different token.
When you create a command from a template, the OAuth scoping is handled carefully to protect user privacy.
Token Scope is preserved. If the template command used command_specific, the new command also uses command_specific.
Authentication Policy is preserved if it's any_user or owner_only.
User lists are always removed. If the template had a whitelist or blacklist of Telegram users, those lists are not copied to the new command. This prevents the template creator's user data (names, usernames, Telegram IDs) from leaking to the person who installs the template.
Whitelist/Blacklist policies are reset to any_user. Since the user lists are removed, a whitelist or blacklist policy would have no list to check against. The policy is automatically reset to any_user for safety.
You create a /team_inbox template with:
command_specificwhitelist with users Alice, Bob, CharlieSomeone else installs this template. Their new command gets:
command_specific ✅ (preserved)any_user 🔄 (reset — Alice, Bob, Charlie are not copied)The new bot owner can then configure their own whitelist if desired.
command_specific unless you have a reason not toThe principle of least privilege applies to OAuth tokens. If your command only reads emails, don't request full Gmail access. Narrower scopes mean less risk if something goes wrong.
owner_only for automation commandsIf a command is designed to run on a schedule or via webhook using your account, set it to owner_only. This prevents other users from accidentally triggering authorization prompts.
Whitelisting is more secure because it defaults to "deny all". With blacklisting, new users are automatically allowed. For commands that access sensitive data, whitelist is the safer choice.
Rather than one /gmail command with full access, create separate commands: /check_inbox (read), /send_email (send), /manage_labels (full). Each gets only the permissions it needs.
As your bot grows, review your whitelist and blacklist entries. Remove inactive users from whitelists and check if blacklisted users should be unblocked.
Yes. Each OAuth provider attached to a command has its own independent Token Scope and Authentication Policy. For example, a command could use command_specific for Gmail and full_provider for Google Drive, with any_user for Gmail and whitelist for Drive.
The defaults are command_specific for Token Scope and any_user for Authentication Policy. This is the most common setup: narrow permissions, open to all users.
Changing the policy doesn't delete existing tokens, but it does block access. If you switch from any_user to whitelist, users who previously authorized but aren't on the whitelist will be blocked from running the command even though their token still exists.
Users don't see the scoping settings directly. They see the Google consent screen (which reflects the Token Scope) and, if blocked by the Authentication Policy, they see a message saying they're not authorized for this command's OAuth.
Absolutely. OAuth scoping works with any OAuth provider configured on the platform — Google, custom providers, or any other OAuth 2.0-compliant service. The examples in this guide use Gmail for familiarity, but the concepts apply universally.
The user receives a Telegram message indicating they are not authorized to use OAuth for this command. The exact wording varies by policy: for owner_only, they're told the command is restricted to the bot owner; for whitelist/blacklist, they're told they're not authorized.
Yes. If a user authorizes a command_specific command and a full_provider command that both use Gmail, they'll have two separate tokens. Each command uses the token that matches its scope. This ensures token isolation.
Create a new command or edit an existing one to start using the 2-dimensional scoping system.