> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Book meetings with the Meeting Scheduler

> Set up the Meeting Scheduler component so an agent shows live calendar availability and books a meeting inside the conversation.

Hosts connect their own Google Calendar or Microsoft Outlook account, and Tars assigns each booking to a free host. The scheduler lives on a [Component gambit](https://hellotars.com/docs/guides/building/gambits/component.md), so an agent can open it when asked or a flow can run it as a step.

## Before you start

Before you start, sign in to [the dashboard](https://dashboard.hellotars.com) and select the organization you want to work in.

* Connect the calendar of every host in **Tools**: Google Calendar or Microsoft Outlook. Each host needs their own connected account. See [Connect a toolkit](https://hellotars.com/docs/guides/tools/connect-a-toolkit.md).
* For confirmation emails from Google hosts, connect a Gmail account that sends for all of them.
* To use your own booking system instead, publish a CodeKit scheduling integration. See [Build a custom scheduling integration](https://hellotars.com/docs/guides/tools/build-a-scheduling-integration.md).

## Set up the Meeting Scheduler

**1. Add a Component gambit and include Meeting Scheduler**

In agent mode, turn on the **Meeting Scheduler** switch. In Workflow Mode, pick it from the **Component** list.

**2. Select the gear icon on Meeting Scheduler**

The setup dialog opens on the first step that still needs setup, such as **Integration** for a new scheduler. With nothing left to set up, it opens on **Metadata**, where you can adjust the tool name and description.

**3. Pick a scheduling integration**

On **Integration**, pick **Google Calendar**, **Microsoft Outlook**, or a published CodeKit integration.

**4. Add hosts and pick an assignment strategy**

Select **Add calendar account** for each host, then choose **Round robin** or **Priority order**.

**5. Set availability**

On the **Availability** step, set the timezone, meeting length, and working hours.

**6. Set the booking card**

Add a logo and brand name. With Google Calendar or Microsoft Outlook, add any **Guest fields** the agent must collect.

**7. Choose the emails**

On the **Emails** step, turn on **Confirmation emails** if you want more than the calendar invite.

**8. Check the Review step**

Each row on **Review** opens its step again for a change. Select **Done** to return to the gambit editor.

**9. Save the gambit**

Save after completing the configuration. With CodeKit in **Workflow Mode**, first [map the guest details](#map-guest-details-for-a-codekit-integration).

A CodeKit integration handles hosts, availability, and emails itself, so the dialog skips those settings for it. Every setting is listed in [Meeting Scheduler settings](https://hellotars.com/docs/guides/building/gambits/meeting-scheduler-settings.md).

For Google Calendar and Microsoft Outlook, the prefill fields are optional. Map guest details from a preceding form to avoid asking for them again on the booking card. With CodeKit, both fields are required.

![Meeting Scheduler Integration step offering Google Calendar, Microsoft Outlook, and a published CodeKit integration named Demo scheduling, which is selected](https://hellotars.com/docs/docs/guides/building/gambits/images/meeting-scheduler-integration.png)

### Map guest details for a CodeKit integration

In **Workflow Mode**, collect the end user's actual name and email before the scheduler. For example, use a Form with **Variable** `guest_details`. Add required fields keyed `name` and `email`, using the `text` and `email` field types. Connect its **Submitted** outcome to the scheduler.

Under the scheduler's **Inputs**, map `prefillName` to `{{api.guest_details.form.answer.name}}` and `prefillEmail` to `{{api.guest_details.form.answer.email}}`. Both inputs are required. Leaving them empty blocks saving. See [Collect and reuse form answers](https://hellotars.com/docs/guides/building/collect-form-answers.md).

In agent mode, the agent asks for the required guest details before opening the CodeKit scheduler. It passes those details as inputs. It must use the end user's answers, not invented names or email addresses.

## What the end user sees

The booking card shows the open times. The end user picks one, and the card confirms the booking. Every outcome is counted in the **Components** card in Analytics. See [Read the Analytics cards](https://hellotars.com/docs/guides/analytics/overview-tab.md#components).

In a builder test conversation, availability and booking are simulated for every integration, including Google Calendar, Microsoft Outlook, and CodeKit. Google Calendar and Outlook still apply your working hours, timezone, meeting duration, and minimum notice.

In Workflow Mode, the gambit leaves on **Booked**, **No slots**, **Error**, **Skipped**, or **Free text**. Only the web widget shows the booking card. On WhatsApp, the gambit follows **Error**.

## Troubleshooting

| Symptom | What to check and how to recover |
| - | - |
| **No slots** | Check that working hours include the chosen day in the configured host timezone. Allow enough time for the meeting duration and buffer, and check minimum notice. Busy calendars can legitimately leave no available times. Try another day within the next 14 days, or adjust availability and save. |
| Times look shifted | Host working hours use the configured **Timezone**. The booking card displays the end user's timezone. Check both zones before changing the working hours. |
| **Error** with Google Calendar or Outlook | Open the calendar connection in **Tools** and reconnect it if expired or revoked. Confirm each host has the right account, Google **Calendar ID**, or Outlook **Mailbox email**, then retry. See [When a provider revokes access](https://hellotars.com/docs/guides/tools/connect-a-toolkit.md#when-a-provider-revokes-access). |
| **Error** with a CodeKit integration | Check the selected integration version is still available and inspect its toolkit's **Logs**. Correct the actions, deploy them, publish a new version, and select that version in the scheduler. |
| Booking succeeds but an extra email is missing | Turn on **Confirmation emails** and the intended email template. Check the sender account is connected. Google hosts need a shared Gmail inbox. Outlook can use each host's mailbox. For **Booking notification**, set the selected host's **Notification email**. The attendee needs an email address for **Meeting confirmation**. A missing extra email does not mean the calendar booking failed. Check the calendar before booking again. |
| No calendar event or email after a builder test | This is expected: test conversations simulate the booking. Use a controlled live booking to verify provider delivery. |

Route **No slots** to an alternative, such as collecting a preferred time. Route **Error** to a message that offers another way to reach your team. Save the gambit after changing its configuration.

## Verify

Select **Test** in the toolbar and run the flow into the Meeting Scheduler. Test conversations use a simulated booking, so no calendar event, invite, or email is created.

Google Calendar and Outlook tests keep your configured working hours, timezone, duration, and minimum notice while simulating calendar availability. Simulated CodeKit integrations use weekday 9:00–17:00 working hours instead. See [Test your agent](https://hellotars.com/docs/guides/building/testing-your-agent.md).

## Related pages

* [Meeting Scheduler settings](https://hellotars.com/docs/guides/building/gambits/meeting-scheduler-settings.md)
* [Build a custom scheduling integration](https://hellotars.com/docs/guides/tools/build-a-scheduling-integration.md)
* [Component gambit](https://hellotars.com/docs/guides/building/gambits/component.md)
* [Connect a toolkit](https://hellotars.com/docs/guides/tools/connect-a-toolkit.md)
* [Write a custom action](https://hellotars.com/docs/guides/tools/write-a-custom-action.md)
* [Monitor tool calls](https://hellotars.com/docs/guides/tools/monitor-tool-calls.md)
* [Test your agent](https://hellotars.com/docs/guides/building/testing-your-agent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.