Агенты

Группы

Создание группы

Для создания группы агентов необходимо вызвать POST ​/api​/teams, передавая данные авторизации в заголовке и параметры группы в теле запроса.

Параметры запроса

Параметр	Тип данных	Описание
name обязательный	string	Название группы.
avatar	string	Код эмодзи аватара группы.
description	string	Описание группы.
timeTable	array[object]	Расписание работы группы, к которой прикреплен виджет. Может быть несколько вариантов расписания.
outOfHoursCustomerAutoreply	string	Автоматический ответ, который появляется в чате, если все агенты в группе недоступны.

Timetable

Каждый объект внутри массива timeTable обозначает день недели, в который назначается расписание. То есть, варианты названия объекта могут быть такие:

• MONDAY - понедельник
• TUESDAY - вторник
• WEDNESDAY - среда
• THURSDAY - четверг
• FRIDAY - пятница
• SATURDAY - суббота
• SUNDAY - воскресенье

Объект дня недели включает в себя параметры:

Параметр	Тип данных	Описание
startTime	object	Время начала работы группы.
endTime	object	Время окончания работы группы.

Внутри объектов startTime и endTime задаются одинаковые параметры:

Параметр	Тип данных	Описание
hour	integer	Часы.
minute	integer	Минуты.
second	integer	Секунды.
nano	integer	Наносекунды.

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

{
  "avatar": "check-mark-button",
  "description": "Team description",
  "name": "Changed name",
  "outOfHoursCustomerAutoreply": "Sorry, out of service",
  "timeTable": {
    "MONDAY": {
      "startTime": {
        "hour": 08,
        "minute": 30
      },
      "endTime": {
        "hour": 20,
        "minute": 10,
        "nano": 10,
        "second": 30
      }
    },
    "FRIDAY": {
      "startTime": {
        "hour": 12,
        "minute": 40,
        "nano": 20,
        "second": 20
      },   
      "endTime": {
        "hour": 22,
        "minute": 00
      }
    }
  }
}

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

Параметр	Тип данных	Описание
result	integer	ID созданной группы.

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

{
    "result": "10613"
}

Изменение группы

Для изменения группы агентов необходимо вызвать PUT /api​/teams​/{teamId}, передавая данные авторизации в заголовке и параметры группы в теле запроса.

Параметры запроса

Параметр	Тип данных	Описание
teamId	integer	ID обновляемой группы. Path-параметр.
name	string	Название группы.
avatar	string	Код эмодзи аватара группы.
description	string	Описание группы.
timeTable	array[object]	Расписание работы группы, к которой прикреплен виджет. Может быть несколько вариантов расписания.
outOfHoursCustomerAutoreply	string	Автоматический ответ, который появляется в чате, если все агенты в группе недоступны.

Timetable

Каждый объект внутри массива timeTable обозначает день недели, в который назначается расписание. То есть, варианты названия объекта могут быть такие:

• MONDAY - понедельник
• TUESDAY - вторник
• WEDNESDAY - среда
• THURSDAY - четверг
• FRIDAY - пятница
• SATURDAY - суббота
• SUNDAY - воскресенье

Объект дня недели включает в себя параметры:

Параметр	Тип данных	Описание
startTime	object	Время начала работы группы.
endTime	object	Время окончания работы группы.

Внутри объектов startTime и endTime задаются одинаковые параметры:

Параметр	Тип данных	Описание
hour	integer	Часы.
minute	integer	Минуты.
second	integer	Секунды.
nano	integer	Наносекунды.

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

{
  "avatar": "check-mark-button",
  "description": "Team description",
  "name": "Changed name",
  "outOfHoursCustomerAutoreply": "Sorry, out of service",
  "timeTable": {
    "MONDAY": {
      "startTime": {
        "hour": 08,
        "minute": 30
      },
      "endTime": {
        "hour": 20,
        "minute": 10,
        "nano": 10,
        "second": 30
      }
    },
    "FRIDAY": {
      "startTime": {
        "hour": 12,
        "minute": 40,
        "nano": 20,
        "second": 20
      },   
      "endTime": {
        "hour": 22,
        "minute": 00
      }
    }
  }
}

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

При успешной авторизации сервис возвращает параметр result в значении null и HTTP-статус 200.

