Доступ к ассистенту

Как устроен доступ

У ассистента один владелец (user_id) и список пользователей с доступом (shared_user_ids в объекте ассистента). Ролей две: владелец и пользователь с доступом.

	Владелец	Расшаренный пользователь
Видит ассистента в GET /assistants и в дашборде	да	да
Настройки, агенты, первые экраны, пейволл, языки, домены, Telegram	да	да
Подписчики, платежи, начисление кредитов, обращения	да	да
Ключ ассистента: получить и перевыпустить	да	да
Посмотреть, кому открыт ассистент	да	да
Выдать доступ и закрыть его другим	да	нет
Закрыть доступ себе	—	да
Удалить ассистента	да	нет

Расшаренный пользователь заходит в дашборд под своим аккаунтом и работает со своим личным ключом user_… — ключ владельца ему не нужен.

Выдаёт и закрывает доступ только владелец. Пользователь с доступом может лишь отказаться от него сам — убрать себя из списка; на любую другую запись в список он получает 403.

Методы

Кому открыт ассистент

Возвращает владельца и список пользователей с доступом.

GET /assistants/{assistantId}/access

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	id ассистента, в пути

curl -s "$BASE/assistants/$ASSISTANT/access" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "owner": {
    "id": 1,
    "public_id": "u_a1b2c3d4e5",
    "name": "Анна",
    "email": "owner@example.com"
  },
  "shared": [
    { "id": 517, "email": "tg_100000001@telegram.local", "name": "Иван" },
    { "id": 533, "email": "user@example.com", "name": "Мария" },
    …
  ]
}

Поле	Тип	Описание
owner	object или null	Владелец: id, public_id, name, email
shared	array	Пользователи с доступом: id, email, name. Пустой массив — ассистент никому не открыт

У пользователей, вошедших через Telegram, почта служебная: tg_<telegram id>@telegram.local.

HTTP	Когда
404	{"error": "Project not found or access denied"} — ассистент чужой или не существует

Открыть доступ

Добавляет пользователя в список доступа. Доступно только владельцу. Повторная выдача ничего не меняет.

Открыть доступ можно только человеку из круга ассистента: у него уже есть диалог с ассистентом, платёж, начисленные кредиты или обращение в поддержку. Проще всего попросить коллегу один раз открыть ассистента, войдя в свой аккаунт. Незарегистрированная почта и человек вне круга дают одинаковый ответ 404 — по нему нельзя узнать, есть ли такой аккаунт на площадке.

POST /assistants/{assistantId}/access

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	id ассистента, в пути
user	string	да	Кому открыть, в теле. Почта (если есть @), числовой id или public_id вида u_…

curl -s -X POST "$BASE/assistants/$ASSISTANT/access" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "colleague@example.com"}'

Ответ — обновлённый список shared:

{
  "success": true,
  "shared": [
    { "id": 533, "email": "user@example.com", "name": "Мария" },
    { "id": 8120, "email": "colleague@example.com", "name": "Олег" }
  ]
}

HTTP	Когда
400	{"error": "User is the project owner"} — это владелец ассистента
403	{"error": "Only the project owner can manage access"} — запрос сделан не владельцем
404	{"error": "User not found among this project's users", "message": "…"} — пусто в user, такого человека нет или он не из круга ассистента
404	{"error": "Project not found or access denied"} — ассистент чужой или не существует
422	{"error": "Anonymous users cannot be granted access"} — гостевой аккаунт без входа

Закрыть доступ

Убирает пользователя из списка доступа. Владелец может убрать любого, пользователь с доступом — только себя. Пользователь ищется только в списке доступа: кого там нет, того метод не находит (404), и ответ ничего не говорит о людях вне списка.

DELETE /assistants/{assistantId}/access/{userRef}

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	id ассистента, в пути
userRef	string	да	Кого убрать, в пути: почта, числовой id или public_id. Почту кодируйте: @ как %40

curl -s -X DELETE "$BASE/assistants/$ASSISTANT/access/8120" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "shared": [
    { "id": 533, "email": "user@example.com", "name": "Мария" }
  ]
}

HTTP	Когда
403	{"error": "Only the project owner can manage access", "message": "A shared user can remove only their own access"} — пользователь с доступом пытается убрать не себя
404	{"error": "User has no shared access to this project"} — такого человека нет в списке доступа
404	{"error": "Project not found or access denied"} — ассистент чужой или не существует

warning

Доступ почти равен владению

Пользователь с доступом видит почты всех, кому открыт ассистент, меняет пейволл и кассы, начисляет кредиты и перевыпускает ключ ассистента. Когда сотрудник уходит, закрывайте ему доступ сразу.

Дальше

• Авторизация
• Ассистенты