Attributes - Fini

An agent that doesn’t know who it’s talking to gives generic answers. User Attributes is how Fini fetches the customer’s context, fresh on every message, so the agent can reference the customer’s actual plan, order, account state, or any other detail you’d otherwise have to look up by hand.

User Attributes page listing every configured attribute with its field count, viewed across all agents

The model

An attribute is three decisions:

Source: the native conversation context the attribute starts from. You pick one when you create the attribute: your app’s UI metadata, a signed widget JWT, or a connected integration. The source seeds the attribute with fields and (for integrations) credentials.
Fields: what you end up with. Fields arrive from four groups in the Available Data panel: System Attributes, passed-in UI/JWT fields, connected-integration metadata, and fields collected by external API calls. The first three are native (no HTTP call you write); the fourth is an API chain that can reach any endpoint, your internal API, Shopify, anything, independent of the source.
Switches: each field has up to three independent switches that decide who downstream can use it. Toggling a switch doesn’t move data; it exposes the field to that consumer.

At runtime, Fini fetches every attribute attached to the responding agent before each LLM call and exposes the resulting fields as conversation context. The rest of this page walks each decision in order, then shows the pattern applied end-to-end.

For a walkthrough showing how User Attributes feeds into Actions, Rulebook, and Reply Behavior end-to-end, see End-to-end: cancellation flow.

1 · Source: where data comes from

Each attribute has a source, picked when you create it. The source seeds the attribute with a starting set of fields and (for integrations) credentials:

Source	What it seeds the attribute with	Typical use
App UI (`ui`)	Metadata your app passes when it embeds Fini.	Logged-in user’s id / plan / role from your dashboard.
Widget (`widget`)	The signed JWT payload your backend hands the widget.	Authenticated widget conversations (you sign a JWT with the Widget Signing Key and pass user fields inside it).
Connected integration (Zendesk, Intercom, Front, Gorgias, HubSpot, Salesforce, LiveChat)	The integration’s standard conversation objects, plus its API credentials.	Look up the customer in Zendesk by email, read the ticket’s status, etc.

The source is only the starting point, it seeds native context. Anything the source doesn’t already provide is fetched via external API calls, available to every attribute regardless of source. Sources are gated by what’s connected: integrations show up in the dropdown only if you’ve connected them on the corresponding Deploy page (helpcenter is excluded), and widget only shows up if you have at least one widget created.

2 · Fields: what you can fetch

Fields arrive from four groups, all in the Available Data panel, which describes itself: “Data your AI can reference. For each field, choose independently whether it’s used as an API input, available in the Rulebook, and shared with the LLM.” Each group shows an enabled-over-total count in its header (e.g., System Attributes 7/8, Conversation 2/11, Collected attributes 44/44) so you can see at a glance how many are switched on.

Group	Available for	Where it comes from
System Attributes	Every attribute	The conversation itself (always present)
Passed-in fields	UI / Widget sources	Your embed metadata or signed JWT
Integration metadata	Any source (credentials); integration sources (conversation fields)	A connected native integration
External systems	Any source	An API chain you configure, see below

The first three are native: the data is already in Fini because of how the agent is reached, so there’s no HTTP call you write. The fourth is external: an API chain that fetches anything the source doesn’t already provide. Each group is detailed below.

System Attributes (always available)

Every attribute, regardless of source, exposes the same set of universal System Attributes about the conversation itself:

string

The customer’s display name, when known.

string

The customer’s email, when known.

string

Whether this conversation arrived on an email channel or a chat channel.

boolean

True if the inbound message has any attachments.

string

Time of the inbound message in UTC.

string

Day of the week of the inbound message in UTC.

boolean

True if the inbound message landed Mon-Fri UTC. Useful for “stay silent off-hours” rules.

string

The integration the conversation came from, zendesk, intercom, widget, ui, and so on.

Use these for time- or channel-based rules without needing any external lookup. They’re free to enable; no API call runs. For the App UI source, fields you’ve passed in via your embed metadata. For the Widget source, fields inside the JWT payload your backend signed.

