> This page is for version 2022-09-01.
> For other versions, use one of these documentation indexes:
> - 2026-09-29 (default): https://docs.withpersona.com/2026-09-29/llms.txt
> - 2025-12-08: https://docs.withpersona.com/2025-12-08/llms.txt
> - 2025-10-27: https://docs.withpersona.com/2025-10-27/llms.txt
> - 2023-01-05: https://docs.withpersona.com/2023-01-05/llms.txt
> - 2022-09-01: https://docs.withpersona.com/2022-09-01/llms.txt
> - 2021-07-05: https://docs.withpersona.com/2021-07-05/llms.txt
> - 2021-05-14: https://docs.withpersona.com/2021-05-14/llms.txt
> - 2020-05-18: https://docs.withpersona.com/2020-05-18/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

# Verify users directly in chat

> Verify users in a chat assistant with Inquiries, Device Handoff, and mobile SDKs, and return only the outcome to the model.

You can verify a user's identity from inside a chat assistant without sending the user to a separate sign-up page. This applies to a chat you build into your own website or app and a chat that runs inside a partner's app.

This guide connects existing Persona features for a chat integration: Inquiries, the Embedded Flow SDK, Device Handoff, the mobile SDKs, and webhooks. No new Persona API is involved.

## How the pieces fit

Your application controls the whole sequence. In this design, the AI model does not start a verification and never receives verification data.

