Real-Time Video API tutorial

It is an easy-to-use video meeting tool.

A video conference room can be inserted in two ways:

1. Codeless — just copy a URL, paste iframe on your page and join a call.
2. API-based — for fine-tuning and integration with your platforms or enterprise internal systems.

Embed video meetings into an application or website with iframe or Server API/Client API allowing your team to build faster and release more often.

Get started

Create a meeting in a browser:

1. Open https://meet.gcore.com/new.

2. Click the Create conference button.

3. A Room URL will be created automatically.

4. Click the Join button.

5. Send the URL to other attendees to join your video call.

Example: https://meet.gcore.com/call/?roomId=serv2testroom

Embed a video call room in your website or app via iFrame. The iframe’s src attribute is specified as the URL.

Example:

      Copy
      
    <iframe allow="camera; microphone; fullscreen; display-capture" src="https://meet.gcore.com/call/?roomId=serv2testroom"></iframe>

Customize a video call room with URL attributes. 

Example: https://meet.gcore.com/call/?roomId=serv2testroom&displayName=JohnSnow

Codeless integration

Create Room URL

1. Generate a video room ID. Use an alphanumeric character set. For example: bokxlj33.

2. Add a server location to the beginning of the set. For example, insert "serv2" for a server in the USA: serv2bokxlj33.

3. Specify /call/ as a method for your video call room.

4. Insert the Room ID into the final URL. The result should be as follows: https://meet.gcore.com/call/?roomId=serv2bokxlj33

You can create a URL, save it, send it, or write it in your notes. The URL is reusable. The URL will be accessible all the time – before an event, during an event, and even 1 year later after an event.

The Room is created on a server when the first participant enters it.

The Room is automatically destroyed without saving information when the last participant leaves.

Embed Room on a Site

Embedding a meeting into a service or app requires using an iframe with the src attribute specified as the URL. Read the "Allowed domain names" section to learn how to configure your website’s domain so that browsers don’t block the iframe.

Settings of iframe must have the special permissions required for video calling:

allow="camera;microphone;fullscreen;display-capture;autoplay;screen-wake-lock"

HTTP Feature-Policy header provides a mechanism to allow: 

• camera – permission to use a cam inside iframe.  
• microphone – permission to use a mic inside iframe. 
• fullscreen – permission to open iframe’s UI in the fullscreen mode. 
• display-capture – permission to use the screen sharing feature inside iframe. 
• autoplay – permission to start the video autoplay inside iframe after page load. 
• screen-wake-lock – permission that allows devices not to dim or turn off the screen during a call.

Example:

      Copy
      
    <iframe src="https://meet.gcore.com/call/?roomId=serv2bokxlj33"    
allow="camera; microphone; fullscreen; display-capture; autoplay; screen-wake-lock"></iframe>

Mobile app integration

Embedding in Android app

Embedding in Android can be done in two ways:  

1. Android Native SDK – please look at SDK and open-source demo app.
2. WebView.

It’s better to use the native Android SDK. One-to-one calls and/or with many participants for real-time communication within your own app. 

There are two modules: 

1. SDK — a  native library of video calls to be implemented into apps. The library is responsible for all internal processes: get cam/mic data, make video streams, send, and receive data to/from a video server.
2. DEMO —  a native demo application with open-source code. The app shows cases and scenarios of SDK usage in real app. You can compile the code and run it.

WebView requires the use of the WebView class. To allow a video call room access the camera, you need to do two things: 

1. Override the  WebChromeClient.onPermissionRequest  method to avoid the default implementation. You can just return true. 
2. Add the  &nameScreenDisabled=true parameter  to the Room URL and call "Join" Client API method.

Embedding in iOS app

Embedding in iOS can be done in two ways:  

1. iOS Native SDK – please look at SDK and open-source demo app. 
2. WebView.

It’s better to use the native iOS SDK. One-to-one calls and/or with many participants for real-time communication within your own app. 

There are two modules: 

1. SDK —  a native library of video calls to be implemented into apps. The library is responsible for all internal processes: get cam/mic data, make video streams, send, and receive data to/from a video server.  
2. DEMO —  a native demo application with open-source code. The app shows cases and scenarios of SDK usage in real app. You can compile the code and run it.

WKWebView supports embedding pages that use WebRTC from iOS 14.5 onwards.  

To support older iOS versions, we recommend using one of the following options: 

• For iOS 14.3 and 14.4, use SFSafariViewController to open a web page containing an iframe with its src specified as a video call room URL. 
• Redirect to mobile Safari for iOS versions lower than 14.3.

To use Video Calls with Cordova (Phonegap) please use the plugin for SafariViewController.

Embedding in React Native app

Embedding in React Native iOS/Android can be done via wrapper:  

React Native Wrapper – please look at SDK and open-source demo app.

There are four modules: 

1. iOS Wrapper – React Native demo app with open-source code. 
2. Android Wrapper – React Native demo app with open-source code. 
3. SDK – native library of video calls to be implemented into apps. The library is responsible for all internal processes: get cam/mic data, make video streams, send, and receive data to/from the video server.  
4. DEMO – demo app with open-source code. The app shows cases and scenarios of SDK usage in the real app. You can compile the code and run it.

Video Call Customization

Calls or Webinars

Video call rooms

A video conferencing room is a room where all invited participants are active and have their cameras and microphones on. One video call room can hold up from 1 to 100 participants or more. 

A method to create video conferencing rooms is /call/. 

Example: https://meet.gcore.com/call/?roomId=

Webinar rooms

