Attributes system

The attributes system is the central key-value store that holds all configuration, state, and metadata for agents on the Newo platform. Every piece of data an agent needs -- from business hours to conversation history -- lives in one of three attribute namespaces, each scoped to a different entity.

Overview

Attributes are typed key-value pairs organized into namespaces (Customer, Persona, Project) and groups (Business, Agent, Knowledge Base, etc.). They drive agent behavior at every level: platform configuration, per-conversation state, and deployment-specific settings.

The attribute service stores each attribute as an AttributeDocumentValue -- a JSON document with a consistent schema across all three namespaces. NSL skills read and write attributes through dedicated commands such as GetCustomerAttribute and SetPersonaAttribute.

Three attribute namespaces

Every attribute belongs to exactly one of three namespaces. Each namespace is scoped to a different entity and has its own API surface.

Customer attributes

Customer attributes contain the bulk of agent configuration. They are shared across all projects and personas within a customer account. When a business owner fills in their agent's name, working hours, or escalation rules in the Newo dashboard, those values are stored as customer attributes.

Customer attributes are the only namespace that supports the is_read_only flag, which prevents modification through the standard API.

Persona attributes

Persona attributes track per-user state across conversations. The platform creates and updates these automatically as conversations progress. For example, the system extracts user phone numbers, tracks booking status, and stores RAG (retrieval-augmented generation) context as persona attributes.

At the end of each session, the platform can optionally reset transient persona attributes (controlled by the project_attributes_setting_session_ended_reset_persona_attributes customer attribute).

Project attributes

Project attributes hold deployment-level configuration. They are scoped to a specific project within a customer account and are identified by both a customer_id and a project_idn. Project attributes are typically used for initialization flags and project-specific links.

Attribute fields

Every attribute has the following fields:

::: 🗒️ NOTE Although attributes have a value_type field, the value is always stored as a string. The value_type serves as a hint to the UI and to NSL skills for how to interpret or validate the value. :::

ValueType enum

The ValueType enum defines how an attribute's value should be interpreted:

::: ⚠️ CAUTION Boolean values in attributes are stored as the strings "True" and "False" (capitalized), not as native booleans. NSL comparisons must use these exact string values. :::

Customer attribute groups

Customer attributes are organized into numbered groups that appear in the Attributes page sidebar in the dashboard. Each group contains related configuration attributes.

Attributes in Advanced groups are hidden by default in the UI. Toggle Show Hidden in the dashboard to reveal them.

::: 🗒️ NOTE Groups with an Unassigned label contain attributes that have an empty or missing group field. These appear in the dashboard under a special "Unassigned" section. :::

Persona attributes overview

Persona attributes are session-level state that track an individual user's interaction context. Unlike customer attributes (which are configured by the business owner), persona attributes are primarily set and read by the agent system during conversations.

Common persona attributes include:

Persona attributes do not support the is_read_only flag.

Project attributes overview

Project attributes are scoped to a specific deployment and are used primarily for:

• Initialization control -- The project_attributes_setting_init_attributes_metadata_enabled flag triggers one-time metadata setup when set to True
• Deployment-specific links -- For example, project_attributes_chat_link_demo stores the demo chat widget URL
• Auto-update settings -- The project_attributes_setting_init_on_auto_update_enabled flag controls whether initialization runs during automatic version updates

Project attributes do not support the is_read_only flag. They include denormalized customer_id and project_idn fields to enable efficient lookups by project identifier.

NSL access patterns

NSL (Newo Scripting Language) skills read and write attributes using built-in commands. Each namespace has dedicated getter and setter commands.

Reading attributes

{# Read a customer attribute #}
{% set business_name = GetCustomerAttribute(field="project_business_name") %}
{% set timezone = GetCustomerAttribute(field="project_business_time_zone") %}

{# Read a persona attribute (requires user ID) #}
{% set user_bookings = GetPersonaAttribute(id=user_id, field="bookings") %}
{% set conversation_meta = GetPersonaAttribute(id=user_id, field="conversation_meta") %}

{# Read a project attribute #}
{% set init_enabled = GetProjectAttribute(field="project_attributes_setting_init_attributes_metadata_enabled") %}

Writing attributes

{# Set a customer attribute value #}
{{SetCustomerAttribute(field="project_business_name", value="Menlo Tavern")}}

{# Set a persona attribute (requires user ID) #}
{{SetPersonaAttribute(id=user_id, field="conversation_concluded", value="True")}}
{{SetPersonaAttribute(id=user_id, field="rag", value=rag_context)}}

{# Set a project attribute #}
{{SetProjectAttribute(field="project_attributes_setting_init_attributes_metadata_enabled", value="False")}}

Common patterns

Conditional logic based on attribute values:

{% if GetCustomerAttribute(field="project_attributes_setting_session_ended_report_enabled") != "True" %}
    {{Return()}}
{% endif %}

Using attribute values in expressions:

{% set current_datetime = GetDateTime(
    timezone=GetCustomerAttribute(field="project_business_time_zone"),
    format="date"
) %}

Resetting persona attributes at session end:

{{SetPersonaAttribute(id=userId, field="rag", value="")}}
{{SetPersonaAttribute(id=userId, field="bookings", value="")}}
{{SetPersonaAttribute(id=userId, field="conversation_concluded", value="False")}}

NSL command reference

Metadata attributes

Metadata attributes define the schema (title, description, group, value type, possible values) for customer attributes. They are set using SetCustomerMetadataAttribute with the field="multiple_fields" parameter, which allows writing all metadata fields in a single call.

{{SetCustomerMetadataAttribute(
    idn="project_business_name",
    field="multiple_fields",
    value={
        "title": "1-01-A. Business Name [A]",
        "description": "Short business name (2-5 words) for email headers, SMS, and signatures.",
        "group": "1. Business",
        "value_type": "string",
        "is_hidden": False
    }
)}}

Metadata initialization is a resource-intensive operation. It is gated behind the project attribute project_attributes_setting_init_attributes_metadata_enabled:

1. Set the attribute to True
2. Press Publish in the dashboard
3. The initialization flow runs once, writing metadata for all defined attributes
4. The system automatically sets the flag back to False after completion

::: ❗❗ IMPORTANT Metadata initialization writes schema information (titles, descriptions, groups, value types) for all standard attributes. It does not overwrite existing attribute values. If attribute metadata needs to be refreshed after a platform update, the flag must be manually re-enabled. :::

Attribute naming conventions

Attribute idn values follow a consistent prefix convention:

Managing attributes in the dashboard

The Attributes page in the Newo dashboard provides a three-tab interface for managing attributes across all namespaces:

• Customer -- View and edit customer-scoped attributes, grouped by category
• Personas -- Select a persona, then view and edit their attributes
• Projects -- Select a project, then view and edit project-scoped attributes

Each tab supports:

• Group navigation -- Filter attributes by group using the sidebar
• Search -- Filter by idn, title, or group using the search field
• Show Hidden toggle -- Reveal advanced and system attributes
• Create/Edit/Delete -- Manage attributes through the drawer form

See Manage agents for information about how attributes are configured during initial agent setup.