kabot v0.1.0

Getting started

This guide takes you from nothing to a working message box. When you finish, a visitor can write a message on your website and it arrives in your Telegram chat a moment later. It takes about fifteen minutes.

You need:

  • A Cloudflare account. The free plan is enough.
  • A Telegram account. If you prefer Bale, follow the Bale guide for step 1 and come back for the rest.
  • A website you can add a <script> tag to, or a backend that can make an HTTPS request.
  • For the command-line steps, Node.js 18 or later and curl.

1. Create a Telegram bot

  1. In Telegram, open @BotFather and send /newbot.
  2. Send a display name, for example My Site Messages.
  3. Send a username. It must end in bot, for example mysite_messages_bot.
  4. BotFather replies with a token like 7012345678:AAH….
Important

Keep the token private. Anyone who has it controls the bot.

The bot only talks to chats you link with a pairing code, so it is safe for other people to find it. The Telegram guide lists optional settings such as a description and a profile picture.

2. Deploy the Worker

Option A: the Deploy button

Open the Deploy to Cloudflare link. Cloudflare copies the repository to your GitHub account, creates the D1 database and deploys the Worker. When it asks for secrets, fill them in as described in step 3 and skip that step.

Option B: the command line

Terminal
git clone https://github.com/mtnaskari/kabot
cd kabot
npm ci
npx wrangler login
npm run deploy

npm run deploy deploys the Worker, which creates the D1 database on the first run, and then creates the tables. Wrangler prints the Worker's URL, for example https://kabot.your-name.workers.dev. You will use it in every later step, so save it in your shell:

Terminal
export KABOT=https://kabot.your-name.workers.dev

To use your own domain instead, see Configuration.

3. Set the secrets

kabot needs two random secrets and the bot token:

Terminal
openssl rand -hex 32 | tee admin-token.txt | npx wrangler secret put ADMIN_TOKEN
openssl rand -hex 32 | npx wrangler secret put KABOT_SECRET
npx wrangler secret put TELEGRAM_BOT_TOKEN      # paste the token from BotFather
  • ADMIN_TOKEN lets you manage the deployment through the admin API. The first command also saves it to admin-token.txt so you can use it below. Move it to a password manager when you are done, and delete the file.
  • KABOT_SECRET protects the webhook URL and hashes visitor IP addresses. You never need to type it again.

Load the admin token into your shell:

Terminal
export ADMIN_TOKEN=$(cat admin-token.txt)

Check that the Worker responds:

Terminal
curl "$KABOT/health"
# {"ok":true,"name":"kabot","version":"0.1.0"}

4. Connect the bot to the Worker

Terminal
curl -X POST "$KABOT/admin/webhooks" -H "Authorization: Bearer $ADMIN_TOKEN"

The response shows the webhook for each configured bot:

JSON
{ "ok": true, "webhooks": { "telegram": { "ok": true, "url": "https://kabot.your-name.workers.dev/bot/telegram/…", "pendingUpdates": 0, "lastError": null } } }

Telegram now sends the bot's messages to the Worker, and the bot shows a command menu with /inbox, /sites and /help.

5. Add your website

Choose a short id for the site, made of lowercase letters, digits and hyphens. List every origin the message box will run on, with the scheme and without a path.

Terminal
curl -X POST "$KABOT/admin/sites" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-site",
    "name": "My site",
    "allowedOrigins": ["https://example.com", "https://www.example.com"]
  }'

The response contains two things you need:

JSON
{
  "ok": true,
  "site": { "id": "my-site", "name": "My site", "…": "…" },
  "apiKey": "kb_X1y2…",
  "pairing": {
    "code": "k3m9q2…",
    "expiresAt": "2026-11-12T10:00:00.000Z",
    "command": "/start k3m9q2…",
    "links": { "telegram": "https://t.me/mysite_messages_bot?start=k3m9q2…" }
  }
}
  • apiKey is only needed if your backend sends messages. It is shown once. Store it as a secret on your server, or ignore it if you only use the widget. You can issue a new one at any time.
  • pairing links your chat to the site. The code works once and expires after an hour.

Open pairing.links.telegram on a device where you are signed in to Telegram. Telegram opens the bot with a Start button. Press it. The bot replies:

✅ This chat now receives messages from My site (my-site).

If the link doesn't open, open the bot yourself and send the pairing.command text, for example /start k3m9q2….

To receive messages in a group, or in more than one chat, see Linking chats.

7. Add the message box to your website

Add this line before </body> on every page that should show the message box:

HTML
<script src="https://kabot.your-name.workers.dev/widget.js" data-site="my-site" async></script>

A round button appears in the bottom-right corner. Clicking it opens a form with name, email and message fields.

Other ways to send messages:

8. Send a test message

Open your website, click the button, fill in the form and press Send. The message arrives in Telegram:

📬 My site · #1 · 🔵 New
From: Sara <sara@example.org>
Page: https://example.com/contact
At: 2026-11-12 09:14 UTC

Hello! I'd like to ask about your services.

[ ✅ Mark read ]  [ 🗄 Archive ]

Press Mark read or Archive to change its status. Using the bot describes the rest.

If nothing arrives, see Troubleshooting.

Next steps

  • Turn on Turnstile to stop automated spam.
  • Add another site with a second POST /admin/sites. One deployment serves any number of sites.
  • Read the security model to see what each protection covers.

Edit this page on GitHub