Identity and metadata

Your application has already signed the user in. On every conversation start you tell us who they are, and TrolleyChat keeps one customer record per user so their history follows them.

{
  "user": {
    "id": "b7f3c2d1",
    "name": "Matthew",
    "email": "matthew@example.com",
    "metadata": { "role": "admin", "plan": "growth" }
  }
}

Field	Required	Notes
id	yes	Your stable user id. 1 to 128 characters: letters, digits, . _ : @ -.
name	no	Shown to your team in the dashboard. Up to 120 characters.
email	no	Kept as a note on the record for your team. Never a key; see below.
metadata	no	Short notes for the assistant. See below.

How identity works

• The same id always resolves to the same customer record and the same conversation history in the inbox.
• Records created through the API are separate from records created by the widget or a Shopify store, even if an email matches. Your user is never linked to someone else's record, and nobody else is linked to theirs.
• email never acts as a key. It is stored as a note from your application, not in the record's email field, so a store webhook or a widget visitor with the same address can never be linked to your user, and your user is never treated as verified for that address.
• Users without an email are fine. Many applications identify people by phone or by an internal id only.

Metadata

metadata is context for the assistant, not data for it to report and not a way to grant access. Use it for things like the user's role or plan so answers are pitched right.

• Up to eight keys. Keys are up to 40 characters of letters, digits, . _ -.
• Values must be strings, numbers, or booleans. Strings are clipped to 80 characters. Objects and arrays are dropped.
• The assistant sees the notes marked as unverified and not instructions. It will not state them as facts, and text such as "ignore your rules" in a value has no effect.
• Metadata is refreshed on every conversation start, so send the current values each time.

Never use metadata for authorisation. TrolleyChat makes no access decisions with it. If the assistant needs to know something about the user to answer well, put it here. If your application needs to decide what the user may see, decide that on your side before calling us.