Server Side User Details Provider

Kaleyra Video solution treats users of a company referring to them only via anonymous identifiers, in order to display users' details on SDK integrations (chat widget, Android, and iOS SDKs) and call links each platform expose a set of client API to customize the user information (display name and avatar).

To obtain user display name and image customization on the client call and chat UIs, a new convenient, centralized way has been developed to achieve the same result using an API as Server Side User Details Provider.

To enable this functionality you must specify a valid user_details_provider_url through the Update company rest API.

The provider URL (if defined) will be used as an endpoint to request the details of the users through an HTTP post request whenever a client needs to display some user details. The best use case scenario for the Server Side User Details Provider implementation is represented by those integrations that rely on a heterogeneous usage of client SDKs (for example, mobile SDKs alongside chat widget implementation) and call links. Using the Server Side User Details Provider will result in a more concise (and less error-prone too) way to display users' information. Furthermore, it’s not necessary to implement the Client side user Details Provider APIs for the client SDKs.

Kaleyra Video's Signature

When Kaleyra Video makes the POST HTTP requests to your server, it will 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 with any way. Such a signature is included in the bandyer-signature header specified in each request sent by Kaleyra Video 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 (for example, the request body)

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 a secret key.

For example, secret key: ak_live_123456 → SHA256 HMAC: 6841e55cb12f2d9d1216c47097c75fd737a22a3a00c8d8f8d3d35fb2b613ce5b

Header Parameters

Payload Parameters

Response

For a successful API request, the following response appears:

{
    "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"
            }
    ]
}

Response Parameter

user_ids object

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.