Blog

News

Press Releases

Events

Knowledge Base

Terminology

Webinars

Go back

How to Use TrueConf API to Make Video Calls from the Website

June 21, 2019

Dimitrii Zuikov

Categories: Knowledge Base, Automation and API

With TrueConf Server API, you can create a click-to-call widget to make instant video calls from your website.

This widget allows your website guests to call their managers for a personal video consultation at any time. They don’t need to fill out any contact forms — just type in the name.

Adding the widget to your website is easy. Install TrueConf Server to get started

Download for Free

You won’t spend more than 15 minutes setting up the server.

Table of Contents

How to Interact with API

You can access TrueConf Server API via OAuth 2.0. For more information, please refer to TrueConf Server documentation.

TrueConf Server API is accessed through HTTP requests sent to the server.

The server sends back replies as JSON objects.

A list of TrueConf Server API-based functions can be found below:

API Documentation

Step 1: Make a video call to TrueConf Server through API requests. For this purpose, you should create a conference with two participants (one of them is your website manager).

Step 2: Get HTML code of your widget in TrueConf Server control panel.

Step 3: Add the widget to your website.

Step 4: Delete the conference after its ending.

Creating and setting up a conference using API

TrueConf Server Setup

Configure the server to support HTTPS connections
Add your website manager as a server user to let them receive video calls from guests
Create an OAuth 2.0 application.

Let’s get started!

How to Use TrueConf API

Obtain an API access token
Create a conference by using Conferences method and set the following parameters:

"schedule":{"type":"-1"} — without schedules
"max_participants": 2 — for two participants
"allow_guests": true – the ability to invite guests.

To connect guest users to the video conferences hosted on TrueConf Server, you need to add the Public conferences extension to your licence. To learn more about it, contact us.

"auto_invite": 1 — automatic invitation of participants if any participant (including a guest) joins the conference. This parameter also can have values:
- 0 – do not send invitations (default value);
- 2 – send invitations only if invited participants joins the conference.

Appoint your website manager as the conference owner and indicate their TrueConf Server username, e.g., "owner":"george".

The following examples of TrueConf Server API requests are intended to be used with cURL.

To handle requests, you can also use Postman software, as described in the article about the introduction to TrueConf API.

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'

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'

If the conference has been successfully created, the server sends back a reply with the conference data.

{
  "id": "0560438410",
  "type": 0,
  "topic": "My Conference",
  "owner": "george@server.company.com",
  "description": "",
  "max_podiums": 2,
  "max_participants": 2,
  "schedule": {
    "type": -1
  },
  "invitations": [],
  "url": "https://server.company.com/c/0560438410",
  "webclient_url": "https://server.company.com/webrtc/0560438410",
  "allow_guests": true,
  "allow_guests_message": true,
  "allow_guests_audio_video": true,
  "auto_invite": 1,
  "state": "stopped"
}

{

"id": "0560438410",

"type": 0,

"topic": "My Conference",

"owner": "george@server.company.com",

"description": "",

"max_podiums": 2,

"max_participants": 2,

"schedule": {

"type": -1

"invitations": [],

"url": "https://server.company.com/c/0560438410",

"webclient_url": "https://server.company.com/webrtc/0560438410",

"allow_guests": true,

"allow_guests_message": true,

"allow_guests_audio_video": true,

"auto_invite": 1,

"state": "stopped"

}

Save the ID parameter of your conference page.

Add your website manager as a participant of the conference you have created (previously you have appointed them as the conference owner) by using Conferences_Invitations method. In $conference_id, indicate id given in the previous paragraph.

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"}'

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"}'

In response, the server sends back the object that contains data on the participant you have added.

{
    "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"
    }
}

{

"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"

}

To connect to the conference by-passing the authorization page, obtain login data from Software_Clients – Get Client List:

curl --request GET \
--url 'https://server.company.com/api/v3.1/software/clients?call_id=0560438410'

1 2	curl --request GET \ --url 'https://server.company.com/api/v3.1/software/clients?call_id=0560438410'

The response will contain a JSON object with the list of all applications for connecting to a conference, including "name": "TrueConf Web" JSON object and login data to connect via WebRTC:

{
    "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>"
        }
    ]
    ...
}

{

"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>"

}

]

...

}

Save the web_url parameter.

Well done!

You can make a test call via TrueConf Server API on our website.

Add the Widget to the Website

Use HTML code template of your widget which is available in TrueConf Server control panel as shown in our article. Add url from the object with conference data you have previously received to src parameter.

Once your website guest joins the conference via the widget, TrueConf Server automatically sends an invitation to the website manager (auto_invite parameter).

Tracking widget events

The widget can send notifications about events and errors using postMessage technology. It will also send the following messages:

notSupported –the browser does not meet requirements of the widget
connectionFail – a user could not connect to the server
loginFail – a user could not log in
callFail – a user could not join the conference
hangUp – a user hung up (left the conference)
remoteHangUp– a user was removed from the conference, e.g., by the moderator
logout– a user logged out
connectionClosed– the user disconnected from the server.

You can use such notifications for tracking the moment of conference ending, e.g., hangUp or remoteHangUp.

Start tracking messages before embedding the widget into your website; otherwise you may miss them.

Deleting a conference

You can only delete the conference that has already been ended. When you receive the message about the call ending, end the conference with the help of Conferences – Stop Conference method:

curl --request POST \
--url 'https://server.company.com/api/v3.1/conferences/0560438410/stop?access_token=5a8212f4a2dcec763e3eeb8ca2dc78e1a6005be2'

1 2	curl --request POST \ --url 'https://server.company.com/api/v3.1/conferences/0560438410/stop?access_token=5a8212f4a2dcec763e3eeb8ca2dc78e1a6005be2'

In response, you receive a notification about the conference ending

{
    "state": "stopped"
}

{

"state": "stopped"

}

Delete a conference with the help of Conferences – Delete Conference method:

curl --request DELETE \
--url 'https://server.company.com/api/v3.1/conferences/0560438410?access_token=5a8212f4a2dcec763e3eeb8ca2dc78e1a6005be2'

1 2	curl --request DELETE \ --url 'https://server.company.com/api/v3.1/conferences/0560438410?access_token=5a8212f4a2dcec763e3eeb8ca2dc78e1a6005be2'

The answer request will contain the ID of the ended conference.

{
    "id": "0560438410"
}

{

"id": "0560438410"

}

Happy video conferencing!

Still have questions? Please contact our support team directly via online chat.