Connect an external calendar

Summary

You connect an external calendar in the Integrations section of the Edit calendar page in the KonversAI console. Select Calendar in the left sidebar, select Calendar settings, then select Edit on the calendar. You paste the secret iCal address of the external calendar into Secret iCal address and select Add. KonversAI then reads that calendar every 15 minutes and blocks the busy times, so no customer books over an event you already have. The sync goes one way only. KonversAI reads the external calendar. KonversAI never writes into it.

Who can do this

A Tenant Admin, or any team member whose role includes the calendar permission. The console calls the two calendar permissions View calendar and Modify calendar. You need Modify calendar to add, sync or remove an external calendar. A Tenant Operator does not get the calendar permissions by default. If you do not see Calendar in the left sidebar of the KonversAI console, ask a Tenant Admin to change your role.

Before you start

Make sure your tenant has the calendar feature. Calendar is a per-tenant feature flag. When the feature is off, the Calendar item is missing from the left sidebar of the KonversAI console. Contact KonversAI support to switch the feature on.

Save the calendar first. The Integrations section appears only on the Edit calendar page, never on the Create calendar page. Select Save calendar on a new calendar first, then open it again with Edit. See Set up a booking calendar.

Get the secret iCal address of the external calendar. The address must start with https:// and must be reachable from the public internet. KonversAI also accepts a webcal:// address and changes it to https://. The address is a secret. Anyone who has it can read your event times, so treat it like a password.

Know the direction of the sync before you start. The external calendar blocks time in KonversAI. KonversAI does not add, change or delete anything in the external calendar. A booking that a customer makes in KonversAI does not appear in your Google Calendar through this feed.

Steps

Get the secret iCal address from Google Calendar

1. Open Google Calendar settings on a computer. The Integrations section of the Edit calendar page in the KonversAI console holds the link Open Google Calendar settings ↗ for this.
2. In the left sidebar of Google Calendar, under Settings for my calendars, select the name of the calendar that holds the busy times.
3. Go down the page to the Integrate calendar section.
4. Find Secret address in iCal format. Select the address to show it, then copy it. The address starts with https://calendar.google.com/calendar/ical/ and ends with .ics.

A work or school Google account often hides the secret address. Ask your Google administrator to allow it, or use a personal Google account. Outlook, Apple iCloud and other calendars work in the same way. Paste any private .ics link.

Add the calendar in KonversAI

1. Select Calendar in the left sidebar of the KonversAI console, then select Calendar settings.
2. Go to Your calendars and select Edit on the calendar you want to protect. The Edit calendar page opens.
3. Go to the Integrations section. The help text reads Connect external calendars to block availability when you are busy elsewhere.
4. Paste the address into Secret iCal address.
5. Type a name in Label. The field is optional, for example Owner’s Google calendar. KonversAI shows a short form of the address when you leave Label empty.
6. Select Add. KonversAI reads the calendar at once, so you do not wait for the next poll. The message Connected. Found N busy time(s) to block. shows how many busy windows KonversAI cached.
7. KonversAI shows Paste the secret iCal address from Google Calendar. when Secret iCal address is empty. It shows Enter a valid https:// (or webcal://) calendar feed URL. when the address is not a valid https:// or webcal:// address.

You do not need to select Save calendar for this. Add, Sync now, Enabled and Remove in the Integrations section act at once.

Check, pause or remove an external calendar

1. Select Calendar in the left sidebar of the KonversAI console, select Calendar settings, then select Edit on the calendar.
2. Go to the Integrations section and read the status under each row. Synced with a date and time means the last read worked. Not synced yet means KonversAI has not read the calendar yet. A red line shows the error text of the last failed read.
3. Select Sync now to read the external calendar immediately. KonversAI shows Synced — N busy time(s) blocking this calendar.
4. Clear the Enabled checkbox to pause a row. KonversAI stops reading that calendar, and stops blocking its times. Check Enabled again to start it.
5. Select Remove to delete the row. KonversAI deletes the cached busy times with it, and those hours become bookable again.

