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 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

ParameterTypeDescription
bandyer-signatureStringSignature for WhatsApp Video.
For example, t=1554193902,v0=ComputedHMAC.

Payload Parameters

ParameterTypeDescription
eventStringName of the event (in this case: user_details_request).
event_versionStringThe version of the request payload (In this case: 1.0).
namespaceStringNamespace of the webhook event (In this case: user_details_provider).
dataObjectThe event data.
user_idsArray of stringList of user_id that participate to the call.

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

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

user_ids object

ParameterTypeDescription
user_idStringThe user_id passed in the request identifying the user
display_nameStringThe name 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
2Client side user details provider if defined in the SDK or via query parameter for the call link (only the self name).
1Server side user details provider centralized way across all of our platforms.
0Information stored on the user, specified using the /rest/user/create or the /rest/user/update APIs (Deprecated).