Получение данных групп

Для получения данных групп можно воспользоваться двумя методами:

1. GET ​/api​/teams​/{teamId}, чтобы получить одну группу по ее ID.
2. GET /api​/teams, чтобы получить информацию обо всех группах организации.

В заголовках обоих методов необходимо передать данные авторизации.

Параметры запроса

Параметр	Тип данных	Описание
teamId	integer	ID для получения одной группы. Path-параметр.

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

Получение данных одной группы

curl -X GET "https://chat.devinotele.com/api/teams/1234" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Получение данных всех групп

curl -X GET "https://chat.devinotele.com/api/teams" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Параметр	Тип данных	Описание
id	integer	ID группы.
name	string	Название группы.
avatar	string	Код эмодзи аватара группы из веб-интерфейса бизнес-чата.
description	string	Описание группы.
timeTable	array[object]	Расписание работы группы, к которой прикреплен виджет. Может быть несколько вариантов расписания.
outOfHoursCustomerAutoreply	string	Автоматический ответ, который появляется в чате, если все агенты в группе недоступны.

Timetable

Параметр	Тип данных	Описание
startTime	string	Время начала работы группы в формате hh:mm:ss. Пример: 10:00:00
endTime	string	Время окончания работы группы в формате hh:mm:ss. Пример: 20:00:00
days	array[string]	Дни недели, в которые группа работает в данные часы работы. Может быть несколько.

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

{
   "id": 466,
   "name": "Support team",
   "avatar": "red-heart",
   "description": "Great team",
   "timeTable": [
     {
       "startTime": "08:00:00",
       "endTime": "23:59:00",
       "days": [
         "MONDAY",
         "TUESDAY",
         "WEDNESDAY",
         "THURSDAY",
         "FRIDAY"
       ]
     },
     {
        "startTime": "10:00:00",
        "endTime": "23:00:00",
        "days": [
          "TUESDAY",
          "THURSDAY",
          "SUNDAY"
        ]
      }
   ],
   "outOfHoursCustomerAutoreply": "Sorry, out of service"
}

Агенты

Создание агента

Для создания агента необходимо вызвать POST /api​/agents, передавая данные авторизации в заголовке и параметры агента в теле запроса.

Параметры запроса

Параметр	Тип данных	Описание
login обязательный	string	Логин агента, по которому он входит в личный кабинет.
password обязательный	string	Первоначальный пароль агента, который далее он сможет поменять в личном кабинете. Также в личном кабинете можно отдельно включить агенту двухфакторную аутентификацию.
roles обязательный	array	Роли агента. Доступны значения: ○ ROLE_ORGANIZATION_ADMIN - администратор организации. Может управлять группами и агентами. ○ ROLE_ORGANIZATION_TEAM_LEADER - администратор группы. Может управлять агентами. ○ ROLE_ORGANIZATION_AGENT - агент. В данном параметре может быть несколько значений.
teamIds обязательный	array	ID групп, к которым принадлежит агент.
firstname	string	Имя агента.
lastname	string	Фамилия агента.
avatarFileId	string	ID аватара агента в виде ID заранее загруженного файла.
position	string	Должность агента. Показывается в его профиле.
emailSignature	string	Подпись агента в email-письмах.

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

{
  "avatarFileId": "234fjvsifvgr14rijf",
  "emailSignature": "Best wishes",
  "firstname": "Team",
  "lastname": "Leader",
  "login": "teamleader@dev.com",
  "password": "123456789",
  "position": "Organisation manager",
  "roles": [
    "ROLE_ORGANIZATION_AGENT",
    "ROLE_ORGANIZATION_TEAM_LEADER"
  ],
  "teamIds": [    
    "25",
    "34"
  ]
}

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

Параметр	Тип данных	Описание
result	integer	ID созданного агента.

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

{
    "result": "31648"
}

Обновление агента

Для обновления данных агента необходимо вызвать PATCH ​/api​/agents​/{agentId}, передавая данные авторизации в заголовке и параметры агента в теле запроса.

Параметры запроса