A webinar room is a room  where participants are divided into two groups: speakers and viewers. Speakers  are active participants with cameras and microphones. Speakers' video is shown on the screen of the webinar room, participants can watch and hear them. Viewers can only watch the speakers without interaction. They have neither camera, nor microphone on. One webinar room can hold up between 1 and 20 speakers and between 0 and 2000 viewers.   A method to create video conferencing rooms is /webinar/.  

Moreover, please see &itisparticipant attribute. 

Example: https://meet.gcore.com/webinar/?roomId=

Allowed domain names

Video calls are accessible from two types of domains:

1. companyname.gvideo.co – example of a client's special domain in our "gvideo.co" zone. 
2. video.domain.com – example of an external client's domain.

By default, we provide a third-level tech domain in the  "gvideo.co"  zone. If you prefer to use your own domain, please contact us.

Advanced URL Attributes for rich customization

Conferencing is customized by optional URL parameters for each iframe instance. It’s possible for each participant in a meeting to have different parameter combinations. 

      Copy
      
    Examples:

1. https://meet.gcore.com/call/?roomId=serv2testroom&displayName=JohnSnow
  
2. https://meet.gcore.com/call/?roomId=serv2testroom&displayName=JohnSnow&disableChat=true
  
3. https://meet.gcore.com/call/?roomId=serv2testroom&displayName=JohnSnow&disableChat=true&lang=en

Attribute details

&accessToken=<token>

It is a security access token generated on your side. If this parameter is specified, then, whenever a user enters a room, our server will additionally ask your authorization server whether the user with the peerID and accessToken parameters is allowed to connect. For more details, refer to the server-side authorization method. 

Type: String. default = not set.

Example: &accessToken=802380f4-dd70-4d60-9738-fb5ae8709ae7

&autoplayWithoutAudioTrack=<true|false>

It is used only for iOS devices and only for webinars.  

The iOS Safari Browser policy requires microphone permission to use audio with WebRTC. So, the browser requests a passive viewer (with no cam/mic buttons) in a webinar room to allow access to the mic. This parameter ensures the browser will not ask for access to a microphone, but will play audio using the simple "play" method. 

Type: Boolean, default = false.

Example: &autoplayWithoutAudioTrack=true

&canRecord=<true|false>

This allows to record and save everything what happens in a room to the Cloud. Not everyone needs a recording for security reasons, legal restrictions, or storage usage. Recording feature can be activated with this attribute. If the feature is on, a moderator can turn on the recording using the UI button.

Type: Boolean, default = false.

Example: &canRecord=true

&controlsDisabled=<true|false>

It is used to hide general controls and buttons from the screen. In this case, you should use ClientAPI methods to manage actions and allow users to turn on/off their cams/mics.

Type: Boolean, default = false.

Example: &controlsDisabled=true

&disableChat=<true|false>

This is designed to disable the chat function. If you add the parameter, the "Chat" button will be un-clickable and chatting will be unavailable for participants. It is useful when you prefer to use our own chat.

Type=Boolean, default value = false.

Example: &disbleChat=true

&handEnabled=<true|false>

This parameter helps to activate the "Raise Hand" feature in a room. Participants will be able to click the "Raise hand" button, and the raised hand icon will appear. The icon is displayed in participant’s tile and in the list of participants in the moderator’s panel.  

Type=Boolean, default value = false. 

Example: &handEnabled=true 

&hideIndicators=<true|false>

It is used to make icons inside a tile of a participant invisible. With this parameter, you can hide a participant name and the following icons: cam on/off, mic on/off, absence, raised hand, and pin button.

Type=Boolean, default value = false.

Example: &hideIndicators=true

&displayName=<name>

This allows to display a name of a participant.

A participant’s name may be known before they join the meeting. It is possible to pass their name from your internal system, so the user doesn't have to enter it on the welcome page.

If you specify the name in the attribute, the user will not be able to change it through UI.

Type: String, default value = not set.

Example: &displayName=JohnSnow

&itisparticipant=<true|false>

This parameter determines roles in a webinar room where there are participants and viewers. All attendees are viewers only by default.

Participants join a room as regular users and can turn on their camera and microphone. Participants also have a standard rectangle icon of a participant. Viewers can observe what is happening in a room, can see and hear, but they do not have a dedicated participant rectangle icon and cannot turn on their camera or microphone.

Note: It is used for webinar rooms only.

Type = Boolean, default value = false.

Example: &itisparticipant=true

&lang=<code>

This helps to set the UI language of a meeting to match your product or service. In general, the UI language depends on language settings of a participant's browser. A user sets the language in their browser settings, and then its value is transmitted by the browser in the "Accept-Language" header of an HTTP request info.  

Select one of these: 

• English = en
• French = fr 
• German = de 
• Luxembourgian = lb

Therefore, in most cases, you do not need to specify this parameter explicitly. If the UI of a video room  is translated and available for user’s language, then UI will be automatically switched to it. If a language is unavailable, the default English version will be shown. 

But sometimes you need to explicitly set a language based on your internal/enterprise settings, use this parameter. 

Type: String, default = not set.

Example: &lang=en

&maxBroadcasters=<num>

This sets the number of concurrent active attendees in a room at one time. This is the maximum value of users/attendees with turned on cams/mics.  

If another user starts to speak (be active, turn on the cam/mic), but the number of active attendees exceeds the specified value, then this user will receive a system error that they cannot turn it on: "The limit of maximum active attendees is exceeded". 

