RIDDYдокументация для разработчиков

Вход через форум

Добавьте на свой сайт кнопку «Войти через форум». Человек подтверждает вход на странице форума, а сайт получает его имя, фото, юзернейм, ID и почту Google. Пароль и переписка сайту не передаются.

1. Компания и проект

В форуме откройте Настройки → Для разработчиков → Вход через форум. Для этого к аккаунту должна быть привязана Google-почта (Настройки → «Аккаунт и вход»).

  1. Создайте компанию: название, логотип, адрес сайта https://example.com, ссылки на политику конфиденциальности и условия использования. Для компании автоматически создаётся публичный канал.
  2. Подтвердите сайт: добавьте в <head> главной страницы тег, который покажет форум, и нажмите «Проверить сайт»:
    <meta name="forum-site-verification" content="fv_...">
  3. Создайте проект: название, логотип, сайт и redirect_uri (оба на домене подтверждённого сайта компании, только https), почта поддержки, по желанию канал новостей. Заявку проверяют модераторы.
  4. После принятия нажмите «Секрет» у проекта: вы получите client_id и client_secret. Секрет показывается один раз, при перевыпуске старый перестаёт работать.

2. Отправьте человека на форум

https://rid3-forum.pages.dev/home/#/oauth?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&state=RANDOM

redirect_uri должен в точности совпадать с зарегистрированным. state придумайте сами (случайная строка, сохраните её в сессии) и сверьте при возврате, это защита от подделки запроса.

3. Человек вернётся к вам

REDIRECT_URI?code=ONE_TIME_CODE&state=RANDOM

Если человек нажал «Отмена»: ?error=access_denied&state=…. Если не привязан Google или аккаунт заморожен: ?error=5001&error_name=ERR%3A…&state=… (коды из таблицы ниже).

4. Обменяйте code на токен (с вашего сервера)

POST https://rid3-forum.pages.dev/api/oauth/token
Content-Type: application/json

{"client_id":"fp_...","client_secret":"fs_...","code":"ONE_TIME_CODE","redirect_uri":"REDIRECT_URI"}

→ 200 {"access_token":"ft_...","token_type":"Bearer","expires_in":3600}

Код одноразовый и живёт 5 минут. Поддерживается и форма application/x-www-form-urlencoded. Никогда не отправляйте client_secret в браузер.

5. Получите профиль

GET https://rid3-forum.pages.dev/api/oauth/userinfo
Authorization: Bearer ft_...

→ 200 {"id":"2108785060","username":"@hoshi_sky","name":"Имя","avatar":"https://…/api/avatar/…","email":"user@gmail.com"}

id постоянный, по нему узнавайте человека (имя и юзернейм можно менять; имена могут повторяться, юзернеймы нет). Если у человека нет юзернейма, вместо него приходит #ID. avatar равен null, если фото нет.

Публичная информация о проекте для вашей страницы: GET /api/oauth/info?client_id=…

Боты

Бот это обычный сервер на вашей стороне. Форум отправляет на него события, а сообщения от имени бота вы шлёте через API. В личном чате с ботом люди пишут ему сами или находят его по @юзернейму в поиске.

События на ваш сервер

Тип запроса (JSON, форма или GET) выбирается при создании бота. Поля:

ПолеОписание
eventmessage (сообщение боту или упоминание) или callback (нажата кнопка)
bot_id, message_id, timeномер бота, номер сообщения, время (мс)
textтекст сообщения (для callback то же, что data)
user_id, user_name, user_numкто написал или нажал
dataтолько для callback: значение нажатой кнопки
chatdm, если это личный чат с ботом

Подпись

В заголовке x-bot-signature лежит HMAC-SHA256 (hex) от тела запроса. Ключ: SHA-256 вашего токена в hex.

const key = sha256hex(BOT_TOKEN);
const sig = hmacSha256Hex(key, rawBody);
if (sig !== req.headers['x-bot-signature']) reject();

Ответ на событие

Ответьте текстом или JSON {"text":"…","buttons":[[…]]}. Текст уйдёт человеку (в личке) или в чат. Для callback ответ изменяет то же сообщение, а не создаёт новое.

Отправка сообщений

POST /api/bot/send
Authorization: Bot BOT_TOKEN

{"user_id":"…" | "user_num":2108785060,"text":"Привет","buttons":[[{"text":"Да","data":"yes"}]]}
→ {"ok":true,"id":123}

POST /api/bot/edit
{"message_id":123,"kind":"d","text":"Новый текст","buttons":null}   // kind: "d" — личка, "m" — общий чат

Без user_id/user_num сообщение уходит в общий чат. Писать можно тем, кто не заблокировал бота и не остановил его. Исправить можно только своё сообщение.

Кнопки под сообщением

Массив рядов, до 8 рядов по 8 кнопок:

[[ {"text":"Да","data":"yes","color":"#22aa55"}, {"text":"Сайт","url":"https://example.com"} ],
 [ {"text":"Отмена","data":"cancel"} ]]

Коды ошибок

Все ошибки API для разработчиков приходят в таком виде (HTTP-статус соответствует таблице):

{"ok":false,"code":"8010","error":"ERR:…","message":"…","http":401,"detail":"уточнение (необязательно)"}

Актуальный список в текстовом виде: /api/errors.

