Быстрый старт
В этом руководстве мы создадим AI-агента (бота), настроим его поведение и подключим к Telegram — всё через Worken REST API. Тот же подход работает для любого поддерживаемого канала.
Предварительные требования
- Аккаунт Worken с хотя бы одним проектом
- API-ключ (см. Аутентификация)
curlили пакетworkenустановлен
Все примеры в этом руководстве обращаются к публичному REST API https://api.worken.ru с Bearer API‑ключами. Внутри инфраструктуры Worken также есть внутренний API с заголовками Worken-*, но он недоступен внешним клиентам — для интеграций используйте только API‑ключи из раздела Аутентификация.
1. Установите SDK (опционально)
Можно вызывать REST API напрямую через curl, или использовать официальный TypeScript SDK:
npm install worken
# или
bun add workenimport { WorkenClient } from 'worken'
const worken = new WorkenClient({ apiKey: process.env.WORKEN_API_KEY })2. Создайте бота
Бот (также называемый виртс) — это AI-агент, который будет обрабатывать диалоги.
curl https://api.worken.ru/bots \
-X POST \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{"name": "Бот поддержки"}'const bot = await worken.bots.create({ name: 'Бот поддержки' })
console.log(bot.id) // bot_01j...bot = client.bots.create(name="Бот поддержки")
print(bot.id) # bot_01j...Ответ:
type Bot = {
id: string
name: string
status: 'active' | 'disabled' | 'error'
project_id: string
created_at: string
}3. Настройте агента
Задайте системную инструкцию, AI-модель и параметры через эндпоинт настроек:
curl https://api.worken.ru/bots/${BOT_ID}/settings \
-X POST \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{
"ai": {
"instruction": "Ты дружелюбный специалист поддержки компании Acme. Отвечай кратко и предлагай передать вопрос оператору, если не уверен в ответе.",
"model": {
"id": "openai/gpt-4o-mini",
"temperature": 0.4,
"max_tokens": 1024
},
"memory": {
"lastMessages": 20,
"semanticRecall": true,
"workingMemory": { "enabled": true },
"generateTitle": true
}
}
}'await worken.bots.settings.update(bot.id, {
ai: {
instruction:
'Ты дружелюбный специалист поддержки компании Acme. Отвечай кратко и предлагай передать вопрос оператору, если не уверен в ответе.',
model: {
id: 'openai/gpt-4o-mini',
temperature: 0.4,
max_tokens: 1024,
},
memory: {
lastMessages: 20,
semanticRecall: true,
workingMemory: { enabled: true },
generateTitle: true,
},
},
})Доступные модели
| ID модели | Примечание |
|---|---|
openai/gpt-4o | Максимальное качество |
openai/gpt-4o-mini | Самая быстрая, минимальная стоимость |
anthropic/claude-3-5-sonnet | Отличное рассуждение |
google/gemini-2.0-flash | Лучший длинный контекст |
yandex/yandexgpt-pro | Оптимизирован для русского языка |
4. Создайте интеграцию
Интеграция — это подключение к внешней платформе (Telegram, WhatsApp, amoCRM и др.), через которую сообщения доставляются боту.
Подключить Telegram
curl https://api.worken.ru/integrations \
-X POST \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{
"name": "Мой Telegram бот",
"vendor": "telegram",
"auth_data": {
"token": "7123456789:AAHxxxxxxx"
}
}'const integration = await worken.integrations.create({
name: 'Мой Telegram бот',
vendor: 'telegram',
auth_data: { token: process.env.TELEGRAM_BOT_TOKEN },
})Ответ содержит id, который используется на следующем шаге.
5. Создайте чат и подключите его к боту
Чат — это конкретный канал внутри интеграции (Telegram-группа, входящие сообщения, виджет), связанный с вашим ботом.
curl https://api.worken.ru/integrations/${INTEGRATION_ID}/chats \
-X POST \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{
"bot_id": "bot_01j...",
"name": "Поддержка клиентов"
}'const chat = await worken.integrations.chats.create(integration.id, {
bot_id: bot.id,
name: 'Поддержка клиентов',
})6. Активируйте чат
curl https://api.worken.ru/integrations/${INTEGRATION_ID}/chats/${CHAT_ID}/status \
-X POST \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{"status": "active"}'await worken.integrations.chats.setStatus(integration.id, chat.id, 'active')Бот запущен. Любое сообщение в Telegram будет обработано AI-агентом и получит автоматический ответ.
7. Мониторинг диалогов
Список активных тредов (диалогов) в чате:
curl "https://api.worken.ru/threads?chat_id=${CHAT_ID}&limit=20" \
-H "Authorization: Bearer sk-..."const threads = await worken.threads.list({ chat_id: chat.id, limit: 20 })
for (const thread of threads.data) {
console.log(thread.id, thread.mode, thread.last_message_at)
}Подписка на события тредов в реальном времени через SSE:
const stream = worken.threads.events()
for await (const event of stream) {
// event.type: 'thread.updated' | 'message.created' | ...
console.log(event.thread_id, event.pending_count)
}8. Отправка сообщения оператором
Когда тред в режиме manual, оператор может писать напрямую:
await worken.threads.send(thread.id, {
text: 'Сейчас передам ваш вопрос специалисту.',
})Полный пример
import { WorkenClient } from 'worken'
const worken = new WorkenClient({ apiKey: process.env.WORKEN_API_KEY })
async function setup() {
const bot = await worken.bots.create({ name: 'Бот поддержки' })
await worken.bots.settings.update(bot.id, {
ai: {
instruction: 'Ты helpful специалист поддержки.',
model: { id: 'openai/gpt-4o-mini', temperature: 0.3 },
},
})
const integration = await worken.integrations.create({
name: 'Telegram поддержка',
vendor: 'telegram',
auth_data: { token: process.env.TELEGRAM_BOT_TOKEN },
})
const chat = await worken.integrations.chats.create(integration.id, {
bot_id: bot.id,
name: 'Поддержка клиентов',
})
await worken.integrations.chats.setStatus(integration.id, chat.id, 'active')
console.log('Бот запущен! ID чата:', chat.id)
}
setup()