Your phone's calendar, read by your bot

Member·4 minutes to read

What this does for you

Ask any of your bots "what do I have on tomorrow?" and it can read the answer straight off the calendar on your own phone — every calendar the phone shows you, including ones no connector reaches. The bot reads through the Botseon phone app; nothing is synced or copied in advance, and the bot can never add, change or delete an event this way.

This is separate from the Google Calendar and Outlook Calendar connectors, which read and write one online account. The phone calendar needs no connector and no sign-in to a calendar service.

Before you start

You have the Botseon phone app, signed in. This is a feature of Botseon's hosted service; a self-hosted deployment has no phone app and never offers it.
The app is open on your phone when the bot asks. Nothing listens on your phone: the app fetches the bot's question while it is open and answers it.

How it works

You ask a bot about your schedule, in a chat on any device.
The bot asks for a time range — at most 92 days at once, and at most 200 events come back.

The first time, your phone shows its own system dialog asking whether Botseon may read your calendar. The sentence it shows is this one:

  calendar:
    'Used to let your bot read the events in your calendar when you ask it about your schedule. It reads them only, and never changes one.',

Once you allow it, the app reads each event's title, start and end, whether it is all-day, its location and which calendar it is on, and hands that to the bot. Nothing else — attendees, notes and attachments stay on your phone.

Your phone is never asked at the moment you install or open the app, only when a bot first needs it. On Android, Botseon asks to read calendars only, never to write them.

When the bot says it cannot see your calendar

The bot is told why in one fixed sentence, and repeats it to you:

export const PHONE_TOOL_REFUSAL_MESSAGES: Record<PhoneToolRefusal, string> = {
  no_phone:
    'No phone of yours can share its calendar right now. Open the Botseon app on your phone and allow calendar access, then ask again.',
  permission_denied:
    'You did not allow Botseon to read the calendar on your phone, so I cannot see it. You can allow it in your phone’s settings and ask again.',
  unavailable: 'Your phone could not read its calendar just now, so I have nothing to show.',
  invalid_range: `That time range cannot be read. Give a start before the end, at most ${CALENDAR_RANGE_MAX_DAYS} days apart.`,
  timeout: 'Your phone did not answer in time. Open the Botseon app on your phone and ask again.',
  phone_removed: 'That phone was signed out while this was waiting, so I cannot read its calendar.',
};

What the bot says	What to do
No phone of yours can share its calendar	Open the app on your phone and sign in; if you said no before, allow calendar access in the phone's settings.
You did not allow Botseon to read the calendar	Allow it in the phone's settings (below), then ask again.
Your phone did not answer in time	The phone waits 60 seconds. Open the app on your phone and ask again.
That time range cannot be read	Ask about a shorter stretch — 92 days or less.

If you have more than one phone signed in, the bot asks the one that reported most recently and has not refused.

Taking it away again

iPhone: Settings > Privacy & Security > Calendars > Botseon, and choose None.
Android: Settings > Apps > Botseon > Permissions > Calendar, and choose Don't allow.

The next time the app starts, or the next time a bot asks, the app tells Botseon the permission is gone, and from then on your bots are not offered the calendar at all. Signing the phone out of Botseon does the same.

What Botseon keeps

Each read is a short-lived request: the range the bot asked for and the events your phone sent back. It is kept for a day by default and deleted within seven days at the latest. The bot's reply in the chat is kept like any other message. Because event titles and locations can be written by other people (an invitation's sender), a run that read your calendar treats that text as untrusted, the same as an email it read.