Google OAuth Setup Guide

Learn how to create your own Google OAuth credentials (Client ID & Client Secret) in the Google Cloud Console and use them as a custom OAuth provider on AIBotBuilder.

AIBotBuilder provides built-in system OAuth providers for popular Google Workspace APIs (Gmail, Drive, Calendar, Sheets, Tasks, and more). However, you may want to use your own credentials to get higher API quotas, use your own branding on the consent screen, or maintain full control over your OAuth configuration.

🎯 What You'll Learn

How to create and configure a Google Cloud project
How to enable the Google Workspace APIs you need
How to set up the OAuth consent screen
How to generate OAuth 2.0 Client ID and Client Secret
How to plug your credentials into a custom OAuth provider on AIBotBuilder
How to switch bot commands from the system provider to your own custom provider

⚠️ When Should You Use Custom Credentials?

You don't need to create your own credentials if the system providers are working fine for you. Custom credentials are useful when:

Higher quotas: You need more API calls than the shared system quota allows
Custom branding: You want your own app name on the Google consent screen
Organization policies: Your Google Workspace admin requires apps to be from your own domain
Full control: You want to manage your own OAuth credentials lifecycle

Prerequisites

Before you begin, make sure you have:

A Google account (any Gmail or Google Workspace account)
Access to the Google Cloud Console
A AIBotBuilder account (any plan)
A bot already created on AIBotBuilder with at least one command that uses Google APIs

💡 Good to Know

Google Cloud offers a generous free tier. Creating a project and generating OAuth credentials is completely free. You only pay if you exceed the free-tier API usage limits, which is unlikely for typical bot usage.

Step 1: Create a Google Cloud Project

A Google Cloud project acts as a container for all your API credentials and settings.

1

Go to Google Cloud Console

Open console.cloud.google.com and sign in with your Google account.

2

Create a New Project

Click the project dropdown at the top of the page (next to "Google Cloud"), then click "New Project".

Project name: Choose something descriptive, e.g. My AIBotBuilder OAuth
Organization: Leave as default (or select your organization if applicable)
Location: Leave as default

3

Click "Create"

Wait a few seconds for the project to be provisioned. Once created, make sure it's selected as the active project in the top dropdown.

Step 2: Enable the Google APIs You Need

You need to explicitly enable each Google API your bot commands will use. Here's how:

In the Google Cloud Console, go to APIs & Services → Library (or use the search bar and type "API Library")
Search for the API you need (e.g., "Gmail API")
Click on the API in the search results
Click the "Enable" button
Repeat for each API your bot commands require

Common Google Workspace APIs

Here are the APIs you should enable based on which Google services your bot commands use:

📧 Gmail API

Send emails, read inbox, manage labels

gmail.googleapis.com

📁 Google Drive API

Upload, download, share files

drive.googleapis.com

📅 Google Calendar API

Create events, manage calendars

calendar-json.googleapis.com

📊 Google Sheets API

Read/write spreadsheet data

sheets.googleapis.com

✅ Google Tasks API

Create and manage task lists

tasks.googleapis.com

📄 Google Docs API

Create and edit documents

docs.googleapis.com

📽️ Google Slides API

Create and edit presentations

slides.googleapis.com

📷 Google Photos Library API

Access and manage photos

photoslibrary.googleapis.com

💡 Tip

Only enable the APIs you actually need. You can always come back and enable more later. Enabling an API doesn't cost anything — you're only charged for actual API usage beyond free quotas.

Step 3: Configure the OAuth Consent Screen

The OAuth consent screen is what users see when they authorize your bot to access their Google account. You must configure this before creating credentials.

1

Navigate to OAuth Consent Screen

Go to APIs & Services → OAuth consent screen in the left sidebar.

2

Choose User Type

Select the user type for your app:

External (Recommended for most users)

Available to any Google account. This is the right choice if your bot serves users outside your organization. While in testing mode, only users you add as test users can authorize.

Internal (Google Workspace only)

Only available if you have a Google Workspace account. Restricts access to users within your organization only.

3

Fill in App Information

Complete the required fields:

App name: A name your users will recognize, e.g. My AIBotBuilder
User support email: Your email address
App logo: Optional — upload your bot's logo if you have one
App domain: Optional — you can leave these blank
Authorized domains: Add telegrambotbuilder.com
Developer contact email: Your email address

4

Add Scopes

Click "Add or Remove Scopes" and add the scopes for the APIs you enabled. See the Scopes Reference section below for common scopes.

Note: The scopes you add here must match the scopes configured in your custom OAuth provider on AIBotBuilder. If they don't match, the authorization will fail.

5

Add Test Users

While your app is in "Testing" mode, only users you explicitly add can use it. Click "Add Users" and enter the Gmail addresses of the people who will be using your bot commands.

Important: You can add up to 100 test users. These are the Google accounts that will be able to authorize your bot via OAuth while the app is in testing mode. Remember to add your own email address!

6

Review and Save

Review the summary and click "Back to Dashboard". Your consent screen is now configured.

Step 4: Create OAuth 2.0 Credentials

