Verified identity

• A protected record. Only a verifier can write it. The browser, the model and ordinary workflow output cannot.
• Triggers. Verifiers run when your page identifies a visitor, when a call, email or SMS conversation starts, or when the model calls one as a tool mid-conversation.
• Tool gating. An account tool declares that it needs a verified identity, and the platform refuses to run it without one.
• Identity-bound history. In the web widget, a verified conversation follows the customer across devices and disappears when they sign out.

claim (identify() payload, caller ID, email sender, what the customer typed)
   │
   ▼
verifier workflow ── your check: a signature, an API lookup, order + ZIP
   │
   ├── { verified_identity: {...} }   → the platform stamps and stores an entry
   └── { verified: false, reason }    → the attempt is logged, nothing is stored
   │
   ▼
gated tool (requires_verified_identity): runs with the entry, or tells the model to verify first

​

The record

{
  "subject": "7481029",                // the id your tools look things up by, always a string
  "subject_type": "shopify_customer",
  "method": "shopify_login",           // your own name for how it was proved
  "identifiers": { "email": "priya@example.com", "loyalty_member_id": "A-2231" },
  "attributes": { "loyalty_tier": "gold" },
  "level": null,                       // reserved; always null for now
  "verified_by": {                     // stamped by the platform
    "trigger": "session",              // session, start or tool
    "verifier_key": "workflow:4b1c…",
    "workflow_id": "4b1c…",
    "workflow_version": 3,
    "execution_id": "…"
  },
  "verified_at": "2026-09-25T10:12:03Z",   // stamped by the platform
  "expires_at": "2026-09-26T10:12:03Z"     // verified_at + the verifier's ttl
}

• identifiers answers “who is this in another system”. email and phone are reserved: email is lower-cased and dropped unless it contains @, phone keeps only digits and + and is dropped under seven digits. A verified email or phone becomes the first identity used for human handoff (Gladly, for example), ahead of anything the customer typed. Other keys are yours.
• attributes is opaque to the platform: validated against your schema, never interpreted.
• Expiry is not deletion. Past expires_at the entry stays on the conversation (for history and analytics), but tools stop treating it as verified.

​

Where to read it

{% if conversation_metadata.verified_identity %}
The customer is signed in as {{ conversation_metadata.verified_identity.identifiers.email }}.
Do not ask them to verify again.
{% endif %}

​

Writing a verifier workflow

​

What a verifier can trust

​

Output

​

Build rules

• Saved or inline. A verifier can be a saved, published workflow (referenced by workflow_id and workflow_version) or an inline definition; both read workflow credentials, which a verifier almost always needs (a signing secret, an Admin API token). A saved workflow keeps its lockout count when you edit it: an inline one is keyed by its definition, so editing it starts the failed-attempt count afresh.
• Pick the input step. Automatic verifiers (see below) receive conversation_metadata, custom_metadata, user_context and an empty arguments ({}), so they can start from a Pre Call or an Ongoing Conversation input step. A verifier attached as a tool receives the tool’s real arguments and needs an Ongoing Conversation input step. One workflow on an Ongoing Conversation step can therefore serve both.
• Keep secrets in credentials and compare signatures with $hmacVerify, which compares in constant time. Never compare signatures with =.
• Test it from the workflow editor with a sample input before attaching it. See Test without a theme deploy.

​

Verifier settings

​

When verifiers run

​

Automatic verifiers

{
  "identity_verifiers": [
    {
      "type": "workflow",
      "workflow_id": "<shopify login verifier>",
      "workflow_version": 1,
      "initial_step": "trigger",
      "condition": "user_context.signature",
      "verifies_identity": { "subject_type": "shopify_customer" }
    },
    {
      "type": "workflow",
      "workflow_id": "<caller lookup verifier>",
      "workflow_version": 2,
      "initial_step": "trigger",
      "timing": "before_start",
      "condition": "conversation_metadata.channel == 'telephone'",
      "verifies_identity": { "subject_type": "shopify_customer", "lockout": null }
    }
  ]
}

​

Verifier tools (mid-conversation)

{
  "name": "verify_by_order_zip",
  "description": "Verify the customer from an order number and the order's delivery ZIP code. Use it when another tool says the customer needs to verify.",
  "properties": {
    "order_number": { "type": "string", "description": "The order number, e.g. #1042" },
    "zip": { "type": "string", "description": "The delivery ZIP or postcode" }
  },
  "required": ["order_number", "zip"],
  "actions": [
    {
      "type": "workflow",
      "workflow_id": "<order + zip verifier>",
      "workflow_version": 2,
      "initial_step": "trigger",
      "verifies_identity": { "subject_type": "shopify_customer", "ttl": 3600 }
    }
  ]
}

