Skip to content
Docs menu

Agents schedule for you

Ask venom, Chat or Claude to find time with someone: it finds real free times, holds them, sends the options in their time zone with a one-tap link, and books the one they pick. The same Share availability works by hand from the week view.

View .md

You say: "find 30 minutes with Dana next week, mornings preferred, send her three options on WhatsApp". The agent finds real free times across every calendar you connected, holds them so nothing else takes them, and writes the options in Dana's time zone and language with a link she can tap to book. When she answers, it books the time she picked and lets the other times go.

This works from venom in your terminal, from Chat, from Claude or any other MCP client connected to your workspace, and by hand from the week view's Share availability button.

What an offer is

An offer is a few free times proposed to one person:

  • Picked well. The times come from your real availability (working hours, every connected calendar, buffers, notice). The part of the day you prefer comes first, the times are spread across days, and no day gets more than two. Nothing is offered inside the event type's notice.
  • Held. Each time is held, so your booking pages and other bookings skip it. By default the holds last 48 hours (hold_hours, up to 14 days).
  • One link. The offer has a single-use link that shows only the times still on offer. Picking one books it and frees the others at once.
  • Kept honest. If busy time lands on a held time (you booked something else by hand), that time drops out of the offer and its link. When the offer expires, every hold goes.
  • In their words. The message is in the invitee's time zone and language. The zone comes from what People knows (their last booking, the country of their number) unless you name one.

The message looks like this:

Here are a few times that work for me:
Tue 10 Nov: 10:00, 10:30
Wed 11 Nov: 15:00 (Singapore time)
Pick one here: https://cloud.example.com/meet/l/…

Nothing goes out by itself

  • From the app, you press Send yourself. WhatsApp, Telegram and SMS go through Comms from your org's own numbers; email goes through the org's mail provider (Support settings).
  • From an agent, a send follows Comms' approval rules: it waits as pending_approval until a person approves it in Settings, Comms. If an admin opened a Comms profile to agents, an agent that names that profile sends at once.
  • Replies don't book. When the person answers ("Wed 3pm works"), the answer lands in your bell as a suggestion: "Dana replied 'Wed 3pm works'. Book Wed 11 Nov 15:00?". You press Book or Dismiss. If the reply names one of the offered times, it's picked for you; otherwise you choose. An agent may book after the person chose, with calendar_offer_accept. Nothing is booked from free text on its own.

Replies are matched to the offer by the address it was sent to, or by the person's handles in People. Opted-out numbers are never contacted, and quiet hours hold a send until they end.

Share availability, by hand

On the week view, Share availability opens a short form:

  1. Pick the meeting (one of your event types) and the times: Next 3 mornings, afternoons, evenings, or Pick times myself to click free times.
  2. Set their time zone, the language and how long to hold the times.
  3. Press Hold and write the message. Copy the text, or choose WhatsApp, Telegram, SMS or Email, enter the address and press Send.

Sent lists your open offers, with any reply waiting and Book, Dismiss and Withdraw. The bell links straight to the offer a reply is about.

Example: venom in the terminal

When you're logged in to Venom Cloud (venom cloud login), venom registers your workspace's calendar MCP server as calendar, beside globe, tasks and the other Venom products (What agents connect to by default). Its tools load only when the agent searches for them, so the prompt stays the same. Set VENOM_CALENDAR_MCP=off to leave it out.

> find 30 minutes with Dana next week, mornings preferred, send her three options on WhatsApp

● calendar_offer_create  person_id: 5c1e…, duration: 30, prefer: morning, count: 3, from: 2026-11-16, to: 2026-11-21
  Offer 9f2a… (open, held until 2026-11-12T09:14:00Z):
  - 2026-11-17 09:30–10:00 · 2026-11-17T01:30:00.000Z
  - 2026-11-18 10:00–10:30 · 2026-11-18T02:00:00.000Z
  - 2026-11-19 09:00–09:30 · 2026-11-19T01:00:00.000Z

● calendar_offer_send  offer_id: 9f2a…, channel: whatsapp
  Asked to send by whatsapp to …4567: it waits for a person to approve it in Settings, Comms.

I've held three mornings in Dana's time (Singapore) and queued the WhatsApp message. Approve it in Settings, Comms
and it goes out. When she answers, I'll book the time she picks.

> she said Wednesday works

● calendar_offer_accept  offer_id: 9f2a…, start: 2026-11-18T02:00:00.000Z
  Booked: Intro call, 2026-11-18T02:00:00.000Z → 2026-11-18T02:30:00.000Z with Dana Lim (confirmed)

Booked Wednesday 18 Nov, 10:00 her time. The other two times are free again.

MCP tools

Product calendar, on /workspace/mcp/calendar (scopes calendar:read and calendar:write):

Tool Does
calendar_slots_find Free times. prefer puts a part of the day first, spread: true spreads them across days (at most 2 a day), and person_id shows them in that person's zone.
calendar_offer_create Picks and holds times (or takes the slots given), mints the link and returns the offer with its text. Takes event_type_id or duration, person_id or invitee, from/to, count, prefer, hold_hours, time_zone, locale.
calendar_offer_list Your offers, newest first, with any reply waiting.
calendar_offer_get One offer: the times still held, the link, the text, sends and the reply.
calendar_offer_cancel Withdraws it: the holds go and the link stops working.
calendar_offer_send Sends it through Comms (whatsapp, telegram, sms) or email, to the person's channel of choice or to to. An agent's send waits for approval unless profile names a Comms profile open to agents.
calendar_offer_accept Books the offered time the person chose and releases the rest. One booking per offer: a retry with the same time returns it.
calendar_offer_dismiss Clears a reply suggestion; the offer stays open.

The same calls are on the REST API under /api/v1/calendar/offers (see the REST twin), and the app uses /api/workspace/calendar/offers:

Method and path Does
GET / POST /api/workspace/calendar/offers List your offers (status, person_id, limit), or make one
GET /api/workspace/calendar/offers/{id} One offer
POST /api/workspace/calendar/offers/{id}/send Send it now (you pressed Send): {channel?, to?}
POST /api/workspace/calendar/offers/{id}/accept Book {start, invitee?}
POST /api/workspace/calendar/offers/{id}/cancel Withdraw it
POST /api/workspace/calendar/offers/{id}/dismiss Clear the reply suggestion