Chatbots & Telegram

FleetQ lets you deploy AI-powered chatbots that interact with users via embeddable web widgets or Telegram. Every chatbot is backed by a FleetQ Agent, inheriting its model, skills, tools, and prompt configuration. Conversations are stored, analysed, and can feed back into the agent via learning entries.

Scenario: A SaaS company deploys a support chatbot on their docs site and a Telegram bot for their community. Both are powered by the same "Support Agent" in FleetQ. Corrections made via learning entries automatically improve future responses.

Overview

Creating a chatbot

Navigate to Chatbots in the sidebar and click New Chatbot, or use the API. The following fields are available:

curl -X POST /api/v1/chatbots \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "description": "Customer-facing support chatbot",
    "agent_id": "AGENT_ID",
    "greeting_message": "Hi! How can I help you today?",
    "appearance": {
      "primary_color": "#6366f1",
      "position": "bottom-right"
    }
  }'

Chatbot features

Web widget embed

Once a chatbot is created, copy the JavaScript snippet from its detail page and paste it before the closing </body> tag on any page.

<script
  src="https://your-fleetq-domain.com/widget.js"
  data-chatbot-id="CHATBOT_ID"
  data-token="CHATBOT_API_TOKEN"
  async
></script>

Session management

Every browser visitor receives a separate, isolated conversation. Sessions are identified by a unique session token stored in localStorage. Conversations persist across page reloads for the same visitor. Anonymous visitors are tracked by session; authenticated visitors can be identified by passing a user_id attribute to the widget script.

Learning entries

Operators can mark a chatbot response as incorrect and provide the expected answer. This creates a learning entry associated with the chatbot. The backing agent incorporates learning entries into its context on subsequent requests, improving accuracy over time without requiring a full fine-tune.

Knowledge base indexing

A chatbot can index external knowledge sources so its backing agent can answer with up-to-date, grounded information. Indexing runs on a schedule and stores chunks in the team's knowledge base with the chatbot's tag so retrieval stays scoped to this bot.

Human escalation

When the backing agent signals uncertainty (low confidence, explicit "I don't know", or a user clicking "Talk to a human"), the conversation is flagged for escalation. FleetQ creates a Human Task in the Approval Inbox with the full chat history so an operator can jump in, reply, and mark the session as resolved. The chatbot resumes AI control on the next inbound message unless the operator keeps the session locked.

Widget streaming & isolation

The widget is rendered inside a Shadow DOM so host-page CSS can never break it (and your widget styles can't bleed out into the host). Messages stream via Server-Sent Events (SSE) so users see the agent's reply token-by-token, exactly like a native chat product.

Analytics

The chatbot analytics summary tracks:

• Total conversations and messages
• Average response quality score
• User satisfaction ratings (thumbs up / thumbs down)
• Most common topics and unanswered questions

Chatbot API tokens

Each chatbot uses a dedicated API token scoped to that chatbot only. This token is embedded in the widget snippet and authenticates widget requests. Generate a token via the UI or the API:

POST /api/v1/chatbots/{id}/tokens

Telegram bots

Connect FleetQ to Telegram by registering a Telegram bot. Incoming Telegram messages are routed through FleetQ and processed by a configurable routing mode.

Routing modes

Chat bindings

A chat binding maps a specific Telegram chat (group, channel, or DM) to a FleetQ conversation context. Bindings allow you to route messages from different Telegram chats to different agents or workflows, keeping conversations isolated.

Webhook-based delivery

FleetQ receives Telegram updates via the Telegram Bot API webhook at /api/telegram/webhook/{teamId}. The webhook is authenticated with a secret token set during bot registration. Incoming updates are queued and processed asynchronously via ProcessTelegramMessageJob.

Telegram setup

# Via MCP tool
telegram_bot_manage(action="register", bot_token="YOUR_BOT_TOKEN", routing_mode="assistant")

MCP tools

All chatbot and Telegram operations are available as MCP tools for LLM agents and the FleetQ assistant.

API endpoints

Full OpenAPI 3.1 documentation is available at /docs/api. All endpoints require a Sanctum bearer token.