These are automatically visible to the AI by default, even if you don’t list them here.
Listing them here gives you two extra abilities:
- Reference them in Rulebook and Reply Behavior conditions.
- Use them as inputs to API steps further down (for example, pass a user id from the JWT into a Zendesk API call).

Integration metadata fields

This section covers two distinct things that share a UI panel: connected-integration credentials (always available) and conversation-level fields (only for integration-source attributes). Connection Settings (credentials, cross-source). Every connected integration exposes its Connection Settings group regardless of which source you picked for this attribute. So a widget-source or UI-source attribute can pull Zendesk’s subdomain and access token to call Zendesk’s API directly, without rebuilding auth on your side. The group label in the editor is <IntegrationName> Settings (e.g., “Zendesk Settings”). Toggle Use as Input in API on the credential fields, then insert them by their display name into your Data Collection Steps via the $ picker. If you have multiple integrations connected, each one’s Connection Settings appears as its own group. Conversation-level fields (integration sources only). For an integration source, the same panel also shows fields directly available on the integration’s standard objects (e.g., a Zendesk ticket’s status, a Salesforce case’s priority). No API call needed; Fini reads them as part of the conversation context the integration already provides. Use these when the field is on the conversation object itself (“the customer’s email is on the ticket”); they’re cheaper and more reliable than a custom API step. The full field catalog for every integration is in the integration field catalog at the end of this page. The same list is visible live in the editor when you create an attribute.

Attributes from External Systems

The fourth field group, and the only one that costs an HTTP call you write. The distinction that matters:

Native integrations (Zendesk, HubSpot, Salesforce, and the others) are connected once on the Deploy page. Fini knows their object shape, so they come with a pre-built field catalog you just toggle on.
External systems are any other HTTP endpoint, your own internal API, Shopify, a data warehouse, or even a native integration’s REST API. There’s no catalog: you supply the URL, headers, and auth, and declare which response fields to keep.

A multi-step chain of HTTP requests, available to every attribute regardless of source. Each step is one HTTP call; later steps can use any field collected by earlier steps as input. The UI labels this section Attributes from External Systems, with the helper text “Make API calls to fetch additional data. Any field from above, as well as collected attributes from a given API step, can be used as input in subsequent steps.” Steps are configured under Data Collection Steps (“Configure the sequence of API calls that collect the attributes shown above”). Each step has:

A Step Name and Method (GET / POST / PUT / PATCH / DELETE), plus the URL. Type $ in any field to insert a dynamic value.
A Headers block and request body, as JSON. Use the $ picker to interpolate any field from the sections above whose Use as Input in API switch is on, for example, the user’s email in the URL, or an API key in an x-api-key header.
A Save From Response block: the fields to pull out of the response, in "mappedName": "json_path" form.

The fields you map populate the Collected attributes table, where each row shows only Use in Rulebooks and Visible to AI (no input switch) and is labelled with the step that produced it.

3 · Switches: who can see each field

Most fields show three independent switches in the editor table. They don’t move data, they expose a field to a downstream consumer:

Use as Input in API: makes the field available to your Data Collection Steps as a dynamic value you can insert into URLs, headers, or request bodies. In any step field, type $ to open the picker; Fini inserts the field by its display name. Turn this on for credentials and identifiers you want to inject into HTTP calls.
Use in Rulebooks: exposes the field as a condition input in Rulebook and Reply Behavior. Off by default; flip on for fields you want to write rules against.
Visible to AI: includes the field in the LLM’s context for that conversation. Off by default; flip on for fields the agent should reference when answering.

The switches are independent. The patterns that recur:

Field kind	Input in API	Rulebooks	Visible to AI
A credential (bearer token, subdomain)	✓
A customer plan / tier		✓	✓
An order / ticket id	✓	✓	✓

Don’t make every field visible to AI. The LLM context window has a budget; fields that aren’t useful for answering questions just dilute the signal. Default to off, flip on the handful of fields that genuinely help the agent personalize its reply.

Fields collected from API responses (the Collected attributes table under Data Collection Steps) only show Use in Rulebooks and Visible to AI: they’re automatically available to subsequent API steps in the same chain by name, so no input switch is needed.

Creating a user attribute

Open the Attributes page and click New Attribute

