Как использовать TrueConf API для видеозвонков с сайта
С помощью TrueConf Server API вы можете создать виджет для мгновенных видеозвонков через ваш веб-сайт. Такой виджет позволит гостю сайта в любой момент совершить звонок его менеджеру для личной видеоконсультации. Ему достаточно будет указать имя, не заполняя при этом никаких контактных форм.
Добавить виджет на ваш сайт очень просто. Чтобы начать, установите TrueConf Server
Настройка сервера займет не более 15 минут вашего времени.
Как взаимодействовать с API
Доступ к API сервера осуществляется по протоколу OAuth 2.0. Более подробно вы можете прочитать об этом в документации TrueConf Server.
Обращение к TrueConf Server API заключается в отправке HTTP-запросов на сервер. Ответы на запросы сервер возвращает в формате объектов JSON.
Список функций TrueConf Server, доступных через API, можно узнать тут:
План установки виджета
Общий план действий будет таким:
Этап 1 — через API-запросы организуйте видеозвонок на TrueConf Server. Для этого нужно будет создать конференцию на двух участников, один из которых будет менеджером вашего веб-сайта.
Этап 2 — в панели управления TrueConf Server получите html-код виджета видеозвонка.
Этап 3 — разместите виджет на странице своего сайта.
Этап 4 — удалите конференцию после её завершения.
Использование API
Подготовка TrueConf Server
- Настройте на сервере поддержку HTTPS соединения
- Добавьте в пользователи сервера менеджера вашего веб-сайта, который будет принимать видеозвонки от гостей.
- Создайте приложение OAuth 2.0.
А теперь приступим!
Создание и настройка конференции с использованием API
1. Получите токен доступа к API.
2. Создайте конференцию с помощью метода Conferences, задав такие параметры:
"schedule":{"type":-1}
— без расписания;"max_participants": 2
— на двух участников;"allow_guests": true
– возможность подключения гостей;
"auto_invite": 1
— автоматическое приглашение участников при подключении к конференции любого пользователя, в том числе и гостя. Также параметр может принимать значения:- 0 – не рассылать приглашения (по умолчанию);
- 2 – рассылать приглашения при подключении пользователя только из списка участников конференции.
Владельцем конференции назначьте менеджера вашего сайта, указав его имя пользователя на TrueConf Server. Например, "owner":"george"
.
Приведенный ниже пример TrueConf Server API запроса, как и следующие за ним, оформлены для использования с cURL.
1 2 3 4 |
curl --request POST \ --url 'https://server.company.com/api/v3.1/conferences?access_token=5a8212f4a2dcec763e3eeb8ca2dc78e1a6005be2' \ --header 'Content-Type: application/json' \ --data '{ "topic": "My Conference", "type":0, "auto_invite": 1, "max_participants": 2, "schedule":{"type":"-1"}, "owner":"george", "allow_guests": true}' |
Если конференция будет успешно создана, от сервера придёт ответ с данными о конференции.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
{ "conference": { "id": "0560438410", "type": 0, "topic": "My Conference", "owner": "george@server.company.com", "description": "", "max_podiums": 10, "max_participants": 10, "schedule": { "type": -1 }, "invitations": [ ], "allow_guests": true, "auto_invite": 1, "state": "stopped", "url": "https://server.company.name/c/0560438410", "webclient_url": "https://server.company.name/webrtc/0560438410", "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
страницы конференции.
3. Добавьте менеджера вашего веб-сайта в участники созданной конференции (выше он был назначен её владельцем), используя метод Conferences_Invitations. В качестве параметра $conference_id
метода укажите id
из предыдущего пункта.
1 2 3 4 |
curl --request POST \ --url 'https://server.company.com/api/v3.1/conferences/0560438410/invitations?access_token=5a8212f4a2dcec763e3eeb8ca2dc78e1a6005be2' \ --header 'Content-Type: application/json' \ --data '{"id":"george"}' |
В ответ на такой запрос придёт объект с данными о добавленном участнике.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
{ "invitation": { "id": "george", "uid": "george@server.company.com", "avatar": null, "login_name": "george", "email": "george@company.com", "display_name": "Georgiy Jakovlev", "first_name": "", "last_name": "", "company": "", "groups": [ { "id": "0002", "display_name": "operators", "rights": [] } ], "mobile_phone": "", "work_phone": "", "home_phone": "", "is_active": 1, "status": 1, "is_owner": 1, "type": "user" } } |
4. Для автоматического подключения гостя к конференции минуя форму авторизации, получите авторизационные данные для виджета с помощью метода Software_Clients — Get Client List:
1 2 |
curl --request GET \ --url 'https://server.company.com/api/v3.1/software/clients?call_id=0560438410' |
Ответ будет содержать в себе JSON со списком всех приложений для подключения к конференции, в том числе JSON-объект с именем "name": "TrueConf Web"
и данными для подключения по WebRTC:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
{ "clients": [ ... { "name": "TrueConf Web", "type": "web", "platform": "webrtc", "download_url": "", "download_urls": null, "market_url": "", "web_url": "https://server.company.com/webrtc/0560438410#login=*guest*guest&token=$28e23b726661ddd12bcaebeae3f626c71*1576493428*30eb00e80f3068ff43236ffa5baaa557&lang=auto", "iframe": "<iframe src=\"https://server.company.com/webrtc/0560438410#login=*guest*guest&token=$28e23b726661ddd12bcaebeae3f626c71*1576493428*30eb00e80f3068ff43236ffa5baaa557&lang=auto\" allowfullscreen=\"allowfullscreen\" allow=\"microphone; camera; autoplay\" ><\\iframe>" } ] ... } |
Запомните значение параметра web_url
.
Готово!
Добавление виджета на сайт
Используйте шаблон html-кода виджета из панели управления TrueConf Server, как это показано в нашей статье. В параметр src
вставьте полученный ранее web_url.
После того, как гость сайта присоединится к конференции через виджет видеозвонка, TrueConf Server автоматически отправит приглашение менеджеру сайта (параметр auto_invite
).
Отслеживание событий виджета
С помощью технологии postMessage виджет информирует о возникающих событиях и ошибках выдачей определённых сообщений:
- “notSupported” – браузер пользователя не удовлетворяет требованиям виджета;
- “connectionFail” – пользователь не смог подключиться к серверу;
- “loginFail” – пользователь не смог авторизоваться;
- “callFail” – пользователь не смог позвонить в конференцию;
- “hangUp” – пользователь положил трубку (вышел из конференции);
- “remoteHangUp” – пользователь вышел из конференции не по собственному желанию. Например, если пользователя удалил модератор конференции;
- “logout” – пользователь разлогинился;
- “connectionClosed” – пользователь отключился от сервера.
Вы можете использовать их для отслеживания момента завершения сеанса связи, например, сообщения hangUp или remoteHangUp.
Удаление конференции
1. Удалить можно только завершившуюся конференцию. Поэтому, получив от виджета сообщение о завершении звонка, остановите конференцию с помощью метода Conferences – Stop Conference:
1 2 |
curl --request POST \ --url 'https://server.company.com/api/v3.1/conferences/0560438410/stop?access_token=5a8212f4a2dcec763e3eeb8ca2dc78e1a6005be2' |
В ответ вы получите подтверждение остановки конференции:
1 2 3 |
{ "state": "stopped" } |
2. Удалите конференцию, используя метод Conferences – Delete Conference:
1 2 |
curl --request DELETE \ --url 'https://server.company.com/api/v3.1/conferences/0560438410?access_token=5a8212f4a2dcec763e3eeb8ca2dc78e1a6005be2' |
Ответ будет содержать ID удалённой конференции:
1 2 3 |
{ "id": "0560438410" } |
Приятных конференций!