If no value is specified in the URL, any participant can turn on cam/mic. Please be aware that the number of active users is directly proportional to the load on media servers. With an overwhelming number of active attendees, a server may become overloaded, and newly connected users may see a connection error. 

The maxBroadcasters and maxWatchers parameters should be specified for each participant in the URL. Please refer to &maxWatchers parameter. 

Type: Numeric, default = 0. 

Example: &maxBroadcasters=10

&maxWatchers=<num>

This sets the number of concurrent attendees in a room at one time. This is the maximum value of users/viewers that can be in a room and be represented by their own "participant" rectangle. Participants can turn on their cam/mic at any time.   

The maxBroadcasters and maxWatchers parameters should be specified for each participant in the URL. Please refer to &maxWatchers parameter. 

Type: Numeric, default = 0. 

Example: &maxWatchers=50 

&minimizeTiles=<true|false>

This helps to squeeze the participants' tiles so that as many participants as possible can fit into one view without scrolling. This parameter allows increasing the number of simultaneously displayed tiles of participants on a screen to the maximum.

Type: Boolean, default = false.

Example: &minimizeTiles=true

&nameScreenDisabled=<true|false>

This helps to skip the welcome page with the name input field and cam/mic selection. You can skip the cam/mic selection elements when you already know the user's devices, or you need to connect the user immediately.

In that case, you should specify a user’s name in the attribute and use ClientAPI for "Join" method. Please refer to the "Join" method.

Type: Boolean, default = false.

Example: &nameScreenDisabled=true

&peerId=<id>

This is an identifier of a participant in case you want to set it explicitly. It is used for synchronization with your database or enterprise services.

You can select any value you prefer: number, GUID or even email.

Please, note: Only one session is possible with one unique identifier. If another participant with the same peerID connects, a new session will be created for the recent participant, while the session of the first one will be terminated. This is also the case when a link is opened in a different browser: a new session will be created with the recent browser, while previous connection will be terminated.

Example:

• User1 opens a link with &peerID=5 and then User2 opens the same link with &peerID=5. The second user will log in, but the server connection with the first user will be closed and the User1 will not be able to participate. Thus, you need to use two different peerID's.
• A User opens a link with &peerID=5 on a desktop computer and then opens the same link on a mobile device. They will log in on the mobile device, but the server connection with the desktop computer will be closed.

The peerID is used for:

• ClientAPI methods when you want to apply a method for a specific user.
• Download statistics on the attendance of a video call room and the duration of the users' presence on a call.

Type = String, default value = set by the video server with a random GUID value.

Example: &peerId=802380f4-dd70-4d60-9738-fb5ae8709ae7

&role=<role>

This parameter sets a privileged role for a participant.

Values:

• [not set] — regular participant.
• moderator —  super-user who can manage participants and video call settings.
• interpreter —  (beta) special role for interpreters from one language to another. A special audio channel is dedicated for them. Be aware that users of this role cannot turn on their cameras.

By default, all attendees are regular participants. They can manage their own cams and mics. But a moderator can manage participants, turn off their cams/mics, allow entering, etc. You can assign the "moderator" role to a host, and all other attendees will be regular participants. For more details, please refer to the Moderator feature.

Type: String, default = not set.

Example: &role=moderator

roomId=<id>

A room ID is set by you according to your rules. You don't need to call any special methods that might restrict you in naming rooms. 

An identifier consists of two parts: «server ID» + «room ID». A server ID is a "servN". Please see the List of servers. A room ID is any alphanumeric character set. If a server is not specified, you will be connected to a default one. If a server is specified explicitly, you will be connected to it.

Please note that &roomId determines the room number, but the prefixes /call/ or /webinar/ are interface modifiers. Thus, the methods /call/?roomId=testroom and /webinar/?roomId=testroom lead to the same room with a different interface. 

Type: String. Default = required field to be specified explicitly.

Example:

      Copy
      
    &roomId=1111   
&roomId=bokxlj33   
&roomId=serv21111   
&roomId=serv2bokxlj33   
&roomId=serv2f53c1aa5-1492-4964-b4fe-f83b5b545e8d

&sortPeers=<true|false>

It is used to arrange tiles of participants so that those who have cameras on will be displayed on the top.  

By default, the participants' tiles are ordered based on the time they connected. This order does not change during a meeting. For example, if first users connect without video, and then the last participant turns on the camera, they may be placed under the scrolling (visible area) of the screen and no one will see them. 

Using this parameter allows you to show active participants with video. However, enabling this option increases load on participants' CPUs. 

Type=Boolean, default value = false.

Example: &sortPeers=true

&startWithFS=<true|false>

It helps to start a meeting room in the Full Screen mode. Please see the "Full Screen mode" in our Knowledge Base.

Type: Boolean, default = false.

Example: &startWithFS=true

&token=<jwt>

The JSON Web Tokens is an open, standard method for representing claims securely between two parties: https://jwt.io/

The JWT allows you:

• To specify attributes inside a token, rather than URL attributes.
• Sign a token with a secret key and be sure that all parameters in it are specified by you, and cannot be changed by someone else.

Please see "Security" for details.

Type=String, default value = not set.

Example:

      Copy
      
    &token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X6GFjopXf62C6y4OgeeEk9KEb1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zWMk3sYLpWxULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg

&tokenLifetime=<milliseconds>

The parameter limits the lifetime of a token. The lifetime is counted in milliseconds from the first connection. After the specified period has expired, a participant cannot reconnect to the room with the token.

Type=Number, default value = not set.

Example: &tokenLifetime=60000

&video=<url>