1. Your application decides when verification is required, for example at sign-up or before a sensitive action.
2. Your backend creates an Inquiry from an Inquiry Template.
3. Your chat front end shows the Persona flow, a Device Handoff QR code, or a link. The right option depends on where the chat runs. See [Choose a setup](#choose-a-setup).
4. The user captures the government ID and selfie on the device with the best camera access, usually a phone.
5. The chat front end receives a completion signal and updates the conversation.
6. Your backend fetches the Inquiry result from the Persona API or receives it by webhook, and makes the pass or fail decision.
7. Your application tells the model one of two values, such as `verified` or `not_verified`.

The Inquiry Template, checks, and consent screens are the ones you already use.

> **Warning**
>
> Moving verification into a chat does not change your compliance obligations. Keep the consent screen in your Inquiry Template, and do not collect ID numbers or ID images in the chat thread.

## Choose a setup

The right setup depends on where the chat runs and which device the user is on. Persona recommends a handoff or native SDK path over loading the Persona iframe inside the chat window. See [Why avoid nesting the Persona iframe](#why-avoid-nesting-the-persona-iframe).

| Where the chat runs         | Device            | Recommended                                            | Fallback                                                                      |
| --------------------------- | ----------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Your website                | Desktop           | Device Handoff with a QR code or text link             | Webcam capture in the page, only if every embedded layer allows camera access |
| Your website                | iPhone browser    | Persona in a full browser tab, then return to the chat | Embedded Flow in the page, if camera access is allowed                        |
| Your website                | Android browser   | Persona in a full browser tab, then return to the chat | Embedded Flow in the page, if camera access is allowed                        |
| Your own app                | iPhone            | Native SDK                                             | Secure in-app browser sheet                                                   |
| Your own app                | Android           | Native SDK                                             | Secure in-app browser sheet (Chrome Custom Tab)                               |
| Chat inside a partner's app | iPhone or Android | Persona in a full browser tab                          | None                                                                          |

**Chat inside a partner's app is untested.** The partner's app decides how links open. Many apps open links in their own built-in browser, which can block the camera. Confirm with the partner that links can open in the system browser, and test on real devices before you build. A mobile SDK is a separate integration the partner builds. It is not a fallback for a link-based setup.

Persona does not recommend capturing the ID and selfie inside the chat window as the main path. Use it only as the desktop fallback above, when every embedded layer allows camera access.

For Device Handoff behavior and the desktop and mobile capture settings, see the Help Center articles on the [Device Handoff component](https://help.withpersona.com/articles/r9sOQvL9uRALxnHxKbTsfO/) and [Capture Methods](https://help.withpersona.com/articles/7JQ78WDWLj5L63qXEu7AqJ/).

## Why avoid nesting the Persona iframe

Most chat widgets already run in an iframe. The Embedded Flow adds a second iframe inside it. The camera then works only if every frame in the chain grants camera permission. Each page that frames the chat must allow Persona camera access through its `Permissions-Policy` header. Nested frames often break camera access, especially in iOS Safari. See [iframe permissions](/2022-09-01/embedded-flow-security#iframe-permissions).

With Device Handoff, the chat shows the QR code and the camera runs in the phone's own browser, outside any iframe. Native SDK paths also avoid the problem. The outer page does not need camera permission for these paths.

## Configure your Inquiry Template

In [Capture Methods](https://help.withpersona.com/articles/7JQ78WDWLj5L63qXEu7AqJ/), turn on handoff for desktop web. Handoff links expire after 1 hour by default. Change this interval in your Inquiry Template's [expiration settings](/2022-09-01/inquiry-expiration#configuring-expiration-intervals).

The setups in this guide assume the Device handoff setting Use native mobile app flow is off. That setting applies to every user of the template. When it is on, iPhone users verify in an App Clip (iOS 17.6 or newer), Android users are asked to install the Persona Wallet app, and desktop users must hand off to a phone. You cannot send iPhone users to the App Clip and Android users to a browser tab from the same template. See the Help Center article Verifying users within chat assistants for the native setup and its limits.

## Create the Inquiry on your backend

Create the Inquiry from your server, tied to the signed-in user with `reference-id`. Do not create it from the model's tool call or from browser code.

```bash
curl -X POST https://api.withpersona.com/api/v1/inquiries \
  -H "Authorization: Bearer $PERSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "inquiry-template-id": "itmpl_...",
        "reference-id": "your-user-id"
      }
    }
  }'
```

The response contains the Inquiry ID in `data.id` (prefix `inq_`). Send that ID to the chat front end. Keep your API key on the server.

## Show the flow in the chat

If you render your own QR code or link instead of using the Device Handoff screen, generate a [one-time link](/2022-09-01/inquiry-one-time-links) from your backend. A plain Inquiry link stops working once the user has started.

Pass the Inquiry ID to the SDK from your chat front end. If the chat page is itself loaded inside another page, set `frameAncestors` to every origin above the Persona iframe and `messageTargetOrigin` to your page's origin. See [Embedded Flow parameters](/2022-09-01/embedded-flow-parameters).

```javascript
import Persona from 'persona';

const client = new Persona.Client({
  inquiryId: '<inquiry ID from your backend, starting with inq_>',
  environmentId: '<environment ID starting with env_>',
  // Only if the chat page is embedded in other pages.
  frameAncestors: ['https://partner.example.com'],
  messageTargetOrigin: 'https://chat.example.com',
  onReady: () => client.open(),
  onComplete: ({ inquiryId }) => {
    // Update the chat UI, then ask your backend for the result.
    notifyBackendOfCompletion(inquiryId);
  },
  onCancel: () => showResumeOption(),
  onError: (error) => showFallbackLink(error)
});
```

For an inline layout instead of a modal, follow [Inlined flow](/2022-09-01/inlined-flow). The inline guide recommends a minimum width of `400px` and a minimum height of `650px`. Test the layout in the actual chat container, because a compact chat card can be smaller than that.

Add the domains that load the flow to your **Allowed Domains**. A list set on the Inquiry Template can override your organization's list, so check both. See [Embedded flow security](/2022-09-01/embedded-flow-security).

## Handle completion, cancel, and error

Handle each callback so the user is never stuck in the chat. See [Client callbacks](/2022-09-01/embedded-flow-client-callbacks) for the full list.

| Callback     | Chat behavior                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `onComplete` | Show a waiting or verified state. Do not decide pass or fail here. The callback is not guaranteed to fire. |
| `onCancel`   | Offer to resume the same Inquiry instead of creating another one.                                          |
| `onError`    | Show a fallback, such as a link that opens the verification in a full browser tab.                         |

A user can also finish on a phone and never press the final button on the desktop. Rely on your backend webhook to update the conversation state in that case.

Device handback is an optional Inquiry Template setting that lets users return to the original device after a handoff. It is off by default. Test this setting if your flow continues on desktop after the phone steps.

## Decide on your backend

Listen for [Webhooks](/2022-09-01/webhooks) on the Inquiry, and use the decisioning statuses to decide. Fetch the Inquiry with the API when you need to confirm the current state.

* Subscribe to the Inquiry events for every outcome you act on, such as `inquiry.completed`, `inquiry.failed`, `inquiry.approved`, `inquiry.declined`, and `inquiry.marked-for-review`.
* Act on `approved`, `declined`, and `needs-review` if your Inquiry Template uses Workflows or manual review. See [Accessing Inquiry status and data](/2022-09-01/accessing-inquiry-status).
* Store the result against the same `reference-id` you used when you created the Inquiry.

Then pass only the outcome to the model:

```json
{ "identity_verification": "verified" }
```

Do not pass ID images, names, dates of birth, addresses, or any other fields from the Inquiry to the model. Your backend keeps that data.

## Resume an interrupted verification

Users leave chats and come back. Reuse the existing Inquiry so they continue from where they stopped, rather than creating a new one.

* For Embedded Flow and the mobile SDKs, resume with a session token. One-time links don't work in these flows. See [Resuming Inquiries](/2022-09-01/resuming-inquiries).
* For the hosted flow (a browser tab or text link), generate a [one-time link](/2022-09-01/inquiry-one-time-links). If the Inquiry has expired, [resume it first](/2022-09-01/resuming-inquiries), because you can't create a one-time link for an expired Inquiry.
* A pending Inquiry expires after a set period. See [Inquiry expiration](/2022-09-01/inquiry-expiration), including the Device Handoff link setting.
* If a user starts on desktop and continues on a phone, Persona creates a second [Inquiry Session](/2022-09-01/inquiry-sessions) for the phone.

## Test before you launch

Run one full verification in your real chat page in each desktop browser you support, and on each mobile path from the table above. On real phones, test both scanning the QR code and tapping the link. Check that the chat shows the flow or QR code, that the completion signal updates the chat, and that your backend receives the webhook. See [Integration testing](/2022-09-01/integration-testing) for sandbox guidance.

If the chat sits inside a page you do not control, confirm who manages the allowlist and `frameAncestors` values for that page before you build.