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

15.03.2024Около 7 минAPI / SDKAPI / SDK

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

С чего начать

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

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

Для работы с 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. Формирование токена доступа

В Postman в новой рабочей области введите запрос:
```
https://server.company.name/oauth2/v1/token
```
где server.company.name – IP-адрес или внешний адрес из раздела Веб → Настройки установленного TrueConf Server.
Выберите слева от поля запроса HTTP-метод POST.
На вкладке Body укажите:
- тип x-www-form-urlencoded
- такие пары KEY - VALUE:

KEY	VALUE
grant_type	client_credentials
client_id	96f2973300c9b7740dd315b3d7890c60fb787fd5
client_secret	e19769eb12f6cad7847260dfaa0e94f4a9537f2e

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

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

{
  "access_token": "e696b81ca99f267fe92ced3c6baaabcd3b964db6",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "conferences conferences:read conferences:write conferences.participants conferences.participants:read conferences.participants:write"
}

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

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

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

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

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

Сформируйте список свойств создаваемой конференции в виде 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" – владелец конференции.

Получим JSON-представление объекта конференции:

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

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

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

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

{
  "conference": {
    "id": "4219111751",
    "type": 0,
    "topic": "My Conference",
    "owner": "tamara@ruwu1.trueconf.name",
    "description": "",
    "max_podiums": 10,
    "max_participants": 10,
    "schedule": {
      "type": -1
    },
    "invitations": [
      {
        "id": "dima",
        "display_name": null
      },
      {
        "id": "tamara",
        "display_name": null
      }
    ],
    "allow_guests": false,
    "auto_invite": 1,
    "state": "stopped",
    "url": "https://server.company.name/c/4219111751",
    "webclient_url": "https://server.company.name/webrtc/4219111751",
    "created_at": 1573653531,
    "multicast_enable": false,
    "multicast_address": "224.0.1.224:4000-6000",
    "tags": [],
    "recording": 0,
    "stream_recording_state": 0,
    "rights": {
      "guest": {
        "chat_send": true,
        "chat_rcv": true,
        "slide_show_send": true,
        "slide_show_rcv": true,
        "white_board_send": true,
        "white_board_rcv": true,
        "file_transfer_send": true,
        "file_transfer_rcv": true,
        "desktop_sharing": true,
        "recording": true,
        "audio_send": true,
        "audio_rcv": true,
        "video_send": true,
        "video_rcv": true
      },
      "user": {
        "chat_send": true,
        "chat_rcv": true,
        "slide_show_send": true,
        "slide_show_rcv": true,
        "white_board_send": true,
        "white_board_rcv": true,
        "file_transfer_send": true,
        "file_transfer_rcv": true,
        "desktop_sharing": true,
        "recording": true,
        "audio_send": true,
        "audio_rcv": true,
        "video_send": true,
        "video_rcv": true
      }
    },
    "broadcast_enabled": false,
    "broadcast_id": null,
    "broadcast": null,
    "allow_only_planned_participants": false
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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