Google Calendar & Sheets tools

Two Google tools for your agents. Google Calendar books, checks and manages events - the natural companion to a voice receptionist. Google Sheets reads and writes spreadsheet data - lead logs, order lists, small reports. Connect either one in a click by signing in with Google, or set it up by hand with your own Google Cloud project.

Two ways to connect

Both routes produce the same kind of configuration. The agent, the blueprints and the connection test behave exactly the same whichever you pick.

• Connect with Google - you sign in with your Google account, approve Hania, and come back connected. There's no Google Cloud project to create and nothing to copy. This is the route most people want.
• Connect manually - you create an OAuth client in your own Google Cloud project, mint a refresh token, and paste three values into Hania. Worth it only if you need the connection to run through your own Google Cloud project.

Google Calendar - what it does

Eight actions. The calendar_id defaults to the account's primary calendar.

• list_calendars - the calendars on the account.
• list_events - events in a time window (time_min / time_max), with an optional text filter; recurring events are expanded.
• get_event - a single event's details.
• create_event - summary, start_time and end_time (RFC3339) are required; optional description, location, attendee emails and IANA timezone. Set notify_attendees to email invitations.
• update_event - change any field (partial update).
• delete_event - remove an event; notify_attendees emails a cancellation.
• check_availability - free/busy across one or more calendars.
• quick_add - create an event from a natural-language phrase.

Google Sheets - what it does

Nine actions. Ranges use A1 notation (Sheet1!A1:C10). Cell values are parsed the way typed input is - "42" becomes a number, "2026-07-19" a date, "=SUM(A1:A5)" a formula.

• create_spreadsheet - make a new spreadsheet (returns its id and URL).
• get_spreadsheet - the tabs and their sizes.
• read_range - read a range of cells.
• append_rows - add rows at the bottom of a table.
• update_range - overwrite specific cells.
• clear_range - empty a range.
• add_sheet - add a new tab.
• find_replace - find and replace across the whole spreadsheet.
• delete_spreadsheet - delete a spreadsheet the tool created (see the limitation below).

Connect with Google (one click)

1. Go to Tools, choose Add tool, then Google Calendar or Google Sheets.
2. The form shows you exactly what the tool will be able to do with your account. Read it, then choose Connect with Google. When an agent asks for these details in a chat, the same form is in the chat card.
3. Google opens in a new tab. Sign in with the Google account the agent should use.
4. Tick every permission on Google's screen and approve. Google lists each one with an empty checkbox, and if you leave one unticked the connection can't be made.
5. That tab returns to Hania and confirms the connection, which is ready to assign to an agent. It's named after the account, for example Google Calendar ([email protected]). If you started from a chat, the agent carries on by itself and you can close the tab.

The form you started from stays open in the first tab: press Done there to refresh your tools. If your browser blocks the new tab, use the Open the approval page link in the form. If you're signed out when Google sends you back, just sign in and the connection finishes by itself.

This is what each tool asks Google for:

• Google Calendar - see, create, change and delete events on your calendars, see the list of calendars in your account, and see when you're free or busy.
• Google Sheets - see, create, change and delete your spreadsheets, and manage only the Drive files Hania creates or you open with it.
• Both - your Google account's email address, which is only used to name the connection.

Calendar and Sheets ask for different permissions, so each one is approved on its own. If you want both, connect one and then the other. You can find out more about how we handle this data in the Google user data section of our privacy policy.

When you open a connection made this way, it shows Connected and the account's email address, with a Reconnect button instead of the credential fields. Hania looks after the credentials for you, so there's nothing to renew by hand. You can still change the description and the safety settings whenever you like.

If the connection ever stops working, the tool shows Needs reconnecting on its card, along with the reason. Choose Reconnect and go through the approval again. Your safety settings are kept.

Connect manually

Choose Enter the details manually instead in the form when you add the tool. One Google Cloud setup covers both tools, so if you're using Calendar and Sheets you only go through these steps once.

Before you start

For the manual route you need:

• The Google account whose calendar and spreadsheets the agent will use.
• Access to the Google Cloud Console (console.cloud.google.com) for that account.

One-time Google Cloud setup

This single setup serves both tools. Do it once, then paste the same three values into each tool you use.

1. Create a project at console.cloud.google.com.
2. Enable the APIs under APIs & Services → Library: Google Calendar API, Google Sheets API, and Google Drive API (Drive is required for deleting spreadsheets). Enabling an API is a separate switch from granting its scope - skip it and calls fail with a "has not been used or is disabled" 403.
3. Publish the OAuth consent screen. OAuth consent screen → External → Publish to Production. Add the scopes .../auth/calendar, .../auth/spreadsheets and .../auth/drive.file. See the callout under Connect manually - this is the step that makes the token permanent.
4. Create an OAuth Client ID. Credentials → Create OAuth Client ID → type Web application, and add the redirect URI https://developers.google.com/oauthplayground.
5. Mint the refresh token at the OAuth Playground: open the gear icon (top right), tick "Use your own OAuth credentials" and paste the Client ID and Secret; in Step 1 authorize the three scopes as the target Google account; in Step 2 exchange the authorization code for tokens; copy the refresh token.
6. Paste Client ID + Client Secret + Refresh Token into the Hania tool form and save.

