> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Biometrics Webview configuration

> Configure the outputs and customize the rules, branding, and messages of Biometrics Webview.

## Outputs

### Success

<AccordionGroup>
  <Accordion title="Biometrics approved" icon="circle-check">
    Confirms that biometric verification succeeded.

    **Variable:** `approved`

    **Description:** Biometrics approved

    **Response structure (JSON):**

    ```json theme={null}
    {
      "document_response": {
        "document_check": {
          "result": "",
          "verified_fields": { "...": "Main document data" },
          "secondary_fields": { "...": "Secondary document data" },
          "details": { "...": "Document type details" },
          "status_fields": { "...": "Validation status" },
          "image_quality_details": { "...": "Image quality details" },
          "images_extracted": { "...": "Images extracted from the document" },
          "gov_entity_fields": { "document_number": "ID document number" }
        },
        "document_image_front_url": "Front document image URL",
        "document_image_back_url": "Back document image URL",
        "document_face_image_url": "Face image extracted from document URL"
      },
      "liveness_response": {
        "result": "true",
        "url_selfie_image": "URL of the photo used for liveness"
      },
      "facematch_response": {
        "facematch_result": "approved",
        "facematch_confidence": "Match percentage (0-100)"
      },
      "reporte_de_biometria": {
        "report": "Biometric report URL (web)",
        "report_pdf": "Biometric report URL (PDF)"
      },
      "device_info": {
        "userAgent": "User agent string",
        "browser": "Browser",
        "operatingSystem": "Operating system",
        "platform": "Device platform",
        "language": "Language",
        "timezone": "Timezone",
        "screenResolution": "Screen resolution",
        "colorDepth": "Color depth in bits",
        "timestamp": "Device timestamp",
        "ipAddress": "IP address",
        "location": {
          "latitude": "Latitude (if the user grants permission)",
          "longitude": "Longitude (if the user grants permission)"
        },
        "deviceId": "Unique device id",
        "deviceName": "Device name"
      },
      "gov_entity_data": {
        "...": "Government entity data for the country (varies by country)"
      }
    }
    ```

    **Important fields:**

    * `document_response`: ID document information
    * `liveness_response`: Photo used for liveness
    * `facematch_response`: Facial comparison result
    * `reporte_de_biometria`: Report URLs (web and PDF)
    * `device_info`: Device and location data (audit and traceability)
    * `gov_entity_data`: Government entity data (if applicable)

    **JSON response variable definitions:**

    * **document\_response:** `document_check` (result, verified\_fields, secondary\_fields, details, status\_fields, image\_quality\_details, images\_extracted, gov\_entity\_fields), `document_image_front_url`, `document_image_back_url`, `document_face_image_url`
    * **liveness\_response:** `result`, `url_selfie_image`
    * **facematch\_response:** `facematch_result` (approved/decline), `facematch_confidence`
    * **reporte\_de\_biometria:** `report`, `report_pdf`
    * **device\_info:** `userAgent`, `browser`, `operatingSystem`, `platform`, `language`, `timezone`, `screenResolution`, `colorDepth`, `timestamp`, `ipAddress`, `location` (latitude, longitude; only if location permission is granted), `deviceId`, `deviceName`
    * **gov\_entity\_data:** government entity data for the country (fields vary by country)
  </Accordion>
</AccordionGroup>

### Errors

<AccordionGroup>
  <Accordion title="Process abandoned" icon="door-open">
    The user left the process before completing it.

    **Variable:** `incomplete`

    **Description:** Process abandoned
  </Accordion>

  <Accordion title="Biometrics rejected" icon="ban">
    Biometric verification failed or was rejected.

    **Variable:** `reject`

    **Description:** Biometrics rejected
  </Accordion>

  <Accordion title="Process error" icon="triangle-exclamation">
    Error while running the biometric process.

    **Variable:** `error`

    **Description:** Process error
  </Accordion>
</AccordionGroup>

## How to customize the experience?