Параметр	Тип данных	Описание
agentId	integer	ID обновляемого агента. Path-параметр.
roles	array	Роли агента. Доступны значения: ○ ROLE_ORGANIZATION_ADMIN - администратор организации. Может управлять группами и агентами. ○ ROLE_ORGANIZATION_TEAM_LEADER - администратор группы. Может управлять агентами. ○ ROLE_ORGANIZATION_AGENT - агент. В данном параметре может быть несколько значений.
teamIds	array	ID групп, к которым принадлежит агент.
firstname	string	Имя агента.
lastname	string	Фамилия агента.
avatarFileId	string	ID аватара агента в виде ID заранее загруженного файла.
position	string	Должность агента. Показывается в его профиле.
emailSignature	string	Подпись агента в email-письмах.
activityStatus	string	Статус активности агента. Доступны значения: ○ ONLINE - агент готов принимать сообщения. ○ OFFLINE - агент не готов принимать сообщения.
state	string	Статус профиля агента. Доступны значения: ○ NEW - профиль агента создан, но агент еще не авторизовался в личном кабинете. При первом входе в личный кабинет агент может изменить пароль. В дальнейшем агент будет использовать и менять его самостоятельно. ○ ACTIVE - агент активен и может общаться с пользователями. ○ BLOCKED - агент заблокирован администратором организации или группы и не может общаться с пользователями.
language	string	Двухбуквенный код языка. На данном языке агент общается с пользователями.

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

{
  "avatarFileId": "234fjvsifvgr14rijf",
  "emailSignature": "Best wishes",
  "firstname": "Team",
  "lastname": "Leader",
  "position": "Organisation manager",
  "roles": [
    "ROLE_ORGANIZATION_AGENT",
    "ROLE_ORGANIZATION_TEAM_LEADER"
  ],
  "teamIds": [    
    "25",
    "34"
  ],
  "activityStatus": "OFFLINE",
  "state": "BLOCKED",
}

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

Параметр	Тип данных	Описание
id	integer	ID агента.
organizationId	integer	ID организации, к которой принадлежит агент.
login	string	Логин агента, по которому он входит в личный кабинет.
firstname	string	Имя агента.
lastname	string	Фамилия агента.
avatarFileId	string	ID аватара агента в виде ID заранее загруженного файла.
isUsingSecondFactor	boolean	Двухфакторная аутентификация для агента при входе в личный кабинет. Настраивается в личном кабинете.
position	string	Должность агента. Показывается в его профиле.
roles	array	Роли агента. Доступны значения: ○ ROLE_ORGANIZATION_ADMIN - администратор организации. Может управлять группами и агентами. ○ ROLE_ORGANIZATION_TEAM_LEADER - администратор группы. Может управлять агентами. ○ ROLE_ORGANIZATION_AGENT - агент. В данном параметре может быть несколько значений.
activityStatus	string	Статус активности агента. Доступны значения: ○ ONLINE - агент готов принимать сообщения. ○ OFFLINE - агент не готов принимать сообщения.
teamIds	array	ID групп, к которым принадлежит агент.
state	string	Статус профиля агента. Доступны значения: ○ NEW - профиль агента создан, но агент еще не авторизовался в личном кабинете. При первом входе в личный кабинет агент может изменить пароль. В дальнейшем агент будет использовать и менять его самостоятельно. ○ ACTIVE - агент активен и может общаться с пользователями. ○ BLOCKED - агент заблокирован администратором организации или группы и не может общаться с пользователями.
emailSignature	string	Подпись агента в email-письмах.
language	string	Двухбуквенный код языка. На данном языке агент общается с пользователями.

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

{
  "result": [
    {
      "id": 31,
      "organizationId": 1,
      "login": "teamleader@dev.com",
      "firstname": "Team",
      "lastname": "Leader",
      "roles": [
        "ROLE_ORGANIZATION_TEAM_LEADER"
      ],
      "activityStatus": "OFFLINE",
      "teamIds": [
        "25"
      ],
      "state": "BLOCKED",
      "emailSignature": "Best wishes",
      "language": "ru"
    }
  ]
}

Получение данных агентов

Для получения данных агентов можно воспользоваться двумя методами:

1. GET ​/api​/agents​/{agentId}, чтобы получить одного агента по его ID.
2. GET /api​/agents, чтобы получить информацию обо всех агентах организации.

