What the user needs
The user’s phone must have a screen lock, with Face ID, Touch ID, or a fingerprint set up. The BotShield app checks this during setup and tells the user what to turn on if the phone is not ready. The biometric check runs on the phone. BotShield receives a signed assertion from the passkey, not a face or a fingerprint, and you receive neither.What you see
You do not see the state of the user’s phone. When the phone cannot confirm, the verification ends as Unavailable, and one surface tells you why:
BotShield sends
device_lock_required when the BotShield app reports a failure and the phone’s own message says that no passcode or screen lock is set, or that no biometric is set up or enrolled. The reason comes from what the phone reports at the moment of the confirmation, so it arrives only when the person opened the request and tried to confirm.
census is the API’s name for BotShield Gate.) error_message is free text from the phone. Its wording varies by device, so branch on reason and keep error_message for your logs.
A phone without a screen lock does not always get this far. A person who reads the app’s setup instructions and leaves does not report a failure, and the request expires with no webhook at all. A phone that reports the problem in words BotShield does not recognize arrives as
internal_error. Use device_lock_required to show better help when you receive it, and keep a general Unavailable message for every other case.How to message it
The BotShield app handles the instructions on the phone. On your side, give the user somewhere to go:- When your server receives
device_lock_required, show the specific help: “BotShield needs a phone with a screen lock and Face ID, Touch ID, or a fingerprint set up. Turn one on in your phone’s settings, then try again.” - For every other Unavailable result, say what happened without blame: “We couldn’t confirm you just now.” Keep the screen lock line near the gate as general help.
- Offer a retry and your alternative path. A new attempt is a new request. See Result states for the design rule: offer, never punish.
botshield:failure event reports failed for this case, the same as any other failed confirmation. The specific reason reaches your server on the webhook, so pass it to your page if you want the tailored message there.
Do not tell the user their device is insecure, and do not treat the result as a sign of automation. A missing screen lock is a setting, and the person can change it and come back.
Result states
Verified, Unavailable, and the
gate.unavailable reasons.Testing
Try your gate, including the Unavailable path.