Session Customization

Customize the FaceSign verification permissions page and UI controls to match your brand and user experience requirements.

Overview

FaceSign provides customization options for the permissions page shown before verification begins and global UI control settings. Customizations are applied when creating a session.

Customizations are optional. If not provided, FaceSign uses sensible defaults with your configured avatar.

Permissions Page

The permissionsPage property customizes the page that asks for camera/microphone permissions. Use it to change text, background, and translations.

Available Options

Property	Type	Description
`buttonText`	`string`	Text displayed on the start button (e.g., “Begin Verification”). Defaults to “Continue”.
`mainHeading`	`string`	Primary heading text shown at the top of the permissions page.
`subheading`	`string`	Secondary text providing additional context below the main heading.
`backgroundType`	`"AVATAR" \| "COLOR"`	Page background: `"AVATAR"` (default, shows avatar image) or `"COLOR"` (solid color).
`backgroundColor`	`string`	Background color when `backgroundType` is `"COLOR"` (e.g., `"#f0f0f0"`).
`buttonTextTranslates`	`Record<string, string>`	Button text translations by language code (e.g., `"es"`, `"fr"`).
`mainHeadingTranslates`	`Record<string, string>`	Main heading translations by language.
`subheadingTranslates`	`Record<string, string>`	Subheading translations by language.

Permissions Page Customization

{
  "permissionsPage": {
    "mainHeading": "Identity Verification",
    "subheading": "We need camera access to verify your identity",
    "buttonText": "Start Verification",
    "backgroundType": "COLOR",
    "backgroundColor": "#1a202c"
  }
}

UI Controls

Global UI control settings that apply throughout the verification session.

Available Options

Property	Type	Description
`showUxControls`	`boolean`	Show or hide UX control elements during verification. Defaults to `true`.

UI Controls Customization

{
  "controls": { "showUxControls": false }
}

Multi-language Support

Use Translates fields to provide translated text for multi-language sessions. Language keys should match ISO codes.

Translation Fields

Property	Type	Description
`buttonTextTranslates`	`Record<string, string>`	Button translations by language code.
`mainHeadingTranslates`	`Record<string, string>`	Main heading translations.
`subheadingTranslates`	`Record<string, string>`	Subheading translations.

Multi-language sessions also require langs and defaultLang fields at the session level.

Multi-language Example

{
  "permissionsPage": {
    "mainHeading": "Identity Verification",
    "mainHeadingTranslates": { "es": "Verificación de Identidad", "fr": "Vérification d'identité" },
    "subheading": "Camera access required",
    "subheadingTranslates": { "es": "Se requiere acceso a la cámara", "fr": "Accès à la caméra requis" },
    "buttonText": "Continue",
    "buttonTextTranslates": { "es": "Continuar", "fr": "Continuer" }
  }
}

Implementation

Supply a customization object when creating a session. Nested fields are optional — only include what’s needed.

Complete Example

This example shows all customization options combined: custom permissions page with color background, multi-language support for English/Spanish/French, and hidden UX controls for a minimal interface.

cURL
JavaScript
Python

curl https://api.facesign.ai/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "clientReferenceId": "user-123",
    "langs": ["en", "es", "fr"],
    "defaultLang": "en",
    "metadata": {},
    "flow": [
      { "id": "start", "type": "start", "outcome": "end" },
      { "id": "end", "type": "end" }
    ],
    "customization": {
      "permissionsPage": {
        "mainHeading": "Verify Your Identity",
        "mainHeadingTranslates": {
          "es": "Verifica tu Identidad",
          "fr": "Vérifiez votre Identité"
        },
        "subheading": "This helps us keep your account secure",
        "subheadingTranslates": {
          "es": "Esto ayuda a mantener segura tu cuenta",
          "fr": "Cela aide à sécuriser votre compte"
        },
        "buttonText": "Begin Verification",
        "buttonTextTranslates": {
          "es": "Comenzar Verificación",
          "fr": "Commencer la Vérification"
        },
        "backgroundType": "COLOR",
        "backgroundColor": "#1a202c"
      },
      "controls": {
        "showUxControls": false
      }
    }
  }'

const client = new Client({
  auth: 'sk_test_...',
})

const { session, clientSecret } = await client.session.create({
  clientReferenceId: "user-123",
  langs: ["en", "es", "fr"],
  defaultLang: "en",
  metadata: {},
  flow: [
    { id: "start", type: "start", outcome: "end" },
    { id: "end", type: "end" }
  ],
  customization: {
    permissionsPage: {
      mainHeading: "Verify Your Identity",
      mainHeadingTranslates: {
        es: "Verifica tu Identidad",
        fr: "Vérifiez votre Identité"
      },
      subheading: "This helps us keep your account secure",
      subheadingTranslates: {
        es: "Esto ayuda a mantener segura tu cuenta",
        fr: "Cela aide à sécuriser votre compte"
      },
      buttonText: "Begin Verification",
      buttonTextTranslates: {
        es: "Comenzar Verificación",
        fr: "Commencer la Vérification"
      },
      backgroundType: "COLOR",
      backgroundColor: "#1a202c"
    },
    controls: {
      showUxControls: false
    }
  }
})