В заголовках обоих методов необходимо передать данные авторизации.

Параметры запроса

Параметр	Тип данных	Описание
agentId	integer	ID для получения одного агента. Path-параметр.

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

Получение данных одного агента

curl -X GET "https://chat.devinotele.com/api/agents/1234" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Получение данных всех агентов

curl -X GET "https://chat.devinotele.com/api/agents" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Параметр	Тип данных	Описание
id	integer	ID агента.
organizationId	integer	ID организации, к которой принадлежит агент.
login	string	Логин агента, по которому он входит в личный кабинет.
firstname	string	Имя агента.
lastname	string	Фамилия агента.
avatarFileId	string	ID аватара агента в виде ID заранее загруженного файла.
isUsingSecondFactor	boolean	Двухфакторная аутентификация для агента при входе в личный кабинет. Настраивается в личном кабинете.
position	string	Должность агента. Показывается в его профиле.
roles	array	Роли агента. Доступны значения: ○ ROLE_ORGANIZATION_ADMIN - администратор организации. Может управлять группами и агентами. ○ ROLE_ORGANIZATION_TEAM_LEADER - администратор группы. Может управлять агентами. ○ ROLE_ORGANIZATION_AGENT - агент. В данном параметре может быть несколько значений.
activityStatus	string	Статус активности агента. Доступны значения: ○ ONLINE - агент готов принимать сообщения. ○ OFFLINE - агент не готов принимать сообщения.
teamIds	array	ID групп, к которым принадлежит агент.
state	string	Статус профиля агента. Доступны значения: ○ NEW - профиль агента создан, но агент еще не авторизовался в личном кабинете. При первом входе в личный кабинет агент может изменить пароль. В дальнейшем агент будет использовать и менять его самостоятельно. ○ ACTIVE - агент активен и может общаться с пользователями. ○ BLOCKED - агент заблокирован администратором организации или группы и не может общаться с пользователями.
emailSignature	string	Подпись агента в email-письмах.
language	string	Двухбуквенный код языка. На данном языке агент общается с пользователями.

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

{
  "result": [
    {
      "id": 31,
      "organizationId": 1,
      "login": "teamleader@dev.com",
      "firstname": "Team",
      "lastname": "Leader",
      "roles": [
        "ROLE_ORGANIZATION_TEAM_LEADER"
      ],
      "activityStatus": "OFFLINE",
      "teamIds": [
        "25"
      ],
      "state": "BLOCKED",
      "emailSignature": "Best wishes",
      "language": "ru"
    },
    {
      "id": 375,
      "organizationId": 1,
      "login": "orgadmin@dev.com",
      "firstname": "Admin",
      "lastname": "Main",
      "roles": [
        "ROLE_ORGANIZATION_ADMIN"
      ],
      "activityStatus": "ONLINE",
      "teamIds": [
        "1",
        "2",
        "3",
      ],
      "state": "ACTIVE",
      "emailSignature": "",
      "language": "en"
    },
    {
      "id": 11646,
      "organizationId": 1,
      "login": "agent@dev.com",
      "firstname": "Agent",
      "lastname": "Employee",
      "position": "Company position",
      "roles": [
        "ROLE_ORGANIZATION_AGENT"
      ],
      "activityStatus": "OFFLINE",
      "teamIds": [
        "1"
      ],
      "state": "NEW",
      "emailSignature": ""
    }
  ]
}

Получение агентов со статусом ONLINE

Для получения активных агентов со статусом ONLINE необходимо вызвать GET /api​/agents​/current, передавая данные авторизации в заголовке.

Данный запрос не имеет дополнительных параметров.

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