​

Gating tools

• Found: the actions run, and their workflows receive the entry as conversation_metadata.gated_identity. Take the customer id from gated_identity.subject, never from the tool’s arguments.
• A verifier still running (a background verifier on a call, the widget refreshing its session): the gate waits up to 5 seconds for it, then treats the conversation as unverified. A verifier that started more than 30 seconds ago is not waited for.
• Not found: nothing runs and the model gets

{ "needs_verification": true, "subject_type": "shopify_customer", "available_verifiers": ["verify_by_order_zip"] }

{
  "name": "get_order_status",
  "description": "Look up the customer's recent orders and their shipping status.",
  "requires_verified_identity": {
    "subject_type": "shopify_customer",
    "methods": ["shopify_login", "order_zip"],
    "unverified_result": "{% if available_verifiers %}Ask for the order number and delivery ZIP code, then call {{ available_verifiers | join(' or ') }}.{% else %}Offer to connect the customer with a person.{% endif %}"
  },
  "actions": [
    { "type": "workflow", "workflow_id": "<order lookup>", "workflow_version": 4, "initial_step": "trigger" }
  ]
}

​

On email

• Identity taken from the sender address needs a DMARC pass. A start verifier can only rely on the address, so on email it runs on the owner’s first message that passed, whenever that arrives: after the agent has already replied too, as on a thread your agent started. Each turn before that is recorded as no_evidence with the reason sender_unauthenticated, sender_not_owner or ambiguous_sender.
• In-chat proofs work on any of the owner’s messages, but carry over only with a DMARC pass. An order number plus ZIP proves what the customer typed, so a verifier tool runs whether or not the owner’s mail passed. The entry records the address and the batch it was proved in. A later email uses it only when it passed DMARC; otherwise the customer proves it again.
• Replies on a verified thread go only to its owner. Once someone was verified on a thread over email, replies (the agent’s, and a human agent’s from your helpdesk) go to the owner and copy only the people the owner copied on its last message that passed DMARC (nobody, if it never sent one). A Reply-To, a Cc another message added, and every other sender are ignored. A thread nobody was verified on keeps the usual reply-all routing.

​

Human handoff

​

Outcomes and lockout

​

Example: Shopify customer login

<script>
  window.anyreach = window.anyreach || [];
{%- if customer %}
  {%- assign anyreach_ts = 'now' | date: '%s' -%}
  {%- capture anyreach_message -%}{{ customer.id }}:{{ customer.email }}:{{ anyreach_ts }}{%- endcapture -%}
  {%- assign anyreach_signature = anyreach_message | hmac_sha256: shop.metafields.anyreach.identity_secret.value %}
  window.anyreach.push(['identify', '{{ customer.id }}', {
    email: {{ customer.email | default: '' | json }},
    first_name: {{ customer.first_name | json }},
    ts: '{{ anyreach_ts }}',
    signature: '{{ anyreach_signature }}'
  }]);
{%- else %}
  window.anyreach.push(['identify', null]);
{%- endif %}
</script>

// Condition step, branches in this order
// 1. no_evidence
{{ $not($exists(trigger.user_context.signature)) }}
// 2. verified: a valid signature, at most 12 hours old and at most 5 minutes in the future
{{ (
  $uc := trigger.user_context;
  $ts := $number($uc.ts);
  $now := $millis() / 1000;
  $ts > $now - 43200 and $ts < $now + 300 and
  $hmacVerify($credential('shopify_identity').secret,
              $uc.external_user_id & ':' & $uc.email & ':' & $uc.ts,
              $uc.signature)
) }}
// 3. stale: the signature is valid, so the timestamp is what failed
{{ (
  $uc := trigger.user_context;
  $hmacVerify($credential('shopify_identity').secret,
              $uc.external_user_id & ':' & $uc.email & ':' & $uc.ts,
              $uc.signature)
) }}
// default: bad_signature

// Output step on "verified"
{
  "verified_identity": {
    "subject": "{{ trigger.user_context.external_user_id }}",
    "subject_type": "shopify_customer",
    "method": "shopify_login",
    "identifiers": { "email": "{{ trigger.user_context.email }}" }
  }
}
// Output steps on the other branches
{ "verified": false, "reason": "no_evidence" }
{ "verified": false, "reason": "stale_timestamp" }
{ "verified": false, "reason": "bad_signature" }

