--- name: "calendar_book" area: "calendar" title: "Book a meeting" price: "$0.01" method: "POST" url: "https://api.conecto.chat/v1/tools/calendar_book" mcp_server: "https://api.conecto.chat/mcp/calendar" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/calendar/calendar_book" --- # Book a meeting (`calendar_book`) Books a free time for someone, who gets a confirmation email with an invite and a link to change it. Book a free time (from calendar_find_times) for someone. They get a confirmation email with a calendar invite and a link to reschedule or cancel (if you give their email), and so do their guests (without the link). A round-robin type picks the host by its rules unless you name one. Set confirmation_call_agreed only if the person agreed to a call before the meeting asking whether they can still come. Price: $0.01 a call. A call that fails costs nothing. ## Use it when Someone asked the agent to book them a meeting, by chat, email or phone. - For a meeting that is already booked and should move, use [calendar_move](https://conecto.chat/tools/calendar/calendar_move.md). ## Say this to your agent > Book Rachel Kim in for the 11:30 bike fitting on Saturday the 24th. Her email is on her contact card. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `meeting_type` | string | yes | Its slug, or "/". | | | | `person` | string | no | The meeting type is on this person's own calendar. Up to 254 characters. | | | | `host` | string | no | A round-robin type: give it to this host (they must be free then). Up to 254 characters. | | | | `start` | string (date-time) | yes | | | | | `name` | string | yes | 1 to 120 characters. | | | | `email` | string | no | Up to 254 characters. | | | | `phone` | string | no | Up to 30 characters. | | | | `guests` | array of strings | no | More people to invite, by email. Up to 10 items. | | | | `timezone` | string | no | The attendee's IANA time zone. Up to 80 characters. | | | | `answers` | object | no | Answers to the meeting type's questions, by key. | | | | `confirmation_call_agreed` | boolean | no | | | `false` | | `notify` | boolean | no | Email the attendee, the guests and the hosts (or the owner). | | `true` | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `calendar_book` on the MCP server `https://api.conecto.chat/mcp/calendar` with these arguments: ```json { "meeting_type": "bike-fitting", "start": "2026-10-24T11:30:00-07:00", "name": "Rachel Kim", "email": "rachel.kim@example.com", "timezone": "America/Los_Angeles" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/calendar_book \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"meeting_type": "bike-fitting", "start": "2026-10-24T11:30:00-07:00", "name": "Rachel Kim", "email": "rachel.kim@example.com", "timezone": "America/Los_Angeles"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "calendar_book", "status": "succeeded", "replayed": false, "cost_usd": "$0.01", "balance_usd": "$19.75", "result": { "booking": { "booking_id": "4171ec2e-7840-4cea-98ae-6d838f73ece6", "reference": "86NAQ7U36W", "status": "scheduled", "meeting_type": "bike-fitting", "title": "Bike fitting", "start": "2026-10-24T18:30:00+00:00", "end": "2026-10-24T19:15:00+00:00", "attendee_local_time": "Saturday, October 24, 2026 at 11:30 (America/Los Angeles)", "attendee": { "name": "Rachel Kim", "email": "rachel.kim@example.com", "phone": null, "timezone": "America/Los_Angeles" }, "hosts": [], "guests": [], "answers": {}, "location": "Halverson Cycle & Repair, 1830 SE Ash St, Portland, OR 97214", "booked_via": "bot", "manage_url": "https://cncto.co/booking/4171ec2e-7840-4cea-98ae-6d838f73ece6?t=IjQxNzFlYzJlLTc4NDAtNGNlYS05OGFlLTZkODM4ZjczZWNlNiI:1xJYro:Q8e98jEbJrio_RLE2aJ-Bq5gIqRRIaYy61VCE7jYikc", "confirmation_call": null, "cancel_reason": null } } } ``` `result`: The booking: booking_id, reference, status, meeting type, start and end, the attendee's local time and details, the hosts and guests, answers, location, how it was booked, a manage link and the confirmation call. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_set_up` | 404 | The business has no calendar yet. | Create it with calendar_setup, then call again. | | `not_found` | 404 | No meeting type has that slug. | Call calendar_list_meeting_types and use one of its slugs. | | `time_taken` | 409 | That time is not free: taken, outside the hours, too soon or too far ahead. | Pick a start from calendar_find_times; the message lists free times nearby. | | `inactive` | 409 | The meeting type is switched off. | Switch it on with calendar_save_meeting_type and active: true, or book another type. | | `invalid_input` | 400 | The name, email, phone, an answer or the time is missing or not valid. | Fix what the message names: phones in international form like +15035550123, times with their offset. | | `payment_required_for_outbound` | 402 | The balance is still free credit, which cannot email people outside the business. | Top up once (POST /v1/topups), or book with notify: false. | | `new_recipient_limit` | 429 | The business has emailed as many new addresses today as it may. | Book with notify: false and tell the person yourself, or book tomorrow. | | `not_a_host` | 400 | host is not one of the meeting type's round-robin hosts. | Leave host out to let the round robin pick, or name one of its hosts. | | `sending_paused` | 403 | Email from the business is paused, so the attendee cannot be emailed. | Call again with notify: false, and ask the owner to contact Conecto about the pause. | | `suppressed` | 422 | The attendee's address bounced, complained or unsubscribed before. | Call again with notify: false, or use another address for them. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [calendar_setup](https://conecto.chat/tools/calendar/calendar_setup.md): Sets the business's calendar or a person's own: name, booking address, time zone, weekly hours, closed days, reminder emails and confirmation calls. $0.001 a call. - [calendar_get_setup](https://conecto.chat/tools/calendar/calendar_get_setup.md): The calendar's settings, booking page, iCal link, connected Google calendar, meeting types, and its people's own calendars. Free up to 1,000,000 reads a month. - [calendar_connect](https://conecto.chat/tools/calendar/calendar_connect.md): A link that opens a page naming the business, where the owner, or a person for their own page, connects Google Calendar in one click. Free up to 1,000,000 reads a month. - [calendar_save_meeting_type](https://conecto.chat/tools/calendar/calendar_save_meeting_type.md): Creates or changes a kind of meeting people can book, on the business's calendar or a person's, taken by one host, a round robin or everyone. $0.001 a call. - [calendar_list_meeting_types](https://conecto.chat/tools/calendar/calendar_list_meeting_types.md): Every meeting type people can book, the business's and each person's own, with its hosts and booking page. Free up to 1,000,000 reads a month. - [calendar_find_times](https://conecto.chat/tools/calendar/calendar_find_times.md): Free start times for a meeting type between two dates, in the time zone you ask for. Free up to 1,000,000 reads a month. - [calendar_list_bookings](https://conecto.chat/tools/calendar/calendar_list_bookings.md): Bookings between two times (from now on by default), soonest first, with each one's hosts, guests and confirmation call. Free up to 1,000,000 reads a month. - [calendar_move](https://conecto.chat/tools/calendar/calendar_move.md): Moves a booking to another free time and sends the attendee an updated invite. $0.01 a call. - [calendar_cancel](https://conecto.chat/tools/calendar/calendar_cancel.md): Cancels a booking and tells the attendee by email, unless notify is false. $0.01 a call. - [calendar_save_routing_form](https://conecto.chat/tools/calendar/calendar_save_routing_form.md): Creates or changes a routing form that asks visitors a few questions and sends each to the right meeting type, host, site or message. $0.001 a call. - [calendar_list_routing_forms](https://conecto.chat/tools/calendar/calendar_list_routing_forms.md): The routing forms with their addresses, questions, routes and how many people answered each. Free up to 1,000,000 reads a month. - [calendar_list_routing_responses](https://conecto.chat/tools/calendar/calendar_list_routing_responses.md): What people answered on the routing forms, newest first, where each was sent, and the booking it led to. Free up to 1,000,000 reads a month.