This is a super feature for joint viewing of online broadcasts directly in a video call room. No, you do not need to "share screen" with others and lose both video and audio quality and overload one of the participant's PC. You just need to insert a code of the YouTube player, our player, or any other HTML player, and it will appear for all participants in the room. Besides, the player saves all its standard functions: adaptive bitrate, counting unique viewers, displaying ads, Google Analytics counter, etc. Please refer to .

Type=String, default value = not set.

Example: https://meet.gcore.com/call/?roomId=serv2testroom&displayName=John%20Snow&video=https%3A%2F%2Fwww.youtube.com%2Fembed%2FXBPjVzSoepo

&waitingRoom=<true|false>

The waiting room function allows a moderator to manually determine which user is allowed to enter a video call room and who is not.

After enabling the feature, each participant will see the "Please wait for confirmation" message.

Type: Boolean, default = false.

Example: &waitingRoom=true

Debug and Dev URL attributes only

A set of debug attributes can be used by developers to create and test a video call room.

These parameters are used for debugging only.

&accessUrl=<url>

A URL of REST method to check accessToken. Please see "Authentication of participants" for details. 

Make sure you use https:// instead of http://. 

Please do not use this attribute publicly. For public use, a URL must be registered on our server or in your account. 

Type=String, default value = not set.

Example: &accessUrl= https://your.domain.com/api/gcore/auth

&apiEvent=<url>

A URL to get webhooks/events from a video calls server. Please see "Webhooks" for details.

Make sure you use https:// instead of http://.

Please do not use this attribute publicly. For public use, URL must be registered on our server or in your account.

Type=String, default value = not set.

Example: &apiEvent=https://your.domain.com/api/gcore/webhook

&authEvent=<header>

This is for extra header request parameters and credentials for server-side webhooks/events. Use it for enabling Basic or Bearer authentication, etc.

Please do not use this attribute publicly. For public use, a URL must be registered on our server or in your account.

Type=String, default value = not set.

Example: &authorizationAccess=Basic%20Z2NvcmVfbWVldDo4dFpvOTZLSkhWRXFBanFBQlpZQg%3D%3D

&authorizationAccess=<header>

This is for extra header request parameters and credentials for server-side check of authorization.

Use it for enabling Basic or Bearer authentication, etc.

Please do not use this attribute publicly. For public use, URL must be registered on our server or in your account.

Type=String, default value = not set.

Example: &authorizationAccess=Basic%20Z2NvcmVfbWVldDo4dFpvOTZLSkhWRXFBanFBQlpZQg%3D%3D

Moderator

By default, all attendees are regular participants. They can manage their own cams and mics. But a moderator can manage participants, turn off their cams/mics, allow entering etc. 

A moderator can do the following:  

1. Operate the "Waiting room" function:  

• Activate and deactivate a waiting room.
• Confirm and reject a participant's entry

2. Operate cameras and microphones of participants: 

• Allow or disallow cameras and microphones.
• Ask participants to turn on cameras and microphones.

3. Operate the sharing screen feature:

• Allow or disallow the screen sharing.
• Ask to turn on the screen sharing.

4. Operate raised hands: 

• Remove a participant's hand.

5. Operate the list of participants: 

• Kick the user out of the room.

To use the moderator role, you need to follow these steps: 

1. Get a Secret Key for JWT. See the "Security" section.  
2. Generate a link for regular participants with &roomId=XXX parameter. 
3. Generate a JWT token and add additional attribute &role=moderator to it.  
4. Generate a link for moderators. Concatenate the JWT token from Step 3 to the general link from Step 2.

Example:

Link for a regular user:

      Copy
      
    https://meet.gcore.com/call/?roomId=serv0_test1

Link for a moderator:

      Copy
      
    https://meet.gcore.com/call/?roomId=serv0_test1&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwid2FpdGluZ1Jvb20iOnRydWUsImhhbmRFbmFibGVkIjp0cnVlfQ.DO_JHMDfK2mi5rycIepLVxDVs0qcQAXAhHvI7hcOIjw

Where JWT is:

• HEADER: (ALGORITHM & TOKEN TYPE)
• { "alg": "HS256", "typ": "JWT" }
• PAYLOAD: (DATA)
• { "role": "moderator", "waitingRoom": true, "handEnabled": true, "roomId": "serv0_test1" }

Recording

What can be recorded

Recording is a video recording of the entire interface of a meeting room, as it is seen by regular viewers. A video includes:  

• attendees,  
• screen sharing, 
• original audio of speakers.

Recording is a complex process that is carried out by our professional Streaming Platform. The video is recorded on a cloud server and is also stored in the Cloud of the Streaming Platform.   

When a meeting is over and a video is recorded, it is automatically converted and becomes available for viewing in the video player. You can download the video, copy the player code for viewing on a web site, or get HLS video stream and insert manifest.m3u8 into your mobile app. 

Recording can be started by moderator only. 

To record, you need to follow these steps: 

1. Generate a JWT token with additional attribute role=moderator inside it.  2. Add attribute canRecord=_true into the JWT.  3. Open a room with the link.   4. Open the "Moderator" panel inside a room.   5. Press the "Record" button.   6. Press the "Stop" button. 

A JWT example: 

PAYLOAD: (DATA) 

      Copy
      
    { "role": "moderator", "canRecord": true, "roomId": "serv0_test1" } 

Auto-recording

By default, a moderator can manually record meetings.  

If you want to record all meeting rooms automatically, you can enable the "Auto Recording" feature for your account.  

