Перейти к содержанию

Быстрый старт

Этот раздел описывает минимальный путь для начала работы с LocalHub Robot API: создание робота, выпуск токена и выполнение первого запроса.

Шаг 1. Войти в LocalHub

Установите приложение LocalHub. Зарегистрируйтесь или войдите в существующий аккаунт.

Робот создаётся в аккаунте пользователя и действует от его имени только в пределах явно выданных разрешений.

Шаг 2. Открыть раздел LocalHub Robot

В приложении LocalHub перейдите:

Настройки аккаунта → Разработчикам → LocalHub Robot

В этом разделе доступны создание роботов, управление разрешениями, выпуск и отзыв токенов, а также отключение роботов.

Шаг 3. Создать робота

Нажмите «Создать робота» и заполните форму:

  1. Имя робота — произвольная подпись, по которой удобно его узнать в списке, например chat-monitor или analytics-bot.
  2. Права (scopes) — отметьте галочками те разрешения, которые действительно нужны интеграции.

Для первого запроса достаточно разрешения account.read. Для работы с чатами потребуется chats.read.

Полный перечень разрешений приведён в разделе Общие сведения об API.

После сохранения робот появится в списке со статусом «активен».

Принцип наименьших прав

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

Шаг 4. Выпустить токен

Откройте карточку только что созданного робота и нажмите «Выпустить токен».

  • При необходимости укажите срок действия. Для производственных интеграций рекомендуется задавать срок действия и регулярно ротировать токены.
  • Нажмите «Создать».

После создания на экране появится секрет — строка вида lhrk_XjN4QBuhBiocsSEr4hCQdYUI....

Полный токен виден только в момент выпуска

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

В интерфейсе управления отображается только короткий префикс токена, например lhrk_XjN4QB..., чтобы его можно было отличить от других токенов.

Шаг 5. Первый запрос

Сохраните токен в переменную окружения:

export ROBOT_TOKEN='lhrk_XjN4QBuhBiocsSEr4hCQdYUI...'

Выполните запрос к профилю аккаунта. Метод требует scope account.read, который был выдан на предыдущем шаге:

curl -s 'https://robot.prod.lclhub.ru/v1/account' \
  -H "Authorization: Bearer $ROBOT_TOKEN" | jq

Ожидаемый ответ:

{
  "id": "019560a1-b2c3-7def-8901-234567890abc",
  "username": "alice",
  "display_name": "Alice Johnson",
  "bio": "Photographer & traveler",
  "avatar_url": "https://cdn.localhub.example/avatars/alice.jpg",
  "is_verified": true,
  "created_at": "2025-06-15T10:30:00Z"
}

Если API вернул JSON с профилем, токен действителен и разрешение account.read настроено корректно.

Что дальше

  • Общие сведения об API — доступные методы, разрешения, лимиты и формат ошибок.
  • Чаты — подписка на групповые чаты и получение новых событий через механизм обновлений.
  • GET /v1/robot — информация о текущем роботе и токене.
  • GET /v1/robot/limits — текущие лимиты использования API.

Управление роботами

В разделе Разработчикам → LocalHub Robot доступно:

  • Список роботов — все роботы аккаунта, их имена, текущий набор scopes и состояние.
  • Список токенов робота — выпущенные токены, их префиксы, даты создания, срок действия и статус. Полное значение токена не отображается.
  • Отозвать токен — сделать токен недействительным. После отзыва запросы с этим токеном получают 401.
  • Отключить робота — перевести робота в неактивное состояние. Все его токены перестают работать.

Типичные ошибки на старте

401 — нет авторизации или токен невалиден

Заголовок Authorization отсутствует, не начинается с Bearer или токен невалиден, отозван либо истёк.

Проверьте, что используется полный токен с префиксом lhrk_. Если токен истёк или был отозван, выпустите новый в приложении LocalHub.

403 permission_denied

У робота нет нужного scope для этого endpoint'а. В теле ответа в поле details.required_scope указан недостающий scope.

Добавьте недостающее разрешение роботу или создайте нового робота с нужным набором разрешений.

429 rate_limit_exceeded / monthly_quota_exceeded

Превышен лимит запросов или израсходована месячная квота. В ответе есть заголовок Retry-After со временем в секундах, после которого можно повторить запрос.

503 service_unavailable

Сервис временно недоступен. Повторите запрос позже с экспоненциальной задержкой.