СОЗДАВАЙТЕ ВМЕСТЕ

Ваши идеи.
Внутри Teamyfy.

Подключайте ботов и инструменты к сообществам. Автоматизируйте ответы, команды и модерацию с разрешениями, которые задаёт владелец группы.

Создать первую интеграцию Посмотреть API

HTTPS + JSON: Нативный API
Явные разрешения: Приложение, ключ и установка
Защищённый runtime: Шифрование на стороне клиента

01 / НАЧАЛО РАБОТЫ

Первый бот — от приложения до подключения

Создайте приложение
Войдите в Teamyfy, откройте Настройки → Боты → Создать приложение. Выберите только необходимые разрешения. Новое приложение по умолчанию приватное.
Добавьте его в сообщество
В настройках нужной группы откройте раздел «Боты». Выберите каналы и разрешения установки. Для приватного приложения используйте отдельный ключ добавления, который выпускает владелец приложения. Публичные приложения доступны в поиске авторизованным пользователям.
Сохраните API-ключ
В настройках приложения откройте «Ключи и подключение» и выпустите ключ. Он показывается один раз и действует до отзыва. Храните его только у оператора бота: отдельно от исходного кода, браузера, журналов и ключа добавления.
Проверьте доступ
Из доверенного окружения выполните запрос идентификации ниже. Переменную TEAMYFY_BOT_TOKEN задайте через защищённое окружение процесса. Пример читает сведения о боте и ничего не отправляет в чаты.

Terminal · нативный Bot API

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bot ${TEAMYFY_BOT_TOKEN}" \
  https://teamyfy.ru/api/bot/v1/me

Ответ содержит applicationId, botUserId, name и scopes. Успешный запрос подтверждает ключ; доступ к сообщениям дополнительно требует текущей установки и криптографического допуска.

02 / ДОСТУП

Три разных границы авторизации

Назначение	Адрес и заголовок	Что разрешает
Пользователь	`https://teamyfy.ru/api/v1` `Authorization: Bearer <access-token>`	Действия текущего пользователя. Управление своими приложениями; установка ботов при наличии прав в группе.
Нативный бот	`https://teamyfy.ru/api/bot/v1` `Authorization: Bot <tmb_…>`	Действия отдельного Bot principal в пределах приложения, ключа и установки. Не даёт доступа к API владельца.
Приватный SDK	`http://127.0.0.1:8788/discord/api/v10` `Authorization: Bot <local-token>`	Связь SDK с runtime этого же бота. Отдельный локальный токен; не публикуйте этот адрес в интернете.

Разрешение действует только если его допускают текущие настройки приложения, API-ключ и установка для конкретного канала. Gateway intents определяют подписки SDK и не заменяют права сервера. Расширение прав приложения не расширяет ранее выданные ключи и установки.

Ключ добавления приватного приложения — отдельное приглашение, а не API-ключ. Передавайте его в JSON-теле installationKey, никогда в URL. Документация не принимает и не сохраняет ваши ключи.

Разрешения приложения

Возможность	Имена scopes
Каналы и участники	`channels.read`, `members.read`
Сообщения и история	`messages.read`, `messages.write`, `messages.manage`, `history.read`
Медиа и реакции	`embed_links`, `attachments.read`, `attachments.write`, `reactions.write`
Модерация и выбранные роли	`members.moderate`, `roles.assign`
Команды и ответы	`commands.manage`, `interactions.respond`
Голос	`voice.connect`, `voice.speak`, `voice.listen`

Начните с минимального набора для своей задачи. history.read не выдаёт ключи прежней истории автоматически; roles.assign ограничен выбранными ролями, а voice.listen — отдельное разрешение на получение аудио.

03 / РАЗРАБОТКА БОТА

Знакомый SDK, нативная доставка

Профиль Teamyfy для discord.js 14.27.0 сохраняет реальные Client, события и Message.reply, но подключается к изолированному runtime Teamyfy. Это ограниченная совместимость, а не публичный Discord-прокси.

Интеграция находится в исходном пакете bot-runtime/sdk-js. Пример ниже запускается из его корня, после npm ci --ignore-scripts --no-audit --no-fund, в Node.js 22.12 или новее. Это локальный пакет; команда установки несуществующего npm-пакета здесь не требуется.

JavaScript · файл в bot-runtime/sdk-js

import { Client, Events } from './src/index.js';

const client = new Client({
  origin: process.env.TEAMYFY_BOT_LOCAL_ORIGIN
});

client.on(Events.MessageCreate, async message => {
  if (!message.author.bot && message.inGuild()
      && message.content === '!ping') {
    await message.reply({
      content: 'pong',
      allowedMentions: { parse: [], repliedUser: false }
    });
  }
});