​

Test without a theme deploy

// ANYREACH_IDENTITY_SECRET=... node sign-identify.mjs 7481029 priya@example.com
import { createHmac } from 'node:crypto';

const [customerId, email] = process.argv.slice(2);
const ts = String(Math.floor(Date.now() / 1000));
const signature = createHmac('sha256', process.env.ANYREACH_IDENTITY_SECRET)
  .update(`${customerId}:${email}:${ts}`)
  .digest('hex');
const traits = { email, ts, signature };

console.log(`window.anyreach.identify(${JSON.stringify(customerId)}, ${JSON.stringify(traits)});`);
console.log(JSON.stringify({ external_user_id: customerId, ...traits }, null, 2));

# ANYREACH_IDENTITY_SECRET=... python3 sign_identify.py 7481029 priya@example.com
import hashlib
import hmac
import json
import os
import sys
import time

customer_id, email = sys.argv[1], sys.argv[2]
ts = str(int(time.time()))
signature = hmac.new(
    os.environ["ANYREACH_IDENTITY_SECRET"].encode(),
    f"{customer_id}:{email}:{ts}".encode(),
    hashlib.sha256,
).hexdigest()
traits = {"email": email, "ts": ts, "signature": signature}

print(f"window.anyreach.identify({json.dumps(customer_id)}, {json.dumps(traits)});")
print(json.dumps({"external_user_id": customer_id, **traits}, indent=2))

{
  "conversation_metadata": {
    "id": "",
    "organization_id": "<your org id>",
    "direction": "inbound",
    "user_id": "",
    "agent_number": "",
    "channel": "webchat",
    "status": "triggered",
    "created_at": "2026-09-25T10:12:03Z",
    "widget_id": "<widget id>"
  },
  "custom_metadata": { "user_context": { "external_user_id": "7481029", "email": "priya@example.com", "ts": "…", "signature": "…" } },
  "user_context": { "external_user_id": "7481029", "email": "priya@example.com", "ts": "…", "signature": "…" }
}

​

In the web widget

• On by itself. There is no widget setting: the widget config reports identity_enabled: true whenever the agent has identity verifiers, and only then does the widget ask Anyreach to verify anyone. Without verifiers it never does, though identify(null) still drops any token it holds.
• Lazily, not per page. The loader passes every identify() into the widget, and the widget keeps the latest payload. It asks Anyreach to verify only when it needs to: when the chat is opened or a conversation is created without a valid identity, when the identified user changes, and shortly before the identity expires. A new page for the same shopper (a fresh ts) is not checked again until then; that renewal sends the newest payload. A shopper who never opens the chat costs nothing. A payload with no proof field (signature, ts, token, jwt, hmac), such as the user id the loader remembers on pages that don’t call identify(), is sent only to renew an identity the widget already holds for that user. While that identity is valid, nothing waits on its renewal.
• A failure is not a sign-out. A verifier that times out or errors never signs the shopper out: the widget keeps its identity and tries again shortly (after 30 seconds, then longer). Only a rejected proof counts (so does a request Anyreach refuses outright, such as an oversized payload), and even then a shopper already signed in stays signed in until their identity expires. If the sign-in succeeds but the open chat could not be updated, the shopper is signed in and the widget retries the chat on the same schedule.
• An identity token, kept in the widget. A successful check returns a token that lasts an hour at most (never past the entries’ own expiry). It lives in the widget iframe’s session storage, on Anyreach’s origin, so your page cannot read it and it is gone when the tab closes.
• Carried into conversations. A new conversation starts with the verified entries (trigger: "session") already in place, so an identity-aware greeting can use them. A chat that is open when the visitor signs in is covered in Signing in mid-chat.
• Shown in the header. The widget header reads “Signed in as priya@example.com” (the verified email, or phone), with Not you? Start a new chat, which starts a new, unverified conversation in that tab, without that visitor’s traits, until the page identifies someone again. The widget cannot sign anyone out of your store.
• Reported to your page as host-page events that carry the subject types and methods but never identifiers: identity_verified when the widget gets a token for a visitor who was unverified in that tab, or for a different user, and identity_cleared whenever it drops a token it held, including after Not you?. Refreshing the same visitor’s token fires neither.

​

Signing in mid-chat