Connecting both tools

With Connect with Google, just connect each tool in turn. On the manual route, Calendar and Sheets share one Google Cloud setup, so connecting both is easy: do the Google Cloud steps once, then create a configuration for each tool and paste the same three values (Client ID, Client Secret, Refresh Token) into each. The refresh token you minted authorized all three scopes, so it works for both. Behind the scenes Hania shares the minted access token between the tools.

Field reference

These are the fields on a manual configuration. Both tools use the same three, all required. A connection made with Connect with Google hides them, because it manages its own credentials.

• Client ID (required) - the OAuth Client ID from your Google Cloud project (APIs & Services → Credentials).
• Client Secret (required, secret) - the OAuth client's secret. Stored encrypted and never returned.
• Refresh Token (required, secret) - a permanent refresh token for the Google account. The consent screen must be published "In production" - a token minted in "Testing" mode expires after 7 days. Access tokens are minted from it automatically.

Sheets deletion limitation

The Sheets tool can only delete spreadsheets it created itself. This is a safety boundary of the drive.file scope, which grants access only to files the app made - not your whole Drive. Ask the agent to delete a spreadsheet it didn't create and the call comes back "not found". So don't expect the agent to tidy up files it never touched; it can only remove ones it made.

Working with the agents

Two blueprints give you a configured agent in one click - you only need to connect your Google account:

• Scheduling Assistant (Calendar) - checks availability before booking, confirms with you before it changes anything on your calendar, and can email invitations to attendees.
• Spreadsheet Assistant (Sheets) - reads the data before writing, and confirms with you before it overwrites or clears cells.

Both are built for the write-carefully habits that matter when an agent is touching a real calendar or a live spreadsheet.

Troubleshooting

• Works, then breaks after about a week - the consent screen was still in "Testing" when the token was minted. Publish it to Production (step 3) and mint a fresh refresh token.
• "unauthorized_client" error - the token was minted without ticking "Use your own OAuth credentials" in the Playground. Re-mint with your own credentials pasted in.
• A "Drive / Calendar / Sheets API has not been used… or is disabled" 403 - that API isn't enabled in the Cloud project. Enable it (step 2) and wait a minute before retrying.
• PERMISSION_DENIED / NOT_FOUND / INVALID_ARGUMENT - Google's own error, surfaced verbatim in the trace. NOT_FOUND on a spreadsheet delete usually means the tool didn't create that file (see the limitation).
• Validation errors (a missing required field, an empty update) - the agent self-corrects these, so they may flash through a trace before the call succeeds.

If you used Connect with Google, you may see one of these in the tab that comes back to the console. To try again, close that tab and press Connect with Google again in the form you started from.

• "The approval was declined" - you backed out on Google's screen, so nothing was connected.
• "Not every permission was ticked" - one of the checkboxes on Google's screen was left empty. Tick all of them when you try again.
• "That approval link expired or was already used" - more than ten minutes passed between starting and approving, or the same approval was used twice.
• "Couldn't finish the connection" - something else went wrong along the way. Try once more, and if it keeps happening, use the manual route.
• The form switches to the manual fields when you press Connect with Google - Connect with Google isn't available right now. The manual route works just the same.

Safety in autonomous runs

Like any tool, these carry a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Because both tools change real data - events that email people, spreadsheet cells that get overwritten or cleared - a new configuration of either is created with Read-only switched off, Destructive switched on, and Sends data externally on. That's true whether you connect with Google or set it up by hand, and reconnecting later never resets settings you've changed. Destructive actions are then gated in autonomous runs unless the agent's "Allow destructive actions in autonomous runs" is enabled. Keep those defaults, and let the blueprints' confirmation prompts do their job. Interactive chat is never gated by these flags.

Security

The Client Secret and Refresh Token are stored AES-encrypted at rest and are never returned by the API - the console shows only whether each is set. Editing a configuration without retyping a secret preserves the stored one, so you must retype it to replace it. To revoke access, remove the app's access in your Google account's security settings or delete the OAuth client in the Cloud Console.

A connection made with Connect with Google works the same way. Google's authorization is held encrypted, is never shown back to you, and saving the configuration can't wipe it, so you can safely edit its description or safety settings at any time. To take access away, delete the configuration here, or remove Hania from the third-party access page of your Google account.