Land on API Setup → Attributes in the sidebar. The list shows every attribute you’ve created so far, scoped to the agent you have selected at the top of the page.

Fill in the basics

Name (required): how this attribute shows up in the list and in test logs (e.g., “Customer Plan”, “Recent Orders”).
Description (optional): a sentence about what this attribute fetches. Useful when teammates open the page later.
Source (required): pick from the dropdown. Determines which field-source sections you’ll see in the detail view.

New Attribute dialog showing Name, Description, and Source dropdown

Configure Available Data

The detail view opens. Walk through each section: System Attributes, your source’s passed-in or integration-metadata fields, and (if needed) Data Collection Steps for the API chain.

Attribute detail view for a UI source showing the System Attributes, UI Metadata Attributes, Attributes from External Systems, and Data Collection Steps sections

Toggle the three switches per field

For each field, decide independently whether it’s Use as Input in API, Use in Rulebooks, Visible to AI, or some combination. Credentials are typically input-only; identifiers like an order id are often all three; sentiment fields are usually rule + AI but not input.

Test the chain

Click the Play button at the top of the detail view. The Test panel opens; provide sample inputs and run the chain step by step to confirm fields come back as expected before the agent relies on them. Each Data Collection Step also has its own play button for testing in isolation.

Save

Click Save. Subsequent chat messages will fetch this attribute as part of building the agent’s context.

Deploying attributes for an AI agent

The page header has an agent dropdown (top right). With All selected, the list shows every attribute you’ve configured across the workspace with its total field count, the way the screenshot at the top of this page shows. Picking a specific agent switches into deployment mode for that agent: each attribute card grows a checkbox toggle, channel tags, and a “Save / Cancel” pair appears in the header so you can commit attachment changes.

Attributes page in deployment mode for the Marketing-AI-Agent: Always-Get banner, an attribute card with Chat + Email tags, an Active for Marketing-AI-Agent status line, and a checkbox toggle on the left

The Always-Get banner at the top of the list is a reminder: every attached attribute runs on every chat message for the selected agent. There’s no “fetch on demand” mode; if it’s attached, it runs.
Each attribute card shows the Chat and Email channel tags it’s currently active on, plus an “Active for [agent name] on Chat & Email”-style status line. Use the checkbox on the card to toggle attachment.
The card also shows the total field count the attribute exposes (system + passed-in + collected).
Click Save in the top-right to commit attachment / channel changes; Cancel discards.

If an agent has no attributes attached, no per-message lookup runs for it. Conversations on that agent get only the defaults the integration already provides (sender email, conversation subject, etc.) plus the System Attributes.

Deleting an attribute also deletes the API steps configured under it. The action is irreversible; the confirmation dialog calls this out. If the attribute is attached to agents, the attachment is removed from those agents automatically.

When attributes run

User attributes attached to the responding agent are fetched on every chat message before the agent composes its reply. The chain runs server-side; the customer doesn’t see anything happen. Because they’re fetched up front, the resulting fields are available to the LLM, Rulebook, and Reply Behavior (under the User Attributes field group), each according to the per-field switches described in Switches. The fetch is per-message, so if a customer’s plan changes mid-conversation, the next message picks up the new value.

Worked examples

Every attribute follows the same shape: create → expose source fields → call an API → toggle collected fields → attach to an agent. The three examples below apply that shape to the three sources. Pick the tab that matches how your agent is deployed, you only need the one.

UI metadata
Widget (JWT)
Connected integration

Order status from UI metadata. Your app embeds the Fini agent and passes a per-conversation order id plus an auth token via UI metadata. Fini calls your order API with those, gets back the order’s status, and exposes it to the agent.

Attribute detail view for a UI source where Token and Order Id UI Metadata Attributes feed a Get Order Status API step that collects orderStatus

Create the attribute

Name: Get Attributes for Fini UI Inbox Conversation. Source: ui.

Add the UI Metadata Attributes you'll use

Two passed-in fields, both with all three switches on:

Field	Use as Input in API	Use in Rulebooks	Visible to AI
Token	✓	✓	✓
Order Id	✓	✓	✓

Use as Input in API lets the API step interpolate them; Visible to AI lets the LLM see the order id; Use in Rulebooks lets a rule match on them later.