• Account tools work from the next message, and the header shows who is signed in.
• The agent is told on its next turn, in a note built from the verified record and never from anything the browser sent: “The customer has signed in. Verified: shopify_customer via shopify_login.” So it stops asking them to sign in or verify, even when a verifier tool had locked after earlier wrong guesses. The note is the platform’s, not a customer message, so a customer who types the same words has only typed them: a text-only widget adds it to the agent’s instructions and keeps it in the conversation’s transcript, at the point the agent was told; any other widget, voice or chat, adds it as a system message the agent keeps for the rest of the session, tool calls included. A renewal of the sign-in before their next message does not lose it.
• The chat is not added to the customer’s history on their other devices: what was typed before the sign-in was typed as a guest, perhaps by someone else on a shared computer. Otherwise it is a signed-in chat like any other: from the sign-in on, it opens only with the customer’s identity, so another tab still showing it as a guest can no longer reopen it (on a text-only widget, that tab leaves it at once and starts a new chat). When they sign out, the widget leaves it and forgets it on this device: it cannot be reopened, not even by them.
• A chat already verified in the conversation as someone else (an order + ZIP proof naming another customer, or an identity of another type), even if that proof has since expired or been replaced, is left as it is, and the widget starts a new chat for the signed-in customer.
• Only the chat open at that moment continues. An ended chat, a chat reopened from the history list, and a guest chat reopened while someone was already signed in stay guest chats; a new chat has the account’s tools.

​

Signing out and shared devices

​

History that follows the customer

• When the widget holds an identity, the history lists that customer’s bound conversations on this widget from any device, up to the 50 most recent, alongside the unverified conversations stored on this device. A chat continued at sign-in is listed only on the device it was continued on, until they sign out there.
• A conversation verified through the page sign-in can only be listed, resumed or read with that customer’s identity. Signed out, or signed in as someone else, it is absent from the history and the server refuses it. It is not deleted.
• A conversation verified only by a verifier tool keeps working on its own device as before. It does not follow the customer to other devices.
• A sign-in never takes a conversation that belongs to someone else. If someone else signs in while a conversation another customer verified through the page sign-in is open, the new customer is never written to it, and when they are the same kind of account (another shopify_customer) that conversation is signed out as well.
• Reopening one of their conversations from the history, signed in, gives it back the page sign-in’s entries if it lost them (a sign-out, or their expiry). So does the next message, or the chat’s stream reconnecting, from a tab still signed in as them, when the chat holds no unexpired entry of that type: a sign-out on another device does not leave the chat open here unverified. An ended chat gets nothing back this way.
• While someone is signed in, the history labels any conversation not tied to their account as a Guest chat (“Anyone using this browser can see these”), listed below Your chats. Guest chats are never attached to the account: only the chat open at sign-in continues, and only on that device, so a stranger’s chat on a shared browser cannot follow the next person to their other devices. A visitor who never signs in sees one unlabelled list, as before.

​

Debugging “why wasn’t I verified?”

​

Security notes

• Sign on the server only. A secret in browser JavaScript ships to every visitor. Liquid runs on Shopify’s server; for a single-page app, have your backend sign the payload and hand it to the page. A session token your verifier checks against your site’s API works as well as a signature.
• Name the user. identify() must say who the proof is for: an id, an email or a phone, or a JWT (in jwt or token) whose sub names them. Pass the user’s id alongside an opaque session token: identify('7481029', { token }). A payload that names no one is not verified, and the widget logs a warning in the browser console.
• A copied payload is replayable inside its window. Keep the window as short as your pages allow, and sign the customer’s id, not just an email.
• Proof fields stay out of the record and your analytics. signature, ts, token, jwt and hmac are removed from user_context before it is stored on a conversation, and from the traits of the identify host event, so the signed payload does not end up in conversation metadata, exports or your data layer. Use those names for proof fields. The verifier still receives them, but the runs Anyreach starts for it store them as «redacted», in the input and wherever a step copied them unchanged.
• Templates and workflows read conversation_metadata.*. Gated workflows take the subject from conversation_metadata.gated_identity, never from tool arguments or custom_metadata.
• Verified data is still user text. A verified first name is what the customer typed into Shopify. Treat identifiers and attributes as data in prompts, not instructions, and store flags or references in attributes rather than raw sensitive values.
• Weak channels, narrow methods. Caller ID can be spoofed. On email, only the thread’s owner can prove anything, identity taken from the sender address needs a DMARC pass, an in-chat proof carries over to later mail only with a DMARC pass, and replies on a verified thread go only to its owner (On email). Give sender-based verifiers their own method and list it in methods only on tools where that is enough.
• The lockout is per conversation. It stops guessing inside one conversation, not across many.

​

Related