AI assistant (Claude, ChatGPT, Codex)
What an AI assistant can do in herbe.calendar for a person who connects it through herbe ID, who may use it, and what it cannot do yet.
People can connect an AI assistant (Claude, ChatGPT or Codex) to herbe.calendar and ask it things in plain words, also by voice in the phone app. This page is for admins: what it can do, who may use it, and how to switch it off. The steps for the person who connects it are in AI assistant.
It needs Sign in with herbe ID to be set up for the account (see Sign in with herbe ID). There is nothing to turn on in herbe.calendar itself.
What it can do
In plain words, in three groups:
- Look up. Who is in the account, the person's favorites and templates, the places an event or task can be created (each ERP company, Outlook, Google, Microsoft To Do, Google Tasks), activity types, customers, projects and items. Public holidays.
- Read. The calendar of one person or a favorite over a period, one event in full, common free time for several people, the person's tasks, their share and booking links, the free slots a booking link offers, and who booked through those links.
- Change. Create an event or an activity (ERP planned or actual time, Outlook with Teams, Google with Meet, optionally a Zoom meeting, from a template, with a repeat or a reminder). Change an event, move an ERP activity to another Kanban stage, answer an Outlook or Google invitation, add a comment, set the long description, watch an activity. Create a task, edit it, mark it done. Book a time for a customer through one of the person's own booking links (see Booking for a customer).
If something needed is missing (for an ERP activity, the fields its type requires), the assistant asks the person instead of guessing, and nothing is written until it has them.
Same rights as the screen
The assistant works as the person who connected it, with exactly the rights that person has on screen, never more. In practice:
- Anyone can read any person of the account, and create an activity for anyone.
- An ERP activity can be changed only by someone on it (main person, CC person or the access group) and only while it is not approved or locked. On a locked one only the title (the ERP comment), the long text and the CC persons can change.
- An Outlook event can be changed only by its organiser.
- Tasks: only the person's own.
- Colleagues' own Google, ICS and iPhone calendars show only what their sharing level allows (private, busy, titles, full). ICS feed calendars and iPhone calendars are read-only.
- Several ERP companies: the assistant must name the company; it never picks the first one.
- Writes are refused during an ERP maintenance window, with the time it ends.
createEventdoes not even reach the ERP then, so it answers at once instead of waiting on a server that is not answering. The window is the one declared on the ERP connection in Configuration; a window nobody declared is not known to the assistant. - When the ERP does not answer a create (
createEvent), the assistant is told the event may already exist (write_unconfirmed) and must look for it withlistEventsbefore creating it again, so a retry does not book it twice.
Machine keys (hcal_) never work for the assistant.
The Ask button (herbe assist panel)
Besides connecting an outside assistant, herbe.calendar can show an Ask button in the top bar that opens the herbe assist panel beside the calendar. It appears only for people whose session came through herbe ID, and not while an admin is impersonating someone. It tells the panel which ERP activity the person has open; the panel's own key, rules and who may use AI are set in herbe assist's Settings, not here.
It is switched on per deployment by the environment variable NEXT_PUBLIC_ASSIST_ORIGIN (the address of herbe assist, for example https://assist.herbe.app). It is read at build time, so changing it needs a redeploy. Unset, there is no button and nothing else changes. The same address is the only thing added to the page's frame-src security policy. The wire contract between the app and the panel is in docs/assist-button.md in the repository. The person-level article is Ask (herbe assist panel).
Who may use it
Access is decided in herbe ID, not in herbe.calendar. In herbe ID open Admin → Organisations → the organisation → People → the person:
- the person's AI tools switch must be on, and
- the AI column on the calendar row must be on. herbe ID words it as: "whether AI assistants (Claude, ChatGPT, Codex) may use this app as the person". It is on by default for apps the person has access to while AI tools is on, so you can allow calendar for the assistant and later withhold another app.
The person must also have signed in to herbe.calendar with herbe ID at least once; otherwise the assistant tells them to do that first. If an organisation is set to forced privacy, the person cannot connect this way.
herbe ID checks all of this on every request. Switch AI tools or the AI column off, remove the person's access, or remove them from the organisation, and the assistant stops working at once. Allow a few minutes at most for the person's side to notice.
Switching AI tools or the AI column off also ends the person's AI connections, and switching it back on does not restore them: the person connects the assistant again.
What it cannot do yet
- Delete anything except one event at a time, and only with the person's approval (see Deleting an event): no tasks, bookings, share links, favorites or templates.
- Cancel a booking.
- Create or change share links, landing pages, favorites or templates (it can read them; set them up on screen).
- Upload attachments.
- Change iOS calendars or reminders, or ICS feed calendars: those are read-only, as on screen.
- Repeat a Google event (Outlook events and ERP activities can repeat).
- Add Teams to an Outlook event after it was created.
- Switch between two calendar accounts: a person in two organisations names the organisation in each request.
What needs the person's approval
Some things the assistant asks for are never done on its own word. For these it answers with an approval link instead, and nothing happens until the person opens that link in herbe.calendar in their browser, signed in as themselves, reads the whole action and presses Approve:
- Creating an event with a guest who is not in the organisation. "In the organisation" means an active member of the calendar account (Admin → Members), nothing else: an address in the people list that is not a member (an Azure guest, an ERP user with an outside address, a removed member) counts as outside, even when it is well known. That applies to a colleague the assistant names by code too.
- Changing an Outlook or Google event when anyone outside the organisation is on it or is being added, including removing them (they are told). Changing the notes of such an event counts: the notes go to the guests.
- Answering an invitation (accept, tentative, decline) when the organiser is outside the organisation. On Google the answer is sent to everyone on the event, so any outside attendee counts too.
- Deleting an event. A delete cannot be undone, so it always needs approval, whoever is on the event.
- Booking for a customer through a booking link when the customer's e-mail address is not an active member of the account: the customer gets a confirmation e-mail with a cancel link.
Creating or changing an event with only people inside the organisation, and everything else the assistant does, works as before.
What the approval page and link do:
- The page shows the whole action: which event it is (title and time), every guest address (the outside ones separately), the title, the time, the notes in full, the location, any Zoom meeting, repeat and reminder, for a delete exactly which event goes and who is told, or for a booking the link and template by name, the time, the customer and every answer to the booking page's fields. If the page cannot show it in full there is no Approve button.
- Only the person the request was made for can use the link, in the calendar account it was made for. Someone else, a super admin viewing as that person, and a phone's app token are refused. A link in a chat message is no use to anyone else.
- The link works once and for 15 minutes. After that, or after Reject, the assistant has to ask again. The assistant can ask how it ended (approved, rejected, expired, failed) with the
getApprovalStatustool. - It is checked again when the person presses Approve: the person must still be an active member, the stored request must be unchanged, the addresses of colleagues named by code must still be the ones that were shown, and for a change, an answer or a delete the people on the event must still be the ones that were shown, and for a change or an answer the event must still have the same title and time. If a new outside person joined the event, or it was renamed or moved, meanwhile, nothing is done. If the calendar cannot read the event or its guests at that moment, nothing is done either and the link keeps working. A booking is checked against the link too, see below.
- An invitation, update or answer is sent by Outlook or Google, as on screen. A Zoom meeting is created only when the person approves.
- Each request is one row in
agent_approvals(migration 84): who asked, which tool, the exact arguments, who approved and when, and how it ended. Rows are kept for 90 days. A person can have ten requests waiting at a time.
Booking for a customer
A person who agreed a time with a customer can ask the assistant to book it through their own booking link, so the link's template does what it does for a customer on the booking page: the ERP activity, the Outlook or Google event, the Zoom meeting, and the confirmation e-mail with the cancel link. Two tools do it:
linkSlotslists the free slots of one of the person's own booking links between two dates (at most 31 days), in the person's zone, with the questions the booking page asks the customer (which are required). Each slot carries its exact start as a UTC time (slot) next to the date and time in the person's zone.bookViaLinkbooks one of those slots: the assistant passes theslotexactly aslinkSlotsgave it, never a date and a time of its own, so the two 03:30s of a clock change cannot be mixed up. It is the same booking code and the same checks as the public booking page: opening hours, the buffer, the 30-minute lead time, the booking horizon, public holidays unless the template allows them, and busy time in the host's calendars.
What that means in practice:
- Only the link's own free slots. A time the link does not offer is refused. To put a meeting at another time the person creates an event from a template instead (
createEvent); there is no way to force a booking through a link. - Only the person's own links. Someone else's link answers "not found", the same as a link that does not exist. An expired link, a link with booking switched off and a password-protected link are refused. The link and template are shown by name.
- Nothing is invented. A question the booking page marks required must be answered by the customer; if the assistant does not have the answer it asks the person and books nothing. A field the booking page does not have is refused.
- Anyone outside the account needs approval. The customer, and every person on the link (the people the booking invites and e-mails), are checked, not only the customer. Unless every one of those addresses is an active member of the account the assistant answers with an approval link and books nothing until the person presses Approve. The page shows the link and template by name, the time, the customer's address, every answer, and everyone who is told, with the outside ones named. On Approve the link is read again: if the link or template was renamed or removed, its settings changed (which calendars and ERP companies it creates in, the people on the link, the time zone), a required question was added, someone outside who was not shown would now be told, or the slot is taken meanwhile (or is no longer offered), nothing is booked and the request ends as failed.
- Booked as on the public page. The booking appears in the person's bookings (
listMyBookings) like any other. If the confirmation e-mail or one of the template's targets (ERP, Outlook, Google) fails, the answer says so, and the approve page shows the same note under the result. If every target fails the assistant is told the booking may or may not have been created (an ERP record can be written without being read back) and to check the person's bookings and calendar before booking again. The cancel link goes to the customer in the e-mail; the assistant does not receive it, and bookings cannot be cancelled from the assistant.
Deleting an event
The assistant can delete one event, and only when the person approves it (see above). Its deleteEvent tool never deletes: it checks that the person may delete the event, then answers with an approval link. The page shows exactly what would go (title, time, calendar, who organises it, and whether attendees or watchers are told). The delete runs when the person presses Approve, and only if the event is still the one that was shown. The rules are the screen's own:
- ERP activity: only if the person is on it, it is not approved or locked by herbe.service, the ERP company is not in its maintenance window and WebExcellentAPI is available on that ERP connection. People watching the activity are notified, as when deleting on screen.
- Outlook: only the organiser. For an invitation the assistant is told to decline it instead. Attendees are told.
- Google: the organiser on the person's own primary calendar. On a calendar the person connected (their own, a colleague's or a team's) the person may delete any event on it, as on the screen. The page names who organises it (by name) and says that deleting it removes it for everyone on that calendar. Guests are told only when the person organises the event and it has guests; otherwise the page says nobody is told, and why. Guests on the event are checked again when the person presses Approve even when nobody would be told: a new outside guest, or the person becoming the organiser, stops the delete.
- A repeating event: the occurrence the assistant was given is deleted alone; if it was given the series itself, the whole series goes, as on the screen. The page says plainly when it is the whole repeating series (with its rule), so the person can say no.
- ICS feeds, iPhone calendars and colleagues' shared calendars are read-only.
The calendar's saved copy of the event is removed at once, so the next question about the calendar no longer shows it.
Addresses
Production: https://id.herbe.app/mcp. Test site: https://id-test.herbe.app/mcp. People use the production address; the test site is for trying it out on calendar-test.
Links in answers
Every event or task the assistant mentions or changes comes with a link that opens it in herbe.calendar, so the person can check it. An ERP activity opens as /cal?activity=<company>:<number>.
Disconnecting
A person can disconnect an assistant in herbe ID under My account → Connected apps, where an assistant is listed as "{name} (AI)", for example "Claude (AI)". Admins see the same list on the person's page. Disconnecting ends the assistant's access at once; the person's calendar sessions are not touched.
Privacy
The AI provider receives what the assistant reads from the calendar: event titles, times, people's names, customers, comments and so on. herbe ID removes e-mail addresses, phone numbers and personal ID codes from answers before they go to the provider, but the rest is passed on. Tell people what the provider's terms say about data before they connect a work account. If you do not want calendar data to go to an AI provider, switch AI tools off for those people in herbe ID.
Troubleshooting
"Your login ... is not linked to a person code. Ask an admin to link it in Members." The assistant needs to know which person code the person is, and it finds it by matching the email they sign in with against the email on their ERP user. When the two addresses differ, there is no match. Open Admin → Members, find the person's login, click link in the Code column and pick their person code. They can connect again straight away, nothing else needs changing. See Members.
"Sign in to calendar once with herbe ID first." The person has not yet signed in to herbe.calendar with herbe ID. Ask them to do that once.
Good to know
- The assistant deletes an event, invites or updates someone outside the organisation, or books a customer outside it through a booking link, only after the person pressed Approve on the page for exactly that action. A changed activity, a created event or a deleted event is a real change in ERP, Outlook or Google. Everything is attributed to the person who connected the assistant.
- The old email login keeps working whether or not people use the assistant.