await client.login(process.env.TEAMYFY_BOT_LOCAL_TOKEN);

Что подготовить до запуска

Нативное приложение бота, ключ и установку в выбранные каналы.
Защищённый JVM runtime с подходящей нативной MLS-библиотекой и выделенным защищённым хранилищем; Python facade и, если нужен голос, RTC-пакет. Это отдельные компоненты, один JS-файл их не устанавливает.
TEAMYFY_BOT_LOCAL_ORIGIN, например http://127.0.0.1:8788, и отдельный TEAMYFY_BOT_LOCAL_TOKEN. Бот и runtime должны быть в одном приватном сетевом окружении.
Сохранённые идентичность, ключ защиты хранилища и состояние runtime между перезапусками. Не создавайте новую идентичность при каждом старте.

Python facade запускает защищённый JVM subprocess; он использует TEAMYFY_BOT_API_BASE_URL=https://teamyfy.ru/api/bot/v1, файлы credential/store key и постоянное состояние. Точные параметры поставляются в botRuntime/README.md клиентского репозитория и bot-runtime/runtime/README.md серверного. SDK не должен получать ключи комнат или MLS.

Этот пример показывает обработчик команды. Полная установка runtime и доставка на ваших устройствах требуют отдельной проверки. Не включайте отладочное логирование объектов SDK или расшифрованных тел сообщений.

04 / СПРАВОЧНИК

Нативный Bot API v1

Базовый адрес: https://teamyfy.ru/api/bot/v1. Все маршруты ниже требуют Authorization: Bot …. Идентификаторы установки — UUID; числовые идентификаторы в JSON бота передаются строками, без преобразования в JavaScript Number.

Метод и путь	Назначение и граница
GET `/me`	Идентичность приложения и эффективные права его ключа.
GET `/installations`	Доступные этому боту установки с выбранными каналами и правами.
GET `/installations/{installationId}/channels`	Разрешённые каналы. Само чтение списка не выполняет MLS-допуск.
GET `/installations/{installationId}/members`	Участники в пределах текущей установки; `after` и `limit` от 1 до 100.
GET `/installations/{installationId}/roles`	Роли сообщества, доступные боту; наличие роли в списке не разрешает её назначать.
GET `/installations/{installationId}/channels/{channelId}/events`	События после `after`, `limit` 1–100. Нужны актуальные права и зарегистрированный `X-XChat-Device-Id`. Содержимое сообщений зашифровано.
GET `/installations/{installationId}/channels/{channelId}/messages`	Доступная история: `before` / `after`, `limit` 1–100. Требуются устройство, допуск и отдельное разрешение для прежней истории.
POST `/installations/{installationId}/channels/{channelId}/secure/applications`	Приём подписанного зашифрованного сообщения от допущенного устройства. Используйте защищённый runtime; JSON с открытым текстом не является запросом этого маршрута.
POST `/direct-conversations`	Создание или получение личного диалога при проверенных общих установке/участии и ограничениях получателя. Не даёт произвольного доступа ко всем пользователям.
GET `/capabilities`	Консервативный базовый список: `application_identity`, `installation_grants`. Сейчас это не полный каталог реализованных маршрутов.

Это выбранный справочник, не полная OpenAPI-спецификация. Также существуют семейства команд, взаимодействий, вложений, модерации, истории и голосовых сессий. Их права и протоколы не сводятся к одному токену: для прикладного кода используйте реализованный адаптер runtime.

05 / ПОЛЬЗОВАТЕЛЬСКИЕ ИНТЕГРАЦИИ

API пользователя и управление приложением

Базовый адрес: https://teamyfy.ru/api/v1. После входа клиент использует Authorization: Bearer …. Bot API-ключ не заменяет пользовательскую сессию. Для автоматизации сообщества предпочтителен отдельный бот с ограниченными правами, а не пароль владельца.

Метод и путь	Контракт
POST `/auth/login`	JSON `{email, password, clientName?, clientPlatform?}`; заголовок `X-XChat-Device-Id` задаёт стабильный ID клиента. Без Bot-авторизации. Ответ содержит access token, срок и refresh proof для обычного native-потока.
POST `/auth/refresh`	JSON с `refreshToken` и тем же устройством. Сохраняйте новую пару access/refresh proof, возвращённую сервером; не выводите её в журналы.
GET `/profile/me`	Собственный профиль текущего авторизованного пользователя.
GET / POST `/bot-applications`	Список своих приложений / создание: `{name, scopes, visibility?}`. Видимость по умолчанию `PRIVATE`.
PATCH `/bot-applications/{applicationId}`	Владелец изменяет `{scopes, visibility, expectedRevision}`. Устаревшая ревизия возвращает 409.
POST `/bot-applications/{applicationId}/credentials`	Владелец выпускает отдельный API-ключ с `{scopes}`; значение показывается только в ответе выпуска.
POST `/communities/{communityId}/bot-installations`	`{applicationId, scopes, channelIds, allowedRoleIds?, installationKey?}`. Сервер повторно проверяет права управляющего и текущую политику приложения.
POST `/auth/realtime-ticket`	Текущая сессия получает короткоживущий ticket для realtime. Это не замена ботовому Gateway и не разрешение обходить доступ к каналам.

