Troubleshooting and FAQ
Messages don't arrive in the chat
First, check whether the message was stored and what happened to its notification:
npx wrangler d1 execute DB --remote --command \
"SELECT id, site_id, notified_at, notify_attempts, notify_error FROM messages ORDER BY id DESC LIMIT 5"- No row. The submission was refused. Look at the response in the browser's developer tools (Network tab, the
messagesrequest) or at the error from@mtnaskari/kabot/client, and see the sections below. notify_errorisNo chat is paired with this site.Link a chat; see Linking chats.notify_errormentionsbot token is not configured. The chat is on a platform without a token. SetTELEGRAM_BOT_TOKENorBALE_BOT_TOKEN.Forbidden: bot was blocked by the user. Unblock the bot in that chat.chat not foundorgroup chat was upgraded to a supergroup. The chat no longer exists under that id. Link it again with a new code.Unauthorized. The bot token is wrong or was revoked. Set the current one.
Failed notifications are retried every ten minutes, up to five times within two days, so after you fix the cause the message usually arrives without anything else to do.
The widget doesn't appear
Open the browser's developer tools and check the console.
[kabot] widget.js needs a data-site attribute.Adddata-site="your-site-id"to the script tag.[kabot] data-target … matched no element.The inline target doesn't exist when the page loads. Check the selector.- The script fails to load. Check the
srcaddress, and your Content Security Policy. - No error, no button. Some ad blockers hide floating chat buttons. Try a private window without extensions.
The form says the origin isn't allowed
The page's origin must exactly match an entry in the site's allowedOrigins. Common mismatches:
https://example.comandhttps://www.example.comare different origins. Add both if both are used.- Local development addresses such as
http://localhost:3000must be added too. - Preview deployments get their own hostnames. Add them, or use a separate site for previews.
See Change the allowed origins.
The form says verification failed
The site has Turnstile enabled and the token was missing or rejected.
- In the Cloudflare dashboard, make sure the Turnstile widget lists the page's hostname.
- Make sure the site key and secret stored on the site belong to the same Turnstile widget.
- If you changed
KABOT_SECRET, store the Turnstile secret again. - If you use your own form, render the Turnstile challenge and send its token as
turnstileToken.
The bot does not answer
curl "$KABOT/admin/webhooks" -H "Authorization: Bearer $ADMIN_TOKEN"urlisnull. The webhook isn't registered. RunPOST /admin/webhooks.lastErroris set andpendingUpdatesis growing. The platform can't deliver to the Worker. Register the webhook again on the address the Worker actually serves, for example after moving to a custom domain or changingKABOT_SECRET.okisfalse. The bot token is wrong.- In a group, send the command with the bot's username, such as
/start@your_bot <code>, because of Telegram's privacy mode.
The pairing code is invalid or has expired
Codes work once and expire one hour after they are created. Create a new one with POST /admin/sites/:id/pairing-codes. Make sure the whole code was sent; it has 20 characters. After five attempts in a minute from one chat, the bot asks you to wait.
Too many messages
Visitors are limited to 5 messages a minute and DAILY_LIMIT_PER_IP (20 by default) a day for each site. People who share an IP address, for example in an office, share these limits. Raise DAILY_LIMIT_PER_IP or the RATE_LIMITER limit in wrangler.toml if needed; see Rate limits.
For server submissions without visitorIp, all requests share 60 a minute for the site. Pass visitorIp.
The API key is refused
401 unauthorized. The key is wrong, or it was rotated or revoked. Issue a new one withPOST /admin/sites/:id/api-key.400 bad_request: API keys must not be used from a browser.The request has anOriginheader. API keys only work from servers. In browsers, use browser mode withsiteinstead.
FAQ
Can I reply to visitors from the chat? No. kabot delivers messages to you; it doesn't send anything back to visitors. Reply by email to the address in the message.
Does my website's server need to reach Telegram? No. Only the Cloudflare Worker talks to Telegram or Bale. Your server either does nothing (the widget talks to the Worker directly) or makes one HTTPS request to the Worker.
Can one deployment serve several websites? Yes. Create a site for each one. Each has its own origins, API key, Turnstile settings and linked chats.
Can several people receive the same site's messages? Yes. Link each person's chat with its own pairing code, or link a group. Status changes appear in every chat.
Can I use Telegram and Bale together? Yes. Set both tokens. Each chat is on one platform, and a site can have chats on both.
Where are messages stored, and for how long?
In the D1 database in your Cloudflare account, until you delete them. Set RETENTION_DAYS to delete archived messages automatically.
Are visitors' IP addresses stored? No. Only a keyed hash, used to count messages per visitor.
Can visitors attach files? No. Messages are text only.
Does kabot work without JavaScript on the page? The widget needs JavaScript. A plain HTML form can post to your own backend, which then calls kabot with the API key.