API ИИ-агента

Проверить токен

GET /api/v1/me

Возвращает название, права и срок действия токена и агента, к которому он привязан. Подходит для проверки настройки интеграции: работает с любым правом.

Право: любое

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/me

Ответ

{
  "token": {
    "id": "6f1c2a9e-4b7d-4f0e-9a51-0c3d2e8b7a10",
    "name": "CRM",
    "prefix": "usv_agt_Ab3x",
    "scopes": ["read", "ask"],
    "createdAt": "2026-10-25T09:12:44.000Z",
    "expiresAt": "2027-01-23T09:12:44.000Z"
  },
  "agent": { "id": "1a2b3c4d-…", "name": "Консультант магазина" }
}

Агент и его каналы

GET /api/v1/agents/{agentId}

Имя агента, состояние экземпляра и подключённые мессенджеры. Статусы каналов берутся из базы, без опроса агента — запрос быстрый.

Право: read

Поля ответа

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID

Ответ

{
  "id": "1a2b3c4d-…",
  "name": "Консультант магазина",
  "status": "ACTIVE",
  "instanceStatus": "RUNNING",
  "channels": [
    { "messenger": "TELEGRAM", "status": "CONNECTED", "account": null, "updatedAt": "2026-10-20T08:00:00.000Z" }
  ]
}

Каналы со сверкой входа

GET /api/v1/agents/{agentId}/channels

Как каналы в предыдущем методе, но запущенный агент дополнительно сверяет, что аккаунт мессенджера действительно вошёл. Медленнее — используйте, когда нужен точный статус.

Право: read

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/channels

Ответ

{ "channels": [ { "messenger": "VK", "status": "CONNECTED", "account": null, "updatedAt": "…" } ] }

Состояние агента

GET /api/v1/agents/{agentId}/instance

Запущен ли экземпляр агента. Ответы в мессенджерах, «ответ агента» и отправка работают только в состоянии RUNNING.

Право: read

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/instance

Ответ

{ "status": "RUNNING", "error": null }

Запустить, остановить или перезапустить

POST /api/v1/agents/{agentId}/instance

Время работы агента оплачивается по тарифу личного кабинета: запуск проверяет баланс владельца. Агент поднимается 1–3 минуты — опрашивайте состояние, пока не увидите RUNNING.

Право: manage

Тело запроса (JSON)

Запрос

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"start"}' https://usveree.ru/api/v1/agents/$AGENT_ID/instance

Ответ

{ "status": "STARTING" }

Возможные ошибки: INSUFFICIENT_BALANCE, INSTANCE_BUSY, INSTANCE_LIMIT_REACHED, START_FAILED

Статистика

GET /api/v1/agents/{agentId}/stats

Суммарное время работы, число запусков, журнал запусков и остановок, объём переписки за 7 и 30 дней и расход ИИ (токены и списания в копейках).

Право: read

• messages.out7d и out30d считают только ответы агента — без ручных сообщений и отправленного через API.

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/stats

Ответ

{
  "instance": { "status": "RUNNING", "totalUptimeSeconds": 864000, "starts": 4 },
  "messages": { "in7d": 312, "out7d": 280, "in30d": 1290, "out30d": 1144, "chats": 87 },
  "events": [ { "kind": "START", "detail": null, "at": "2026-10-20T08:00:00.000Z" } ],
  "ai": {
    "keySource": "SERVICE",
    "tokens": {
      "today": { "prompt": 41000, "completion": 5200, "calls": 38 },
      "d7": { "prompt": 302000, "completion": 39000, "calls": 290 },
      "d30": { "prompt": 1250000, "completion": 160000, "calls": 1180 }
    },
    "costKop": { "today": 210, "d7": 1580, "d30": 6400 }
  }
}

Чаты мессенджера

GET /api/v1/agents/{agentId}/chats

Чаты, которые видит аккаунт, и чаты, известные агенту по истории. chatId отсюда подходит для истории чата и для отправки сообщения.

Право: read

Параметры запроса

Поля ответа

• Запрос опрашивает аккаунт мессенджера и может занять до 30 секунд.

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  "https://usveree.ru/api/v1/agents/$AGENT_ID/chats?messenger=TELEGRAM"

Ответ

{
  "chats": [
    {
      "chatId": "512345678",
      "userId": "512345678",
      "title": "Анна",
      "type": "PERSONAL",
      "url": "https://t.me/anna_example",
      "messages": 14,
      "autoReply": "AUTO",
      "autoReplyDefault": true,
      "pausedUntil": null,
      "sendBlocked": false,
      "available": true,
      "leftAt": null
    }
  ],
  "liveAvailable": true
}

Лента переписки

GET /api/v1/agents/{agentId}/conversations

Все сообщения агента по всем чатам, новые сверху, — как вкладка «ПЕРЕПИСКА»: входящие с исходом, ответы агента, ручные сообщения, отправленное через API и комментарии под постами.