Now you'll generate the Client ID and Client Secret that you'll use in AIBotBuilder.

1

Go to Credentials

Navigate to APIs & Services → Credentials in the left sidebar.

2

Create OAuth Client ID

Click "+ Create Credentials" at the top, then select "OAuth client ID".

3

Configure the Client

Fill in the following settings:

Application type: Select Web application
Name: e.g. AIBotBuilder OAuth
Authorized JavaScript origins: Leave empty
Authorized redirect URIs: Click "+ Add URI" and enter:
https://app.telegrambotbuilder.com/api/oauth/callback

🚨 Critical: The redirect URI must be exactly https://app.telegrambotbuilder.com/api/oauth/callback. If it doesn't match exactly, OAuth authorization will fail with a "redirect_uri_mismatch" error.

4

Copy Your Credentials

Click "Create". A dialog will appear showing your credentials:

Client ID:

123456789012-abcdefghijklmnop.apps.googleusercontent.com

Client Secret:

GOCSPX-AbCdEfGhIjKlMnOpQrStUvWxYz

⚠️ Important: Copy and save both values securely. The Client Secret will only be shown once in this dialog. You can always access it later from the Credentials page, but it's easier to copy it now.

Google API Scopes Reference

When creating a custom OAuth provider on AIBotBuilder, you need to specify the correct scope for the Google API you're targeting. Here are the most commonly used scopes:

Service	Scope URL	Access Level
📧 Gmail	`https://mail.google.com/`	Full access (read, send, delete)
📧 Gmail (Send only)	`https://www.googleapis.com/auth/gmail.send`	Send emails only
📧 Gmail (Read only)	`https://www.googleapis.com/auth/gmail.readonly`	Read inbox only
📁 Google Drive	`https://www.googleapis.com/auth/drive.file`	Files created/opened by the app
📁 Google Drive (Full)	`https://www.googleapis.com/auth/drive`	Full access to all files
📅 Google Calendar	`https://www.googleapis.com/auth/calendar`	Full calendar access
📊 Google Sheets	`https://www.googleapis.com/auth/spreadsheets`	Full spreadsheets access
✅ Google Tasks	`https://www.googleapis.com/auth/tasks`	Full tasks access
📄 Google Docs	`https://www.googleapis.com/auth/documents`	Full documents access
📽️ Google Slides	`https://www.googleapis.com/auth/presentations`	Full presentations access
📷 Google Photos	`https://www.googleapis.com/auth/photoslibrary`	Full photos library access
🔍 Custom Search	`https://www.googleapis.com/auth/cse`	Google Custom Search
📊 Google Analytics	`https://www.googleapis.com/auth/analytics.readonly`	Read analytics data
🎓 Google Classroom	`https://www.googleapis.com/auth/classroom.courses`	Access courses and assignments

💡 Multiple Scopes

If a single command needs access to multiple Google services, you can combine scopes by separating them with commas. For example, to access both Calendar and Tasks:
https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/tasks

Step 5: Add Credentials to AIBotBuilder

Now that you have your Client ID and Client Secret, let's create a custom OAuth provider on AIBotBuilder.

1

Go to OAuth Providers

Log in to AIBotBuilder and navigate to the OAuth page from the main menu.

2

Create a Custom Provider

Click the "Custom OAuth Providers" tab, then click "Create Custom Provider".

3

Fill in Provider Details

Here's an example for Google Calendar (adapt for your target API):

Name: google_calendar

Display Name: Google Calendar (My Custom)

Description: Access Google Calendar with my own credentials

Client ID: 123456789012-abc...googleusercontent.com

Client Secret: GOCSPX-AbCdEf...

Auth URL: https://accounts.google.com/o/oauth2/auth

Token URL: https://oauth2.googleapis.com/token

Scopes: https://www.googleapis.com/auth/calendar

API Base URL: https://www.googleapis.com/calendar/v3

4

Save the Provider

Click "Create" to save your custom provider. It will appear in your custom providers list.

📋 Common Provider Configurations

All Google Workspace APIs share the same Auth URL and Token URL. Only the Scopes and API Base URL differ:

Auth URL (always): https://accounts.google.com/o/oauth2/auth
Token URL (always): https://oauth2.googleapis.com/token

API Base URLs by Service

Service	API Base URL
Gmail	`https://gmail.googleapis.com`
Google Drive	`https://www.googleapis.com/drive/v3`
Google Calendar	`https://www.googleapis.com/calendar/v3`
Google Sheets	`https://sheets.googleapis.com/v4`
Google Tasks	`https://tasks.googleapis.com/v1`
Google Docs	`https://docs.googleapis.com/v1`
Google Slides	`https://slides.googleapis.com/v1`
Google Photos	`https://photoslibrary.googleapis.com/v1`
Google Analytics	`https://www.googleapis.com/analytics/v3`

Switching from System to Custom Provider

If you already have bot commands using our built-in system OAuth providers (e.g., the system Gmail or Google Calendar provider) and want to switch them to use your own custom credentials, here's how:

Navigate to your Bot Detail page and find the command you want to update
When generating a new command or editing OAuth settings, you'll see two checkboxes:
- "Requires System Supplied OAuth Login" — these are the built-in providers managed by AIBotBuilder
- "Requires Custom OAuth Login" — these are your own custom providers
Uncheck the system provider (e.g., Google Calendar)
Check your custom provider (e.g., Google Calendar (My Custom))
Save the command

✅ What Happens After Switching

Existing users will need to re-authorize with the new OAuth provider the next time they use the command
The authorization flow will show your app name on the Google consent screen instead of the system app name
API usage will count against your own Google Cloud project quotas
The command functionality remains exactly the same — only the OAuth credentials change

⚠️ Before You Switch

Make sure your custom provider uses the same scope (or broader) as the system provider it replaces. If you use a narrower scope, commands may fail due to insufficient permissions.

Testing Your Setup

After creating your custom provider, test it to make sure everything works correctly.

Create a test command (or update an existing one) that uses your custom OAuth provider
Run the command in your Telegram bot
When prompted, click the authorization link to open the Google consent screen
Verify that the consent screen shows your app name (not the system app name)
Authorize the app and verify the command executes successfully

🔍 Verification Checklist

✓ Google consent screen appears with your app name
✓ Authorization completes without errors
✓ Bot command executes and returns expected results
✓ Subsequent uses don't require re-authorization

Publishing Your App (Moving Out of Testing)

By default, your Google Cloud OAuth app is in "Testing" mode, which limits authorization to the test users you've manually added. To allow any Google user to authorize your bot:

Go to APIs & Services → OAuth consent screen in Google Cloud Console
Click "Publish App"
If your app uses sensitive or restricted scopes (like full Gmail access), Google will require a verification review before it can go live. This process can take several weeks.
If your app only uses non-sensitive scopes, it will be published immediately

💡 Do You Need to Publish?

If your bot is only used by yourself or a small team:

No need to publish. Just add team members as test users (up to 100 users)
Test users can fully authorize and use all features
Tokens for test users don't expire sooner than published apps

You only need to publish if your bot serves more than 100 users who each need to authorize with their own Google account.

Scope Sensitivity Levels

Non-sensitive Scopes (No review required)

Google Calendar, Google Tasks, Google Drive (file-level), Google Sheets

Sensitive Scopes (Review may be required)

Google Drive (full access), Google Photos, Google Contacts

Restricted Scopes (Review required)

Gmail (full access), Google Fit (health data)

Troubleshooting

🔴 Error: "redirect_uri_mismatch"

Cause: The redirect URI in your Google Cloud credentials doesn't match what AIBotBuilder sends.

Fix: Go to your Google Cloud credentials and make sure the Authorized Redirect URI is exactly: https://app.telegrambotbuilder.com/api/oauth/callback

🔴 Error: "Access blocked: This app's request is invalid"

Cause: The OAuth consent screen is not properly configured, or the requested scopes don't match what's configured in the consent screen.

Fix: Go to OAuth consent screen settings and ensure you've added all required scopes. Also check that the scopes in your AIBotBuilder custom provider exactly match.

🔴 Error: "Error 403: access_denied"

Cause: The Google account trying to authorize is not a test user (while app is in testing mode).

Fix: Add the user's Gmail address to the test users list in the OAuth consent screen settings, or publish your app.

🔴 Error: "API not enabled"

Cause: You haven't enabled the required API in your Google Cloud project.

Fix: Go to APIs & Services → Library, search for the API, and click Enable.

🔴 Authorization works but command fails with permission error

Cause: The scope configured in your custom provider is too narrow for what the command needs.

Fix: Check the Scopes Reference table and use a broader scope. Users will need to re-authorize after updating scopes.

Frequently Asked Questions

Can I use the same Client ID for multiple Google APIs?

Yes! A single OAuth Client ID works with any Google API. You create one Client ID per Google Cloud project and then create separate custom providers on AIBotBuilder for each Google service (each with different scopes and API base URLs), all using the same Client ID and Client Secret.

Will my existing commands stop working if I switch providers?

The command code doesn't change — only the OAuth credentials used for authentication. Users will need to re-authorize once when you switch to the new provider, but after that, everything works exactly the same.

Is there a cost to using Google Cloud for OAuth?

Creating a project and OAuth credentials is free. Most Google Workspace APIs have generous free-tier quotas. For example, the Gmail API allows 250 quota units per user per second, and the Calendar API allows 1,000,000 queries per day. You're unlikely to hit these limits with typical bot usage.

Can I revert back to the system provider?

Absolutely. Simply edit the command's OAuth settings, uncheck your custom provider, and re-check the system provider. Users will need to re-authorize once.

How many custom OAuth providers can I create?

There's no limit on the number of custom OAuth providers you can create on AIBotBuilder. You can create separate providers for Gmail, Drive, Calendar, etc., all using the same Google Cloud project credentials.

What happens to tokens if I delete my Google Cloud project?

All existing OAuth tokens will be invalidated immediately. Users will need to re-authorize, but authorization will fail since the credentials no longer exist. Make sure to switch commands back to system providers before deleting your project.