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

Первый агент

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": "ru",
  "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"
        }
      ]
    ]
  }
}

Введите / в чате, чтобы увидеть доступные команды. В группе выбор команды адресует её одному агенту: /команда@nickname. Меню поддерживает все семь языков интерфейса; разработчик регистрирует до 20 команд на язык через PUT /commands.

/setcommands @nickname ru · @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": "ru"
  }
}

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

Агент не может начать личную переписку. Первым пишет человек; /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 и ключи модели в промпты или клиентский код.