КодИмяОписаниеHTTP
0000ERR:UNKNOWN_ERRORНеизвестная или необработанная ошибка системы.500
0001ERR:MULTIPLE_ERRORS_OCCURREDПри обработке запроса произошло несколько ошибок.400
0002ERR:BATCH_PARTIAL_FAILUREЧасть операций в пакетном запросе завершилась с ошибкой.207
0003ERR:SYSTEM_MAINTENANCEСистема временно недоступна из-за проведения технического обслуживания.503
0004ERR:REQUEST_CANCELLEDВыполнение операции было отменено пользователем или таймаутом.499
0005ERR:DEPRECATED_API_VERSIONИспользуемая версия API устарела и больше не поддерживается.410
5000ERR:INTERNAL_API_ERRORВнутренняя необработанная ошибка API-сервера.500
5001ERR:THE_SERVER_REJECTED_THE_SESSIONСервер отклонил текущую сессию пользователя.403
5002ERR:SERVER_ERROR_ACCESS_DENIEDСервер отказал в доступе к ресурсу из-за внутренних правил.403
5003ERR:SERVICE_UNAVAILABLEСервер или микросервис временно перегружен.503
5004ERR:MANY_REQUESTSПревышен лимит частоты отправки запросов (Rate Limit).429
5005ERR:DATABASE_TIMEOUTПревышено время ожидания ответа от базы данных.504
5006ERR:GATEWAY_BAD_RESPONSEПолучен некорректный ответ от внутреннего микросервиса.502
5007ERR:THIRD_PARTY_SERVICE_FAILUREСбой при вызове стороннего внешнего сервиса.502
5008ERR:FEATURE_DISABLEDЗапрашиваемый функционал отключен конфигурацией сервера.501
5009ERR:DATABASE_CONNECTION_FAILEDОшибка подключения к серверу баз данных.500
6000ERR:FRONTEND_RENDER_ERRORОшибка рендеринга компонента UI в JavaScript Runtime.0
6001ERR:CLIENT_STATE_CORRUPTEDПовреждение локального состояния приложения (Store/LocalStorage).0
6002ERR:STORAGE_QUOTA_EXCEEDEDПревышен лимит локального хранилища браузера (LocalStorage/IndexedDB).0
6103ERR:CONNECTION_FAILUREНе удалось установить соединение с сервером на стороне клиента.0
6104ERR:UNSUPPORTED_BROWSERБраузер не поддерживает требуемые Web API.0
6105ERR:ASSET_LOAD_FAILEDСбой при загрузке статического бандла (JS/CSS/Font).0
6106ERR:SCRIPT_EXECUTION_TIMEOUTПревышено время выполнения клиентского скрипта.0
7000ERR:NETWORK_OFFLINEУ пользователя отсутствует подключение к сети Интернет.0
7001ERR:CONNECTION_REFUSEDСервер отклонил сетевое соединение на транспортном уровне.0
7002ERR:CONNECTION_TIMED_OUTПревышено время ожидания установления TCP/IP соединения.504
7003ERR:DNS_LOOKUP_FAILEDНе удалось разрешить доменное имя сервера через DNS.0
7004ERR:DNS_NAME_NOT_RESOLVEDДоменное имя не существует или не найдено в DNS (NXDOMAIN).0
7005ERR:DNS_SERVER_FAILEDDNS-сервер вернул ошибку обработки запроса (SERVFAIL).0
7006ERR:DNS_TIMED_OUTПревышено время ожидания ответа от DNS-сервера.0
7007ERR:DNS_PROBE_FINISHED_NXDOMAINПроверка DNS завершена: имя хоста не найдено.0
7008ERR:DNS_REFUSEDDNS-сервер отказался выполнять запрос.0
7009ERR:DNSSEC_VALIDATION_FAILEDОшибка проверки подлинности цифровой подписи DNSSEC.0
7010ERR:SSL_HANDSHAKE_FAILEDСбой при установке защищенного TLS/SSL соединения.0
7011ERR:CORS_POLICY_VIOLATIONЗапрос заблокирован политикой безопасности браузера (CORS).0
7012ERR:WEBSOCKET_DISCONNECTEDПостоянное WebSocket-соединение разорвано.0
7013ERR:PROXY_AUTHENTICATION_REQUIREDПромежуточный прокси-сервер требует авторизации.407
8000ERR:BAD_REQUESTНекорректный синтаксис запроса или некорректный JSON.400
8001ERR:INVALID_PAYLOAD_FORMATПереданные данные не соответствуют ожидаемой JSON-схеме.422
8002ERR:MISSING_REQUIRED_FIELDВ запросе отсутствует обязательное поле.422
8003ERR:INVALID_PARAMETER_VALUEПереданное значение параметра не прошло валидацию.422
8004ERR:RESOURCE_NOT_FOUNDЗапрашиваемый ресурс не найден.404
8005ERR:PAYLOAD_TOO_LARGEРазмер передаваемых данных превышает допустимый лимит.413
8006ERR:UNSUPPORTED_MEDIA_TYPEЗаголовок Content-Type не поддерживается эндпоинтом.415
8007ERR:DUPLICATE_RESOURCEЗапись с такими уникальными идентификаторами уже существует.409
8008ERR:UNAUTHORIZEDДля выполнения запроса требуется аутентификация.401
8009ERR:TOKEN_EXPIREDСрок действия токена доступа (Access Token) истек.401
8010ERR:INVALID_TOKENПередан недействительный или поврежденный токен.401
8011ERR:FORBIDDEN_ACCESSУчетная запись не имеет прав на выполнение этого действия.403
8012ERR:ACCOUNT_LOCKEDАккаунт заблокирован из-за нарушений или подозрительной активности.403