Право: read

Параметры запроса

Поля ответа

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  "https://usveree.ru/api/v1/agents/$AGENT_ID/conversations?show=unanswered&limit=20"

Ответ

{
  "entries": [
    {
      "id": "0b9e…",
      "kind": "MESSAGE",
      "direction": "IN",
      "at": "2026-10-25T10:02:11.000Z",
      "messenger": "TELEGRAM",
      "chatId": "512345678",
      "chatTitle": "Анна",
      "chatType": "PERSONAL",
      "chatUrl": "https://t.me/anna_example",
      "senderName": "Анна",
      "text": "Здравствуйте! Есть доставка в Казань?",
      "author": null,
      "reply": "PENDING",
      "context": null,
      "deleted": false
    }
  ],
  "nextCursor": "2026-10-25T10:02:11.123456Z|0b9e…"
}

История чата

GET /api/v1/agents/{agentId}/messages

Сообщения одного чата в хронологическом порядке (старые сверху). Служебные сообщения мессенджера не возвращаются.

Право: read

Параметры запроса

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  "https://usveree.ru/api/v1/agents/$AGENT_ID/messages?messenger=TELEGRAM&chatId=512345678&limit=20"

Ответ

{
  "messages": [
    { "id": "…", "direction": "IN", "author": null, "senderId": "512345678", "senderName": "Анна", "text": "Здравствуйте! Есть доставка в Казань?", "at": "2026-10-25T10:02:11.000Z" },
    { "id": "…", "direction": "OUT", "author": "AGENT", "senderId": null, "senderName": null, "text": "Здравствуйте, Анна! Да, доставляем в Казань за 2–3 дня. Подсказать стоимость?", "at": "2026-10-25T10:02:48.000Z" }
  ],
  "hasMore": true,
  "nextBefore": "2026-10-24T18:40:05.000Z"
}

Получить ответ агента на текст

POST /api/v1/agents/{agentId}/ask

Агент отвечает тем же способом, что в живом чате: по своему промту, правилам поведения и инструментам (поиск по сайту, каталог). Ничего не отправляется в мессенджеры и не сохраняется в переписку. Работает и при выключенных авто-ответах; нужен запущенный агент. Расход ИИ учитывается и списывается как обычно.

Право: ask

Тело запроса (JSON)

Поля ответа

• Ответ может занять до 170 секунд, если агент обращается к инструментам. Ставьте таймаут клиента не меньше 180 секунд.
• Историю диалога храните на своей стороне и передавайте в history — сервер её не запоминает.

Запрос

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  --max-time 180 \
  -d '{"text":"Сколько стоит доставка в Казань?","history":[{"role":"user","text":"Здравствуйте"}]}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/ask

Ответ

{
  "shouldRespond": true,
  "message": "Доставка в Казань — 390 ₽, бесплатно от 5 000 ₽.",
  "reason": "вопрос о доставке",
  "action": null,
  "deliverTo": "chat",
  "toolCalls": [ { "tool": "search_site", "status": "OK", "errorCode": null, "durationMs": 820 } ]
}

Возможные ошибки: NO_BALANCE, AI_NOT_CONNECTED, AGENT_OUTDATED, INSTANCE_NOT_RUNNING, AGENT_UNAVAILABLE

Очередь модерации

GET /api/v1/agents/{agentId}/pending-replies

Ответы, ждущие решения: входящее сообщение и подготовленный агентом ответ.

Право: moderate

Параметры запроса

Поля ответа

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/pending-replies

Ответ

{
  "replies": [
    {
      "id": "c7d1…",
      "messenger": "TELEGRAM",
      "chatId": "512345678",
      "chatTitle": "Анна",
      "chatType": "PERSONAL",
      "chatUrl": "https://t.me/anna_example",
      "messageUrl": null,
      "sender": { "id": "512345678", "name": "Анна" },
      "incomingText": "Здравствуйте! Есть доставка в Казань?",
      "replyText": "Здравствуйте, Анна! Да, доставляем в Казань за 2–3 дня. Подсказать стоимость?",
      "suggestedDeliverTo": "chat",
      "reason": "MANUAL",
      "kind": "MESSAGE",
      "createdAt": "2026-10-25T10:02:12.000Z",
      "fromPreviousAccount": false
    }
  ]
}

Отправить ответ из очереди

POST /api/v1/agents/{agentId}/pending-replies/{replyId}/send

Отправляет подготовленный ответ — как есть или с правкой. Без deliverTo ответ уходит туда, куда предложил агент.

Право: moderate

Тело запроса (JSON)

Запрос

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"text":"Здравствуйте, Анна! Да, доставляем в Казань за 2–3 дня. Подсказать стоимость?"}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/pending-replies/$REPLY_ID/send

Ответ

{ "sent": true }