import facesignai

client = facesignai.Client(
    auth='sk_test_...',
)

response = client.session.create(
    client_reference_id="user-123",
    langs=["en", "es", "fr"],
    default_lang="en",
    metadata={},
    flow=[
        {"id": "start", "type": "start", "outcome": "end"},
        {"id": "end", "type": "end"}
    ],
    customization={
        "permissionsPage": {
            "mainHeading": "Verify Your Identity",
            "mainHeadingTranslates": {
                "es": "Verifica tu Identidad",
                "fr": "Vérifiez votre Identité"
            },
            "subheading": "This helps us keep your account secure",
            "subheadingTranslates": {
                "es": "Esto ayuda a mantener segura tu cuenta",
                "fr": "Cela aide à sécuriser votre compte"
            },
            "buttonText": "Begin Verification",
            "buttonTextTranslates": {
                "es": "Comenzar Verificación",
                "fr": "Commencer la Vérification"
            },
            "backgroundType": "COLOR",
            "backgroundColor": "#1a202c"
        },
        "controls": {
            "showUxControls": False
        }
    }
)

Common Examples

Minimal Branding

Customize just the heading and button text:

Minimal Setup

{
    "customization": {
      "permissionsPage": {
        "mainHeading": "Welcome to SecureBank",
        "buttonText": "Get Started"
      }
    }
}

Avatar Background

Default (avatar video):

Avatar Background

{
    "avatarId": "65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0",
    "customization": {
      "permissionsPage": {
        "backgroundType": "AVATAR",
        "mainHeading": "Let's verify your identity",
        "buttonText": "Start"
      }
    }
}

Color Background

Solid color (with heading and subheading):

Color Background

{
    "customization": {
      "permissionsPage": {
        "backgroundType": "COLOR",
        "backgroundColor": "#0f172a",
        "mainHeading": "Identity Verification Required",
        "subheading": "We'll guide you through the process",
        "buttonText": "Continue"
      }
    }
}

Multi-language

Switchable “en”/“es”:

Bilingual Setup

{
    "langs": ["en", "es"],
    "defaultLang": "en",
    "customization": {
      "permissionsPage": {
        "mainHeading": "Verification",
        "mainHeadingTranslates": { "es": "Verificación" },
        "buttonText": "Start",
        "buttonTextTranslates": { "es": "Comenzar" }
      }
    }
}

Test your customizations across different devices and screen sizes to ensure a consistent user experience.

Auto-brand from your website (FaceSign MCP)

The customization fields above cover the FaceSign-hosted permissions page. If you want the same brand applied to the landing and recap pages that wrap the session in your own app — typically generated through the FaceSign MCP server with launch_session_ui or export_app — you can point the AI agent at your product website and have it pull the visual language automatically. Hand the agent a reference URL and ask for a branded demo, for example:

“Use https://acme.example.com as the style reference.”

The agent fetches the page with its own web-fetch tool, reads the HTML and CSS, and adopts:

Primary accent color — scanned from CSS custom properties (--primary, --brand, --accent) and the most frequent hex on buttons and links.
Typography — the first two font-family declarations on body and headings.
Border-radius scale — taken from buttons and cards.
Shadow style — subtle vs. strong drop-shadow feel.
Logo — the first <img> inside <header> (or with alt matching the brand name).

The reference URL is used as style inspiration only — the agent won’t clone layout, body copy, or images from it.

When fetching fails — If the reference site is behind auth, Cloudflare, or is a JS-rendered SPA that the web-fetch tool can’t introspect, the agent should tell you and ask for explicit hex codes and a font stack rather than silently falling back to a generic default.

Next steps

Sessions

Create sessions with customization

Languages

Multi-language support

Avatars

Choose AI avatars

Getting started

Use cases

Guides

Security

Concepts & reference

Session Customization

Overview

Permissions Page

Available Options

UI Controls

Available Options

Multi-language Support

Translation Fields

Implementation

Complete Example

Common Examples

Minimal Branding

Avatar Background

Color Background

Multi-language

Auto-brand from your website (FaceSign MCP)

Next steps

Sessions

Languages

Avatars

​Overview

​Permissions Page

​Available Options

​UI Controls

​Available Options

​Multi-language Support

​Translation Fields

​Implementation

​Complete Example

​Common Examples

​Minimal Branding

​Avatar Background

​Color Background

​Multi-language

​Auto-brand from your website (FaceSign MCP)

​Next steps

Sessions

Languages

Avatars

Overview

Permissions Page

Available Options

UI Controls

Available Options

Multi-language Support

Translation Fields

Implementation

Complete Example

Common Examples

Minimal Branding

Avatar Background

Color Background

Multi-language

Auto-brand from your website (FaceSign MCP)

Next steps