Connecting large language models (LLMs) directly to Telegram-бот via a standard text prompt quickly runs into limitations: the model has no access to your database, cannot check order statuses, and cannot create bookings in a CRM. The solution to this problem is the Tool Calling (Function Calling) mechanism.
In this article, we will break down how to build a reliable Agent Loop in Node.js, where the model independently decides to call the get_order or create_booking function, while the server executes the code and returns the result back to the model to generate the final response for the client.
Interaction Architecture: Telegram, Node.js, and LLM
The main principle of building secure AI bots is strict separation of concerns. The language model is merely a reasoning engine, but it has no direct access to external APIs, your database, or especially to Telegram Bot API.
- Telegram Client sends a Webhook to your Node.js server.
- Node.js Backend receives
update_id, verifies authorization, and passes the message history to the LLM along with the description of available tools (Tool Schemas). - OpenAI LLM returns a
tool_callsinstruction with a function name and a valid JSON argument instead of text. - Node.js Backend executes local code (a DB/CRM request), receives the result, and sends it back to the LLM.
- OpenAI LLM generates the final text response for the user based on the received data.
- Node.js Backend sends the final message to the user via the
sendMessagemethod of the Telegram Bot API.
Why the Model Should Never Know the Telegram Bot Token
Security Rule: Never pass the
TELEGRAM_BOT_TOKENinto the system prompt or LLM context parameters. Models are vulnerable to Prompt Injection attacks. If an attacker tricks the model into revealing the system prompt or executing arbitrary code, the compromised token will allow a complete takeover of your bot.
The Telegram token must reside exclusively in environment variables (process.env.TELEGRAM_BOT_TOKEN) of your Node.js environment. All requests to the Telegram API are executed solely by the backend.
Defining Tool Schemas (Tools Definition)
In order for the model to understand what actions are available to it, we describe tools using JSON Schema format. Let us look at two common scenarios: retrieving order status (get_order) and creating a service booking (create_booking).
// tools.js
export const toolsSchema = [
{
type: "function",
function: {
name: "get_order",
description: "Получить информацию о статусе и составе заказа по его ID",
parameters: {
type: "object",
properties: {
order_id: {
type: "string",
description: "Идентификатор заказа, например, ORD-12345"
}
},
required: ["order_id"]
}
}
},
{
type: "function",
function: {
name: "create_booking",
description: "Забронировать слот на услугу для клиента",
parameters: {
type: "object",
properties: {
service_name: {
type: "string",
description: "Название услуги (например, 'Консультация' или 'Стрижка')"
},
date_time: {
type: "string",
description: "Дата и время в ISO формате, например 2025-04-10T15:00:00"
},
customer_name: {
type: "string",
description: "Имя клиента"
}
},
required: ["service_name", "date_time", "customer_name"]
}
}
}
];
Implementing the Tool Calling Cycle (Agent Loop)
After receiving a response from the model, you need to check the finish_reason field or the presence of the tool_calls array. If the model decided to call a function, we execute the corresponding handler, append its response to the message array with the tool role, and repeat the request to the LLM.
// agent.js
import OpenAI from "openai";
import { toolsSchema } from "./tools.js";
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
// Имитация работы с базой данных / CRM
async function executeTool(name, args) {
if (name === "get_order") {
// В реальном проекте: SELECT * FROM orders WHERE id = args.order_id
if (args.order_id === "ORD-12345") {
return JSON.stringify({ status: "shipped", items: ["Ноутбук"], delivery_date: "2025-03-30" });
}
return JSON.stringify({ error: "Заказ не найден" });
}
if (name === "create_booking") {
// В реальном проекте: INSERT INTO bookings ...
const bookingId = "BK-" + Math.floor(1000 + Math.random() * 9000);
return JSON.stringify({ success: true, booking_id: bookingId, details: args });
}
throw new Error(`Неизвестный инструмент: ${name}`);
}
export async function processUserMessage(userMessage, chatHistory = []) {
const messages = [
{ role: "system", content: "Вы — вежливый ассистент поддержки. Используйте инструменты для получения данных и создания записей." },
...chatHistory,
{ role: "user", content: userMessage }
];
let runner = true;
let iterations = 0;
const maxIterations = 5; // Защита от бесконечного цикла
while (runner && iterations < maxIterations) {
iterations++;
const response = await openai.chat.completions.create({
model: "gpt-4o-mini",
messages: messages,
tools: toolsSchema,
tool_choice: "auto"
});
const responseMessage = response.choices[0].message;
messages.push(responseMessage);
if (responseMessage.tool_calls && responseMessage.tool_calls.length > 0) {
for (const toolCall of responseMessage.tool_calls) {
const functionName = toolCall.function.name;
const functionArgs = JSON.parse(toolCall.function.arguments);
const functionResult = await executeTool(functionName, functionArgs);
messages.push({
tool_call_id: toolCall.id,
role: "tool",
name: functionName,
content: functionResult
});
}
} else {
runner = false;
return responseMessage.content;
}
}
return "К сожалению, не удалось обработать запрос. Попробуйте позже.";
}
Integration with Telegram Webhook and Deduplication
In case of emergency situations or server response delays exceeding 5 seconds, Telegram may resend the exact same Update. To avoid duplicate function calls (for example, re-creating a booking), let's implement an update_id check and validation of the X-Telegram-Bot-Api-Secret-Token header.
// server.js
import express from "express";
import { processUserMessage } from "./agent.js";
const app = express();
app.use(express.json());
const processedUpdates = new Set();
const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
const SECRET_TOKEN = process.env.TELEGRAM_SECRET_TOKEN;
async function sendTelegramMessage(chatId, text) {
const url = `https://api.telegram.org/bot${BOT_TOKEN}/sendMessage`;
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: chatId,
text: text,
parse_mode: "HTML"
})
});
const data = await response.json();
if (!response.ok || !data.ok) {
console.error("Telegram API Error:", data);
}
}
app.post("/webhook", async (req, res) => {
const incomingSecret = req.headers["x-telegram-bot-api-secret-token"];
if (incomingSecret !== SECRET_TOKEN) {
return res.status(403).send("Unauthorized");
}
const update = req.body;
if (!update || !update.update_id) {
return res.status(400).send("Bad Request");
}
// Идемпотентность: пропуск уже обработанных update_id
if (processedUpdates.has(update.update_id)) {
return res.status(200).send("OK");
}
processedUpdates.add(update.update_id);
// Очистка старых update_id для предотвращения утечки памяти
if (processedUpdates.size > 10000) {
const firstItem = processedUpdates.values().next().value;
processedUpdates.delete(firstItem);
}
// Отвечаем Telegram 200 OK незамедлительно, чтобы избежать таймаута
res.status(200).send("OK");
if (update.message && update.message.text) {
const chatId = update.message.chat.id;
const userText = update.message.text;
try {
const replyText = await processUserMessage(userText);
await sendTelegramMessage(chatId, replyText);
} catch (error) {
console.error("Error processing agent loop:", error);
await sendTelegramMessage(chatId, "Произошла ошибка при обработке вашего запроса.");
}
}
});
app.listen(3000, () => {
console.log("Server started on port 3000");
});
Common Mistakes When Working with Tool Calling
- Response Delay (Timeout 5000ms): An LLM with function calling can take anywhere from 2 to 8 seconds to generate a response. Be sure to return a
200 OKstatus to Telegram immediately upon receiving the Webhook, while performing processing and sendingsendMessageasynchronously. - Lack of Argument Validation: The LLM may generate invalid JSON or pass a string argument instead of a number. Always wrap
JSON.parse()in atry...catchblock and validate data types before passing them to your business logic. - No Iteration Limit: If the model starts calling functions repeatedly in a loop, it will drain your API balance. Always limit the
whileloop with a counter (for example, no more than 5 iterations).
If you require professional development of complex AI bots and CRM integrations, contact the specialists at BotCreator.