<Steps>
  <Step title="Open the Biometrics panel">
    Click the **Configure Webviews** button on the Biometrics node, or go to the **Biometrics** section in the platform's left sidebar.
  </Step>

  <Step title="Learn the Biometrics sections">
    In the **Biometrics** section you will see:

    * **Activity:** shows every biometric process in detail, with the status of each stage and access to the biometric report.
    * **Webviews Configuration:** lets you create biometrics agents with different configurations, colors and styles, messages, and screens, which you can use within the same company or workflow.
  </Step>

  <Step title="Configure your Webview">
    In **Webviews Configuration** you will see the agent's configuration tabs. Each tab is explained below.
  </Step>
</Steps>

<Info>
  While you configure, the platform shows a phone preview. You can customize how the Webview looks and what it says, but not how the capture works or its security controls. This is an intentional restriction to maintain the verification standard.
</Info>

<AccordionGroup>
  <Accordion title="General" icon="sliders">
    Configure the agent's basic performance rules. This is where your client's main business rules should be reflected.

    **Validation country**

    Defines which documents must be accepted and which official registry the validation runs against.

    **What does biometrics include?**

    * **Liveness, document verification, and facial comparison:** they are the foundation of the process and cannot be turned off.
    * **Enable government review:** validates the document data against an official source.
    * **Facematch with government entity:** compares the selfie with the official photo from the government source. **Only available in Ecuador.**

    Learn the details in [Government validation](/en/guides/integraciones/identidad/government-validation).

    <Warning>
      If you need to disable government validation, send an email to support or open a client request ticket with the Biometrics Product team.
    </Warning>

    **Which documents are allowed?**

    * **National ID document.**
    * **Passport from the validation country.** The passport can only be captured with the preview, so enabling it locks that experience in **Document verification**.

    With more than one type allowed, the user chooses which one to present before the capture.

    **Expiration time**

    Defines how long the Webview link stays active before it expires. The default is **60 minutes**.

    **Language**

    The language the experience opens in.
  </Accordion>

  <Accordion title="Branding" icon="palette">
    Adapt the colors and style of the experience to your brand. It is organized into three sections: **Brand**, **Logo**, and **Interface**. Colors are configured separately for **light mode** and **dark mode**.

    **Brand**

    * Brand colors: dots of the completed-steps indicator.
    * Color of the main buttons, the terms and conditions link, spinners, and uncompleted steps.
    * Background color and text color.
    * Color of the spinners on the final verification screen.
    * Style of the stepper in the header of all screens. It is circular by default.
    * Language selector, so the user can change the language of the experience.

    **Logo**

    * **Company logo:** enter the URL of your logo image. You can see it in a preview before saving.

    **Interface**

    * **Show arrow on main buttons:** turns an arrow on or off on the main buttons of the experience.
  </Accordion>

  <Accordion title="Start screen" icon="house">
    This is the first screen of the process. Here the user accepts the terms and starts the verification.

    | Field | Description |
    | - | - |
    | Screen HTML | The screen's own HTML. If left empty, the Webview uses the one from the **Default** tab. |
    | Legal link text | For example, "Terms and conditions". |
    | Terms and conditions URL | Public URL that must mention the use, storage, and processing of personal and biometric data. |
  </Accordion>

  <Accordion title="Liveness screen" icon="face-smile">
    Defines the selfie instructions and the attempt limit.

    **Maximum selfie attempts**

    * Choose **1, 2, or 3** attempts. The default is 2.
    * It is independent of the document attempt limit.
    * More attempts help the legitimate user. Fewer attempts limit someone trying multiple times.

    **Instructions screen layout**

    * **Image and text:** the Webview shows its illustration and, below it, the text you define.
    * **Full screen:** your HTML replaces the illustration and the text. The header with the steps and the continue button remain.
  </Accordion>

  <Accordion title="Document verification" icon="id-card">
    Defines the instructions, capture, results, and security rules for the document.

    | Setting | What it does |
    | - | - |
    | Maximum attempts | 1, 2, or 3 attempts. The default is 2. |
    | Document analysis level | Standard, Advanced, or Custom. Review [Document analysis level](/en/guides/integraciones/identidad/document-analysis-level) before choosing it. |
    | Enable human review | Activates [HIL](/en/guides/integraciones/identidad/hil). Enterprise accounts only, with an additional cost. |
    | Enable recapture validation | Rejects documents photographed from screens or printouts. To enable it, open a client request with the Biometrics Product team. |
    | Facial comparison threshold | Minimum match percentage between the selfie and the document photo. The default is **70%**. It is adjusted in the **Security** section. |

    <Warning>
      **Review the analysis level before publishing.** It is the setting that most affects the approval rate. Learn each level and the recommended configuration by country in [Document analysis level](/en/guides/integraciones/identidad/document-analysis-level). If you need help defining the best configuration for your document, use the [Onboarding with Jelou CLI](/en/guides/integraciones/identidad/biometrics-onboarding).
    </Warning>

    <AccordionGroup>
      <Accordion title="Screen customization" icon="mobile-screen">
        Defines the instructions, capture, and verification screens for the document.

        **Document instructions screen**

        * **Screen layout:** choose **Image and text** (the Webview shows the screen illustration and, below it, your text block) or **Full screen** (your HTML replaces the illustration and the text; the header with the steps and the continue button remain).
        * **Screen's own HTML:** choose **From the company** to use your HTML or **Default** to use the Webview's. If you don't define your own HTML, the Webview uses the one from the **Default** tab.

        **Document screen image**

        Enter the URL of the image shown on the document screen. You can see it in a preview.

        **Document capture**

        Defines the experience the end user goes through when capturing the front and back of their document. Choose one of these options:

        | Option | What the user sees |
        | - | - |
        | **Countdown** | After capturing the front, they see a 5-second counter telling them to flip the document and take the back. |
        | **Preview** | After each capture, they see the photo taken and decide whether to retake it or continue. When they confirm the front, a 5-second counter tells them to flip the document. When they capture the back, they also see the photo to confirm it. Applies to both front and back. |

        <Note>
          The passport can only be captured with the **Preview** option. When you allow the passport in the **General** tab, that option is locked.
        </Note>

        **Information verification screen**

        List of steps the user sees while their document is analyzed. You can edit each text; if you leave it empty, the default text is used.

        | Process | Process description | What the user sees by default |
        | - | - | - |
        | Screen title | Header while the analysis runs. | Analyzing your document |
        | Step: data reading | OCR extraction of the document data. | Getting your document data |
        | Step: authenticity | Recapture detection (photo of a screen or printout). Only appears with recapture detection enabled. | Verifying document authenticity |
        | Step: integrity | Image tampering analysis. | Verifying document integrity |
        | Step: government entity | Cross-check with the civil registry. Only appears with government validation enabled. | Validating with the government entity |
        | Step: facial match | Comparison between the selfie and the document photo. | Verifying facial match |

        **Success screen**

        This is what the user sees when the document has been validated. The default text of each field is the one the Webview uses if you leave it empty. You can also use **Screen's own HTML** (**From the company** or **Default**).
      </Accordion>

      <Accordion title="Recapture validation" icon="camera-rotate">
        A **recapture** happens when the user photographs a screen or a printout of the document instead of the physical document. This validation is an extra layer of security that protects your operation against spoofing attempts with photos of screens.

        Keep in mind that the tool analyzes photos of screens, but it can also flag photos with a lot of glare or reflections, for example from direct light or laminated documents. These cases may be considered false positives and affect the approval rate.

        <Tip>
          Before enabling it, assess the conditions in which your users usually take the photo. If you already have human review (HIL), those cases can be reviewed instead of rejected. To enable recapture validation, open a client request with the Biometrics Product team.
        </Tip>

        <Warning>
          Enabling it makes the analysis more rigorous: it can increase the total process time and lower the approval rate when documents show glare or flash reflections caused by indoor lighting.
        </Warning>
      </Accordion>

      <Accordion title="Facial comparison threshold" icon="face-viewfinder">
        A high threshold prioritizes security and rejects more. A low threshold prioritizes approval and lets more through. It is a risk decision for your company; adjust it to the risk level your operation can accept.
      </Accordion>

      <Accordion title="Default texts: approved result and errors" icon="message-lines">
        If you leave a field empty, the default text is used. The same text is reused on the attempt-limit screen.

        | Screen | When it appears | Default text |
        | - | - | - |
        | Approved result | The document was verified. | **Document validated.** Your ID document has been successfully verified. |
        | Data reading failed | OCR couldn't read the document. | We couldn't read the information on your document. Avoid glare or too much light. |
        | Recapture detected | The document looks like a photo of a screen or a printout. | We couldn't read the information on your document. Avoid glare, too much light, or photos of screens. |
        | Integrity compromised | Tampering was detected in the image. | We couldn't verify the integrity of your document. Make sure it is an original, unmodified document and try again. |
        | Government entity | The civil registry didn't confirm the data. | We couldn't validate your document with the government entity. Check that your document data is legible and try again. |
        | Front and back differ | The two sides belong to different documents. | We detected an inconsistency while validating your document. Please try again. |
        | Facial match failed | The selfie face doesn't match the document face. | We couldn't compare your face with the document photo. Avoid glare, shadows, or strong lights when taking the photo. |
        | Generic error | Fallback for all of the above and the attempt limit. | We couldn't validate your document after several attempts. Please contact support. |
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="WhatsApp messages" icon="comments">
    Defines what the agent writes during the validation.

    * The agent's messages during the validation, by moment of the conversation.
    * The language of each message.
    * The validation invitation: title, message, footer, and button text.
    * The waiting message.

    Empty fields use the default text:

    | Message | Default text |
    | - | - |
    | Title | I'm going to validate your identity |
    | Message | It'll be quick and safe. Your data is protected and we'll use it to confirm it's you. I'll guide you step by step. |
    | Footer | Press the button to start |
    | Button text | Start validation |
    | Waiting message | If you don't want to continue, type EXIT. |
  </Accordion>

  <Accordion title="QA mode" icon="flask">
    This option is only for **internal test versions**. It shows the end user (QA) a performance panel when capturing the document image and, at the end, the details of the failure.

    <Warning>
      Do not enable it in versions your end customers will use.
    </Warning>
  </Accordion>