Terminal · чтение собственного профиля

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${TEAMYFY_ACCESS_TOKEN}" \
  https://teamyfy.ru/api/v1/profile/me

Здесь показан bearer-поток для доверенного клиента. Web-клиент Teamyfy использует отдельный защищённый cookie-поток с проверками Origin. Документация на dev.teamyfy.ru не выполняет вход, не переносит cookies между хостами и не предоставляет OAuth-приложение для стороннего сайта.

06 / ДАННЫЕ

Допуск к каналу не равен всей его истории

Сообщения обрабатываются через нативный MLS-протокол. Сервер хранит зашифрованные конверты; runtime проверяет подпись, идентичность устройства, текущий доступ и состояние канала, затем открывает содержимое локально. API-ключ сам по себе не расшифровывает сообщение.

Обычный доступ бота начинается с эпохи допуска — FROM_JOIN_EPOCH. Прежняя история требует отдельного текущего grant для установки и канала, подготовки ключей и проверки каждого сообщения.
Состояние pending_keys означает, что ключи ещё не подготовлены. Оно не даёт права пропустить проверку или читать содержимое другим способом.
Личные ответы доступного бота подготавливаются по серверной политике общих установок и участия; блокировки получателя сохраняют силу. Права приложения не предоставляют историю чужих личных диалогов.
Повторы одной отправки должны сохранять clientMessageId и исходный защищённый конверт. После неоднозначного результата не создавайте новую отправку вслепую.
Вложения шифрует runtime. URL не должен содержать ключ расшифрования, токен доступа или ключ комнаты.

07 / НАДЁЖНОСТЬ

Обрабатывайте причину, а не только статус

Ответ	Действие клиента
`400`	Проверьте схему, ID, Content-Type и границы параметров. Не повторяйте неизменённый запрос.
`401`	Остановите запросы от недействующей сессии/ключа. Бот не может восстановить доступ паролем владельца.
`403` / `404`	Проверьте текущую установку, разрешения и доступность ресурса. Не обходите отказ сохранённым plaintext или старым grant.
`409`	Проверьте точный код конфликта и текущую ревизию. Результат изменения может требовать сверки; универсальный повтор записи небезопасен.
`429`	Соблюдайте `retry_after` и `X-RateLimit-Bucket`. Runtime автоматически повторяет только проверенное нативное отклонение `RATE_LIMITED` до выполнения обработчика, в пределах общего дедлайна.
Таймаут / обрыв сети	Отличайте недоступность транспорта от ошибки криптографической проверки. Для записи сначала выясните результат по сохранённой идентичности операции.
`501` в адаптере	Эта операция SDK не поддержана. Не считайте пустой ответ успешным выполнением.

События могут доставляться повторно. Храните курсор и обрабатывайте повтор по идентичности события. После разрыва восстанавливайте пропуски через предусмотренный runtime replay; утрата доступного окна требует нового snapshot, а не выдачи старых сообщений за новые команды.

08 / ГРАНИЦЫ ПОДДЕРЖКИ

Что учитывать перед интеграцией

Один runtime — один бот. Отдельные процессы, локальные токены и хранилища для разных приложений. Один Gateway shard на runtime.
SDK не означает полную совместимость Discord. Проверяйте конкретные команды и модули. Произвольные плагины, threads и часть операций с вложениями/реакциями могут возвращать явную ошибку.
Голос имеет отдельный протокол. @discordjs/voice и Discord UDP/DAVE не поддерживаются. Музыкальные адаптеры используют приватный PCM/LiveKit runtime с текущими voice.connect/voice.speak/voice.listen правами; прослушивание не включается по умолчанию.
Локальный OpenAPI не является общим API ботов. contracts/bot-v1/runtime.openapi.json описывает приватный музыкальный интерфейс. Его нельзя размещать как публичный proxy или использовать вместо описанных нативных маршрутов.
Документация не обещает доступ без проверки. Авторизация, блокировки, текущие grants и криптографические проверки остаются обязательными для каждого ресурса.

Справочник относится к реализованным маршрутам API v1. Отдельные возможности зависят от разрешений, версии runtime и состояния допуска. Для сообщения об ошибке используйте обратную связь в Teamyfy; не прикладывайте API-ключи, пароли или содержимое приватных хранилищ.