Quick Start

This guide walks you through creating an AI agent (bot), configuring its behaviour, and connecting it to a Telegram chat — all via the Worken REST API. The same flow works for any supported channel.

Prerequisites

• A Worken account with at least one project
• An API key (see Authentication)
• curl or the worken npm package installed

1. Install the SDK (optional)

You can call the REST API directly with curl, or use the official TypeScript SDK:

npm install worken
# or
bun add worken

import { WorkenClient } from 'worken'

const worken = new WorkenClient({ apiKey: process.env.WORKEN_API_KEY })

2. Create a bot

A bot (also called a virt) is the AI agent that will handle conversations.

curl https://api.worken.ru/bots \
  -X POST \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Bot"}'

const bot = await worken.bots.create({ name: 'Support Bot' })
console.log(bot.id) // bot_01j...

bot = client.bots.create(name="Support Bot")
print(bot.id)  # bot_01j...

The response:

type Bot = {
  id: string
  name: string
  status: 'active' | 'disabled' | 'error'
  project_id: string
  created_at: string
}

3. Configure the agent

Set the system instruction, AI model, and parameters using the settings endpoint:

curl https://api.worken.ru/bots/${BOT_ID}/settings \
  -X POST \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "ai": {
      "instruction": "You are a friendly support agent for Acme Inc. Answer concisely and always offer to escalate if you are unsure.",
      "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:
      'You are a friendly support agent for Acme Inc. Answer concisely and always offer to escalate if you are unsure.',
    model: {
      id: 'openai/gpt-4o-mini',
      temperature: 0.4,
      max_tokens: 1024,
    },
    memory: {
      lastMessages: 20,
      semanticRecall: true,
      workingMemory: { enabled: true },
      generateTitle: true,
    },
  },
})

Available models

Model ID	Notes
openai/gpt-4o	Highest quality
openai/gpt-4o-mini	Fastest, lowest cost
anthropic/claude-3-5-sonnet	Excellent reasoning
google/gemini-2.0-flash	Best for long context
yandex/yandexgpt-pro	Russian-language optimised

4. Create an integration

An integration is a connection to an external platform (Telegram, WhatsApp, amoCRM, etc.) that delivers messages to your bot.

Connect Telegram

curl https://api.worken.ru/integrations \
  -X POST \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Telegram Bot",
    "vendor": "telegram",
    "auth_data": {
      "token": "7123456789:AAHxxxxxxx"
    }
  }'

const integration = await worken.integrations.create({
  name: 'My Telegram Bot',
  vendor: 'telegram',
  auth_data: { token: process.env.TELEGRAM_BOT_TOKEN },
})

The response includes an id you will use in the next step.

5. Create a chat and connect it to the bot

A chat represents a specific channel within an integration (e.g. a Telegram group or direct-message inbox) associated with your bot.

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": "Customer Support"
  }'

const chat = await worken.integrations.chats.create(integration.id, {
  bot_id: bot.id,
  name: 'Customer Support',
})

6. Activate the chat

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')

Your bot is now live. Any message sent to the Telegram bot will be processed by the AI agent and answered automatically.

7. Monitor conversations

List active threads (conversations) for the chat:

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)
}

Subscribe to real-time thread events via 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. Send a message as an operator

When a thread is in manual mode, operators can send messages directly:

await worken.threads.send(thread.id, {
  text: 'Let me transfer you to a specialist who can help.',
})

Complete example

import { WorkenClient } from 'worken'

const worken = new WorkenClient({ apiKey: process.env.WORKEN_API_KEY })

async function setup() {
  const bot = await worken.bots.create({ name: 'Support Bot' })

  await worken.bots.settings.update(bot.id, {
    ai: {
      instruction: 'You are a helpful support agent.',
      model: { id: 'openai/gpt-4o-mini', temperature: 0.3 },
    },
  })

  const integration = await worken.integrations.create({
    name: 'Telegram Support',
    vendor: 'telegram',
    auth_data: { token: process.env.TELEGRAM_BOT_TOKEN },
  })

  const chat = await worken.integrations.chats.create(integration.id, {
    bot_id: bot.id,
    name: 'Customer Support',
  })

  await worken.integrations.chats.setStatus(integration.id, chat.id, 'active')

  console.log('Bot is live! Chat ID:', chat.id)
}

setup()

Next steps

Learn more

Endpoints Reference

Full list of available endpoints with request and response types

↗

Learn more

worken npm package

MCP tool hosting and TUI for your agents

↗

Learn more

Channels

Connect WhatsApp, VK, Avito, amoCRM, and more

↗

Learn more

Agent settings

Fine-tune memory, tools, and formatting

↗