Add a Data Collection Step that calls your order API

Name: Get Order Status. Method: GET. Configure:

URL:     https://api.yourstore.com/orders/${Order Id}
Headers: {"Authorization": "${Token}"}
Save From Response: {"orderStatus": "order.status"}

The ${Order Id} and ${Token} tokens are the passed-in fields by their display name, inserted with the $ picker. The order.status path on the right of Save From Response is the JSON path inside your API’s response.

Toggle Collected attributes for orderStatus

The chain produces one collected field, orderStatus. Toggle Visible to AI so the agent can reference it in its reply (“Your order is in transit and will arrive Monday”).

Optionally enable a System Attribute for time-based rules

To suppress the agent off-hours, toggle Use in Rulebooks + Visible to AI on Is Weekday (UTC) so a Reply Behavior rule can stay silent when it’s false.

Attach to the responding agent on the right channels

Pick the agent from the top-right dropdown, toggle the attribute on, leave Chat + Email tags as-is (or trim to one channel if needed), and click Save.

Business hours from Zendesk via the widget. A widget-source attribute uses the customer’s accountType from the signed JWT, then calls Zendesk’s API, using credentials made available by the connected Zendesk integration, to get the team’s business hours schedules. The agent can then answer “are we open?” without you wiring anything custom.

Attribute detail view for a Widget source showing System Attributes, Zendesk Settings, JWT Token Attributes, External Systems, and Data Collection Steps

Create the attribute

Name: Get Attributes for Fini Widget Conversation. Source: widget.

Toggle the System Attributes you want exposed

Pick the universal fields useful for this agent. A common set turns on Use in Rulebooks + Visible to AI for User Name, User Email, Has Attachment, and Time (UTC).

Use Zendesk's credentials for cross-source API calls

Because Zendesk is connected on the Deploy page, its Zendesk Settings group appears here even though the attribute source is widget. Toggle Use as Input in API on:

Field	Use as Input in API
Zendesk Account Subdomain	✓
Zendesk API Access Token	✓

Leave Use in Rulebooks / Visible to AI off, credentials shouldn’t be exposed to the LLM.

List the JWT field you'll branch on

Your backend signs a JWT containing an accountType claim and hands it to the widget. List accountType under JWT Token Attributes with Use in Rulebooks + Visible to AI so a Rulebook condition can match on it and the agent knows the tier.

Add a Data Collection Step that calls Zendesk

Name: Get Business Hours Schedules from Zendesk. Method: GET. Configure:

URL:     https://${Zendesk Account Subdomain}.zendesk.com/api/v2/business_hours/schedules.json
Headers: {"Authorization": "Bearer ${Zendesk API Access Token}"}
Save From Response: {"schedules": "schedules"}

The ${Zendesk Account Subdomain} and ${Zendesk API Access Token} tokens are the Zendesk Connection Settings fields by their exact catalog label, inserted via the $ picker. The right side of Save From Response is the JSON path in Zendesk’s response, Zendesk returns { schedules: [...] }, so the path is schedules.

Toggle Collected attributes

The chain produces schedules (array). Toggle Use in Rulebooks + Visible to AI so the agent can reason about whether the conversation arrived during business hours.

This pattern (widget source + cross-source credentials + integration API call) generalizes to any “widget needs data from your helpdesk” case: ticket lookup by JWT user id, last conversation summary, organization details, and so on.

Enriching Zendesk tickets. When the agent replies on Zendesk tickets, you usually want more than the raw ticket subject. A Zendesk-source attribute exposes Zendesk’s standard Ticket fields directly, plus the connection’s credentials so you can call any Zendesk API for richer context.

New Attribute dialog with Source set to zendesk

Create the attribute

Name: Get Attributes for Zendesk Tickets. Source: zendesk.

Pick standard Ticket fields

Under the Ticket field group, toggle Visible to AI on the fields the agent should reference when answering. A common minimum:

Field	Use in Rulebooks	Visible to AI
Status	✓	✓
Priority	✓	✓
Subject		✓
Type	✓
Group Id	✓
Organization Id	✓

