Set up the Telegram bot
Create a bot with BotFather
Open Telegram and message @BotFather. Send
/newbot, follow the prompts, and copy the bot token it gives you.Connect the bot to Quikly
In the Quikly app, go to Settings → Integrations → Telegram. Paste your bot token and save.
Webhook is set automatically
Quikly registers a webhook with Telegram so your bot receives messages. You don’t need to configure the webhook URL manually.
How it works
When a client messages your Telegram bot:- Quikly creates a lead session linked to the Telegram chat ID
- The AI agent runs technical discovery — asking about the project, stack, timeline, and budget
- Once enough information is gathered, you receive a notification to review the lead
- You can start Agent Mode from the lead session to generate a full proposal
- When the proposal is ready, share the link back to the client via Telegram
Bot capabilities
| Feature | Description |
|---|---|
| Lead intake | Receives project inquiries from clients |
| AI discovery | Asks qualifying questions about the project |
| Lead sessions | Tracks conversation state and collected data |
| Notifications | Alerts you when a new lead arrives or a client responds |
| Multi-bot (Agency plan) | Connect up to 3 separate bots for different brands or teams |
Plan availability
| Plan | Telegram bots |
|---|---|
| Starter | Not available |
| Professional | 1 bot |
| Agency | Up to 3 bots |
| Lifetime | 1 bot |
Troubleshooting
Bot is not responding to messages
Bot is not responding to messages
Check the webhook URL. Go to Settings → Integrations → Telegram and verify the webhook is registered. You can click Re-register Webhook to reset it.If you recently moved environments or changed your backend URL, the webhook may be pointing to an old address.
Bot responds with errors or generic messages
Bot responds with errors or generic messages
Verify your API key is active. The Telegram integration uses your Quikly API key internally. If the key was revoked or expired, the bot cannot communicate with the Quikly API.Go to Settings → API Keys and check that you have at least one active key.
Webhook returns 404 or 500 errors
Webhook returns 404 or 500 errors
This typically means the Quikly backend webhook endpoint is unreachable:
- Confirm the backend is running and accessible at the configured URL
- Check that the
/api/webhooks/telegramroute is not blocked by a firewall or reverse proxy - Look at the backend logs for error details
Messages go to the wrong user
Messages go to the wrong user
Each Telegram bot is linked to one Quikly account. If multiple team members need bots, use the Agency plan which supports up to 3 bots, each linked to a different team member or brand.Verify the bot token in Settings matches the bot you’re testing with.
Bot works locally but not in production
Bot works locally but not in production
Telegram webhooks require a publicly accessible HTTPS URL.
localhost or private IPs will not work.If you’re testing locally, use a tunneling tool like ngrok to expose your local server, then update the webhook URL in Quikly settings.Duplicate lead sessions for the same chat
Duplicate lead sessions for the same chat
Quikly de-duplicates lead sessions by
channel + channel_id. If a session already exists for a Telegram chat ID and its status is not completed or provider_rejected, new messages continue the existing session.If you’re seeing duplicates, check whether old sessions were marked as completed — new messages after completion create a new session.