←back to tutorials

Creating an Intelligent Productivity AI Agent for Google Calendar

Learn how to create an intelligent productivity AI agent for Google Calendar using a Telegram chatbot. This tutorial covers blueprint setup, Google Calendar ability templates, per-user OAuth authentication, and interaction steps, enabling users to manage their calendars seamlessly. Updated March 2026.

In this tutorial, we will walk through the steps to create a Telegram chatbot that authenticates end users and allows them to interact with their personal Google Calendars. Each user authenticates with their own Google account, so the bot can list events, create new meetings, and check availability - all through natural conversation.

What You'll Build

A Telegram-connected AI agent powered by Google Calendar abilities:

  • List Calendars - shows all calendars available to the authenticated user
  • List Events - retrieves upcoming events from a specific calendar
  • Create Event - schedules a new meeting with optional attendees
  • Update Event - modifies an existing event
  • Check Availability - finds open time slots based on working hours
  • Book a Slot - creates an event from an available time slot

Here is the blueprint you will create:

Prerequisites

Step 1: Create a New Blueprint

  1. From your dashboard, navigate to Blueprints.
  2. Click Create to start a new blueprint.
  3. Give it a name like Google Calendar Agent and save.
  4. Click Design to open the blueprint designer.

Tip: You can paste the blueprint YAML above directly into the designer's code view to create all resources at once.

Step 2: Add the Bot Resource

  1. Add a Bot resource to the canvas.
  2. Configure it with the following settings:
    • Name: Calendar Agent
    • Model: claude-4.6-sonnet (or gpt-4o for a cost-effective alternative)
    • Backstory: paste the system prompt from the blueprint above - it tells the agent how to use the calendar tools and how to handle unauthenticated users.
  3. Leave the Skillset field empty for now - you will connect it after creating the skillset.

Step 3: Create the Skillset and Abilities

  1. Add a Skillset resource to the canvas and name it Google Calendar Tools.

  2. Connect the skillset to the bot by setting the bot's Skillset field.

  3. Add the following Ability resources, each connected to the skillset:

    AbilityTemplatePurpose
    List Calendarsgoogle/calendar/listDiscovers the user's calendars
    List Eventsgoogle/calendar/event/listRetrieves upcoming events
    Create Eventgoogle/calendar/event/createSchedules new meetings
    Update Eventgoogle/calendar/event/updateModifies existing events
    List Availabilitygoogle/calendar/availability/listFinds open time slots
    Book Slotgoogle/calendar/availability/bookBooks a slot as a new event

    For each ability, set the Instruction to use the corresponding template name (e.g., template: google/calendar/event/list).

Shortcut: Instead of adding the availability abilities individually, you can use the Install Google Calendar Event Booking Tools pack ability (pack/google/calendar[booking]). This pack installs the availability list and book abilities in one step. Add the remaining abilities manually for full calendar management.

Step 4: Configure Google Calendar Authentication

All Google Calendar abilities use the Google Calendar platform secret, which handles OAuth on behalf of your users. This secret is managed by ChatBotKit - you do not need to create a Google API key yourself.

The key configuration is setting the secret kind to personal:

  1. Open your blueprint in the designer.
  2. For each Google Calendar ability, the @platform/google/calendar secret is referenced automatically through the template.
  3. To enable per-user authentication (each user connects their own Google account), ensure the secret kind is set to personal in your bot's solution settings.

With personal authentication:

  • Each end user who messages your bot will authenticate with their own Google account.
  • ChatBotKit stores each user's credentials securely and associates them with their contact record.
  • Different users of the same bot will each manage their own calendars independently.

Step 5: Set Up the Telegram Integration

  1. Add a Telegram Integration resource to the canvas.
  2. Configure it:
    • Name: Calendar Telegram Bot
    • Bot Token: paste your token from BotFather (e.g., 1234567890:AAFxxxxxxxxxxxxxxx)
    • Bot: link to the Calendar Agent bot
  3. Save the blueprint and click Deploy to provision all resources.

Step 6: Test the Agent

  1. Open Telegram and find your bot by its username.
  2. Send a message: "List my calendars"
  3. The bot will prompt you to authenticate with your Google account. Follow the provided link to complete the OAuth flow.
  4. After authentication, send the message again - the bot will list your available calendars.

Try these example prompts to exercise each ability:

  • "What events do I have this week on my primary calendar?"
  • "Schedule a team standup tomorrow at 9 AM for 30 minutes."
  • "When am I free for a 1-hour meeting this Friday?"
  • "Book the first available slot for a call with ."
  • "Reschedule the standup to 10 AM."

How It Works

The agent follows a simple flow for every calendar action:

  1. The user sends a natural language request via Telegram.
  2. The bot identifies the appropriate ability (list, create, update, etc.).
  3. The ability calls the Google Calendar API using the user's stored OAuth credentials.
  4. The API response is returned to the bot as structured data.
  5. The bot summarizes the result in a friendly, conversational reply.

Per-user authentication means each contact's credentials are stored independently. When a new user messages the bot for the first time, they are redirected through a one-time OAuth consent screen. After that, all requests proceed automatically without further prompting.

Troubleshooting

"Authentication required" appears every time The user's OAuth token may have expired or been revoked. Ask them to re-authenticate by clicking the link the bot provides.

Ability returns an empty list Verify the calendarId value. Use the List Calendars ability first to find the correct ID for the target calendar (often primary for the user's default calendar).

Bot does not respond on Telegram Check that the Telegram bot token is correct and that the blueprint has been deployed. An incorrect or expired token will cause the integration to fail silently.

Events are created at the wrong time Ensure date and time values include timezone information (e.g., 2026-03-26T10:00:00+02:00) or use UTC explicitly to avoid offset issues.

Key Points

  • Each user's session is connected to their own contact information, which is securely stored in ChatBotKit.
  • Different users interacting with the same chatbot across various channels (Telegram, Slack, and others) will have their own authentication credentials and manage their personal calendars independently.
  • The same blueprint works with any ChatBotKit-supported channel - swap the Telegram integration for a Slack or Discord integration without changing the bot or abilities.
  • This setup can be extended by adding abilities from other catalogues such as Google Tasks, Google Drive, or Notion to build a richer productivity assistant.
telegramchatbotauthenticationGoogleGoogle CalendarAIblueprintabilitiesagenticoauth