Configuration

In order to configure the Teleconsultation Service, you need to deploy two services: the Teleconsultation Service Backend and the Teleconsultation Service Frontend, both available in the Marketplace.

Teleconsultation Service Backend Configuration

1. Create the Teleconsultation Service Backend to serve the APIs needed for the correct functionality of the Teleconsultation Service Frontend. To create the Teleconsultation Service Backend you can search for it in the Console Marketplace. Choose a name for the new service (e.g. teleconsultation-service-be).

2. Create the /api/v1/telecons-be endpoint for the newly created microservice. The endpoint of this microservice must be exactly this one because the Teleconsultation Service Frontend will use this path as prefix for the API calls to the Teleconsultation Service Backend.

The microservice requires the BANDYER_API_SECRET_KEY environment variable in order to communicate with the Kaleyra RESTful APIs.

The microservice supports two operating modes, having a different handing of user information:

• if AUTH_SERVICE env var is specified, the microservice service will retrieve user information from the service having given hostname.
• otherwise, user groups and full name must be provided when participants are added to the teleconsultation instance (i.e in the requests to POST /teleconsultation, POST /teleconsultation/:teleconsultationId/participants/data, PATCH /teleconsultation/:teleconsultationId).

Additional information about the interaction with Auth0

The keys defined inside the API Key section on the console are converted in client-types (e.g. backoffice, cms, etc.). These client-types are used by Auth0 to understand the application the user is authenticating to and get the user's data needed to make the Teleconsultation Service works. If no client-type is provided a default value will be used instead. You need to add the DEFAULT_CLIENT_TYPE environment variable to customize the default value of the client-type.

note

In order to retrieve the auth0 user's data, you need to define the AUTHORIZATION_HEADERS_TO_PROXY environment variable inside the authorization-service with value: cookie,authorization,client-type.

The microservice requires the ADDITIONAL_HEADERS_TO_PROXY environment variable with value: x-forwarded-for,x-request-id,x-forwarded-host,cookie,client-type, in order to forward the auth0 user's data received to the BE services called inside the microservice.

Config map settings

The microservice requires the TELECONSULTATION_SERVICE_CONFIG_PATH environment variable to specify the path where the JSON config file is stored. If no path is defined a default configuration will be used. The default configuration is the following:

{
  "privileges": {
    "basic": {
      "groups": [
        "patient",
      ],
      "tools": {
        "chat": true,
        "screen_sharing": true,
        "file_upload": true,
        "whiteboard": true,
        "snapshot": true,
        "live_edit": true,
        "live_pointer": true,
        "present_to_everyone": true,
      },
    },
    "plus": {
      "groups": [
        "doctor",
      ],
      "tools": {
        "chat": true,
        "screen_sharing": true,
        "file_upload": true,
        "whiteboard": true,
        "snapshot": true,
        "live_edit": true,
        "live_pointer": true,
        "present_to_everyone": true,
      },
    },
  },
  "theme": {
    "light": {
      "primaryColor": "#ffffff",
      "accentColor": "#480ca8",
    },
    "dark": {
      "primaryColor": "#003049",
      "accentColor": "#d62828",
    },
  },
  "companyLogo": {
    "url": "https://www.insert.url.it",
  },
  "customUserId": {
    "source": "_id",
    "target": "authUserId"
}
}

Update the JSON configuration file in the ConfigMaps section according to your needs.

Custom user id

info

v1.8.0 The custom user id feature is available from v1.8.0 onwards.

When the CUSTOM_ID_USERS_API_ENDPOINT environment variable is specified it is possible, for each participant, to resolve a custom user id (customUserId.source) received from a client, like a MongoDB _id or an email address, into the corresponding Auth0 id (customUserId.target), required by the service to perform authentication and authorization. The Teleconsultation Service then looks for the user with the given MongoDb _id or email address and returns the corresponding identity provider id (Auth0 is the only IDP currently supported). These two fields can be customized specifying different values for the source and target fields under the customUserId configuration option:

"customUserId": {
  "source": "The name of the field containing the user ID received from a client, like a MongoDB `_id` or email address",
  "target": "The name of the field containing the user ID of the identity provider, like Auth0 `sub`"
}

Environment Variables

The Teleconsultation Service Backend accepts the environment variables described in the following table.

