the manual

Everything Kabootar does, and how to use it

Kabootar is a helper that lives in your team's WhatsApp. It sets reminders, checks in on people, remembers what you tell it, sets up Google Meet calls, and writes out voice notes. This guide explains all of it in plain words, with examples. The first half is for everyone on the team; the second half is for the person who runs it.

In a hurry? The quick guide fits on one screen.

1. Getting started

If you're on the team

You don't install anything. Kabootar is a normal WhatsApp contact that your admin has already set up. Three things to know:

1. You need to be added first. Kabootar only talks to people the admin has added on the dashboard. If you message it and get nothing back, that's why: ask your admin to add you.
2. In a direct message, just talk. Anything you send gets an answer.
3. In a group, get its attention. It reads everything, but only answers when you @mention it, reply to one of its messages, or use one of its nicknames (your admin picks these — for example kabu).

A first conversation might look like this:

Write the way you'd write to a colleague. There are no commands to learn. Hindi and Hinglish are fine.

If you're the admin

You run the app on a computer or a server and manage it from a web page called the dashboard. In short:

1. Start the app and open the dashboard in a browser (http://localhost:3022 on the same machine).
2. Link a WhatsApp account by scanning a QR code — this account becomes Kabootar.
3. Note the dashboard password it gives you (it's also sent to that WhatsApp account's own chat).
4. Enter an OpenRouter key and pick a model. That's the AI behind the replies.
5. Add your people on the People page. Until you do, Kabootar answers no one.

Every step is spelled out in the admin guide, including Google Meet and voice notes.

2. Talking to Kabootar

Kabootar answers as a person would: it reads the recent conversation, knows who's on the team, and remembers what it's been told. A few things about how it decides when to speak.

Direct messages

If you've been added, every message you send gets a reply. If you send two messages quickly, it answers the latest one — it won't send you two replies to one thought.

Groups

It reads every message in a group it's in (that's how it can remember things said there), but it only replies when someone who's been added does one of these:

• @mentions it — @Kabootar what's on for today?
• replies to one of its messages (long-press → Reply);
• uses a nickname anywhere in the message — hey kabu, remind us at 5. Nicknames are set by the admin; ask them what yours are.

Its group replies quote the message they answer, so it's clear who it's talking to. People who haven't been added are ignored in groups too — they can be seen and added by the admin, but never answered.

Names

Kabootar knows people by the names the admin gave them, plus any nicknames (the admin calls these aliases). "Remind Vivek", "remind viv" and "remind @Vivek" all work if viv is one of Vivek's aliases. If you mention someone it doesn't know, it says so and suggests the admin add them — it will never guess.

Times

All times are Indian Standard Time. "Tomorrow at 9", "Monday 5 pm", "in 2 hours" all work. If it can't tell what time you mean, it asks rather than guessing.

3. Reminders

A reminder is a message Kabootar sends at a time you choose — to you, to someone else on the team, or to a group.

Setting one

It confirms with the exact time and the names, taken from what was actually saved — so what it says is what will happen. A reminder arrives as a plain message in that person's chat (or in the group).

Repeating

Reminders can repeat daily, on weekdays, weekly or monthly. A monthly reminder set for the 31st lands on the last day of shorter months.

Seeing what's set

In a direct message it lists yours; in a group, the group's. Before setting a new one it checks what's already there, so if you ask for the same thing twice it tells you instead of making a duplicate.

Cancelling

A reminder can only be cancelled from the chat it belongs to: yours from your direct message, a group's from that group. If two could match, it asks which one.

Good to know

• Sending one reminder to more than five people at once needs a yes from you first.
• A person the admin has muted can't receive reminders.
• If the app was switched off when a reminder was due and it's more than two hours late by the time it's back, the reminder is marked missed instead of being sent late — a 4 pm "standup in 15!" is worse than nothing. Repeating reminders simply carry on from the next time.
• The admin can see and cancel every reminder on the dashboard's Reminders page.

4. Check-ins

A check-in is a reminder that waits for an answer. Use it when you want to know something got done, not just that someone was told.

What happens next:

1. At 5 pm Vivek gets the question in his direct message with Kabootar.
2. Any reply from him counts as the answer — even "done" or "not yet".
3. If he hasn't replied within the reply window (two hours unless you say otherwise; anywhere from 30 minutes to 8 hours), Kabootar nudges him once: still waiting on this one — even a one-liner works.
4. If there's still no answer after a bit more time, the check-in is marked missed. The admin can see this on the dashboard.

Check-ins go to people, not groups — a group can't "answer". They can repeat like reminders (a daily end-of-day check-in, say).

5. Memory

Kabootar remembers facts about people and groups, and uses them later without being asked. Each thing it remembers is one short sentence, tagged with who said it, where, and when — so it can tell you "Sidhant mentioned in the eng group on Monday that…" rather than just stating things.

When it remembers

• When you ask. "Remember that…", "note that…", "keep this link…" — anything, even if it only matters for a day.
• When you @mention it on something in a group. Tag it on a message that asks it nothing — someone's shared a link, say — and it takes that as "keep this". If the message is about something at a time ("standup moved to 5"), it sets a reminder instead. Reply to someone else's message with @Kabootar remember this and it remembers their message, credited to them.
• On its own, when someone states a lasting fact: a role, who handles what, time off, a preference, how a group works.

Asking it back

It searches everything you're allowed to know before it ever says "I don't know", and it forgives typos — "kabotar link" finds "Kabootar".

Correcting it

A correction replaces the old fact; it never keeps two that disagree. Dates like "tomorrow" or "next Monday" are saved as the actual date, so they still make sense weeks later.

Good to know

• It talks like a person who remembers, not a database — it won't say "note", "record" or "saved to file".
• Up to three facts from one message; each under 300 characters. A summary is only kept if you ask for one.
• Once someone or some group has a lot of facts (over 40), Kabootar quietly tidies them: duplicates and things that are over get dropped, related facts get merged. Nothing is truly deleted — the admin can always see what was removed.
• The admin can pin a fact on the dashboard. A pinned fact is settled: it's never tidied away and can't be changed from chat.

6. Who can see what

Kabootar keeps a separate memory per person and per group, and follows two simple rules — built into the program, not left to the AI's judgement:

• A group's memory belongs to its members. If you're not in the group, Kabootar won't tell you what was said there, and won't even recognise the group's name when you use it.
• Your own facts are yours. What you tell Kabootar in your direct message stays between you. Others can only know about you what was said in a group they're also in.

In a group, it stays on topic

Everyone in a group reads its reply, so there it only answers from that group's memory. If the answer needs more — your personal facts, another group's — it sends the answer to your direct message instead, and the group just sees Sent you a DM, Sidhant.

You can ask for that yourself: @Kabootar DM me the numbers. Calendar answers always come as a DM.

It also won't talk about privacy itself: no "I can't share that because…" — it simply answers with what you may know.

7. Meetings & Google Meet

Kabootar can put a meeting with a Google Meet link on your Google Calendar and tell everyone. You're the host, exactly as if you'd made it yourself. Each person connects their own company Google account once.

Connecting your calendar (once)

• Open the link in a normal browser (Chrome, Safari), not in WhatsApp's built-in one — long-press the link and copy it if needed. A private window helps if you're signed into several Google accounts.
• Only company accounts can connect. A personal Gmail can't — but you can still be invited to meetings; see your email below.
• In a group, the link comes to your direct message. It works once and expires after 15 minutes; just ask again for a fresh one.
• You'll get a WhatsApp message confirming which account connected.

An instant call

The meeting starts right away and everyone named gets the link on WhatsApp immediately.

A scheduled meeting

Who gets what:

• People with an email on file get a Google Calendar invite.
• People on the team without one get the link on WhatsApp instead.
• You and every team member attending get a WhatsApp reminder 5 minutes before, with the link.
• A group name means everyone currently in that group. "Everyone here" means this group.
• Meetings are 30 minutes unless you say otherwise ("for an hour").

Inviting someone outside the team

