Как начать работу с TrueConf API

Димитрий Зуйков
15.04.2021
Димитрий Зуйков

Используя программные продукты TrueConf, вы можете расширить область применения видеосвязи в бизнесе: от видеоконференции с посетителями вашего сайта через виджет для сайта до организации видео-контакт-центра. Мы покажем вам, как с помощью нашего API легко реализуются самые различные сценарии.

С чего начать

TrueConf Server API – набор готовых программных интерфейсов для взаимодействия ваших приложений с TrueConf Server. Данный набор реализует архитектуру RESTful API и в основе его работы лежат HTTP-запросы GET, POST, PUT, DELETE. Ответы сервер возвращает в формате JSON. Подробное описание всех возможностей читайте в нашей документации для разработчиков.

Схема работы TrueConf Server API

Для работы с API требуется настроить HTTPS в панели управления сервером.

Для работы с API рекомендуется использовать протокол OAuth 2.0. Подробнее о нём рассказано в нашей документации к серверу.

Взаимодействие приложения с API происходит следующим образом:

  1. Запрос приложением временного токена доступа к серверу.
  2. Возврат токена доступа приложению.
  3. Использование токена для выполнения запросов от приложения к серверу.

Вы можете использовать Секретный ключ из раздела Веб → Безопасность панели управления сервером и не создавать OAuth-приложение, но мы не рекомендуем этот метод.

Данный Секретный ключ является токеном доступа неограниченного времени действия (до ручного пересоздания кнопкой Сгенерировать новый ключ) и предоставляет полный доступ ко всем функциям API без предварительной авторизации по протоколу OAuth. Поэтому мы рекомендуем применять секретный ключ только для тестирования API или для использования только администратором сервера с правами, которые нельзя указать при создании OAuth-приложения (например, чтение логов).

Шаг 1. Создание приложения OAuth

В панели управления TrueConf Server перейдите в раздел API → OAuth2. Создайте новое OAuth 2.0 приложение, отметив флажками необходимые для решения ваших задач права.

Для работы представленных ниже примеров понадобятся права:

  • conferences
  • conferences:read
  • conferences:write
  • conferences.participants
  • conferences.participants:read
  • conferences.participants:write

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

Для тестирования работы с API вы можете использовать консольную утилиту cURL (встроена в Windows 10 начиная со сборки 1803) или программу Postman. Мы рекомендуем Postman как более удобный вариант.

Шаг 2. Формирование токена доступа

  1. В Postman в новой рабочей области введите запрос:

где server.company.name – IP-адрес или внешний адрес из раздела Веб → Настройки установленного TrueConf Server.

  1. Выберите слева от поля запроса HTTP-метод POST.
  1. На вкладке Body укажите:
  • тип x-www-form-urlencoded
  • такие пары KEYVALUE:
KEY VALUE
grant_type client_credentials
client_id 96f2973300c9b7740dd315b3d7890c60fb787fd5
client_secret e19769eb12f6cad7847260dfaa0e94f4a9537f2e

где client_id и client_secret – идентификатор и секретный ключ соответственно, полученные при создании приложения.

  1. Для выполнения запроса нажмите кнопку Send.
  2. При успешной обработке сервер вернёт JSON с данными о созданном токене доступа:

Эти данные означают:

  • access_token – токен доступа;
  • expires_in – срок действия токена в секундах с момента создания (24 часа);
  • token_type – тип выданного токена, всегда равен “Bearer”;
  • scope – список прав, предоставленных для этого приложения.
После окончания срока действия токен станет недействительным и понадобится запросить новый.

Шаг 3. Создание групповой конференции

Для создания новой видеоконференции используйте метод Conference.

  1. Сформируйте список свойств создаваемой конференции в виде объекта ObjectConference, указав параметры:
  1. Получим JSON-представление объекта конференции:

  1. Введите запрос:

  1. Выберите HTTP-метод POST.
  2. На вкладке Body:
  • укажите тип raw
  • добавьте в поле данных полученный выше JSON.
  1. Выполните запрос. При его успешной обработке сервер вернёт JSON с данными о созданной конференции:

При этом сервер автоматически сформирует ID видеоконференции и выведет его в поле id.

В случае ошибки будет возвращено соответствующее сообщение.

Шаг 4. Получение списка конференций

С помощью метода Conferences получите список конференций, используя HTTP-метод GET:

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

Шаг 5. Запрос информации о конференции

Используйте ID созданной конференции и метод Conferences для получения информации о ней. Укажите HTTP-метод GET:

В ответ вы получите JSON объекта конференции с полной информацией о ней.

Шаг 6. Запуск конференции

Начните видеоконференцию по её ID при помощи метода Conferences, используя HTTP-метод POST:

При успешной обработке запроса сервер тут же запустит конференцию.

Так как при создании конференции вы указали автоматическое приглашение участников, то они сразу получат в неё вызов.

Шаг 7. Приглашение участника в конференцию

Когда конференция запущена, вы сможете пригласить в неё нового участника.

Чтобы выслать приглашение в конференцию, используйте метод Conferences_Participants и HTTP-метод POST:

При этом в Postman на вкладке Body укажите JSON вида {"participant_id":"user_id"}, где user_id – имя пользователя, например { "participant_id":"matvey" }.

В случае успешного выполнения запроса сервер вернёт объект ObjectParticipant приглашённого участника.

Не нашли ответ на свой вопрос? Напишите нам в онлайн-чате, мы будем рады помочь.