</AccordionGroup>

<Info>
  This configuration is saved per Webview. You can create several versions and choose which one each Biometrics node in your flows uses.
</Info>

## FAQ

<AccordionGroup>
  <Accordion title="What document images are required during the biometric process?">
    Photos of the **ID document on both sides**: front and back.
  </Accordion>

  <Accordion title="Do I need a verified WhatsApp account?">
    No. If your account isn't verified, the web page opens in the phone's browser instead of inside WhatsApp.
  </Accordion>

  <Accordion title="Can I customize the colors and language of the experience?">
    Yes. You can adjust the colors and the stepper style in the **Branding** tab, and the language of the WhatsApp messages. The face and document capture widgets are not editable.
  </Accordion>

  <Accordion title="How many outputs does this agent have?">
    **1 success output** (Biometrics approved) and **3 error outputs** (Process abandoned, Biometrics rejected, Process error). Each can route to a custom message or Connect.
  </Accordion>

  <Accordion title="What happens if I'm getting a lot of rejected documents?">
    In most cases, the cause is a document analysis level that is too strict for the country. Check the **Document verification** tab and adjust the level based on the recommended configuration by country in [Document analysis level](/en/guides/integraciones/identidad/document-analysis-level).
  </Accordion>

  <Accordion title="If I cover part of the document that contains relevant information, will document verification still approve it?">
    During the document verification stage, the system identifies the document type (country, issue year) and compares it against a template. If the document matches and shows no signs of tampering, it's approved, extracting the data via OCR. If the covered element doesn't hide relevant information, the document can be approved; but if government validation is enabled and the data is incorrect, the biometric process will be rejected.
  </Accordion>
</AccordionGroup>

<Card title="Next: Reports" icon="arrow-right" href="/en/guides/integraciones/identidad/biometrics-reports">
  Review the activity and the biometric report for each process.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.