curl -X GET "https://chat.devinotele.com/api/agents/current" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Параметр	Тип данных	Описание
id	integer	ID агента.
organizationId	integer	ID организации, к которой принадлежит агент.
login	string	Логин агента, по которому он входит в личный кабинет.
firstname	string	Имя агента.
lastname	string	Фамилия агента.
avatarFileId	string	ID аватара агента в виде ID заранее загруженного файла.
isUsingSecondFactor	boolean	Двухфакторная аутентификация для агента при входе в личный кабинет. Настраивается в личном кабинете.
position	string	Должность агента. Показывается в его профиле.
roles	array	Роли агента. Доступны значения: ○ ROLE_ORGANIZATION_ADMIN - администратор организации. Может управлять группами и агентами. ○ ROLE_ORGANIZATION_TEAM_LEADER - администратор группы. Может управлять агентами. ○ ROLE_ORGANIZATION_AGENT - агент. В данном параметре может быть несколько значений.
activityStatus	string	Статус активности агента. Доступно только значение ONLINE - это значит, что агент готов принимать сообщения.
teamIds	array	ID групп, к которым принадлежит агент.
state	string	Статус профиля агента. Доступно только значение ACTIVE - это значит, что агент активен и может общаться с пользователями.
emailSignature	string	Подпись агента в email-письмах.
language	string	Двухбуквенный код языка. На данном языке агент общается с пользователями.

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

{
    "result": {
        "id": 375,
        "organizationId": 1,
        "login": "orgadmin@dev.com",
        "firstname": "Admin",
        "lastname": "Main",
        "roles": [
          "ROLE_ORGANIZATION_ADMIN"
        ],
        "activityStatus": "ONLINE",
        "teamIds": [
          "1",
          "2",
          "3",
        ],
        "state": "ACTIVE",
        "emailSignature": "",
        "language": "en"
        "isUsingSecondFactor": false
    }
}

Обновление статуса агента

Для обновления статуса активных агентов (то есть, агентов со статусом ONLINE) необходимо вызвать PATCH /api​/agents​/current​/settings, передавая данные авторизации в заголовке и данные статуса в теле запроса.

Параметры запроса

Параметр	Тип данных	Описание
activityStatus	string	Статус активности агента. Доступны значения: ○ ONLINE - агент готов принимать сообщения. ○ OFFLINE - агент не готов принимать сообщения.
language	string	Двухбуквенный код языка. На данном языке агент общается с пользователями.

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

{
  "activityStatus": "ONLINE",
  "language": "en"
}

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

|id|integer|ID агента.| |organizationId|integer|ID организации, к которой принадлежит агент.| |login|string|Логин агента, по которому он входит в личный кабинет.| |firstname|string|Имя агента.| |lastname|string|Фамилия агента.| |avatarFileId|string|ID аватара агента в виде ID заранее загруженного файла.| |isUsingSecondFactor|boolean|Двухфакторная аутентификация для агента при входе в личный кабинет. Настраивается в личном кабинете.| |position|string|Должность агента. Показывается в его профиле.| |roles|array|

Роли агента. Доступны значения:

○ ROLE_ORGANIZATION_ADMIN - администратор организации. Может управлять группами и агентами.
○ ROLE_ORGANIZATION_TEAM_LEADER - администратор группы. Может управлять агентами.
○ ROLE_ORGANIZATION_AGENT - агент.

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

| |activityStatus|string|Статус активности агента. Доступно только значение ONLINE - это значит, что агент готов принимать сообщения.| |teamIds|array|ID групп, к которым принадлежит агент.| |state|string|Статус профиля агента. Доступно только значение ACTIVE - это значит, что агент активен и может общаться с пользователями.| |emailSignature|string|Подпись агента в email-письмах.| |language|string|Двухбуквенный код языка. На данном языке агент общается с пользователями.|

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

{
    "result": {
        "id": 375,
        "organizationId": 1,
        "login": "orgadmin@dev.com",
        "firstname": "Admin",
        "lastname": "Main",
        "roles": [
          "ROLE_ORGANIZATION_ADMIN"
        ],
        "activityStatus": "ONLINE",
        "teamIds": [
          "1",
          "2",
          "3",
        ],
        "state": "ACTIVE",
        "emailSignature": "",
        "language": "en"
        "isUsingSecondFactor": false
    }
}

Удаление агента

Для удаления профиля агента необходимо вызвать DELETE ​/api​/agents​/{id}, передавая данные авторизации в заголовке.

Параметры запроса

Параметр	Тип данных	Описание
id	integer	ID агента. Path-параметр.

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

curl -X DELETE "https://chat.devinotele.com/api/agents/134" \
  -H "accept: */*" \
  -H "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

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

При успешной авторизации сервис возвращает параметр result в значении null и HTTP-статус 200.