API

External Message API

Endpoint for sending messages from external integrations (Telegram, bots, webhooks) with persistent project/chat context.

POST/api/external/message

Required fields: sessionId, message.

Auth: header Authorization: Bearer <token> (from Token Management or EXTERNAL_API_TOKEN).

{
  "sessionId": "user-42",
  "message": "hello",
  "projectId": "my-project-id",
  "chatId": "optional-chat-id",
  "currentPath": "optional/relative/path"
}

Telegram Webhook

Telegram endpoint: POST /api/integrations/telegram. It reuses the same external session context engine as /api/external/message.

Configure credentials in Dashboard -> Messengers(bot token is enough; webhook secret/url are configured automatically).

curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://YOUR_PUBLIC_BASE_URL/api/integrations/telegram",
    "secret_token": "'$TELEGRAM_WEBHOOK_SECRET'"
  }'

Supported commands: /start, /help, /code <access_code>, /new.

API Token Management

Create a token for Authorization: Bearer ... and rotate it when needed.

Loading token status...

How Project Context Is Resolved

  1. If request includes projectId, it is used and saved as active for this session.
  2. Otherwise API uses session's current active project.
  3. If active project is missing and only one project exists, it is selected automatically.
  4. If multiple projects exist and message is not about project navigation, API returns 409 with available projects.

Project Navigation via Natural Language

The agent can answer project questions and switch projects using tools: list_projects, get_current_project, switch_project, create_project. When switch/create succeeds, session context is updated automatically for next requests.

Examples

1. Ask for projects

curl -X POST http://localhost:3000/api/external/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EXTERNAL_API_TOKEN" \
  -d '{
    "sessionId": "user-42",
    "message": "what projects are available?"
  }'

2. Switch by name

curl -X POST http://localhost:3000/api/external/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EXTERNAL_API_TOKEN" \
  -d '{
    "sessionId": "user-42",
    "message": "switch to the backend project"
  }'

3. Send normal message after switch

curl -X POST http://localhost:3000/api/external/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EXTERNAL_API_TOKEN" \
  -d '{
    "sessionId": "user-42",
    "message": "hello"
  }'

4. Create a new project from chat

curl -X POST http://localhost:3000/api/external/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EXTERNAL_API_TOKEN" \
  -d '{
    "sessionId": "user-42",
    "message": "create a new project named crm-support"
  }'

Successful Response Shape

{
  "success": true,
  "sessionId": "user-42",
  "reply": "assistant response",
  "context": {
    "activeProjectId": "backend",
    "activeProjectName": "Backend",
    "activeChatId": "b86f...",
    "currentPath": ""
  },
  "switchedProject": {
    "toProjectId": "backend",
    "toProjectName": "Backend"
  },
  "createdProject": null
}