Назначить беседу

Назначить беседу агенту или команде

Метод запроса

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments

Авторизация

• userApiKey

• agentBotApiKey

Заголовки авторизации

api_access_token (string, обязательный) Заголовок

Этот токен можно получить на странице профиля или через консоль rails. Предоставляет доступ к конечным точкам в зависимости от уровня разрешений пользователя. Этот токен может быть сохранен внешней системой при создании пользователя через API для выполнения действий от имени пользователя.

Параметры пути

account_id (integer, обязательный) Числовой ID аккаунта

conversation_id (integer, обязательный) Числовой ID беседы

Тело запроса

application/json

assignee_id (number) ID пользователя-исполнителя Пример: 1

team_id (number) ID команды. Если присутствует assignee_id, этот параметр будет игнорироваться Пример: 1

Ответ

200 - Успешно

application/json

Возвращает информацию о назначенном пользователе

Основная информация пользователя

id (number) ID пользователя

name (string) Имя пользователя

email (string) Email пользователя

display_name (string | null) Отображаемое имя

available_name (string) Доступное имя

avatar_url (string) URL аватара пользователя

role (enum<string>) Роль пользователя Доступные варианты: agent, administrator

Системная информация

access_token (string) Токен доступа

account_id (number) ID аккаунта

confirmed (boolean) Подтвержден ли пользователь

message_signature (string | null) Подпись сообщения

hmac_identifier (string) HMAC идентификатор

inviter_id (number) ID пригласившего пользователя

provider (string) Провайдер аутентификации

pubsub_token (string) Токен PubSub

ui_settings (object) Настройки пользовательского интерфейса

uid (string) Уникальный идентификатор пользователя

type (string | null) Тип пользователя

custom_attributes (object) Доступно для пользователей, созданных через API платформы и имеющих связанные пользовательские атрибуты

Информация об аккаунтах

accounts (object[]) Массив аккаунтов пользователя

Структура объекта аккаунта

id (number) ID аккаунта

name (string) Название аккаунта

status (string) Статус аккаунта

active_at (string<date-time>) Время последней активности

role (enum<string>) Роль в аккаунте Доступные варианты: administrator, agent

permissions (string[]) Массив разрешений

availability (string) Доступность

availability_status (string) Статус доступности

auto_offline (boolean) Автоматический переход в оффлайн

custom_role_id (number | null) ID пользовательской роли

custom_role (object | null) Объект пользовательской роли

Примеры запросов

Назначение беседы конкретному агенту

curl --request POST \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "assignee_id": 456
}'

Назначение беседы команде

curl --request POST \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "team_id": 2
}'

Назначение беседы агенту и команде (приоритет у агента)

curl --request POST \
  --url https://helpdesk.vivacrm.ru/api/v1/accounts/{conversation_id}/conversations/{conversation_id}/assignments \
  --header 'Content-Type: application/json' \
  --header 'api_access_token: <api-key>' \
  --data '{
  "assignee_id": 456,
  "team_id": 2
}'

Пример ответа

{
  "id": 456,
  "access_token": "agent_access_token_456",
  "account_id": 123,
  "available_name": "Анна Агент",
  "avatar_url": "https://helpdesk.vivacrm.ru/avatars/anna.jpg",
  "confirmed": true,
  "display_name": "Анна",
  "message_signature": "С уважением,\nАнна\nHelpDesk vivaCRM",
  "email": "[email protected]",
  "hmac_identifier": "hmac_anna_456",
  "inviter_id": 1,
  "name": "Анна Сидорова",
  "provider": "email",
  "pubsub_token": "pubsub_token_456",
  "role": "agent",
  "ui_settings": {
    "theme": "light",
    "language": "ru",
    "notifications": {
      "sound_enabled": true,
      "desktop_enabled": true
    }
  },
  "uid": "anna_uid_456",
  "type": "User",
  "custom_attributes": {
    "department": "техническая_поддержка",
    "specialization": "платежи",
    "experience_years": 3
  },
  "accounts": [
    {
      "id": 123,
      "name": "HelpDesk vivaCRM - Основной",
      "status": "активный",
      "active_at": "2023-11-07T05:31:56Z",
      "role": "agent",
      "permissions": [
        "conversation:read",
        "conversation:write",
        "conversation:assign",
        "contact:read",
        "contact:write",
        "report:read"
      ],
      "availability": "доступен",
      "availability_status": "онлайн",
      "auto_offline": false,
      "custom_role_id": 3,
      "custom_role": {
        "name": "Старший агент поддержки",
        "description": "Агент с расширенными правами"
      }
    }
  ]
}

Коды ответов

• 200 - Беседа успешно назначена агенту/команде

• 401 - Неавторизованный доступ

• 404 - Беседа или агент/команда не найдены

• 400 - Неверный запрос

• 403 - Недостаточно прав для назначения

Примечания по использованию

Логика назначения

1. Приоритет агента: Если указаны и assignee_id, и team_id, беседа будет назначена конкретному агенту, а параметр team_id будет проигнорирован

2. Назначение команде: Если указан только team_id, беседа будет назначена команде, и любой агент из этой команды сможет ее обработать

3. Пустое назначение: Если не указан ни один параметр, беседа останется неназначенной

Роли пользователей

• agent - Обычный агент поддержки

• administrator - Администратор с расширенными правами

Статусы доступности

• онлайн - Агент в сети и готов принимать беседы

• занят - Агент в сети, но не принимает новые беседы

• отошел - Агент временно недоступен

• оффлайн - Агент не в сети

Автоматическое назначение

Система может автоматически назначать беседы на основе:

• Загруженности агентов

• Навыков и специализации

• Настроек команды

• Правил маршрутизации

Уведомления

После назначения беседы агент получит уведомление через:

• Email (если включено)

• Push-уведомления в браузере

• Звуковые сигналы в интерфейсе

• WebSocket подключение для мгновенного обновления