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

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

С чего начать

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

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

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

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

Вы можете использовать Секретный ключ из раздела Веб → Безопасность панели управления сервером и не создавать 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 в новой рабочей области введите запрос:
   https://server.company.name/oauth2/v1/token

   1	https://server.company.name/oauth2/v1/token

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

2. Выберите слева от поля запроса HTTP-метод POST.
3. На вкладке Body укажите:
   • тип x-www-form-urlencoded
   • такие пары KEY — VALUE:

   KEY	VALUE
   grant_type	client_credentials
   client_id	96f2973300c9b7740dd315b3d7890c60fb787fd5
   client_secret	e19769eb12f6cad7847260dfaa0e94f4a9537f2e

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

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

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

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

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

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

1. Сформируйте список свойств создаваемой конференции в виде JSON объекта ObjectConference, указав параметры:
   • "topic":"My Conference" – название;
   • "type":0 – режим конференции, в данном случае “все на экране”;
     Обратите внимание, что на стороне сервера с помощью параметра type мы можем задать только один общий тип селектора (мероприятия с выделенными докладчикам и слушателями), указав значение "type": 3. А уже его вид (управляемый или автоселектор) дополнительно задаётся отдельным параметром vad_selector — если его значение равно 1 то будет создан автоселектор, если 0 то управляемый селектор. Таким образом, для создания автоселектора надо указать два параметра: "type": 3 и "vad_selector": 1.
   • "auto_invite":1 – автоматическое приглашение участников виртуальной комнаты при подключении к ней любого пользователя (не только из числа приглашённых) и, как следствие, её запуске;
   • "max_participants":10 – максимальное число одновременно подключенных участников;
   • "invitations" – список из двух участников, в формате {"id":"user_id"}, где user_id – ID пользователя (логин) TrueConf Server;
   • "schedule":{"type":-1} – режим запуска, в приведённом примере виртуальная комната (без расписания);
   • "owner":"tamara" – владелец конференции.
2. Получим JSON-представление объекта конференции:
   { "topic":"My Conference", "type":0, "auto_invite":1, "max_participants":10, "invitations":[ { "id":"tamara" }, { "id":"dima" } ], "schedule":{ "type":-1 }, "owner":"tamara" }

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   {   "topic":"My Conference",   "type":0,   "auto_invite":1,   "max_participants":10,   "invitations":[     {       "id":"tamara"     },     {       "id":"dima"     }   ],   "schedule":{     "type":-1   },   "owner":"tamara" }

3. Введите запрос:
   https://server.company.name/api/v3.8/conferences?access_token=e696b81ca99f267fe92ced3c6baaabcd3b964db6

   1	https://server.company.name/api/v3.8/conferences?access_token=e696b81ca99f267fe92ced3c6baaabcd3b964db6

4. Выберите HTTP-метод POST.
5. На вкладке Body:
   • укажите тип raw
   • добавьте в поле данных полученный выше JSON.
6. Выполните запрос. При его успешной обработке сервер вернёт 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 приглашённого участника.