Give their email: set up a call with client@acme.com Friday 3pm. They get a Google invite and nothing on WhatsApp. Tell Kabootar to remember their email once (remember the Acme client's email is …) and next time you can just say the Acme client.

Your email

My email is priya@gmail.com saves your own address so you get invites — useful if you can't connect a company account. Only you can set yours; nobody can set someone else's from chat. The admin can also set it on the dashboard.

What's coming up

Up to 30 days ahead. In a group the answer comes to your DM — a calendar is personal.

Good to know

• If you remove Kabootar's access from your Google account, it notices and sends you a fresh connect link next time you ask for a meeting.
• Moving or deleting the meeting in Google Calendar doesn't move the WhatsApp reminder — ask the admin to cancel it on the Reminders page.
• Kabootar never sees anyone's email in the conversation — it works with names, and the app matches names to emails behind the scenes.

8. Voice notes

Send a voice note and Kabootar writes out what you said and posts the words as a reply, right under the voice note — handy for whoever can't listen right now. In a group it adds your name: 🎤 Sidhant: "…".

If it sounds like a request

Kabootar never acts on a voice note directly — a misheard word shouldn't set a reminder for the wrong person. If the voice note asks it to do something, it says what it would do and asks you to confirm:

React to that question to answer it:

• Yes: 👍 ✅ 👌 🙏 🔥 💯 🙌 👏 🤝, any heart, or a happy face (😀 😊 🥳 😂 …).
• No: 👎 ❌ 🚫, or a sad or crying face (😢 😭 😞 …).
• Any other emoji, and it asks plainly whether that's a yes.

Only the person it asked can confirm, once, within an hour. Typing "yes" as a reply to the question works too. Questions it just answers (like "what's on my calendar?") are answered straight away — no confirmation needed. A voice note that isn't for Kabootar at all gets the transcript and nothing more.

Good to know

• Voice notes up to 5 minutes long. Only from people who've been added.
• Hindi is written in English letters ("bhai kal 10 baje remind karna"), never in Devanagari.
• Names from the team list are spelled correctly.
• Replying to someone's voice note with @Kabootar remember this works — it writes the voice note out first.
• The admin can turn transcripts off everywhere, or for one group.

9. Why you can trust its answers

AI assistants sometimes say "done!" without doing anything. Kabootar has a guard against this: before a reply is sent, the app checks in code whether the things it claims — "I've set the reminder", "noted", "I've cancelled it", "the meeting's booked" — actually happened. If they didn't, the reply is redone; if it still doesn't add up, you get an honest Sorry, I couldn't actually do that just now. Could you ask me again? instead of a false promise.

In the same spirit, its confirmations repeat the time and the names from what was really saved, and it asks rather than guesses when a name or a time is unclear.

10. Admin guide

Everything from here on is for the person who runs Kabootar. The dashboard is a small web page with three sections — People, Reminders, Bot Settings — and every change applies immediately, no restart.

First-run setup

Start the app (your developer or the README covers how). Then open the dashboard in a browser:

• On the same machine: http://localhost:3022
• On a server: the address your team's set up, for example https://kabootar.yourcompany.com

The first time, you're walked through four steps:

1. Link WhatsApp. A QR code appears. On the phone whose WhatsApp account should be Kabootar: Settings → Linked devices → Link a device → scan. Use a dedicated number if you can; this account's name is what people will see in their chats.
2. Sync. Wait under a minute while it links up.
3. Password. A random dashboard password is shown once — and sent to the linked WhatsApp account's own chat ("message yourself"), so it's never lost. You can change it later.
4. Configure. Paste an OpenRouter API key, pick a model from the list, choose your dashboard username, and set the system prompt and history limit (Bot Settings explains what these mean). The key and model are tested live before anything is saved.

After that you land on the People page. Kabootar is connected but silent — it replies to no one until you add people.

Logging in & passwords

• Log in with the username you chose and the password from setup.
• Forgot the password? It's in the linked WhatsApp account's self-chat. Every password change is sent there too.
• Change either under Bot Settings → Account. Passwords need at least 8 characters.
• Restarting the app logs you out of the dashboard; just log in again.

People page

This page is Kabootar's permission list. It has three tabs.

People

Everyone Kabootar talks to. For each person:

• Name — the name you give is the name, everywhere: in replies, in reminders, in memory. Not their WhatsApp name.
• The switch mutes and unmutes them. Muted people are ignored, can't receive reminders, and any reminder already set for them is marked missed.
• aka opens aliases and email. Aliases are other names people use in chat ("viv", "the backend guy") — each alias can belong to only one person or group. The email is for meeting invites; the AI never sees it.
• ✎ opens their notes — everything Kabootar remembers about them (see Notes dialog).
• ✕ removes them. Their notes and Google connection go with them.
• google ✓ shows they've connected a Google Calendar.

+ Add person adds someone by phone number (any format like +91 98765 43210); the number is checked against WhatsApp before saving. Or add people from the Unknown tab once they've messaged.

Groups

Kabootar reads every group it's in, but a group only becomes a name it knows — something people can say "remind the eng group" about — once you add it here. Groups appear in the Unknown tab after their first message; give them a name and optional aliases. If the group's WhatsApp name changes, the label follows. Each group row also has a voice toggle to turn voice-note transcripts off in that group.

Unknown

People and groups Kabootar has seen but you haven't added: someone who messaged it, spoke in a group it's in, or was @mentioned. Nothing here is ever answered. Add as person / Add group opens the add dialog with the details filled in — you still choose the name.

Reminders page

Every reminder and check-in, whoever set it, with who asked for it. Statuses:

• pending — waiting for its time.
• waiting reply — a check-in that's been sent and is waiting for an answer (nudged once the reminder nudge has gone out).
• done — sent (or answered, for a check-in).
• missed — not delivered or not answered; the reason is shown ("no answer after nudge", "person is muted", "app was offline past its window").
• cancelled — by someone in chat, or by you here.

Filter by status and by who it's for. + New reminder creates one from here: pick reminder or check-in, write the message (sent word for word), tick people or groups (each gets its own delivery), set the date and time (IST), a repeat, and — for check-ins — the reply window. Cancel a pending one with ✕.

Notes dialog

The ✎ button on any person or group shows what Kabootar remembers about them, newest first. Each line shows the fact and who said it, where and when. For a group, it's everything said in that group, whoever it was about.

• Add a fact by typing it (one sentence, up to 300 characters). It's recorded as said by the admin.
• ✕ deletes a fact. Deletions are soft: the count of deleted notes stays visible so nothing vanishes silently.
• Pin a fact to make it permanent: it's never tidied away and can't be forgotten from chat — people are told only the admin can change it.

Bot Settings

AI Provider

The OpenRouter key and the model that writes Kabootar's replies. Both must pass a live test before Save lights up, so a typo can't take the bot down. Any model in OpenRouter's list that can use tools works; search the list by name.

Behavior

• System prompt — your instructions to the AI, added after Kabootar's own built-in ones (which cover memory, reminders, privacy and the rules above). Use it for tone, persona and anything specific to your team: "be brief", "we're a design studio in Pune", "always reply in Hinglish".
• Chat history limit — how many recent messages from a chat the AI sees each time (20 is a good default). More context, more cost per reply.
• Also answers to — nicknames, comma-separated. In a group, any message from an added person that uses one of these as a whole word wakes Kabootar, like an @mention does.

Voice notes

• Transcribe voice notes — the master switch. Off here is off everywhere; single groups can be switched off on People → Groups.
• Voice model — the model that listens. Only models that accept audio are listed; the default (Gemini 2.5 Flash-Lite) takes WhatsApp's audio as-is and costs a fraction of a paisa per clip.
• Important: OpenRouter requires at least $0.50 of credit in the account for any audio request — even if you bring your own provider key. Without it, voice notes get "Couldn't transcribe that voice note."

Google

The three values from your Google Cloud setup (Client ID, Client secret, Public URL). See Google setup.

Account

Dashboard username and password.

Google setup (one time)

To let people connect their calendars, Kabootar needs to be registered with Google as an app inside your company's Google Workspace. Doing it inside the company means only company accounts can connect, and Google asks for no review and no re-approval. It takes about fifteen minutes.

1. Make the sign-in reachable from the internet. Google has to send people back to Kabootar after they sign in. Kabootar listens for this on port 3023 — that's the only thing to expose; the dashboard stays private. For a quick start run ngrok http 3023 and copy the https://… address it prints (a free static ngrok domain saves you updating Google every restart). On a proper server, give port 3023 its own subdomain with HTTPS.
2. In the Google Cloud Console, in a project that belongs to your Workspace organisation, open Google Auth Platform:
   • Audience: user type Internal.
   • Data access: add the scopes …/auth/calendar.events, openid, …/auth/userinfo.email.
3. APIs & Services → Library: enable the Google Calendar API.
4. Google Auth Platform → Clients → Create client → Web application. Add the authorised redirect URI https://<your public address>/google/callback. Copy the Client ID (ends in .apps.googleusercontent.com) and the Client secret (starts with GOCSPX-).
5. Dashboard → Bot Settings → Google: paste the Client ID, the secret and the public address; save. The page shows the exact redirect URI Google must have — check it matches.
6. Optionally add people's emails (People → aka → Email) so they get calendar invites even before they connect.

Now anyone on the team can say connect my google calendar.

Running it day to day

• Run exactly one copy. Two copies on the same WhatsApp account look like a hijack to WhatsApp and can get the number logged out. The app refuses to start a second copy on the same machine.
• Keep the phone online now and then. Linked devices are dropped if the phone stays offline for weeks.
• Add only the people who need it. A bot that answers everyone, especially in big groups of strangers, is the pattern WhatsApp looks for.
• Go easy on a freshly linked number during the first few days.
• All data lives in one folder called data next to the app: the WhatsApp link (store.db), settings, people, reminders and memory (app.db), chat history (memory.db). Back it up by copying the folder while the app is stopped — but never put an old copy of store.db back: WhatsApp will treat it as a stolen session and log the number out. If the link breaks, delete store.db (and its -wal/-shm files), start the app, and scan the QR again; everything else is kept.
• To start completely fresh, stop the app and delete the data folder.
• If WhatsApp shows "unlinked" on the setup page, restart the app to get a new QR code.

11. Troubleshooting

Kabootar doesn't reply to someone.

They aren't added on the People page, or their switch is off. In a group, they also need to @mention it, reply to it, or use a nickname.

It replied "Sent you a DM" in a group.

That's by design: the answer needed things outside that group's memory, so it went to the person privately. See Who can see what.

It said it doesn't know someone I mentioned.

That person isn't added. Add them on the People page (they're probably waiting in the Unknown tab).