Status and Priority are usually both rule + AI inputs (for triage rules and for the agent to acknowledge urgency). Group Id and Organization Id are typically rule-only, you don’t want the LLM mentioning internal ids. The full set of Ticket fields is in the integration field catalog.

Toggle Zendesk credentials for API calls

Under Zendesk Settings, toggle Use as Input in API on:

Field	Use as Input in API
Zendesk Account Subdomain	✓
Zendesk API Access Token	✓

Leave Use in Rulebooks / Visible to AI off; credentials shouldn’t be exposed to rules or the LLM. With these toggled, your Data Collection Steps can insert the Zendesk subdomain and access token by their display names via the $ picker.

Add a Data Collection Step to enrich the ticket

A common second step fetches the ticket’s requester profile so the agent knows who’s asking.Name: Get Requester. Method: GET. Configure:

URL:     https://${Zendesk Account Subdomain}.zendesk.com/api/v2/users/${Requester Id}.json
Headers: {"Authorization": "Bearer ${Zendesk API Access Token}"}
Save From Response: {
  "requesterRole": "user.role",
  "requesterTags": "user.tags",
  "requesterOrg":  "user.organization_id"
}

${Requester Id} is the Ticket field by its catalog label, available because it’s in the Available Data section with Use as Input in API on.

Toggle Collected attributes

requesterRole, requesterTags, requesterOrg: pick Use in Rulebooks + Visible to AI for VIP-detection rules and richer responses. Tags is usually the most useful, a customer tagged vip or enterprise is exactly the conversation you want to handle differently.

Attach to the responding agent

Pick the agent from the top-right dropdown, toggle the attribute on, leave Email selected (chat tickets in Zendesk are a separate channel; enable both or split into two attributes). Save.

The same pattern works for Intercom, Front, HubSpot, Gorgias, Salesforce, and LiveChat: pick conversation-level fields from Available Data, toggle the integration’s credentials for API inputs, then enrich with API steps as needed. The per-integration field catalog is in the integration field catalog.

Why a field isn’t reaching the agent

The attribute isn't attached to the responding agent

Open the page with that agent selected, confirm the attribute toggle is on, and Save. This is the most common cause.

The field's Visible to AI switch is off

Even if the chain runs and collects the value, the LLM doesn’t see it until the switch is on. The value can still be present for Rulebooks while invisible to the agent.

An API step is failing

Run the Test panel with realistic inputs. A step returning 404 (customer not found) or 401 (token expired) leaves every downstream field blank.

The integration source isn't connected anymore

Re-authorize on the Deploy page for that integration. The attribute can’t fetch from a disconnected source.

The conversation came from a different channel than the attribute is configured for

Check the channel selection on the agent-attribute row. A Chat-only attribute won’t run on an email conversation.

Reference: integration field catalog

The fields each connected integration exposes. Connection Settings are credentials available from any source; the object groups (Ticket, Conversation, Case, etc.) are conversation-level fields available only when the attribute’s source is that integration. This same list appears live in the editor.

Zendesk

Connection Settings: credentials, useful as API-step headers and URLs.

string

Your Zendesk subdomain (the part before .zendesk.com). Used to construct API URLs.

string

Bearer token for Zendesk API calls. Toggle Use as Input in API only; never expose to Rulebooks or the LLM.

Ticket: fields directly on the current Zendesk ticket.

string

The ticket’s unique identifier.

string

The ticket’s URL in your Zendesk instance.

string

The ticket’s title.

string

The full description text of the ticket.

string

The ticket’s subject line.

string

The id of the assigned agent.

string

Custom status id if your Zendesk uses custom statuses.

string

External system id, if your tickets are synced from another source.

boolean

True if the ticket originated from a messaging channel (vs. email).

number

The Zendesk group the ticket is assigned to. Typically rule-only.

boolean

True if this ticket has child incident tickets.

number

The customer’s organization id in Zendesk. Useful for B2B routing.

string

Ticket priority: low, normal, high, or urgent.

string

The id of the customer who submitted the ticket. Used as input to fetch the requester’s profile.

string

Ticket status: new, open, pending, hold, solved, closed.

number

The id of whoever submitted the ticket (may differ from the requester).

string

Ticket type: problem, incident, question, task.

