Agents

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.

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

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

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.

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.

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.