FAQ

Does KonversAI write my bookings into my Google Calendar?

No. The Integrations section of the Edit calendar page in the KonversAI console makes a one-way, read-only link. KonversAI reads the secret iCal address and blocks the busy times so customers cannot book over them. KonversAI never adds an event, never changes an event and never deletes an event in Google Calendar. The help text on the screen says the same: This is read-only — we never add to or change your Google calendar. To get a KonversAI booking into your own calendar, use the calendar invite instead. Type your address in Email notifications under Notifications on the Edit calendar page, and add the .ics invite that KonversAI emails you.

How often does KonversAI read the external calendar?

Every 15 minutes. A background task in KonversAI reads every enabled external calendar on that schedule. KonversAI also reads the calendar at once when you select Add, and each time you select Sync now, in the Integrations section of the Edit calendar page. So a new event in Google Calendar can take up to 15 minutes to block a slot in KonversAI. Select Sync now when you need the block immediately. KonversAI caches busy times for the next 90 days only. A booking further ahead than 90 days does not see the external event yet.

Where do I get the secret iCal address in Google Calendar?

Open Google Calendar settings on a computer. In the left sidebar, under Settings for my calendars, select the name of the calendar. Go down to the Integrate calendar section. Find Secret address in iCal format, select the address to show it, and copy it. The address starts with https://calendar.google.com/calendar/ical/ and ends with .ics. Paste it into Secret iCal address in the Integrations section of the Edit calendar page in the KonversAI console, then select Add. A work or school Google account often hides the secret address. Ask your Google administrator to allow it, or use a personal Google account.

I do not see an Integrations section. Where is it?

The Integrations section appears only after you save the calendar. The Create calendar page in the KonversAI console hides it, because an external calendar must attach to a calendar that already exists. Select Save calendar first. Then select Calendar in the left sidebar, select Calendar settings, go to Your calendars, and select Edit on the calendar. The Edit calendar page shows Integrations below Notifications.

The row says the last sync failed. What do I do?

Open the Integrations section of the Edit calendar page in the KonversAI console and read the red text under the row. Calendar feed URL must use https. means the address is not an https:// address. Could not resolve calendar feed host: means the address points at a host that does not exist. Calendar feed returned HTTP 404. means the external calendar removed or changed the address. Calendar feed URL must resolve to a public address. means the address points inside a private network, which KonversAI refuses. Calendar feed is too large. means the file is over 5 MB. Fix the address in Google Calendar, select Remove on the old row, and add the new address in Secret iCal address. KonversAI keeps the last good busy times until a new read succeeds, and it keeps trying every 15 minutes.

What happens when the secret address stops working?

KonversAI marks the row with the error and keeps the busy times it read last. It does not delete your bookings, and it does not open the blocked hours by itself. Check the Integrations section of the Edit calendar page in the KonversAI console after you reset an address in Google Calendar. A reset in Google Calendar makes a new secret address and kills the old one, so every read fails from then on. Copy the new Secret address in iCal format from Google, select Remove on the failing row in KonversAI, and add the new address. Select Sync now to check the new address at once.

Where do I see the times an external calendar blocks?

On the Bookings screen. Select Calendar in the left sidebar of the KonversAI console, then select Bookings. Check Show external calendars in the toolbar. KonversAI draws each external busy window in the grid, with the legend External calendar (view only). An event with no title shows as Busy. These entries are read-only. You cannot edit or delete them from the Bookings screen. Remove them at the source, or select Remove on the row in the Integrations section of the Edit calendar page.

Can one calendar use more than one external calendar?

Yes. The Integrations section of the Edit calendar page in the KonversAI console holds a list, and you add as many rows as you need. Paste each address in Secret iCal address, type a name in Label, and select Add. Every enabled row blocks time on that one KonversAI calendar. Each row has its own Enabled checkbox, its own Sync now button and its own Remove button. An external calendar attaches to one KonversAI calendar only, so add the address again on each calendar that needs it.