Агенти у ваших чатах

Перший агент

1. Відкрийте @agentfather та надішліть /newagent. Укажіть ім’я й унікальний нік із закінченням _agent (7–32 символи).
2. Натисніть кнопку токена у відповіді менеджера. Підтвердьте випуск і збережіть токен на власному сервері. Він показується один раз в окремому вікні та не потрапляє в історію чату.
3. Запустіть приклад на Python на власному сервері й напишіть агенту. Його логіка та ШІ працюють у вашій інфраструктурі: створення агента не запускає модель.

curl https://znosin.com/api/agent/v1/me \
  -H "Authorization: Bearer $ZNOSIN_AGENT_TOKEN"

ZNOSIN_AGENT_TOKEN · Python 3.10+

Доступно у v1

Отримуйте натискання через GET /updates?callbacks=true. Оновлення містить message або callback. Дані кнопки надходять із сервера, користувач — callback.from. Перевіряйте права у власній системі. Відповідайте через POST /callbacks/{id}/answer із text та showAlert. Клієнт чекає до 10 секунд; натискання діє 120 секунд. Повтор однакової відповіді безпечний. Натискання не створює повідомлення. Webhook і завантаження вихідних вкладень поки не підтримуються.

Довідник API

HTTPS і JSON. Передавайте Authorization: Bearer <token>. Успіх містить ok і result, помилка — ok:false та error. Час повідомлень — Unix у мілісекундах. Повні поля запитів і відповідей доступні у схемі OpenAPI.

https://znosin.com/api/agent/v1

POST /api/agent/v1/messages

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Hello!",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee"
}

PUT /api/agent/v1/commands

{
  "language": "uk",
  "commands": [
    {
      "command": "help",
      "description": "Посібник Agent API"
    }
  ]
}

Команди та кнопки

Додайте markup до POST /messages або PATCH /messages/{id}: рядки inline містять дії (text, id, data), HTTPS-посилання (text, url) або міні-застосунки (text, appId). Клавіатура reply надсилає звичайні повідомлення у відповідь агенту. oneTime ховає її після використання; type remove прибирає клавіатуру. Під час редагування пропустіть markup, щоб зберегти кнопки, або передайте null, щоб видалити їх.

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Choose an action",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee",
  "markup": {
    "type": "inline",
    "rows": [
      [
        {
          "text": "Confirm",
          "id": "confirm",
          "data": "confirm:123"
        },
        {
          "text": "Cancel",
          "id": "cancel",
          "data": "cancel:123"
        }
      ],
      [
        {
          "text": "Website",
          "url": "https://znosin.com"
        },
        {
          "text": "Calculator",
          "appId": "calculator"
        }
      ]
    ]
  }
}

Введіть / у чаті, щоб побачити команди. У групі вибір команди адресує її одному агенту: /command@nickname. Меню підтримує сім мов інтерфейсу; розробник реєструє до 20 команд на мову через PUT /commands.

/setcommands @nickname uk · @agentfather

{
  "type": "reply",
  "rows": [
    [
      "Yes",
      "No"
    ],
    [
      "Help"
    ]
  ],
  "oneTime": true
}

8 rows × 4 buttons · 64 characters/label · 256 UTF-8 bytes/data · HTTPS

Мова користувача

Вхідні повідомлення та натискання кнопок містять from.language_code: en, ru, uk, de, fr, pl або zh. Це мова інтерфейсу відправника на момент події, зокрема у групах. Для старих подій, невідомої мови й повідомлень самих агентів повертається null — оберіть запасну мову у своєму коді. Значення зберігається після перезапуску й повторних запитів; нові повідомлення, редагування та налаштування іншого пристрою його не змінюють. Пересилання містить мову того, хто пересилає, а не автора оригіналу. Це вподобання клієнта, а не визначення мови тексту чи підстава для надання прав. Клієнт передає X-Znosin-Language; запасне джерело — підтримувані мови з Accept-Language. Ваш код перекладає відповіді та кнопки. AgentFather слідує мові інтерфейсу; /language ru закріплює мову, /language auto повертає автоматичний вибір.

{
  "from": {
    "id": "USER_ID",
    "name": "Alex",
    "nickname": "alex",
    "language_code": "uk"
  }
}

Доступ і приватність

Агент не може почати приватну розмову. Першою пише людина; /stop блокує подальші повідомлення, /start відновлює роботу з нових повідомлень. У групі доступні лише команди на кшталт /help чи /help@name_agent та відповіді на повідомлення агента після його додавання. Цитована історія, старі повідомлення, пошта, гаманець і ключі власника не передаються. Видалення з групи відкликає доступ.

Надійна доставка

Long polling чекає до 25 секунд і відповідає з появою повідомлення. Використовуйте один обробник на агента та зберігайте nextOffset навіть за порожнього результату. Повторюйте надсилання з тим самим clientId і вмістом. Черга зберігає до 10 000 вхідних повідомлень до 24 годин; reset сигналізує про завершення строку чи переповнення. Ліміти: 180 запитів/хв, 60 надсилань/хв на агента, 30 надсилань/хв у чат. Дотримуйтеся Retry-After за 429 і 503 та збільшуйте паузу за мережевих помилок.

Керування агентом

Команди @agentfather: /myagents, /token @нік, /disable @нік, /enable @нік, /setname @нік Ім’я та /setdescription @нік Опис. Перевипуск одразу відкликає попередній токен. Вимкнення відкликає токен й очищає чергу. Після ввімкнення випустіть новий токен. /language en|ru|uk|de|fr|pl|zh обирає мову, /language auto слідує інтерфейсу. До 20 агентів на власника.

Підключіть ШІ-модель

Замініть повтор тексту в прикладі викликом моделі на власному сервері. Повідомте користувачам, які дані передаються провайдеру моделі. Вважайте повідомлення й файли недовіреним вводом, обмежуйте права інструментів та вимагайте підтвердження людини для важливих дій. Не додавайте токени Znosin і ключі моделі до промптів чи клієнтського коду.