Описание API ЛК сервиса Team

Примеры даны с использованием Linux утилиты curl. Вы можете использовать любой аналогичный удобный вам инструмент.

Логин и получение токена

Выполните запрос с выводом результата: 

curl -d "{\"login\":\"{YOUR_EMAIL}\",\"password\":\"{YOUR_PASS}\"}" -H "Content-Type: application/json" -H "Accept: application/json, text/plain, */*" -H "Referer: https://{YOUR_TENANT}.softphone.pro/login/" -k -X POST "https://{YOUR_TENANT}.softphone.pro/login/api/auth" -v

где:

Параметр Описание Пример
{YOUR_TENANT} Адрес вашего ЛК в сервисе Team, строка после https:// до первой точки. company
{YOUR_EMAIL} Почта администратора ЛК. admin@company.ru
{YOUR_PASS} Пароль администратора ЛК. password

В результате запроса ищем строку начинающуюся с:

< Set-Cookie: jwt

Из этой строки берём токен (далее по тексту {YOUR_TOKEN}) - всё, что находится между знаком = и символом ;.

Создание пользователя

Выполните запрос: 

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {YOUR_TOKEN}" -d "{\"usesSoftphone\":true,\"name\":\"John\",\"surname\":\"Doe\",\"email\":\"user@company.ru\",\"password\":\"123456\",\"role\":\"EMPLOYEE\",\"groups\":[1,2],\"config\":\"{% include \\\"_Restrictions\\\" %}\n{% include \\\"_SipSettings\\\" %}\n{% include \\\"_Account1\\\" %}\n{% include \\\"_ACW\\\" %}\n{% include \\\"_Statuses\\\" %}\n{% include \\\"_Camera\\\" %}\n{% include \\\"_ScreenRecording\\\" %}\n{% include \\\"Default\\\" %}\"}" https://{YOUR_TENANT}.softphone.pro/api/settings/users/save

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

Параметр Описание Пример
usesSoftphone Использует ли пользователь Softphone.Pro. true
name Имя пользователя (непустая строка, длиной до 256 символов). John
surname Фамилия пользователя (непустая строка, длиной до 256 символов). Doe
email Электронная почта пользователя. user@company.ru
password Пароль пользователя (непустая строка, длиной от 6 до 256 символов). 123456
role Роль пользователя.

EMPLOYEE - оператор;

MANAGER - руководитель;

RESTRICTED_ADMIN - администратор (без управления подпиской).

groups

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

ID групп можно получить в адресной строке браузера во время настройки группы.

[1] - пользователь состоит в группе с ID 1;

[2,4,7] - пользователь состоит в группах с ID 2, 4 и 7.

manageGroups

ID групп, которыми пользователь будет управлять, если его роль MANAGER или RESTRICTED_ADMIN, один или несколько через запятую. Параметр задаётся в квадратных скобках.

ID групп можно получить в адресной строке браузера во время настройки группы.

[1] - пользователь управляет группой с ID 1;

[2,4,7] - пользователь управляет группами с ID 2, 4 и 7.

config Конфигурация Softphone.Pro. Пример конфигурации вы можете найти в поле Конфигурационный файл на странице настроек пользователя сервиса Team. {% include "_Restrictions" %}\n{% include "_SipSettings" %}\n{% include "_Account1" %}\n{% include "_ACW" %}\n{% include "_Statuses" %}\n{% include "_Camera" %}\n{% include "_ScreenRecording" %}\n{% include "Default" %}

После удачного выполнения запроса на добавление вам вернётся ID созданного пользователя, вы можете сохранить его для того, чтобы использовать при удалении.

Добавление большого количества пользователей

Для автоматизации процесса добавления большого количества пользователей можно написать скрипт, который будет загружать данные о сотрудниках из csv таблицы и добавлять пользователей в личный кабинет. Ниже приведён пример такого скрипта на PowerShell.

Инструкция и образец скрипта тестировались на компьютере с ОС Windows 10. На компьютере должен быть разрешён запуск Powershell скриптов.

1. Скачайте архив с файлами скрипта и файлом данных: Add_Agents_to_Team.zip

2. Распакуйте архив в папку на вашем компьютере. В архиве три файла:

  • add_agents.ps1 - PowerShell скрипт, который выполняет запросы к личному кабинету Team;
  • add_agents.bat - исполняемый файл с реквизитами вашего личного кабинета, который нужно отредактировать, указав реквизиты вашего личного кабинета;
  • agents.csv - файл с данными о пользователях, которые нужно добавить.

3. Откройте файл agents.csv. Данные в файле приведены для примера, заполните их своими значениями. Если параметр помечен как обязательный, соответствующий столбец в строке с данными пользователя не может быть пустым. Наличие строки с заголовками обязательно.

Описание столбцов:

Название столбца Описание Пример Обязательный параметр
usesSP Использует ли пользователь софтфон. Возможные значения: true/false. true да
name Имя пользователя, непустая строка, длиной до 256 символов. John да
surname Фамилия пользователя, непустая строка, длиной до 256 символов. Doe да
email Электронная почта пользователя. user@company.ru да
password Пароль пользователя, непустая строка, длиной от 6 до 256 символов. 123456 да
role Роль пользователя.

EMPLOYEE - оператор;

MANAGER - руководитель;

RESTRICTED_ADMIN - администратор (без управления подпиской).

да
groupsIn

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

ID групп можно получить в адресной строке браузера во время настройки группы.

1 - пользователь состоит в группе с ID 1;

2,4,7 - пользователь состоит в группах с ID 2, 4 и 7.

да
groupsMan

ID групп, которыми пользователь будет управлять, если его роль MANAGER или RESTRICTED_ADMIN, один или несколько через запятую. Для роли EMPLOYEE - пустое значение.

ID групп можно получить в адресной строке браузера во время настройки группы.

1 - пользователь управляет группой с ID 1;

2,4,7 - пользователь управляет группами с ID 2, 4 и 7.

нет
siplogin Логин SIP учётной записи пользователя, строка длиной до 256 символов. sip101 нет
sippassword Пароль SIP учётной записи, строка длиной до 256 символов. sippass123 нет
sipdisplayname Отображаемое имя SIP учётной записи пользователя, строка длиной до 256 символов. sip101 нет
sipauthname Имя авторизации SIP учётной записи пользователя, строка длиной до 256 символов. sip101 нет
ext Добавочный номер SIP учётной записи пользователя на АТС, строка длиной до 256 символов. 101 нет

4. Сохраните файл.

При работе с csv файлом в сторонних редакторах убедитесь, что в сохраняемом файле используется разделитель точка с запятой (;) для отделения значений, а не запятая.

5. Откройте файл add_agents.bat в текстовом редакторе и укажите в параметрах token, dashboard и filepath настройки, необходимые для работы скрипта:

  • token - укажите токен Администратора личного кабинета (он же {YOUR_TOKEN}), полученный по инструкции Логин и получение токена;
  • dashboard - укажите адрес вашего личного кабинета Team в виде https://{YOUR_TENANT}.softphone.pro, где {YOUR_TENANT} это адрес вашего ЛК в сервисе Team, строка после https:// до первой точки;
  • filepath - если файл agents.csv находится в той же папке, что и скрипты, оставьте значение .\agents.csv. Если вы хотите использовать файл в другой папке, укажите полный путь к CSV файлу.

Сохраните изменения в файле.

6. Запустите файл add_agents.bat двойным кликом и дождитесь выполнения скрипта.

Если пользователь из таблицы был добавлен успешно, вы увидите в открывшемся окне строку вида:

Successfully added user #1 from csv with ID 2

Номер после # в строке соответствует порядковому номеру строки с данными пользователя из csv файла (без учёта заголовков), номер после with ID - ID созданного пользователя, вы можете сохранить его для того, чтобы использовать при удалении.

Если пользователь не был добавлен, вы увидите строку вида:

Error adding user #2 from csv, got error 500 from Team Dashboard.

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

Удаление пользователя

Выполните запрос: 

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {YOUR_TOKEN}" -d "{USER_ID}" https://{YOUR_TENANT}.softphone.pro/api/settings/users/delete
Параметр Описание Пример
{USER_ID}

ID пользователей для удаления, один или несколько через запятую. Значение параметра задаётся в квадратных скобках.

ID пользователя можно получить в ответе на запрос на добавление или в адресной строке браузера во время настройки пользователя.

[1] - удалить пользователя с ID 1;

[2,4,7] - удалить пользователей с ID 2, 4 и 7.

Получение списка пользователей

Выполните запрос: 

curl -H "Authorization: Bearer {YOUR_TOKEN}" -k -X GET "https://{YOUR_TENANT}.softphone.pro/api/settings/users?sortColumn=name&sortDirection=asc&pageSize=5&pageNumber=3&allUsers=true"

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

Параметр Описание Пример
sortColumn Параметр, по которому отсортирован список пользователей.
Возможные значения:
  • id - ID пользователя;
  • name - имя пользователя;
  • surname - фамилия пользователя;
  • email - email пользователя;
  • groups - названия групп, в которых состоит пользователь;
  • roles - роль пользователя;
  • states - статус пользователя;
  • sfversion - версия софтфона сотрудника.
Значение по умолчанию: id. 		name
sortDirection Направление сортировки списка пользователей по значению из параметра sortColumn.
Возможные значения: asc (по возрастанию), desc (по убыванию).
Значение по умолчанию: desc. 		asc
pageSize Количество пользователей в выборке.
Значение по умолчанию: 20. 		5
pageNumber Номер страницы, от 1.
Значение по умолчанию: 1. 		3
allUsers Вернуть список всех пользователей.
Возможные значения: true/false.
Значение по умолчанию: false.
Если указано значение true, запрос возвращает список всех пользователей, значения параметров pageSize и pageNumber игнорируются. 		true

В ответ на запрос возвращается JSON с данными о пользователях личного кабинета. Описание полей ответа:

Параметр Описание
totalCount Общее количество пользователей личного кабинета.
users Массив пользователей.
users.id ID пользователя.
users.name Имя пользователя.
users.surname Фамилия пользователя.
users.email Email пользователя.
users.state Статус пользователя.
Возможные значения:
  • active - пользователь активен и подключался из приложения Softphone.Pro к личному кабинету;
  • active.unconfirm - пользователь активен, но не подключался из приложения;
  • block - пользователь заблокирован.
users.role Роль пользователя.
Возможные значения:
  • ADMIN - Администратор личного кабинета;
  • RESTRICTED_ADMIN - Администратор (без управления подпиской);
  • MANAGER - Руководитель группы;
  • EMPLOYEE - Оператор.
Различия между ролями описаны в статье Роли пользователей.
users.groups Массив названий групп, в которых состоит пользователь.
users.sfversion Версия софтфона, с которой сотрудник подключался в последний раз. Может быть пустым, если пользователь не подключался из софтфона или не использует его.

Получение истории статусов операторов

Выполните запрос: 

curl -H "Authorization: Bearer {YOUR_TOKEN}" -k -X GET "https://{YOUR_TENANT}.softphone.pro/api/reports/agents/worktime/raw?from=2019-01-01T00:00:00&to=2020-01-02T00:00:00&format=csv"

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

Параметр Описание Пример
from Дата и время в формате UTC, с которого надо получить данные. 2019-01-01T00:00:00
to Дата и время в формате UTC, по которое надо получить данные. 2019-12-31T23:59:59
format Формат полученных данных. Необязательный параметр. csv или tsv

Получение истории звонков

Выполните запрос: 

curl -H "Authorization: Bearer {YOUR_TOKEN}" -k -X GET "https://{YOUR_TENANT}.softphone.pro/api/history/calls/export?dateFrom=2021-10-13T00:00:00%2B05:00&dateTo=2021-10-14T00:00:00%2B05:00&localTimeZoneOffset=%2B300&typeFile=csv"

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

Параметр Описание Пример
dateFrom Дата и время в формате UTC, с которого надо получить историю.
Положительный сдвиг задаётся знаком %2B (+ в кодировке), отрицательный - знаком -.		 2021-10-13T00:00:00%2B05:00
dateTo Дата и время в формате UTC, по которое надо получить историю.
Положительный сдвиг задаётся знаком %2B (+ в кодировке), отрицательный - знаком -.		 2021-10-14T00:00:00%2B05:00
localTimeZoneOffset Сдвиг времени от нулевого часового пояса в минутах. Положительный сдвиг задаётся знаком %2B (+ в кодировке), отрицательный - знаком -. %2B180
или
-300
lang Язык экспортируемого файла. По умолчанию английский (en). Необязательный параметр. ru или en
typeFile Формат полученных данных. По умолчанию xlsx. Необязательный параметр. xlsx или csv

Загрузка информации с АТС Asterisk в личный кабинет сервиса Team

Если вам нужно загрузить информацию с вашей АТС Asterisk в личный кабинет сервиса Team, выполните запрос: 

curl --request POST https://{YOUR_TENANT}.softphone.pro/api/reports/asterisk/upload -H 'Authorization: Bearer {YOUR_TOKEN} ' --form 'logs=@"{YOUR_PATH_TO_FILE_QUEUELOG}"'

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

Параметр Описание Пример
{YOUR_PATH_TO_FILE_QUEUELOG} Путь до файла queue_log на сервере, с которого производится запрос. /var/log/asterisk/queueLog

Результатом успешного запроса будет количество звонков, загруженных в личный кабинет. Если вы получите какую-либо ошибку, вы можете очистить все ранее загруженные данные и повторить загрузку файла.

Чтобы удалить ранее загруженные в ЛК данные об очередях, выполните следующий запрос: 

curl --request POST https://{YOUR_TENANT}.softphone.pro/api/reports/asterisk/clear -H 'Authorization: Bearer {YOUR_TOKEN}'

Список статей