Passer au contenu
Dernière mise à jour

Integration

The LiveID+ service provides several integration features:

  1. inbound integration (start of video identification call) for synchronous calls;
  2. outbound integration (client-side video identification status callback and server-side fully customizable callback) for synchronous calls;
  3. asynchronous calls;
  4. other useful features.

It is highly recommended to use the asynchronous calls method as it provides better control of the call flow.


Inbound Integration

The inbound integration feature allows organizations to start a video identification call from their own web application. This feature is useful for organizations that want to integrate video identification into their existing workflows.

All the details can be found in the app/service-start API description.

Integration Modes

There are two modes in which the video identification call can be initiated:

  • Standalone mode: The call is launched in a new browser tab. Supports server-side callbacks and redirect URL for client-side callbacks.
  • Embedded mode: The call is launched within an HTML iframe directly in the client page, allowing for real-time client-side callbacks via window.postMessage.

Embedded Mode Setup

If you choose to use embedded mode, the iframe must have the allow property set to include geolocation, camera, and microphone access:

<iframe src="..." allow="geolocation; camera; microphone"></iframe>

Starting a Call

To start a video identification, submit a POST request to app/service-start with the following required parameters:

ParameterTypeDescription
id_organizationstringOrganization code (provided by Namirial during setup)
id_processstring (UUID)Process identifier (provided by Namirial during setup)
jsonobject (Base64)UTF-8 Base64 encoded JSON containing customer data and configuration

The json parameter must be a UTF-8 Base64 encoded JSON object following the ServiceStartJson schema. It contains customer information, callback configuration, and custom data fields.

Example json structure (before Base64 encoding):

{
  "lang": "en",
  "liveid_email": "john.doe@example.com",
  "liveid_name": "John",
  "liveid_surname": "Doe",
  "liveid_servercallback": {
    "url": "https://your-system.com/callback",
    "otherParams": {
      "custom_reference": "REF-12345"
    }
  },
  "liveid_priorityQueueLevel": 0,
  "data": {
    "fiscal_code": {
      "datatype": "text",
      "label": "Fiscal Code",
      "value": "RSSMRA85M01H501Z",
      "order": 1,
      "readonly": true
    },
    "birth_date": {
      "datatype": "date",
      "label": "Date of Birth",
      "value": "1985-08-01",
      "order": 2
    }
  }
}

The required fields are: lang, liveid_email, liveid_name, liveid_surname, and data.

The data object contains custom data fields where each field has the following properties:

PropertyTypeRequiredDescription
datatypestringYesHTML input type: text, date, email, number, tel, checkbox, month, time, url
labelstringYesDisplay label for the field
valuestringYesValue of the field
displaystringNo"none" to hide the field, "operator" for operator-only visibility
ordernumberNoDisplay order of the field
disabled, readonly, required, maxlength, max, min, pattern, placeholder, size, step, titlevariousNoStandard HTML input attributes for validation

The liveid_servercallback object configures the server-side callback endpoint (see Outbound Integration):

PropertyTypeRequiredDescription
urlstring (URI)YesHTTPS endpoint to call at the end of the process (must be pre-approved by Namirial)
otherParamsobjectNoAdditional key-value pairs to include in the callback POST request
headersobjectNoAdditional HTTP headers to include in the callback request

Optional Parameters

ParameterTypeDescription
external_idstringCustom ID to identify the call in reports (max 100 characters)
redirectUrlstring (URI)URL where the browser redirects at end of process
redirectMethodstringHTTP method for the redirect: GET or POST (default: POST)
id_operator2Callstring (UUID)Route call to a specific operator by LiveID+ ID
email_operator2Callstring (email)Route call to a specific operator by email
extId_operator2CallstringRoute call to a specific operator by external ID
directstring (JWT)Unique token for calling a specified operator
opInfostringInformation to show the operator before answering (max 100 chars)
skipAVrecTestbooleanSkip audio/video recording check in compatibility test
disableRTCTestbooleanSkip WebRTC check (only for processes without video registration)

Note: id_operator2Call, email_operator2Call, extId_operator2Call, and direct are mutually exclusive. When any of these is set, the call is terminated if the specified operator does not answer — it is not reassigned to another operator.

Self + Live Process Combination

Instead of specifying a single id_process, you can use id_process_live and id_process_self together to let LiveID+ automatically determine whether to start a live or self-identification process based on preconfigured criteria. These two parameters are mutually exclusive with id_process.


Outbound Integration

When a video identification call is initiated, the LiveID+ service provides the ability to receive status updates about the call.

The application can receive the status updates in three ways:

  1. client-side callback: served on client side using the HTML iframe postMessage API;
  2. redirect parameter: when a redirect URL is provided, the LiveID+ client will redirect the user to the specified URL passing the result as a parameter (GET or POST, configurable via redirectMethod);
  3. server-side callback: in the form of POST requests to a specified HTTPS endpoint.

Client-Side Callback

In case of an embedded integration (via HTML iframe), LiveID+ sends postMessage events to the main integrator's page to report the results of network and media tests, as well as the status of an active call.
These messages originate from the LiveID+ client platform and can be received by the parent page hosting the iframe.

To handle these messages, a message event listener must be registered on the client page.

Example (JavaScript):

window.addEventListener("message", function (event) {
    switch(event.data.event) {
        case 'close':
            // Handle close event
            break;
        case 'error':
            // Handle error event
            break;
        case 'WEBRTCTEST_OK':
            // Compatibility test passed
            break;
        case 'WEBRTCTEST_KO':
            // Compatibility test failed
            break;
        case 'WEBRTCTEST_CALLANSWERED':
            // Operator answered, event.data.idConf contains conference ID
            break;
        case 'WEBRTCTEST_CALLNOTANSWERED':
            // No operator answered, event.data.retry indicates retry attempt
            break;
        case 'WEBRTCTEST_CALLCANCELLED':
            // Customer cancelled the call
            break;
        // ...
        case 'status_call':
            // Real-time call status update
            break;
        default:
            // Handle other cases
            break;
    }
});

Redirect Parameter

If a redirectUrl is provided in the app/service-start method, the LiveID+ client will redirect the user to the specified URL, passing the JSON result in a LiveIDPlusResult parameter. The HTTP method used for the redirect can be configured via the redirectMethod parameter (GET or POST, defaults to POST).

Server-Side Callback

If a liveid_servercallback parameter is specified in the json object when starting a call, LiveID+ sends a POST request to the specified URL for call closing status events and errors.

For security reasons, the server callback domain must be HTTPS and pre-approved by the LiveID+ team. To ask for approval, please contact the LiveID+ support team at liveidplus.support@namirial.com.

Server callback payload:

{
  "closeStatus": "N",
  "otherParams": { },
  "idConference": "conference-uuid"
}

The closeStatus values are: N (successfully completed), S (suspended), A (aborted), K (system error).

It is possible to register an email address to receive notifications when server-side callbacks fail. This can be done by using the v2/registerAlertEmail API.



More details on the events messages can be found in the Events and Call closing sections.



Useful Service APIs

LiveID+ provides a set of utility APIs that can help integrators manage the call experience:

APIMethodDescription
/api/service/getAvailableOperatorsPOSTGet the number of operators currently available for an organization
/api/service/getQueuePOSTGet the number of people in queue for a specified process
/api/service/availableLanguagesPOSTGet the languages spoken by an organization's operators
/api/service/getDailyWaitingTimesPOSTGet average daily waiting times (last week and last 60 minutes)

All these APIs require the orgCode (or id_process for getQueue) parameter.



Third-party integration