Skip to content
Docs menu

Booking pages

Your /meet page: event types, times that are really free, holds while someone fills the form, single-use and one-off links, manual confirmation, the invitee's reschedule and cancel link, and the API and MCP tools behind it.

View .md

A booking page lets someone pick a time with you. It offers only the times you are free across every calendar you connected (.ics feeds today, Google next), inside your working hours, with your buffers, notice and limits applied (how slots are computed).

Your pages

Address What it is
/meet/<handle> Your profile: your name, a welcome line and your public event types.
/meet/<handle>/<slug> One event type: a month of free days, the times on the day picked, then the form.
/meet/l/<token> A single-use or one-off link (below).
/meet/manage/<token> The invitee's own booking: the confirmation, "add to calendar", reschedule and cancel.

Your handle is unique across Venom Cloud: 3 to 40 lowercase letters, digits or -. Words the cloud uses itself (api, manage, embed, admin, calendar and a few more) are reserved.

An event type is a kind of meeting: a slug, a title, one or more lengths, a schedule (your working hours in one time zone, with date overrides for days off), where it happens, buffers before and after, minimum notice, how far ahead people may book, limits per day or week, and questions. Questions use the same blocks as Venom Forms (short and long text, choices, phone and so on; file uploads and hidden fields are not offered). A secret event type is bookable but not listed on your profile. An event type that is off is gone from its page at once.

When you save a profile, schedule or event type, every problem is listed at once, so you fix them in one go.

What the invitee sees

The page is drawn on the server and works without JavaScript up to the list of times: the month, the days with free times and the times themselves are plain links. The invitee's time zone is detected in the browser and can be changed; an event type set to lock the time zone (an in-person meeting) shows your zone only. Several lengths show as a choice at the top.

After the booking the invitee lands on their manage page: what, when, where, a Download .ics button and a Google Calendar link (both made on the page; nothing is sent to Google). If the event type has a redirect URL (https only), the invitee goes there instead, with booking_id, start, end, status, name, email and event added to its query string.

Nothing on these pages loads from outside your cloud: no fonts, scripts or images from elsewhere. They carry the same strict content security policy as Venom Forms' public pages, are never indexed, and send no referrer.

Two people, one time

Venom never books the same time twice:

  1. Hold. Picking a time places a 5-minute hold, so other visitors stop seeing it while the form is filled. One hold per browser: picking another time moves it.
  2. Recheck. On submit, every connected calendar is refreshed (for at most 3 seconds) and the time is checked again against fresh busy time, your other bookings and other people's holds. If the refresh runs over, the cached busy time is used and the booking is flagged so you can see it was checked against older data.
  3. Book. The booking is written in one transaction, and the database itself refuses two bookings of yours that overlap (buffers included).

If someone else got there first, the invitee sees "That time was just taken" with the next five free times to pick from. Sending the same form twice (a double click, a retry on a bad connection) returns the first booking, not a second one.

From the API or an agent you can make a link to send someone:

  • Single use: books an event type once, then says it was used.
  • One-off: a meeting of its own. It books once, can change the lengths, the title and the window of dates offered, and works even when the event type is switched off.

A link can expire, and can carry a person and a deal from People and Funnel, which the booking keeps. The link is shown once; only a hash of it is stored.

Confirming by hand

An event type set to manual confirm makes bookings that wait for you (pending). A pending booking holds its time. Accept it and it is confirmed and written to your calendar; decline it and it is cancelled with the reason declined. Bookings you make yourself (in the app, the API or through an agent) are confirmed at once.

Reschedule and cancel

The manage link (/meet/manage/<token>) is the only way in for the invitee: 32 random bytes, of which only a hash is stored. A wrong link and a deleted booking look the same.

  • Reschedule offers the event type's free times. The booking keeps its calendar UID and its sequence number goes up, so calendars update the existing event instead of adding a new one.
  • Cancel marks the booking cancelled and removes the calendar event. Cancelling twice is refused.
  • Neither works once the meeting has started.

You can do both from the API and MCP too.

Limits against abuse

Check Limit
Page opens per visitor (by a salted hash of the IP) 60 a minute
Time lists per visitor 120 a minute
Holds per visitor 30 a minute
Bookings per visitor 10 a minute
Bookings per invitee email 5 a minute
Live bookings per email per event type 3 a week

A booking also needs the page's token (valid for a day), a small proof of work the page solves while the form is filled (about a second in a browser), and an empty spam trap field. There is no third-party CAPTCHA.

Events

Each booking change raises an org webhook event (Settings, Webhooks) and an in-process event other Venom products listen to:

Event When
calendar.booking.created a booking is made (confirmed, or pending for manual confirm)
calendar.booking.confirmed you accept a pending booking
calendar.booking.rescheduled the booking moves (with the previous start and end)
calendar.booking.cancelled the invitee or you cancel it, or you decline it (reason: declined)
calendar.booking.no_show you mark the invitee a no-show after the start (No-shows)

The webhook payload has the booking id, the event type's id and slug, the title, start, end, status, sequence, the invitee's name, email and time zone, the person and deal, and who made the change. Answers to the questions are not in it.

For builders and agents

The console API under /api/workspace/calendar (the signed-in member) and the workspace REST API under /api/v1/calendar (a member's personal key or an OAuth token) have the same operations as the MCP tools on /workspace/mcp/calendar (Workspace MCP):

Tool Does
calendar_profile_get, calendar_profile_save read or save your profile (handle, name, time zone, welcome)
calendar_schedule_list, calendar_schedule_save, calendar_schedule_delete your working-hour schedules; deleting one moves its event types to the default
calendar_event_type_list, calendar_event_type_get, calendar_event_type_save, calendar_event_type_delete event types; a save with an id changes only the fields given
calendar_slots_find free times for an event type, shown in a time zone, morning, afternoon or evening first
calendar_link_create a single-use or one-off link
calendar_booking_list, calendar_booking_get your bookings, newest first, with a cursor
calendar_booking_create book a time for someone (confirmed at once; idempotency_key required)
calendar_booking_reschedule, calendar_booking_cancel, calendar_booking_confirm move, cancel, or accept or decline a pending booking

Reading needs calendar:read, changing calendar:write. A team key has no calendar: use a member's personal key. A time that was taken answers with an error that lists the next free times.

The public API the pages use is open to anyone and lives under /meet/api: GET /meet/api/<handle>, and for an event type (/meet/api/<handle>/<slug>) or a link (/meet/api/l/<token>) POST …/open (the page token), GET …/slots?month=YYYY-MM&time_zone=, POST …/holds and POST …/book. The manage link has GET /meet/api/manage/<token>, …/slots, POST …/reschedule, POST …/cancel and GET …/ics. To put a page on your own site, see Embedding.