Customization

A query string can be used to customize various options.

Query strings

The query string can be used to customize various options for the given video link.

ParameterShort FormTypeDescription
audio_disabledadBooleanStart the call with the audio disabled.
video_disabledvdBooleanStart the call with the video disabled.
swapped_local_cameraslcBooleanStart the call with the local video featured.
mobile_back_camerambcBooleanStart the call with the back camera selected as the default video device on mobile browsers.
display_namednStringSet the name to display in the call. The name is also forwarded to the other participants.
virtual_backgroundvbStringStart the call with the virtual background enabled as default. Allowed parameters are blur or image.
languagelStringSet the language of the UI. Allowed parameters are en, it, pl, fr, and de.
themetStringAllow to start the call with the selected theme (if specified here), the allowed parameters are light and dark.
new_uinew_uiStringAllow to use the new UI, please contact us if you want the new UI as the default.

Remote User Details Provider

The user details provider allows customizing the name of the participants to display during the call instead of the user_id. To enable this functionality you must specify a valid user_details_provider_url through the company update rest API. This URL, if defined, is used by Kaleyra's Video as an endpoint to request the details of the call's participants through an HTTP post request.

Kaleyra Video Signature

When Kaleyra Video makes the POST HTTP requests to your server, it will also include a signature, computed using the company apikey as secret, that allows you to verify that the content of the request comes from a legitimate source and that has not tampered in any way. Such a signature is included in the bandyer-signature header specified in each request sent by Bandyer to the user_details_provider_url.

The bandyer-signature header will be in the form: t=1554193902,v0=ComputedHMAC where v0 is the computed signature.

To check the signature to validate the request on your side you must compute the signature by concatenating:

  • t value (as a string) the character. The actual JSON payload (that is, the request body). For example, Input: 1554193902.{event: ‘provider’, event_version: '1.0’, namespace: 'provider’, data: { users_ids: ['user_xxx’, 'user_yyy’] } }.

You then create a SHA256 HMAC using that string as input and the company apikey as the secret key. For example, secret key: ak_live_123456 → SHA256 HMAC: 6841e55cb12f2d9d1216c47097c75fd737a22a3a00c8d8f8d3d35fb2b613ce5b.

Header parameters

ParameterTypeDescription
bandyer-signatureStringExample: t=1554193902,v0=ComputedHMAC.

Payload

ParameterTypeDescription
eventStringName of the event (In this case: user_details_request).
event_versionStringThe version of the request payload (In this case: 1.0).
namespaceStringThe namespace of the webhook event (In this case: user_details_provider).
dataObjectThe event data.

Data

ParameterTypeDescription
user_idsArray of stringList of user_id that participate in the call.

The request expects a response structured as follows:

Response

ParameterTypeDescription
user_idsArray of objectAn array of user objects containing the information obtained from your server.

Response Example:

{
    "user_ids": [
            {
                "user_id": "user_xxx",
                "display_name": "Custom display name",
                "user_avatar": "https://customurl.com/customImage.jpg"

            },
            {
                "user_id": "user_yyy",
                "display_name": "Custom display name 2",
                "user_avatar": "https://customurl.com/customImage2.jpg"
            }
    ]
}

user_ids object

ParameterTypeDescription
user_idStringThe user_id passed in the request identifying the user.
display_nameStringThe name is to display instead of the user_id during the call.
user_avatarString or NullThe URL of the image to use as an avatar for the user during the call. Note: The link must be publicly accessible to work.

Priority system

The user details provider feature is fully integrated with the other logic that allows specifying a custom name or a custom avatar for the user. The following list shows the priority of the logic applied to display the user name from the highest to the lowest. The first logic that applies is order is the one that will be used to display the user name.

PrioritySystem
3The display_namequery parameter. Note: This logic allows you to specify only the name of the owner of the link and not those of the other participants.
2Provider and formatter for the SDKs and the widget (it is strongly suggested to centralize the provider for both the SDK and the links).
1Remote user provider (see, above System description).
0Information stored on the user, specified using the /rest/user/create or the /rest/user/update APIs (Deprecated).

Theme customization

With the updated company theme API is possible to specify custom colors for the two theme modes of the call page.

Following there are some guidelines that show you where the colors are applied so that you can choose the ones that best represent your business

Call and chat UI

Screenshare UI

Upload File UI

Notification UI

Settings and toggle between theme modes