Getting Started

VideoKit is a service that provides an API and SDK that allow you to add video communications into your web application. A basic integration should take just a few minutes and give you working video call functionality with sensible layout and appearance. From there, you can customize appearance and behavior, and subscribe to events if you want deeper integration with your application.

Starting with a basic call

To get started, just include our SDK and then initialize a call. We need just an apiKey, a callId, and a container. Here's a full working example, which you are encouraged to try out:

1
2
3
4
5
6
7
8
9
10 <div id="video-call"></div>
 
<script src="https://videokit.io/v1/video-kit.js"></script>
<script>
  VideoKit({
    apiKey: 'YOUR_API_KEY',
    callId: 'my-call-1293487',
    container: '#video-call'
  });
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14 import React, { useEffect, useRef } from 'react';
import VideoKit from 'videokit';
 
const App = () => {
  const vk = VideoKit({
    apiKey: 'YOUR_API_KEY',
    callId: 'my-call-1293487',
  });
  const videoCallEl = useRef();
  useEffect(() => vk.mount(videoCallEl.current));
  return (
    <div ref={videoCallEl}></div>
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13 <template>
  <main>
    <div ref="videoCall"></div>
  </main>
</template>
<script>
import VideoKit from 'videokit';
const vk = VideoKit({
  apiKey: 'YOUR_API_KEY',
  callId: 'my-call-1293487',
});
vk.mount(this.$refs.videoCall);
</script>

The callId is an arbitrary identifier provided by you that is unique to the call. You make this up however it makes sense to your application, and then users joining with the same callId will be in the same call. You don't need to register or initialize the call in any other way beforehand.

Using the npm module

The VideoKit client is also available as an npm module:

1 npm install videokit

Then use the module in your front end application:

1
2
3
4
5
6
7
8
9
10
11
12 <div id="video-call"></div>
 
<script>
import VideoKit from 'videokit';
 
const vk = VideoKit({
  apiKey: 'YOUR_API_KEY',
  callId: 'my-call-1293487'
});
 
vk.mount(document.querySelector('#video-call'));
</script>

Participant user details

By default, users will appear as anonymous. In order to specify their name and avatar, send along those parameters from your front end application:

1
2
3
4
5
6
7
8
9 VideoKit({
  apiKey: 'YOUR_API_KEY',
  callId: 'my-call-1293487',
  container: '#video-call',
  user: {
    name: 'Pat Benetar',
    avatar: 'http://gravatar.com/avatar/?d=retro'
  }
})

Secured calls with JWT tokens

Tokens are JWT's signed by your private key, and allow you to specify verifiable user and call details not subject to tampering or spoofing.

Calls can be secured by creating a JWT token comprised of VideoKit parameters, signed with your private key. The token must include your apiKey, callId, and a user object, and may contain all other VideoKit parameters. The apiKey must have a security level of token configured in the admin interface for the given key.

1
2 const token = await fetch('http://myapplication.com/api/videoKitToken')
VideoKit(token)

Generating tokens

You can either send POST requests to our back-end API, or else you can generate your own tokens in your back-end application.

1
2
3
4
5 curl -XPOST https://videokit.io/api/token \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api_secret>' \
  -d '{ "apiKey": "YOUR_API_KEY", "callId": "my-call-1293487",
  "container": "#video-call", "user": { "name": "Pat Benetar" } }'

1
2
3 HTTP/1.1 200
 
{ "token": "eyJhbGciOiJIUzI1NiIsI..." }

You can also generate tokens using a library such as jsonwebtoken for node.js. For example, you can create a new JWT token the following way:

const jwt = require('jsonwebtoken');
const token = jwt.sign(
  {    apiKey, callId, user },
  privateKey,
  { algorithm: 'RS256' },
);

Customizing appearance

You can change the appearance of the video call interface by providing style parameters. For ultimate flexibility, you may also wish to provide your own external stylesheet URL.

1
2
3
4
5
6
7
8
9
10
11 VideoKit({
  apiKey: 'YOUR_API_KEY',
  callId: 'my-call-1293487',
  container: '#video-call',
  stylesheetUrl: 'https://myapplication.com/css/videokit.css'
  style: {
    gap: 10,
    positiveColor: '#ff00ff',
    negativeColor: '#203090',
  }
});

See more about style parameters in the Style Object reference below.

Listening to events

For a deeper integration, you may wish to listen to events and react from your consuming application. For example, when each user joins the call, you may want to flash a message of some sort. In that case you can listen for the peerJoined event, and take whatever appropriate action.

1
2
3
4
5
6
7
8
9 const vk = VideoKit({
  apiKey: 'YOUR_API_KEY',
  callId: 'my-call-1293487',
  container: '#video-call'
})
 
vk.on('peerJoined', event => {
  console.log("Peer joined the call", event)
})

See more about style parameters in the Events reference below.

Alternative iframe API

Under the covers, the JavaScript SDK generates an iframe and sets up the event pipeline with messages traveling through postMessage and event emitters. If you prefer, you can construct your own iframe and listen for your own events manually, without the JavaScript SDK.

1
2
3
4 <iframe
  src="https://frame.videokit.io/call?callId=my-call-1293487&apiKey=YOUR_API_KEY"
  allow="camera;microphone;fullscreen;speaker;display-capture"
/>

In this approach, set up your own iframe with a src attribute pointing to https://frame.videokit.io with query parameters matching arguments to the VideoKit() initialization above. Specify objects' keys and values using conventional syntax in the form of user[avatar]=....

API Reference

VideoKit parameters

Initialize the JavaScript library in the browser with these parameters to VideoKit(params|token). Pass parameters either directly as an object with keys below, or else as a signed JWT token.

name	type	required?	description
`apiKey`	string	required	Your API key.
`callId`	string	required	Arbitrary identifier provided by you that is unique to the call. You make this up however it makes sense to your application, and then users joining with the same `callId` will be in the same call.
`user`	object	optional	Specify details like `name`, `avatar`, and `role` for the user joining the call. More details below. This method is not secure in that it allows motivated users to spoof their own details.
`modules`	array	optional	Specify modules to include in the user interface. Modules available include `actions` and `participants`.
`style`	object	optional	Specify visual style attributes.

User object

The user object above has these optional properties.

name	type	required?	description
`name`	string	optional	The name of the user joining the call. Displayed to other users in the call on their video feed.
`avatar`	string	optional	A URL to an image to be used as the user's avatar.
`role`	string	optional	Specify whether this user should be a `host` or `participant`
`startMuted`	boolean	optional	Start with the mic muted when joining the call.
`startPaused`	boolean	optional	Start with the camera paused when joining the call.

Style object

The style object above has these optional properties.

name	type	required?	description
`streamGap`	string	optional	Pixel gap between video streams
`streamBorderRadius`	string	optional	Border radius on video streams
`baseColor`	string	optional	Default text color
`positiveColor`	string	optional	Selected / active color
`negativeColor`	string	optional	Muted / paused color

Instance methods

vk.mute()

Mute the participant's outgoing audio stream.

vk.unmute()

Unmute the participant's outgoing audio stream.

vk.pause()

Pause the participant's outgoing video stream.

vk.resume()

Resume the participant's outgoing video stream.

vk.configure({ style, modules })

Reconfigure an instance with style or modules parameters.

vk.broadcast({ data })

Broadcast data to all participants in the call. On the receiving end, listen with vk.on('broadcast', ...)

vk.on(event, handler)

Listen to events and run a handler function. See more in the following section below.

Event reference

A VideoKit instance is an EventEmitter, and uses node's event API (e.g. vk.on(event, data => {...}))

event	data	description
`muted`	`{ peer }`	Local participant turned off their microphone.
`unmuted`	`{ peer }`	Local participant turned on their microphone.
`paused`	`{ peer }`	Local participant turned off their camera.
`resumed`	`{ peer }`	Local participant turned on their camera.
`broadcast`	`{ data }`	Custom application data was broadcast to everyone.
`joinCallAttempt`	`{}`	An attempt to join the call is happening.
`joinCallError`	`{ error }`	The `joinCallAttempt` failed.
`joinedCall`	`{}`	The `joinCallAttempt` succeeded.
`leftCall`	`{}`	Local particpant left the call.
`peerJoined`	`{ peer }`	Another participant joined the call.
`peerLeft`	`{ peer }`	Another participant left the call.