---
name: "calendar_setup"
area: "calendar"
title: "Set up the calendar"
price: "$0.001"
method: "POST"
url: "https://api.conecto.chat/v1/tools/calendar_setup"
mcp_server: "https://api.conecto.chat/mcp/calendar"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/calendar/calendar_setup"
---

# Set up the calendar (`calendar_setup`)

Sets the business's calendar or a person's own: name, booking address, time zone, weekly hours, closed days, reminder emails and confirmation calls.

Set the business's calendar, or a person's own (person: like a Cal.com user, with their own booking page, hours, time zone and Google calendar): its name on booking pages, address, time zone, weekly hours, date exceptions (holidays, special hours), and for the business's calendar reminder emails and confirmation calls. Only the fields you pass change. The first call creates the calendar; then add meeting types with calendar_save_meeting_type.

Price: $0.001 a call. A call that fails costs nothing.

## Use it when

The business starts taking bookings, wants its own booking address (cncto.co/book/hansen-voss, like a Cal.com username), or its opening hours, holidays, reminders or confirmation calls change; or a person on the team gets a booking page of their own, with their own hours.

- For one kind of meeting with its own length, place or hours, use [calendar_save_meeting_type](https://conecto.chat/tools/calendar/calendar_save_meeting_type.md).

## Say this to your agent

> Take bookings Monday to Friday 10 to 7 and Saturday 10 to 4, Portland time, and close on Christmas Eve.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `person` | string | no | Someone on the account (admin_save_person), by email: sets up their own calendar and booking page instead of the business's. Up to 254 characters. |  |  |
| `name` | string | no | 1 to 120 characters. |  |  |
| `about` | string | no | A line under the name on the booking page. Up to 300 characters. |  |  |
| `address` | string | no | The booking page's address, like a Cal.com username: cncto.co/book/<address>. Lowercase letters, digits and hyphens, e.g. hansen-voss. The old address keeps working and forwards to the new one; no other business can take it. 3 to 50 characters. |  |  |
| `timezone` | string | no | IANA time zone, e.g. Europe/Berlin. Up to 80 characters. |  |  |
| `hours` | array of objects | no | Weekly hours; several ranges a day are fine. Up to 50 items. |  |  |
| `hours[].day` | string | yes, in each item of `hours` |  | `"monday"`, `"tuesday"`, `"wednesday"`, `"thursday"`, `"friday"`, `"saturday"`, `"sunday"` |  |
| `hours[].start` | string | yes, in each item of `hours` | Matches ^([01][0-9]\|2[0-3]):[0-5][0-9]$\|^24:00$. |  |  |
| `hours[].end` | string | yes, in each item of `hours` | Matches ^([01][0-9]\|2[0-3]):[0-5][0-9]$\|^24:00$. |  |  |
| `date_exceptions` | object | no | {"2026-12-24": []} closes a day; {"2026-12-31": [{"start": "09:00", "end": "13:00"}]} sets its hours. |  |  |
| `show_people` | boolean | no | The business's booking page links the pages of its people who have meeting types (default true). |  |  |
| `reminder_hours` | array of integers | no | Email each attendee this many hours before (default [24]; up to two, e.g. [24, 1]); [] turns it off. $0.002 per reminder sent, paid accounts only. A booking made later than that gets none. For every meeting of the business, its people's too. Up to 2 items. | `1`, `2`, `3`, `6`, `12`, `24`, `48`, `72` |  |
| `confirmation_calls_hours` | integer | no | Call attendees this many hours before (2-72); 0 turns the calls off. 0 to 72. |  |  |
| `connected_calendar_id` | string | no | After the owner (or the person) connected Google Calendar: which of their calendars to use (ids from calendar_get_setup). Up to 1,024 characters. |  |  |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `calendar_setup` on the MCP server `https://api.conecto.chat/mcp/calendar` with these arguments:

```json
{
  "name": "Halverson Cycle & Repair",
  "address": "halverson-cycle",
  "timezone": "America/Los_Angeles",
  "hours": [
    {
      "day": "monday",
      "start": "10:00",
      "end": "19:00"
    },
    {
      "day": "tuesday",
      "start": "10:00",
      "end": "19:00"
    },
    {
      "day": "wednesday",
      "start": "10:00",
      "end": "19:00"
    },
    {
      "day": "thursday",
      "start": "10:00",
      "end": "19:00"
    },
    {
      "day": "friday",
      "start": "10:00",
      "end": "19:00"
    },
    {
      "day": "saturday",
      "start": "10:00",
      "end": "16:00"
    }
  ],
  "date_exceptions": {
    "2026-12-24": []
  }
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/calendar_setup \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Halverson Cycle & Repair", "address": "halverson-cycle", "timezone": "America/Los_Angeles", "hours": [{"day": "monday", "start": "10:00", "end": "19:00"}, {"day": "tuesday", "start": "10:00", "end": "19:00"}, {"day": "wednesday", "start": "10:00", "end": "19:00"}, {"day": "thursday", "start": "10:00", "end": "19:00"}, {"day": "friday", "start": "10:00", "end": "19:00"}, {"day": "saturday", "start": "10:00", "end": "16:00"}], "date_exceptions": {"2026-12-24": []}}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "calendar_setup",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.001",
  "balance_usd": "$19.75",
  "result": {
    "calendar": {
      "name": "Halverson Cycle & Repair",
      "about": null,
      "timezone": "America/Los_Angeles",
      "hours": [
        {
          "day": "monday",
          "start": "10:00",
          "end": "19:00"
        },
        {
          "day": "tuesday",
          "start": "10:00",
          "end": "19:00"
        }
      ],
      "date_exceptions": {
        "2026-12-24": []
      },
      "address": "halverson-cycle",
      "booking_page": "https://cncto.co/book/halverson-cycle",
      "former_addresses": [
        "halverson-cycle-repair"
      ],
      "subscribe_ics": "https://api.conecto.chat/v1/calendar/2U2QwhtxClnMvn6djl-9r9WN9tUOQ099.ics",
      "connected_calendar": null,
      "show_people": true,
      "people": [],
      "reminder_emails": {
        "on": true,
        "hours_before": [
          24
        ],
        "how": "An email to each attendee who gave one, with the time, the place and links to reschedule or cancel. $0.002 each; paid accounts only."
      },
      "confirmation_calls": {
        "on": false,
        "hours_before": null,
        "how": "An automated call before each meeting whose attendee gave a phone number and agreed: a short menu in the business's language where 1 keeps the meeting, 2 cancels it and 3 sends a link to pick another time. No AI. Needs a rented phone number, and calls only landlines and mobiles in its country (the US and Canada count as one)."
      }
    }
  }
}
```

`result`: The calendar: name, address and booking page (with former addresses, which forward to it), time zone, weekly hours, date exceptions, iCal subscribe link, the connected Google calendar, and the reminder-email and confirmation-call settings.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | The hours or date exceptions are not valid, the time zone is unknown, confirmation_calls_hours is not 0 or 2 to 72, or connected_calendar_id is not one of the owner's calendars. | Fix what the message names; calendar_get_setup lists the calendars to choose from. |
| `not_connected` | 409 | connected_calendar_id was given, but the owner has not connected Google Calendar yet. | Send the owner the link from calendar_connect, then pick the calendar. |
| `address_taken` | 409 | The address is another calendar's, was ever another business's, or is kept for Conecto's own pages (book, api, admin ...). | Pick another address, e.g. with the town or the trade added: hansen-voss-hamburg. |
| `calendar_unavailable` | 503 | Google did not answer when the calendars were listed. | Call again in a few minutes; the rest of the setup was saved. |
| `not_found` | 404 | person is not on the account. | Add them with admin_save_person first, then set up their calendar. |

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_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_book](https://conecto.chat/tools/calendar/calendar_book.md): Books a free time for someone, who gets a confirmation email with an invite and a link to change it. $0.01 a call.
- [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.