number

The Zendesk brand the ticket is on.

Intercom

Connection Settings

string

Bearer token for Intercom API calls. Toggle Use as Input in API only.

Conversation: fields on the current Intercom conversation.

string

The conversation’s unique identifier.

string

The conversation type.

string

The conversation’s title.

boolean

True if the conversation is open.

string

The conversation’s state.

boolean

True if the conversation has been read.

string

The conversation’s priority level.

string

The id of the assigned admin.

string

The id of the assigned team.

array

Tags attached to the conversation.

array

Contacts (customers) on the conversation.

HubSpot

Connection Settings

string

Bearer token for HubSpot API calls. Toggle Use as Input in API only.

Thread: the HubSpot conversation thread.

string

The thread’s unique identifier.

string

Thread status.

string

The id of the channel the thread originated on.

string

The account id within that channel.

string

The agent assigned to the thread.

boolean

True if the thread is marked as spam.

boolean

True if the thread is archived.

string

The inbox the thread lives in.

string

The HubSpot contact id linked to the thread.

string

The HubSpot ticket id, if the thread is associated with one.

Contact: the customer record.

string

The contact’s unique identifier.

string

ISO timestamp when the contact was created.

string

ISO timestamp of the last update.

boolean

True if the contact is archived.

object

Full properties bag of the HubSpot contact record.

Channel Details

string

Channel identifier.

string

Channel name.

Ticket

string

HubSpot ticket id.

boolean

True if the ticket is archived.

Salesforce

Connection Settings

string

Your Salesforce subdomain.

string

Bearer token for Salesforce API calls. Toggle Use as Input in API only.

Case: the current Salesforce case.

string

The case’s unique identifier.

string

Master record id (if merged from another case).

string

Human-readable case number.

string

The customer contact’s id.

string

The customer account’s id.

string

Asset id associated with the case, if any.

string

Source id of the case.

string

Parent case id, if this is a child case.

string

Phone number the customer supplied.

string

Company name the customer supplied.

string

Case type.

string

Case status.

string

Case reason (e.g., installation, performance, complaint).

string

How the case originated (web, phone, email, etc.).

string

Case subject line.

string

Case priority.

string

Full case description.

boolean

True if the case is closed.

string

ISO date the case was closed.

boolean

True if the case has been escalated.

string

Case owner’s id.

string

Id of whoever created the case.

Front

Connection Settings

string

Bearer token for Front API calls. Toggle Use as Input in API only.

Conversation

string

The conversation’s unique identifier.

string

Conversation subject line.

string

Conversation status.

boolean

True if the conversation is private.

Gorgias

Connection Settings

string

Your Gorgias subdomain.

string

Bearer token for Gorgias API calls. Toggle Use as Input in API only.

Ticket

string

The ticket’s unique identifier.

string

The ticket’s URL in your Gorgias instance.

string

Channel the ticket arrived on.

number

External system id.

boolean

True if the latest message was from an agent (not the customer).

string

How the ticket was created.

string

Ticket status.

number

The team the ticket is assigned to.

string

Detected language of the ticket.

string

Ticket subject.

LiveChat

Connection Settings

string

Bot bearer token for LiveChat API calls. Toggle Use as Input in API only.

LiveChat exposes only Connection Settings as integration metadata today. To pull conversation- or customer-level fields, use a Data Collection Step, see Attributes from External Systems.

​The model

​1 · Source: where data comes from

​2 · Fields: what you can fetch

​System Attributes (always available)

​Passed-in fields (UI / Widget sources only)

​Integration metadata fields

​Attributes from External Systems

​3 · Switches: who can see each field

​Creating a user attribute

​Deploying attributes for an AI agent

​When attributes run

​Worked examples

​Why a field isn’t reaching the agent

​Reference: integration field catalog

The model

1 · Source: where data comes from

2 · Fields: what you can fetch

System Attributes (always available)

Passed-in fields (UI / Widget sources only)

Integration metadata fields

Attributes from External Systems

3 · Switches: who can see each field

Creating a user attribute

Deploying attributes for an AI agent

When attributes run

Worked examples

Why a field isn’t reaching the agent

Reference: integration field catalog