Name	Required	Default	Minimum version	Description
BANDYER_API_SECRET_KEY	Yes	-	1.0.0	API Secret Key to use in order to communicate with Kaleyra's APIs.
BANDYER_BASE_URL	Yes	-	1.0.0	Base url of the Kaleyra API. From the service version 2.0.0 it must be updated to the Bandyer API v2 base url.
TELECONSULTATION_SERVICE_CONFIG_PATH	No	-	1.0.0	Full path of the updated file defined in the previous section.
TELECONSULTATIONS_CRUD_NAME	No	-	1.0.0	Name of the endpoint of the CRUD with all the teleconsultations.
USER_ID_MAP_CRUD_NAME	No	-	1.0.0	Name of the endpoint of the CRUD with all the user_ids (e.g. receivedUserId, bandyerId), for each user.
AUTH_SERVICE	No	-	1.0.0	Name of the authentication service; if not provided, the operating mode without auth0 dependency is used (see Teleconsultation Service Backend Configuration).
CUSTOM_ID_USERS_API_ENDPOINT	No	-	1.8.0	The url of the API used to retrieve the Auth0 users id from the given custom user id (e.g. http://user-manager-service/users/ or http://crud-service/users/). It works only with AUTH_SERVICE defined.
DEFAULT_CLIENT_TYPE	No	-	1.0.0	Name of the application that auth0-client uses to retrieve data of the users involved in the teleconsultation.
UNLIMITED_TELECONSULTATION	No	true	1.1.2	If the teleconsultation duration is infinite.
LIVE_TELECONSULTATION	No	true	1.3.0	If the teleconsultation ends when a participant leaves the call and the number of the remaining participants are less than two.
IMMUTABLE_PERIOD_MS	No	0	1.2.1	How much time (in milliseconds) before the scheduled start date you can join the teleconsultation room and you can no longer update the teleconsultation.
TELECONSULTATION_DELETE_UPLOADS	No	false	1.5.0	If set to true, the files uploaded during a teleconsultation are deleted when the call ends.

danger

From the Teleconsultation Service version v2.0.0 the BANDYER_BASE_URL must be configured with the Bandyer v2 API base url.

caution

Since v1.5.0, you can set the TELECONSULTATION_DELETE_UPLOADS environment variable to true in order to automatically delete the files uploaded by the participants during the teleconsultation session. Remember that this operation is performed every time the call is interrupted, even if that happens for external causes, like network connectivity issues. Once the participants join the teleconsultation again, if the feature is enabled they will have to upload again all the files, unless they already downloaded a copy on their devices.

tip

If the appointment starts at 11:00 and you want the doctor to be able to start the teleconsultation session earlier than the scheduled appointment date, you simply have to set the IMMUTABLE_PERIOD_MS environment variable accordingly. So, for example, to allow the session to start up to ten minutes before the scheduled date, you can simply set IMMUTABLE_PERIOD_MS to 600000 (ten minutes expressed in milliseconds). If the participants join the call after 10:50, the session starts automatically as soon as they are connected.

Also remember that, in such scenario, after 10:50 the teleconsultation room would be no longer changeable, including the participants, so we recommend setting a value that leaves room for last minute changes, for example if the appointment need to be assigned to a different doctor.

note

When retrieving the teleconsultation link, via GET /teleconsultation/:teleconsultationId, the actual link is returned only if the service is not accepting any further modification to the room. In this case, the teleconsultation is either inside the IMMUTABLE_PERIOD_MS time frame, or its start_date has been passed.

danger

If LIVE_TELECONSULTATION is set to false, the period of time during which a participant is left alone in the call (when all the other participants left) is considered in the teleconsultation provider pricing.

Teleconsultation Service Configuration

The Teleconsultation Service Configuration is a JSON object with 6 root properties.

1. privileges

• type: object;
• required: true;
• description: contains 2 types of users (basic and plus) and their privileges details for the call (e.g. The tools they can use during the call).

3. theme

• type: object;
• required: false;
• description: define the theme of (light and dark mode), of the teleconsultation UI used for the call.

4. companyLogo

• type: object;
• required: false;
• description: contains a field called url, which specify the url where the company logo is stored.

5. groupsWithBackgroundList

note

Available from version 1.6.1 of the teleconsultation-backend service

• type: array;
• required: false;
• description: contains a list of strings referring to user groups for which a virtual background should be used. Follow these instructions to configure a virtual background for the service.

6. userIdPathInRequest

• type: array;
• required: false;
• default: [{ "from": "object", "extract": "headers"}, {"from": "object", "extract": "${env.USERID_HEADER_KEY}"}] (variable interpolation is only for documentation purposes, it is not supported by the service; if needed in configmap, you must use Mia-Platform Console interpolation);
• description: contains the path where the logged user's external ID is received in the fastify request object. It is used by GET /teleconsultation/:teleconsultationId request to make access control and return the correct room URL. Each step of the path is described by an object, containing:
  • a from property, describing how to handle the previously obtained item. The allowed values are object, json and array. The first occurrence must always be set to object, since we must handle the fastify request as a JS object.
  • an extract property, specifying the field to be extracted at the current step

The JSON file is structured like the following example:

{
  "privileges": {
    "basic": {...},
    "plus": {...}
  },
  "theme": {
    "light": {...},
    "dark": {...}
  },
  "groupsWithBackgroundList": [...]
  "companyLogo": {
    "url": ""
  }
}

1.1 Privileges parameters

This part of the configuration object lets you specify the details for the different types of users (basic and plus). At the moment the following parameters are supported:

• basic

• plus

Example:

"privileges": {
  "basic": {
    "groups": ["customer"],
    "tools": {
      "chat": true,
      "screen_sharing": true,
      "file_upload": true,
      "whiteboard": true,
      "snapshot": true,
      "live_edit": true,
      "live_pointer": true,
      "present_to_everyone": true
    }
  },
  "plus": {
    "groups": ["doctor"],
    "tools": {
      "chat": true,
      "screen_sharing": true,
      "file_upload": true,
      "whiteboard": true,
      "snapshot": true,
      "live_edit": true,
      "live_pointer": true,
      "present_to_everyone": true
    }
  }
}

The following specification is valid for both basic and plus:

• type: object;
• required: true;
• description: contains the groups which this user is part of and the tools which this user can use;

1.1.1 Basic / Plus parameters

This part of the configuration object lets you specify the groups which this user belong to and the tools which can be used. At the moment, the following parameters are supported:

• groups

  • type: array;
  • required: true;
  • description: contains the groups' names which this user is part of;

• tools

  • type: object;
  • required: false;
  • description: contains the tools which this user can use during the call;
  • fields list:
    • chat:
      • type: boolean,
      • description: Enable the chat feature
    • screen_sharing:
      • type: boolean,
      • description: Enable the screen_sharing feature
    • file_upload:
      • type: boolean,
      • description: Enable the capability to send file
    • whiteboard:
      • type: boolean,
      • description: If true enable all the whiteboard tools
    • snapshot:
      • type: boolean,
      • description: Enable the snapshot feature (let's you take a screenshot during the call)
    • live_edit:
      • type: boolean,
      • description: Enable the live edit feature
    • live_pointer:
      • type: boolean,
      • description: Enable to send pointer-events to others participants (always active in reception)
    • present_to_everyone:
      • type: boolean,
      • description: Enable the capability to force your own video to be featured for other participants

4.1 Theme parameters

Specify two modes for the theme: light and dark mode.

• light
• dark

Example:

"theme": {
  "light": {
    "primaryColor": "#ffffff",
    "accentColor": "#480ca8"
  },
  "dark": {
    "primaryColor": "#003049",
    "accentColor": "#d62828"
  }
}

The following specification is valid for both light and dark:

• type: object;
• required: false;
• description: contains two fields primaryColor and accentColor used to customize the teleconsultation UI colors during the call.

5.1 CompanyLogo parameters

Contains a field url which contains the URL of the company's logo.

• type: string;
• required: false;
• description: contains the URL of the company's logo.

Example:

"companyLogo": {
  "url": ""
}

Teleconsultations CRUD

The Teleconsultation Service requires a CRUD to save the planned and performed teleconsultation data. The collection can have any name you want, as long as you specify the correct name in the TELECONSULTATIONS_CRUD_NAME environment variable.

A teleconsultation is the equivalent of a Room (the place where the call will have place). Look the Overview section for more details about Room in Kaleyra.

The teleconsultations CRUD needs the following service-specific fields:

• bandyerRoomId (required) - string: the id of the Room created on Kaleyra for the call;
• participantsNumber (required): the number of expected participants,
• participants - array of objects: the list of participants to the call. For each participant, it contains:
  • userBandyerId (required),
  • accessLinkURL (required),
  • groups (if and only if mode without Auth0 is used),
  • fullName (if and only if mode without Auth0 is used),
  • language (optional);
• teleconsultationState - string: the state of the Room (if it's available ecc.);
• startDate (required) - date: the teleconsultation's startDate.
• endDate - date: the teleconsultation's endDate.

participants

In order to create a teleconsultation, an array of participants needs to be specified.

The structure of this array is the following:

{
  participants: [
    {
      bandyerId: "bandyer_user_id_xxx",
      accessLinkURL: "link_to_the_call_for_user_xxx"
    },
    ...
  ]
}

• The field bandyerId is the kaleyra's id of a user.
• The field accessLinkURL is the link required in order to join the call. During the creation of a teleconsultation, every participant receives a link (valid only for that person for that teleconsultation).

User Id Map CRUD

The Teleconsultation Service requires a CRUD in order to save the Kaleyra user id for each user which have used the teleconsultation service at least one time. The collection can have any name you want, as long as you specify the correct name in the USER_MAP_ID_CRUD_NAME environment variable.

The user-id-map CRUD, stores for every user their receivedUserId (which is mainly used to authenticate the users), and the relative Kaleyra's id. This allows the Teleconsultation Service Backend to communicate with Kaleyra (a user needs to be registered on Kaleyra in order to use their services).

The teleconsultations CRUD needs the following service-specific fields:

• bandyerId (required) - string: the id of the user on Kaleyra;
• receivedUserId (required) - string: the id of the user on Auth0;