Known Behaviors

These are intentional surfaces or active edge cases. Design around them.

Liveness can return noFace intermittently

The liveness_detection node occasionally returns noFace even when the user is clearly present, typically under poor lighting or when the user tilts their head during the check. Always route every liveness outcome forward. The video AI analysis handles deepfake scoring out of band.

SMS OTP has a handoff timing issue

two_factor_sms currently has a known form-to-speech handoff timing issue where the avatar occasionally asks for the phone number verbally after the form submit. If SMS is required, audit the transition carefully before production use. Prefer enter_email followed by two_factor_email for most integrations.

Recognition requires accumulated video

The recognition node needs several seconds of video to work. The greeting before recognition must have the avatar speaking for 5 seconds or more. Short greetings cause recognition to fail with newUser even for returning users.

See Conversation Rule 8 for examples.

Camera resumption after document scan

On some mobile devices, the camera occasionally does not resume immediately after a successful document_scan. If you build a flow where the user returns to a conversational node after a scan, verify this path on the devices you target.

Document scan report fields are nested objects

Document scan report fields use Microblink nested structures, not plain strings. Use the safe value extractor pattern:

function sv(v) {
  if (v == null) return '';
  if (typeof v === 'string') return v;
  if (v.latin && v.latin.value != null) return String(v.latin.value);
  if (v.originalString) return sv(v.originalString);
  if (v.day != null && v.month != null && v.year != null)
    return v.month + '/' + v.day + '/' + v.year;
  return '';
}
// Usage: sv(docReport.firstName) -> "ADA"

Media URLs expire after 15 minutes

Media URLs in webhook payloads and session responses are signed and expire 15 minutes after generation. Download immediately if you need to retain them. Re-fetch the session to get a fresh URL if the original has expired.

Delayed report fields

Some session report fields arrive 5-20 seconds after session completion:

Poll or use webhooks to consume delayed fields. See Custom Pages for the split render pattern.

Next Steps