Key Concepts

Kaleyra Video solution has the following main entities:


A Company represents a Kaleyra Video instance. It is a dedicated space where you can register your participants, create rooms and live calls, adjust the user experience to your brand, and much more. The following parameters are required for it:

  • An API key: A secret string that uniquely identifies the instance and must be included in the header of every REST API request.
  • A web application id: To be used in web SDK integrations.
  • A mobile application id: To be used in mobile SDK integrations.

Companies have a set of customizable options such as:

  • Name
  • Default language
  • Logos
  • Theme
  • Virtual Backgrounds


Users in Kaleyra Video are able to participate in calls. Each user is identified by an id that is unique inside a Company.

Each user can have one of these 2 roles:

  • basic: They can join rooms. They can create rooms only if at least one participant has a plus role.
  • plus: They can join rooms. They can create rooms.

Kaleyra Video does not record or store any personal information of the participants.

Participant mapping has to be done in an external system. Kaleyra Video participants can be mapped to users of the target systems in many ways, the simplest being saving their user id in a column of a table on the database.
It is also possible to specify an endpoint to be used to retrieve the display name and user avatar during a call.


A room represents a virtual space where users communicate. A user that is involved in a room conversation – even if not joining – is called a participant.
A room must have at least 2 participants, and at least 1 of them must have a plus role. It can hold a maximum of 25 participants, although the actual number of supported participants depends on the network capacity of the endpoint.
Participants are defined at room creation, and each participant is assigned a different link for joining the call. This improves the level of security since each link is unique and uniquely associated with the user.

For each participant, you can define which tools are available. The complete list of tools is the following:

  • Chat: Exchange text messages with other participants.
  • Screen sharing: Share desktop or mobile phone screen.
  • File upload: Upload documents to be shared with other participants.
  • Whiteboard: Draw and write text in collaboration on a shared canvas.
  • Snapshot: Take a picture of what is shown in the call.
  • Live edit: Similar to the whiteboard feature, draw and write text in a collaborative way on a snapshot.
  • Live pointer: the other participants can see an indicator on the screen that represents your mouse cursor.
  • Present to everyone: focus the attention of the other participants on what you are presenting.
  • Signature: ability to digitally sign documents – this requires integration with a digital signature provider

You can specify which participants are admins of the room. If a participant is an admin they can start recordings manually (for more information, see Session) and can toggle the whiteboard to other users.

A room can have 3 different call types:

  • audio only: only audio is enabled.
  • audio-upgradable: the call starts with only audio enabled, but the video can be enabled during the call.
  • audio-video: the call has both audio and video enabled from the start of the call.

A room can also be set up to be live. In this case, the call will trigger a signaling event (on_call_incoming) that can be used to make the receiving endpoint ring. This feature is mostly used for in-app calling.

Another option that can be specified is the duration. By default, it is unlimited, but it can be set to a specific value in seconds. The duration is calculated on effective call time, namely when at least 2 participants are in the room at the same time.


If the specified room duration has not expired, and if the room is not explicitly disabled or deleted, it is considered active. In this condition, room links are still valid, so the same room can be stopped and resumed several times. A segment of the room where at least one participant is connected is called a session.
A single room can have zero sessions (if the call has not started yet), one, or more sessions depending on the participant's activity.

Sessions can be recorded. There are 2 types of recordings:

  • automatic: The session is recorded from the start.
  • manual: The recording is inactive when the session starts but can be started and stopped anytime by admin participants (or by calling specific REST APIs from your back end).

Call recordings and uploaded files are always bound to a session, thus they can be retrieved by specifying their session IDs.