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

# Telegram bot

> Receive leads and manage proposals directly from Telegram with Quikly's native bot integration.

The Telegram bot integration lets you receive client inquiries, run AI discovery, and create proposals without leaving Telegram. When a lead messages your bot, Quikly creates a lead session and guides you through the proposal flow.

## Set up the Telegram bot

<Steps>
  <Step title="Create a bot with BotFather">
    Open Telegram and message [@BotFather](https://t.me/BotFather). Send `/newbot`, follow the prompts, and copy the **bot token** it gives you.
  </Step>

  <Step title="Connect the bot to Quikly">
    In the Quikly app, go to **Settings → Integrations → Telegram**. Paste your bot token and save.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Test the bot">
    Open your bot in Telegram and send a message. You should see a response from the Quikly agent confirming the connection.
  </Step>
</Steps>

## How it works

When a client messages your Telegram bot:

1. Quikly creates a **lead session** linked to the Telegram chat ID
2. The AI agent runs **technical discovery** — asking about the project, stack, timeline, and budget
3. Once enough information is gathered, you receive a notification to **review the lead**
4. You can start **Agent Mode** from the lead session to generate a full proposal
5. 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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/telegram` route is not blocked by a firewall or reverse proxy
    * Look at the backend logs for error details
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](https://ngrok.com) to expose your local server, then update the webhook URL in Quikly settings.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>