• Recording starts automatically for every new room in ±60 seconds after the first user logs in. 
• Recording goes on for as long as there is at least one user in the room. 
• Recording stops automatically after ±60 seconds after last user logs out. Thus, if by chance all users leave the room and return without a timeout, then the recording will continue.

Please note that, if one of the users forgets to close a browser tab, they still will be present in the room. And if they are present in the room, recording will continue. 

Ask your manager or support team to enable the Auto recording feature. 

Where to find recorded videos

Recording of room is made by our Streaming Platform. Video files are stored in the media storage. 

Steps to find a video: 

1. Open your personal dashboard via link: https://streaming.gcore.com/.  
2. Select the "Video hosting" tab. 
3. Select videos with the "Recording" title with the exact roomId and the exact time.  
4. Open the video.  
5. Copy the video player code, link of the player, or download the video on the "export" tab.

Also, you can use Special API of the Streaming Platform. Please see the "Getting Recorded Video" section. 

How to set up our recording feature

As you know, recording of a room is made by our Streaming Platform, and video files are stored in the media storage. 

Steps: 

1. Generate a permanent token in your personal account via the link.  
2. Use parameters:

• Name = "Video conference recording" or any title you prefer; 
• Role = Administrator; 
• Expiration = Never expire.

  3. Copy the token from the result page  4. Send us the copied token  5. Add the &canRecord advanced attribute to the URL for a moderator, or ask us to set the Auto Recording feature.

Example of a permanent token:

      Copy
      
    1030$0b219f0239c7a418c499a9b0f4d93f0b081700000c346ad254694b15d09981d7cf6b24e41a243df6e9e23d5483820d98921d64c0cb06e9981c842ab31fd0e4db 

Language Interpretation (beta)

In normal use, each user hears the original audio of a speaker. The interpretation feature allows users to hear the interpreter’s speech, that they can understand, in simultaneous translation mode. 

If a moderator wants to include interpreters in their meetings or webinars, they now can enable Language Interpretation. With it, a host can designate an unlimited number (over 20) of participants as interpreters during a video session.  

When a meeting or webinar starts, a host can turn on the interpretation feature which will provide interpreters with their own audio channels for the language they translate to. Attendees can then select the channel and listen to the audio translated in the language they need. They can also mute the original audio so not to hear it at a lower volume together with their chosen language.    

In case of meetings with interpretation, only the original audio of a meeting or webinar is recorded, not the translated speech.  

The languages below are available by default. If you need more, just please let us know: 

• Chinese, zh 
• Dutch, nl 
• English, en 
• French, fr 
• German, de 
• Luxembourgian, lb 
• Portuguese, pt
• Spanish, es 
• Swedish, sv 
• Ukrainian, uk

There can be more than one interpreter for one language. If several interpreters use the same link, all of them can speak in the corresponding channel. They can speak both simultaneously or/and consecutively. For consecutive interpretation, they just need to mute the microphones. 

For regular attendees, new language automatically appears when an interpreter is connected. 

If an interpreter disconnects from a room for whatever reason, regular users can select the language for 30 seconds. If none of the interpreters reconnects, the language will become unavailable for select, and listeners of that language will be switched to the original audio.   

A JWT example is: 

• PAYLOAD: (DATA) 
• { "role": "interpreter", "featureInterpreters": true, "intLang": "de", "roomId": "serv0_test1" }

Client API

Iframe Integration

Example of iFrame integration

      Copy
      
    <iframe allow="camera; microphone; display-capture" style="height: 100%; width: 100%;" src="https://meet.gcore.com/webinar/?roomId=qwesfder4w4&displayName=Tom&accessToken=sda3-q23aed-aerae&peerId=123123-321as-waaew-ads&apiEvent=https://example.com/api/meet&accessUrl=https://example.com/api/accessCheck/&itisparticipant=true&nameScreenDisabled=true&startWithFS=true&controlsDisabled=true"></iframe>

Please see Embed a Room on Site and Attributes details.

Interaction with iFrame

There is a special library for interacting with iframe, which should be loaded separately.

      Copy
      
    <script type="text/javascript" charset="utf-8" src="https://<yourdomain.gvideo.co>/meetBridgeApi.js"></script> 

Example:

      Copy
      
    <script type="text/javascript" charset="utf-8" src="https://meet.gcore.com/meetBridgeApi.js"></script> 

JavaScript's method for initialization:

      Copy
      
    meetIframeBridge = new MeetIframeBridge.default({ element: $iframe.get(0), roomId: "serv1m6oci9e8" });

Where:

• element is a DOM object of iFrame.
• roomIdis an ID of the room.

Note: Before initializing a class, you need to wait for an iframe element to be loaded.

Public methods of Real-Time Video iframe

Client API methods allow you to control a video room, perform actions with hidden main controls, react to what is happening in a room.

Example of method:

Initializing:

      Copy
      
    var meetIframeBridge;  
$('#meetframe').on("load", function() { 
            meetIframeBridge = new MeetIframeBridge.default({ element: $("#meetframe")[0], roomId: "serv1m6oci9e8" });       
});

Joining:

      Copy
      
    meetIframeBridge.method({ name: "join", data: {constraints: {video: false, audio: false }}, callback: (e) => { alert(1); return true; } });

Volume adjusting:

      Copy
      
    meetIframeBridge.method({ name: "setVolume", data: 100, callback: (e) => { alert(1); return true; } });

