> For the full page index, fetch https://echonova.ai/llms.txt # Google Calendar Connect a Google account so your agents gain four calendar tools, know what each tool does and how to write the persona around them, and reconnect when Google access is lost. Connect a Google account and your workspace gains four calendar tools an agent can call during a conversation: check when a calendar is free, create an event, list events and list the account's calendars. Google Calendar is not a channel. Nobody talks to the agent through it; it is a set of actions the agent performs on the connected account's calendars while it talks to a customer somewhere else. After this page you will have the account connected, know exactly what each tool does and what to write in the persona so the agent books the right thing, and know how to reconnect when Google access stops. ## What you need - A Google account whose calendars the agent should read and write. The agent acts as this account: an event it creates is created by this account, on its calendars. - Membership of the workspace. Connecting saves the account's access for the whole workspace, so any agent in it can use the tools. - The account is not connected to another EchoNova workspace. A Google account can be connected once, in one EchoNova workspace. - A persona that names the calendar, the time zone and the rules for booking; see **Get it right**. ## Steps ### Step 1: Open the Connections view Open the agent and add `?tab=connections` to its address in the browser's address bar. The view is headed **Connections** with the line "Manage workspace connections used by your agents and channels." and the button **Add Connection**. The view is not in the agent's tab bar today; the address is the way in. ### Step 2: Choose Google Calendar Press **Add Connection**. The catalog is headed **Add Connection** and filtered by **All**, **Voice & Telephony**, **Messaging**, **Support & Service** and **CRM**. Choose the **Google Calendar** card, under **CRM**; it reads "Give your agents calendar tools: check availability and manage events." The dialog **Connect Google Calendar Account** opens on its **Configure** tab, beside **Tools** and **How To Connect**. ### Step 3: Name the connection and sign in with Google - **Name**: a label for this account, "Shown in your integrations list so you can tell accounts apart." Required. - **Credential**: **Google OAuth**, the only choice. Under the fields the dialog reads "Sign in with Google to grant calendar access. You'll be redirected back here." Press **Connect with Google**. The portal sends you to Google in the same window; the link is valid for 10 minutes. Google asks for two permissions, to create and read events (`calendar.events`) and to read the account's calendars and their events (`calendar.readonly`). Approve both. Google then returns you to the agents list, with no message. Open the Connections view again to see the result: | What you see | What happened | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A row **Google Calendar**, "Calendar scheduling connection", with the account's email under **Google Account**, **0** under **Connected Agents** and the pill **Active** | The account is connected | | The row was already there and is unchanged | The account was already connected in this workspace. Its saved access has been replaced with the sign-in you just completed | | No row | You declined on Google's screen, the link had expired, or the account is connected to another EchoNova workspace. Connect again, or disconnect it there first | The **Tools** tab of the dialog is headed **Actions available through your Google Calendar integration.** and lists the four tools; the **How To Connect** tab restates these steps. ### Step 4: Give the tools to an agent The four tools an agent can gain from the connection, with the description the agent reads when deciding whether to call one: | Tool | Card in the portal | What the agent reads | Values the agent fills in | | -------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `check_availability` | **Check availability**: "Find free and busy times across a calendar for a given window." | Check busy/free intervals on a calendar within a time window (freeBusy). | `timeMin` and `timeMax`, required, as ISO 8601 date-times such as `2026-07-05T09:00:00Z`; `calendarId`, optional | | `create_event` | **Create event**: "Add a new event with a title, time, and optional guests." | Create a calendar event. | `summary`, `start` and `end`, required; `description`, `attendees` as a comma-separated list of email addresses, and `calendarId`, optional | | `list_events` | **List events**: "Read upcoming events from a calendar for a given range." | List events on a calendar within a time window. | `timeMin` and `timeMax`, required; `calendarId` and `maxResults`, optional | | `list_calendars` | **List calendars**: "List the calendars available on the connected Google account." | List the connected account's calendars. | None | Every tool that takes `calendarId` uses the account's primary calendar when the agent leaves it out. `check_availability` returns the busy intervals in the window, and the agent works out the free ones. `list_events` returns single occurrences in start order, with a repeating event expanded into its occurrences. `create_event` adds each address in `attendees` to the event as a guest. The tools reach an agent as workspace tools, one per tool per connection, named after the tool and the account's email so two connected accounts can be told apart. There is no control in the portal today that creates them from a connection or adds them to an agent; the **Tools** tab of the connect dialog lists the four actions. Once a calendar tool is in the workspace library, it is selected on an agent like any other library tool; see [Tools overview](/docs/agents/tools-overview). ## Get it right Tell the agent which calendar, which time zone, how long a booking is, and what to confirm before it creates anything. The tools take a calendar id and date-times with an offset; the persona is where those come from. **Recommended** ```text You book appointments on the "Clinic front desk" calendar. All times are Asia/Riyadh. A visit is 30 minutes, Sunday to Thursday between 09:00 and 17:00. Before creating an event, check availability for the requested slot, read the date and time back to the customer, and ask for their email address to add them as a guest. Never create an event the customer has not confirmed. ``` **Less effective** ```text Help customers book appointments using the calendar tools. ``` The first form gives the agent a calendar to name, a zone to attach to every date-time, a slot length to check, and a confirmation step. The second leaves all four to the agent's guess: an event with no calendar id goes to the primary calendar, and a date-time without the right offset lands at the wrong hour. ## Worked example A caller says on Tuesday: "Can I come in Thursday afternoon?" With the recommended persona: 1. The agent calls `check_availability` with `timeMin` `2026-07-09T13:00:00+03:00`, `timeMax` `2026-07-09T17:00:00+03:00` and the front desk calendar's id, and gets back the busy intervals in that window. 2. It offers the first free 30 minutes, "Thursday at 2:30 pm suits; shall I book it?", and asks for the caller's email. 3. On "yes", it calls `create_event` with `summary` "Visit: Nour Haddad", `start` `2026-07-09T14:30:00+03:00`, `end` `2026-07-09T15:00:00+03:00`, `attendees` `nour@example.com` and the calendar's id. 4. The event appears on the front desk calendar, created by the connected account, with the caller as a guest, and the agent reads the booking back. Each turn in which the agent called a tool is charged like any other turn; see [What a turn costs](/docs/agents/what-a-turn-costs). ## What happens next The connection is listed in the **Connections** view for every agent in the workspace, and the tools created from it act for whichever agent has them. The saved Google access is renewed for you before it expires, so the connection keeps working without another sign-in. When Google no longer accepts the renewal, for example because the account's password was changed or the access was revoked from the Google account's settings, every calendar tool call fails and the agent is told so. Connect the same account again: **Add Connection**, **Google Calendar**, **Connect with Google**, signed in as that account. The existing connection and its tools are kept and the saved access is replaced. Signing in as a different Google account creates a second connection instead. ## Limits | Limit | Value | Applies to | | -------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ | | EchoNova workspaces per Google account | 1 | Connecting | | Sign-in link | 10 minutes | Connecting | | Permissions asked of Google | `calendar.events` and `calendar.readonly` | Connecting | | Default calendar | The account's primary calendar | Every tool that takes `calendarId`, when it is left out | | Calendars the agent can see | Every calendar on the connected account's list | `list_calendars` | | Date and time values | ISO 8601 date-times, for example `2026-07-05T09:00:00Z` | `timeMin`, `timeMax`, `start`, `end` | | Guests on a created event | A comma-separated list of email addresses | `create_event` | | Events returned | Single occurrences, in start order, up to `maxResults` when given | `list_events` | | Connected agents shown on the row | Always **0** | The **Connections** view; the tools, not the row, are what an agent uses | ## Troubleshooting ### There is no row after signing in Google returns you to the agents list whether or not the account was connected. Open the Connections view. If the row is missing, you declined on Google's screen, more than 10 minutes passed, or the account is already connected to a different EchoNova workspace. Connect again, or disconnect the account there first. ### The agent says it could not reach the calendar The saved Google access could not be renewed, or the connection was deleted after the tool was created. Connect the same account again as described in **What happens next**; if the connection is gone, connect it and create the tools again. ### The event landed at the wrong hour The date-times the agent sent carried the wrong offset, or none. Put the time zone in the persona, as an IANA name such as `Asia/Riyadh`, and say that every time is in it. The agent's **Time Zone** on the **Settings** tab sets its working hours, not the clock it books in; see [Working hours](/docs/agents/working-hours). ### The event landed on the wrong calendar The agent left `calendarId` out, so the event went to the primary calendar. Name the calendar in the persona, and have the agent call `list_calendars` first when it needs the id. ### The tools are not on the agent The tools have to exist in the workspace library before an agent can select them, and no control in the portal creates them today. The four actions are listed on the **Tools** tab of the connect dialog. ## FAQ ### Which calendars can the agent see? Every calendar on the connected account's list, through `list_calendars`. The other three tools work on the primary calendar unless the agent passes a `calendarId`. ### Can several agents share one connection? Yes. The connection belongs to the workspace, and a calendar tool acts for whichever agent has it. ### Does the customer get an invitation? The addresses in `attendees` are added to the event as guests, and the event is created with no request to notify them. Have the agent read the booking back to the customer in the conversation. ### Can I connect two Google accounts? Yes, one connection each. The tools created from each connection carry that account's email in their name so the agent, and you, can tell them apart. ### How do I remove the connection? In the Connections view, press the actions button on the row, then **Delete**. Confirm **Delete integration?** with **Delete integration**. The connection, its saved Google access and every tool created from it are removed, and the tools are taken off every agent that had them. The toast reads **Integration deleted**. ## Related - [Tools overview](/docs/agents/tools-overview): what an integration tool is and how an agent decides to call one - [Write the persona](/docs/agents/persona): where the calendar, time zone and booking rules go - [How the prompt is assembled](/docs/agents/prompting-guide): how tool descriptions and the persona reach the agent - [Working hours](/docs/agents/working-hours): what the agent's **Time Zone** setting does and does not affect - [Auth connections](/docs/agents/auth-connections): the credentials EchoNova manages for you, including this one - [What a turn costs](/docs/agents/what-a-turn-costs): what a turn with a tool call is charged