Support Portal includes a set of standard fields for conversations and contacts — name, email address, phone number, and location among them. Custom Attributes extend this data model with fields specific to your organization, allowing agents and automation rules to capture and act on operational context that standard fields do not cover.
Operational objective
Custom Attributes address three requirements:
- Data model extension — Attach structured metadata to conversations or contacts without modifying the underlying platform schema. Examples include contract identifiers, SLA tiers, service regions, or regulatory classification codes.
- Contextual decision-making — Agents see custom fields directly in the conversation or contact side panel, providing the context needed to handle interactions according to organizational policy.
- Automation and segmentation — Custom Attributes are available as conditions and actions in automation rules, enabling routing, classification, and escalation based on organization-specific data points. See Automation.
Standard vs. custom attributes
Standard attributes (name, email, phone, location) are populated automatically by the platform when data is available. Custom Attributes are defined by administrators and populated manually by agents or programmatically through the SDK or API.
Once defined, a Custom Attribute is available across the workspace for all teams and agents.
Creating a custom attribute
Navigate to Settings > Custom Attributes and select Add Custom Attribute.
The configuration interface presents the following parameters:
| Parameter | Description |
|---|---|
| Applies to | Determines whether the attribute is associated with Conversation or Contact records. This cannot be changed after creation. |
| Display Name | The label shown to agents in the side panel. Use a clear, recognizable name (e.g., "Contract ID", "SLA Tier", "Service Region"). |
| Key | A unique machine-readable identifier used in API calls, SDK methods, and automation rules. Keys must be unique within the workspace. |
| Description | An optional explanation of what the attribute represents. Helps maintain consistent usage across teams. |
| Type | The data type for the attribute value. Available types: Text, Number, Link, Date, List, and Checkbox. |
Select Create to save the attribute. A confirmation message indicates the attribute has been registered. The attribute immediately becomes available in the relevant side panel section (Conversation Information or Contact Attributes).
Each key must be unique within the workspace. Attempting to create a second attribute with an identical key produces a validation error.
Using custom attributes on conversations
Conversation-type Custom Attributes appear in the Conversation Information section of the conversation side panel.
Applying an attribute:
- Open a conversation and locate the Conversation Information section in the side panel.
- Select the + control to expand the attribute picker.
- The picker lists all conversation-type Custom Attributes defined in the workspace. Use the search field to locate a specific attribute, or browse the list and select one.
Once an attribute is added to a conversation, its input field appears in the side panel. The field type matches the attribute definition — a date picker for Date attributes, a dropdown for List attributes, a checkbox for Checkbox attributes, and a text or numeric input for the remaining types.
To modify a value, select the attribute field and update it directly. To remove, copy, or edit an attribute entry, hover over the attribute to reveal the available actions.
Enterprise use cases
| Attribute | Type | Purpose |
|---|---|---|
| Contract ID | Text | Link the conversation to a specific service agreement for SLA tracking |
| SLA Tier | List | Classify the expected response and resolution time targets |
| Region | List | Identify the service region for routing or compliance purposes |
| Escalation Reason | Text | Capture the reason a conversation was escalated to a specialist team |
Using custom attributes on contacts
Contact-type Custom Attributes appear in the Contact Attributes section of the contact side panel.
The process for applying and populating contact attributes mirrors the conversation workflow described above: expand the section, select an attribute from the picker, and provide a value.
Contact attributes persist across all conversations with that contact, making them suitable for long-lived metadata such as account type, organization name, or subscriber tier.
Enterprise use cases
| Attribute | Type | Purpose |
|---|---|---|
| Account Type | List | Distinguish between enterprise, government, and individual contacts |
| Subscriber Tier | List | Identify the service level associated with the contact's subscription |
| Organization ID | Text | Reference an external CRM or ERP record for the contact's organization |
| Onboarding Date | Date | Track when the contact completed initial setup or provisioning |
Programmatic management via SDK
Custom Attributes on contacts can also be managed programmatically using the web widget SDK. This is useful for pre-populating contact metadata from an external system when a visitor initiates a conversation.
Setting attributes
Use the setCustomAttributes method to assign one or more attribute values:
window.$chatwoot.setCustomAttributes({
account_type: "government",
subscriber_tier: "priority",
organization_id: "GOV-2847-A"
});
Keys must correspond to Custom Attributes already defined in Settings > Custom Attributes. Values should match the expected data type for each attribute.
Removing attributes
Use deleteCustomAttribute to remove a specific attribute value from the current contact:
window.$chatwoot.deleteCustomAttribute("subscriber_tier");
Attributes set through the SDK appear in the contact side panel alongside manually entered values.
Integration with automation and reporting
Custom Attributes extend the conditions available in automation rules and the filters available across the platform:
- Automation rules — Use Custom Attributes as conditions to trigger actions based on organization-specific data. For example, an automation rule could assign conversations with an SLA Tier of "Critical" to a dedicated team. See Automation.
- Conversation filters — Custom Attributes are available as filter criteria in the conversation list, enabling agents and supervisors to isolate conversations by operational metadata.
- Contact segmentation — Filter the contact list by Custom Attribute values to identify groups of contacts with shared characteristics.
For reporting on conversation metadata, see Reports.