Go back

How to get started with TrueConf API

December 20, 2019
Dimitrii Zuikov

Dimitrii Zuikov

With TrueConf, you can use video conferencing to facilitate your business processes: from video communication with your website visitors to video contact center services. This article explains how to implement different video conferencing scenarios using TrueConf APIs.

Getting Started

TrueConf Server API is an application programming interface designed for interaction of your applications with TrueConf Server. It implements RESTful API architecture and is based on GET, POST, PUT and DELETE HTTP requests which are returned in JSON format by the server. To see the full list of TrueConf Server API features, please read our documentation.

How to get started with TrueConf API 1

Please note that you need to configure HTTPS in the control panel of TrueConf Server.

We recommend using OAuth 2.0 protocol for APIs. You can find more information about it in our server documentation.

The application interacts with API in the following way:

  1. The application requests a temporary access token.
  2. The application receives the access token.
  3. The access token is used to perform requests from the application to the server.

You do not have to create an OAuth application, but rather use the Secret key from the Web → Web security section of the TrueConf Server control panel, but we do not recommend this method.

This Secret key is an unlimited time access token. This means that it is valid until you manually recreate it with the Generate a new secret key button. The token provides full access to all API functions without pre-authorization using the OAuth protocol. Therefore, we recommend using the secret key only for API testing or for use only by a server administrator with rights that you can’t specify when creating an OAuth application (e.g. reading logs).

Step 1. Creating OAuth Application

Open TrueConf Server control panel and proceed to API → OAuth2. Create a new OAuth 2.0 application and check the list of necessary permissions.

To perform the following examples, you will require the following permissions:

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

Application ID and Secret key will be automatically generated when the application is being created.

To test the API features, you can use cURL utility (built-in Windows 10 version 1803 or higher) or Postman software. We recommend using Postman as one of the most convenient options.

Step 2. Creating an Access Token

  1. In Postman, enter the request in a new workplace:

where server.company.name is an IP address or an external IP address that is set in Web → Settings section of TrueConf Server control panel.

  1. Choose the HTTP method POST on the left side of an entry field.
  2. Open the Body tab and set the following parameters:
  • type x-www-form-urlencoded
  • the following KEY – VALUE pairs:
KEY VALUE
grant_type client_credentials
client_id 96f2973300c9b7740dd315b3d7890c60fb787fd5
client_secret e19769eb12f6cad7847260dfaa0e94f4a9537f2e

where client_id and client_secret are Application ID and Secret key respectively (they were obtained when the application was created).

  1. Press Send to proceed.
  2. If processed successfully, the server returns JSON object with the access token details:

Description:

  • access_token – the access token itself.
  • expires_in – expiration period in seconds from the moment of conference creating (24 hours).
  • token_type – a type of access token, always equals “Bearer”.
  • scope – the list of permissions granted to this application.
When the access token expires, it becomes invalid and you will need to request a new one.

Step 3. Creating a Multipoint Conference

Please use the Conference method to create a new video conference.

  1. Create a list of features for the conference in ObjectConference and set the parameters:
  • "topic":"My Conference" – conference name.
  • "type":0conferencing mode; in this case a symmetric one.
  • "auto_invite":1 – automatic invitation of participants once the conference starts.
  • "max_participants":10 – the maximum number of participants.
  • "invitations"  – the list of participants in format {"id":"user_id"}, where user_id is a username of the participant.
  • "schedule":{"type":-1}–  conference schedule; in this case room (without schedule).
  • "owner":"helen" –  username  of the conference owner.
  1. JSON object of the conference will look in the following way:

  1. Enter the request:

  1. Choose the HTTP method POST.
  2. In Body tab:
  • set the raw type
  • add the JSON request in entry field.
  1. Send the request. If the request has been successfully processed, the server returns the JSON object containing the details of the created conference:

The server creates a conference ID which is displayed in the idfield.

In case of an error, the server returns the JSON object with the error message.

Step 4. Getting the Conference List

You can get the list of conferences with the help of Conferences method. Please use the HTTP method GET to perform the request:

The JSON object returned to you by the server will contain the room you have previously created.

Step 5. Getting the Information About the Conference

To obtain the information about the conference, use the Conferences method, the conference ID and the HTTP method GET for the request:

The server returns the JSON object containing the required information.

Step 6. Launching the Conference

To start a video conference, use the Conferences method, the conference ID and the HTTP method POST for the request:

If the request has been successfully processed, the server starts the conference immediately. The participants will immediately be invited to the conference, as you have previously set the automatic invitation during creating the conference.

Step 7. Inviting a New Participant to the Conference

Once the conference is started, you can invite new participants. To send an invitation, use the Conferences_Participants method and HTTPS method POST:

Enter the JSON {"participant_id":"user_id"}, где user_id is a username, e.g. {"participant_id":"kevin"}in Body tab in Postman.

If processed successfully, the server returns ObjectParticipant object of the invited participant.


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

Sign up for newsletter