Возможные ошибки: REPLY_NOT_FOUND, REPLY_ALREADY_DECIDED, CHAT_NOT_JOINED, TARGET_OFF, ACCOUNT_PAUSED, SEND_FAILED, CHANNEL_UNAVAILABLE

Отклонить ответ из очереди

POST /api/v1/agents/{agentId}/pending-replies/{replyId}/ignore

Ответ не отправляется и уходит из очереди.

Право: moderate

Запрос

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/pending-replies/$REPLY_ID/ignore

Ответ

{ "ok": true }

Возможные ошибки: REPLY_NOT_FOUND, REPLY_ALREADY_DECIDED

Отправить сообщение в чат

POST /api/v1/agents/{agentId}/messages

Сообщение уходит от имени подключённого аккаунта в чат, который агент уже знает: он есть в списке чатов или в переписке. В «ПЕРЕПИСКЕ» оно подписано «API» и попадает в контекст агента как его реплика.

Право: send

Тело запроса (JSON)

• Защита от бана действует как для ответов агента: выключенный адресат и пауза мессенджера отправку не пропускают.
• Отправки через API считаются в лимит «ответов в час» из настроек агента.

Запрос

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"messenger":"TELEGRAM","chatId":"512345678","text":"Ваш заказ №1024 передан в доставку."}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/messages

Ответ

{ "sent": true, "messageId": "5e0f…" }

Возможные ошибки: CHAT_NOT_FOUND, DAILY_LIMIT, CHAT_NOT_JOINED, TARGET_OFF, ACCOUNT_PAUSED, SEND_FAILED, CHANNEL_UNAVAILABLE, AGENT_OUTDATED, INSTANCE_NOT_RUNNING

Промты

GET /api/v1/agents/{agentId}/prompts

Промты по мессенджеру (ALL — общий для всех) и типу чата: PERSONAL — личные чаты, GROUP — группы, COMMENT — комментарии под постами. «Триггер» описывает, когда агенту реагировать, «Реакция» — как отвечать.

Право: manage

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/prompts

Ответ

{
  "prompts": [
    {
      "id": "…",
      "messenger": "ALL",
      "scope": "PERSONAL",
      "triggerText": "Отвечай на вопросы о товарах и доставке.",
      "reactionText": "Вежливо, коротко, на «вы». Предлагай оформить заказ.",
      "allowDm": false,
      "autoRespond": true,
      "enabled": true,
      "replyAsQuote": true,
      "updatedAt": "2026-10-20T08:00:00.000Z"
    }
  ]
}

Изменить промт

PATCH /api/v1/agents/{agentId}/prompts

Создаёт или меняет промт одной пары «мессенджер + тип чата». Неуказанные поля остаются прежними. Агент подхватывает изменения сразу.

Право: manage

Тело запроса (JSON)

Запрос

curl -s -X PATCH -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"scope":"PERSONAL","reactionText":"Отвечай коротко и дружелюбно."}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/prompts

Ответ

{ "prompt": { "id": "…", "messenger": "ALL", "scope": "PERSONAL", "…": "…" } }

Возможные ошибки: UNKNOWN_FIELD, INVALID_FIELD

Настройки агента

GET /api/v1/agents/{agentId}/settings

Авто-отправка, задержка и лимит ответов, расписание, передача оператору, правила поведения и защита от бана.

Право: manage

Запрос

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/settings

Ответ

{
  "settings": {
    "autoSend": true,
    "maxRepliesPerHour": 40,
    "replyDelaySeconds": 30,
    "scheduleEnabled": false,
    "scheduleMode": "SILENT",
    "scheduleDays": [1, 2, 3, 4, 5, 6, 7],
    "scheduleStart": "09:00",
    "scheduleEnd": "21:00",
    "scheduleTz": "Europe/Moscow",
    "offHoursPolicy": "IGNORE",
    "handoverEnabled": true,
    "handoverPauseMinutes": 60,
    "ruleHideInternals": true,
    "ruleFactsOnly": true,
    "ruleAbuseBlock": true,
    "ruleBotQuestion": "DEFLECT",
    "ruleHumanHandoff": true,
    "rulePromptGuard": true,
    "ruleStopTopics": true,
    "botDisplayName": "",
    "burstWaitSeconds": 15,
    "memoryEnabled": true,
    "strikeAutoBlock": true,
    "accountGuard": true
  }
}

Изменить настройки

PATCH /api/v1/agents/{agentId}/settings

Передайте только поля, которые меняете. Значение вне допустимого диапазона отклоняется с ошибкой, а не поправляется молча.

Право: manage

Тело запроса (JSON)

Запрос

curl -s -X PATCH -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"autoSend":false,"replyDelaySeconds":20}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/settings

Ответ

{ "settings": { "autoSend": false, "replyDelaySeconds": 20, "…": "…" } }

Возможные ошибки: UNKNOWN_FIELD, INVALID_FIELD