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

# Identify visitors

> Securely connect signed-in users to their Zorvia conversation history.

Identity verification lets Zorvia associate a signed-in user with a stable external ID. Generate the signature on your server, then pass the signed payload to the SDK.

> **Warning**
>
> Never expose the identity signing secret in JavaScript, mobile code, logs, or API responses. Only the public messenger key belongs in client code.

## Build the signed payload

The payload can contain `external_id`, `name`, `email`, `phone`, `custom_data`, and `timestamp`. It is recursively sorted by key, JSON encoded without escaped slashes or Unicode, and signed using HMAC-SHA256.

```php
function sortIdentityPayload(array &$values): void
{
    ksort($values);

    foreach ($values as &$value) {
        if (is_array($value)) {
            sortIdentityPayload($value);
        }
    }
}

$payload = [
    'external_id' => (string) $user->id,
    'name' => $user->name,
    'email' => $user->email,
    'timestamp' => now()->timestamp,
];

sortIdentityPayload($payload);

$payload['signature'] = hash_hmac(
    'sha256',
    json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
    config('services.zorvia.identity_secret'),
);
```

Generate a fresh timestamp for each identity response. Zorvia rejects stale signatures.

## Identify through the SDK

Call `identify()` after `init()` succeeds:

```js
await window.zorvia.init({
  workspaceUrl: "https://{workspace}.zorvia.io",
  livechatKey: "YOUR_PUBLIC_MESSENGER_KEY",
});

const identity = await fetch("/api/zorvia-identity").then((response) =>
  response.json(),
);

await window.zorvia.identify(identity);
```

The identity object must include `external_id`, `timestamp`, and `signature`. It may also include `name`, `email`, `phone`, and `custom_data`.