A reminder shows as missed.

The reason is on the Reminders page: the person was muted or removed, the group was un-named, the app was off for over two hours past the time, or a check-in got no answer.

"Couldn't transcribe that voice note."

Almost always the OpenRouter account has under $0.50 of credit (needed for audio even with your own provider key). Otherwise, check the voice model on Bot Settings → Behavior.

The Google link shows a "400 … malformed" page.

It was opened inside WhatsApp's built-in browser. Copy the link into Chrome or Safari (a private window if you have several Google accounts) and sign in with the company account only.

Google says redirect_uri_mismatch.

The redirect URI in Google Cloud must match what Bot Settings → Google shows, exactly. After an ngrok restart the address changes — update both. A brand-new Google client can take a few minutes to start working.

Google says invalid_client.

The Client ID and secret are swapped or mistyped. The ID ends in .apps.googleusercontent.com; the secret starts with GOCSPX-.

Someone with a personal Gmail can't connect.

Expected — only company accounts can. They can still say "my email is …" to receive invites.

I lost the dashboard password.

It's in the linked WhatsApp account's own chat (Settings → the account's own number, or search "Hammer dashboard").

The setup page says WhatsApp was unlinked.

The device was removed from the phone's linked devices. Restart the app and scan the new QR code; settings and history are kept.

12. What it doesn't do yet

• Photos, videos and documents are ignored. It replies in text only.
• Everyone who's been added is equal: anyone can set a reminder for anyone and any group. Roles and permissions are planned.
• All times are IST; there's no per-person time zone.
• Voice notes over five minutes aren't written out.
• The Google sign-in needs a public address; a free ngrok address changes on every restart.
• Relinking WhatsApp means deleting the link file and scanning again — there's no button for it yet.

Kabootar is built on an unofficial WhatsApp client. It behaves like a normal phone — it shows as online, marks messages read after a natural pause, shows "typing…" while it thinks — but WhatsApp's terms don't allow bots, so the risk of the number being logged out is never zero. The tips under Running it day to day keep it low.