Name changing:

      Copy
      
    meetIframeBridge.method({ name: "changeDisplayName", data: "Tom", callback: (e) => { // return value } });

Getting screenshot of a user’s video:

      Copy
      
    meetIframeBridge.method({ name: "getScreenshotByPeerId", data: "id", callback: (e) => { // "e" parameter will have screenshotted data } });

Events from an iframe

Events on the client side allow you to react quickly to actions in a video room.

Example of event subscription:

      Copy
      
    meetIframeBridge.on('switchOnCamera', (e) => { your code here });

Server API

Server Endpoints

Video Conferencing Endpoints

Please see REST API specification. Below is a brief list of endpoints.

To access Server API methods, you need to be authenticated. Please see "Server API Authentication" below.

Example #1:

      Copy
      
    curl -L -X GET 'https://webrtc3.gvideo.co/rooms/serv1l8bsg8zw/durationOfBroadcast' -H 'Authorization: Bearer eyJ0eXAiOiJKV'

Example #2:

      Copy
      
    curl -X POST 'https://webrtc3.gvideo.co/rooms/serv0dxrpxoqr/recording/start' -H 'Authorization: Bearer eyJ0eXAiOiJKV'

Example #3:

Request:

      Copy
      
    curl -L -X POST 'https://webrtc3.gvideo.co/chat/clear-rooms' \  
-H 'Authorization: Bearer eyJ0eXAiOiJKV' \  
-H 'Content-Type: application/json' \  
--data-raw '{  
   "hostname": "102748.gvideo.co",  
   "rooms": [  
    {  
      "roomId": "serv0d17nfe1s"  
    }  
  ]  
}'

Response: 200 OK {"deleted":["serv0d17nfe1s"]} 

Common Response Codes

There is a list of common response codes of REST API methods:

List of servers

We have a lot of servers worldwide. Some of them are for public usage.

A server can be derived from a room ID. For example: &roomId = serv1qweqwe.

Note: There is an offset in a server’s URL. This is a temporary but necessary solution that will be changed soon. We will inform you additionally.

For debug purposes, you can call a server endpoint directly. But for public use, we apply strong restrictions and increase the level of security. Please tell us if you want to allow server-calls for specific servers and security parameters. In this case, all other calls will be rejected.

Example of  video server performance check

A call method such as:

      Copy
      
    https://webrtc3.gvideo.co/rooms/serv0l8bsg8zw1/durationOfBroadcast

For a non-existent room, the answer will be 400 error. If it is a 500 error or a timeout error, the server is unavailable.

Webhooks

Webhooks are user-defined callbacks triggered by meeting events. Webhooks are pushed to the URL specified in the apiEvent attribute:

Webhook joinPeer

This is a method of notifying that a participant has joined a room. This method is used for extra authentication on your side.

      Copy
      
    POST /joinPeer

Attributes:

• roomId
• peerId
• displayName

Example: 

      Copy
      
    {"event":"connected","roomId":"44fde071","peerId":"de9b6927","displayName":"user16"}

Example:

      Copy
      
    https://meet.gcore.com/call/?roomId=44fde071&displayName=user16&accessToken=caa630bb&peerId=de9b6927&apiEvent=https://dev.com/api/events&accessUrl=https://dev.com/api/accesscheck

Webhook closePeer

This is a method of notifying that the connection between a server and a participant’s browser has been closed. In most cases, this means that the participant has left the room intentionally or due to a connection issue.

      Copy
      
    POST /closePeer

Attributes:

• roomId
• peerId
• displayName

Example:

      Copy
      
    {"event":"disconnected","roomId":"44fde071","peerId":"de9b6927","displayName":"user16"}

Special API of Streaming Platform

Video conferencing tool manages data in real time. Thus, Server API and Client API of video conferencing are designed to control the behavior of users and video rooms in real time.

Statistics on usage and video recordings are stored in the Streaming Platform. Thus, please use

Video Platform’s REST API for those methods: https://api.gcore.com/docs/streaming.

To access Video Platform API, you need to be authenticated. Please see "Authentication of Participants and Access Limitation" above.

Statistics

Video conferencing tool sends statistics data every 30 seconds to the Video Platform servers. This means that the usage statistics can always be multiply by 30 seconds. 

1. General data about a room:

This is a summary about a room.

      Copy
      
    GET /streaming/statistics/peers/summary

Attributes:

• room_id
• from – start period of selecting data
• to – finish period of selecting data

Output codes: 

• 200 – OK, json object with the data. 
• 400 – Bad Request, in case of incorrect input attribute values. 
• 403 – Unauthorized access.   
• 404 – Not found, in case there is no data for a room or room is not found in statistics. 
• 500 – Internal error.

Output values:

• participants – total sum of unique participants in a room.
• start_time – UNIX time in seconds when the first participant entered, ex = 1624276920.
• end_time – UNIX time in seconds when the last participant left, ex = 1624358940
• duration – number of seconds when the room was «active», calculated as difference from the end_time parameter value and the start_time parameter value. Ex = 90660

Note: The result is aggregated data for all sessions of the specified room between «from» period until «to» period. Thus, if you use the same room ID each day, then use separate periods.

Example:

https://meet.gcore.com/call/?roomId=serv2test1 used for 60 minutes each day on Monday Jun 21 and on Tuesday Jun 22.

• /summary?from=2021-06-21T00:00:00.0Z&to=2021-06-21T23:59:59.99Z&room_id=serv1test1 – will return 60 minutes (60 mins on Jun 21).
• /summary?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv1test1 – will return 120 minutes (60 mins on Jun 21 + 60 mins on Jun 22).

Example of usage:

      Copy
      
    https://api.gcore.com/streaming/statistics/peers/summary/?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv2test2a

Example of return data:

      Copy
      
    {   
    "data": {   
        "participants": 3,   
        "start_time": 1624268280,   
        "end_time": 1624358940,   
        "duration": 90660   
    },   
    "errors": []  
}

2. Detailed data per participant:

This is data for each participant’s sessions in a room.

If an event lasted 60 minutes, and the user attended it for the first 5 minutes, then left the room, and joined again for the last 5 minutes, the statistics will reflect two sessions, each lasted for five minutes: 5 min + 5 min = 10 minutes (that is, = 600 seconds, instead of 3600 seconds of the total duration).

      Copy
      
    GET /streaming/statistics/peers/

Attributes:

• room_id
• from
• to

Output codes:

• 200 – OK, json object with the data.
• 400 – Bad Request, in case of incorrect input attribute values.
• 403 – Unauthorized access.
• 404 – Not found, in case there is no data for room or room is not found in statistics.
• 500 – Internal error.

Output values:

• array of participant sessions
• person_id – peerId data (your value, if it was specified in URL attributes, or unique GUID made automatically if it was omitted)
• join_time – UNIX time in seconds of the participant's join time, ex = 1624268280
• leave_time – UNIX time in seconds of the participant's leave time, ex = 1624269300
• duration – number of seconds of the session, ex = 1260

Example of usage:

      Copy
      
    https://api.gcore.com/streaming/statistics/peers/summary?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv2test2a

Example of return data:

      Copy
      
    {   
    "data": [   
        {   
            "person_id": "peer2",   
            "join_time": 1624268640,   
            "leave_time": 1624269300,   
            "duration": 660   
        },   
        {   
            "person_id": "peer1",   
            "join_time": 1624270800,   
            "leave_time": 1624274520,   
            "duration": 3720   
        },   
        {   
            "person_id": "peer1",   
            "join_time": 1624270380,   
            "leave_time": 1624270740,   
            "duration": 360   
        }   
    ],   
    "errors": []   
} 

Getting Recorded Video

Recordings of room meetings are stored in the media storage of the Streaming Platform.

You need to search the video and then get by id.

1. Search a video

      Copy
      
    GET /streaming/videos/search

Attributes: q – Search query. The search performed among all video names. Specify roomId as a search query.

Output values: Array of available videos for specified ID.

If a session lasted more than 4 hours, the recording will be divided into several videos for 4 hours each. In this case, you need to get all videos separately.

Please see more details in documentation. 

2. Get video metadata

      Copy
      
    GET https://api.gcore.com/streaming/videos/{video_id}

Please see more details in documentation.  

Output values: Metadata of the video. Use fields "hls_url" for .m3u8 stream in external players or "origin_host"+"origin_resource" for getting an original MP4 file.  

Example of output data:  

      Copy
      
    {   
  "hls_url": "https://id10835.gcore.com/videos/10835_UaX2pjxen2guUw3/master.m3u8",   
  "origin_host": "s-ed1.cloud.gcore.lu",   
  "origin_resource": "9208-mediaplatform10835/videos/UaX2pjxen2guUw3.mp4",   
}

Please see more details in documentation.  

Example of usage: 

Step 1: https://api.gcore.com/streaming/videos/search?q=serv1test2a

Step 2: https://api.gcore.com/streaming/videos/117800

Rate Limits

There is a general limit of four requests per second. If you exceed the rate limit, you will receive a message.

Security

Calling API should be done through an endpoint on your server. This will help to avoid exposing secret keys to users and to keep them safe.

Validating Client API Requests

What is a JWT

To access Client API, we use  JSON Web Tokens (JWT), which is an open, industry standard  RFC 7519  method for representing claims securely between two parties.

For more information what JWT is and how to use it please visit https://jwt.io/introduction

JWT allows you to accurately determine the validity of the video room settings and unambiguously determine the belonging of the token to your account. 

To use the JWT, you need a Public & Secret Key. A new key is generated by you. Send us your public part of the key via support or personal manager. Please see "RSA Public & Secret Key generation" section below for details.

Limitations when using JWT

You can activate the option to use the JWT in your account. If you activate it, you will have to send a JWT &token=xxx in every request. Without a token, the "Access denied" message will appear.

If you activate the JWT option, you will not be able to use the &accessToken=xxx attribute.

JWT Header

The header typically consists of two parts: the type of the token and the signing algorithm being used.

Signing algorithms are:

• RS256 – asymmetric key,
• HS256 – symmetric key.

      Copy
      
    HEADER:ALGORITHM & TOKEN TYPE   
{  
"typ": "JWT",  
"alg": "RS256"  
}

      Copy
      
    HEADER:ALGORITHM & TOKEN TYPE   
{  
"typ": "JWT",  
"alg": "HS256"  
}

JWT Body

The body of a JWT contains important data that should be signed and verified. The data in a JWT has a higher priority over the values of the same parameters specified in the URL attributes. This means that if an attribute value is specified both in a JWT and in the URL attribute set, the value from the JWT will be used.

Please refer to the table of attributes above to see the parameters that can be set in a JWT.

Priority of data from a JWT and URL:

• Parameters with the "JWT" label can be specified inside a token or as an attribute in the URL. If an attribute value is specified in a token, the value in the URL is ignored. If an attribute is not specified in a token, the attribute value will be taken from the URL.
• Parameters with the "URL" label can only be specified as an attribute in the URL.

The list of extra attributes for a JWT: 

• startTime – planned start time of an event in a video room. Please see "Webhook joinPeer method". Date/time is in UTC time zone only, represented as number (milliseconds since Unix epoch), formatted as ISO 8601.
• iat – (optional) Issued At. The "iat" claim identifies the time at which the JWT was issued. This claim can be used to determine the age of a JWT. Date/time is in UTC time zone only, representedas number (milliseconds since Unix epoch), formatted as ISO 8601.

The list of attributes is expanding, tell us what attributes (from general list of URL attributes) you need inside a token.

      Copy
      
    PAYLOAD:DATA  
{  
"roomId": "abcd1234",  
"role": "moderator",  
"startTime": "2022-06-21T00:00:00.0Z",  
"iat": 1516239022  
}

Example:

      Copy
      
    https://meet.gcore.com/call/?roomId=YOUR_ROOM_ID&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X_6GFjopXf62C6y4OgeeEk9KEb_1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zW_Mk3sYLpW_xULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg

JWT Signature

Use your key to sign the token with the algorithm specified in the header.

The signature is used to verify the data wasn't changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is.

We highly recommend using RS256 asymmetric type of algorithm. See section "RSA Public & Secret Key generation" to generate public/private keys.

Validating Server API Requests

Validation with Authorization Header

To access Server API and Streaming Platform API, we use an API token in the Authorization header. The API token is a unique key that all users and applications should add to requests to interact with our services.

Please authenticate via API.

Choose one of the methods described below: Bearer authentication or Permanent API tokens.

Bearer Authentication

The token will be provided upon Login request with login and password from your personal account. 

In the response, you will get two tokens: access and refresh. 

To manage Server API services, add your access token after Bearer in the authorization header like this:  

      Copy
      
    Authorization: Bearer eyJ0eXAiOiJKV 

Use the  Refresh request to refresh your access token. 

Steps as an example: 

1. You authorize in your backend using your username and password: https://api.gcore.com/docs/account#tag/Account/paths/~1auth~1jwt~1login/post 
2. You get two token values: "access" and "refresh".  
3. The "access" token is a token that is active for several hours (24 hours, but we recommend updating every 4 hours). 
4. You pass the auth headers into each endpoint: 'Authorization': Bearer ${token} '. 
5. If the token is correct, everything is fine. 
6. If not, then a 401 error will be returned.

Example:

      Copy
      
    curl -L -X GET 'https://webrtc3.gvideo.co/rooms/serv1l8bsg8zw/durationOfBroadcast' -H 'Authorization: Bearer eyJ0eXAiOiJKV'

Authentication of Participants and Access Limitation

We allow integration with your user control systems. It could be an external CMS, LMS or any security server. You can verify every user who enters a room.

Our server calls the method specified in &accessUrl attribute. Your server should return code as below. Based on the code, the system allows access to the room or doesn't.

If the access to the specified method is protected via Basic authorization, you need to register a required header in the attribute &authorizationAccess=<header>.

These debugging attributes can be used in the URL. But for public use, you need to inform us to register methods on the server.

Example:

      Copy
      
    https://meet.gcore.com/call/?roomId=44fde071&displayName=user16&accessToken=caa630bb&peerId=de9b6927&apiEvent=https://dev.com/api/events&accessUrl=https://dev.com/api/accesscheck

POST

Input values:

• accessToken – unique security identifier from &accessToken attribute
• roomId – ID of the room from &roomId attribute
• peerId – ID of the participant from &peerId attribute

Example:

{"accessToken":"caa630bb","roomId":"44fde071","peerId":"de9b6927"}

Output codes we require from you:

More examples:

• How to prevent unregistered users from joining – send 401 Locked for requests with empty peerId.
• How to close a room after the event is over – send 423 Locked for all requests after the event is over.
• How to limit the maximum number of participants – send 423 Locked for all requests after the maximum is reached, resend 200 OK for a room with decreasing number of participants when someone leaves.

Troubleshooting

JWT Digital Signature Algorithm

We use RS256 or HS256 algorithm for signing and generating hash. RS256 refers to the SHA256 hash function (RFC states). 

Please use https://jwt.io/ to verify your JWT tokens.

RS256

RS256 refers to the SHA256 hash function. (RFC states).

RSA key of size 2048 bits or larger must be used with this algorithm.

The RSASSA-PKCS1-v1_5 SHA-256 digital signature is generated as follows: generate a digital signature of the JWS Signing Input using RSASSA-PKCS1-v1_5-SIGN and the SHA-256 hash function with the desired private key. This is the JWS Signature value.

Please see "RSA Public & Secret Key generation" section below for details.

HS256 

A key of the same size as the hash output (for instance, 256 bits for "HS256") or larger MUST be used with this algorithm. 

RSA Public & Secret Key generation

Keys can be generated by any RSA keygen tool. If you don’t know what to do, we recommend using the OpenSSL tool.

To perform the following actions for Windows or Linux, check and/or install OpenSSL on your system.

Commands to generate secret key and export public key:

      Copy
      
    openssl genrsa -out key_name.key 2048

      Copy
      
    openssl rsa -in key_name.key -pubout -outform PEM -out key_name.key.pub

File key_name.key.pub will contain public part of the key. File key_name.key will contain the private part of the key.

Note: The number "2048" in the above command indicates the size of the private key. You can choose one between 2048 and 4096 (these numbers represent bits). The larger sizes offer greater security, but this is offset by a penalty in CPU performance. We recommend the best practice size of 2048. It seems like 2048 bits is enough for the foreseeable future (2030 horizon).