Custom Fields Guide

Custom fields let you collect and store any information your team needs about contacts and conversations — beyond the built-in fields like name, email, and phone. Custom fields appear in the contact sidebar during live conversations, on contact detail pages, and are accessible via API for integrations.

Subscription requirement: Custom fields must be enabled for your account. Contact your administrator.

---

What Are Custom Fields?

Custom fields are administrator-defined data points attached to contact records or conversations. Examples:

• Account tier (Starter, Professional, Enterprise)
• Preferred contact method (Phone, Email, Chat)
• Industry vertical (Healthcare, Finance, Retail)
• Order ID collected at the start of a conversation
• Internal score calculated by your CRM

Agents fill in custom field values during or after conversations. Values are saved to the contact record and visible to all agents who view that contact in the future. Fields can also be pre-populated via embed code, API, or bot workflows — so agents see the data before they even send the first message.

---

Field Types

Type	Best For	Example
Text	Short free-form values	Customer ID, referral code, account name
Number	Numeric values without formatting	Lead score (0–100), employee count
Textarea	Long notes or multi-line input	Issue description, special instructions
Select	A fixed list of choices	Account tier, region, product line
Checkbox	Yes/no flags	VIP customer, opted in, pilot participant

For Select fields, administrators define the available options. Agents pick from the list — they cannot enter freeform values. This keeps data consistent for reporting and segmentation.

---

Field Scopes

Every custom field has a scope that controls where it appears and what it is linked to.

Scope	Appears On	Use When
All	Contact panel + conversation panel	The information applies to both the person and the chat
Contact Only	Contact panel only	Permanent profile data: industry, account tier, lifetime value
Conversation Only	Conversation panel only	Session-specific data: order ID, support ticket, chat topic
Internal	Agent view only; never shown to visitor	Internal notes, scores, or flags not meant for the customer

Conversation-scoped fields reset on each new conversation. Contact-scoped fields persist across all conversations with that contact.

---

Validation Presets

Field validation keeps your data clean. When validation is set on a Text field, any value the agent enters must match the required format before it can be saved. Validation runs on the server — it cannot be bypassed by embed code, bot input, or API submissions.

Velaro provides 19 built-in validation presets:

Preset Name	Example Value	Use Case
Phone (US)	(555) 123-4567	North American phone numbers with area code
Phone (International)	+44 20 7946 0958	E.164 international format, any country
Email Address	user@example.com	Standard email addresses
URL / Website	https://example.com	Web URLs with http:// or https://
ZIP Code (US)	90210 or 90210-1234	5-digit or 9-digit US postal codes
Postal Code (Canada)	K1A 0A9	Canadian alphanumeric postal codes
Postcode (UK)	SW1A 1AA	UK postcodes (outward + inward code)
Currency (USD)	$1,234.56	Dollar amounts with $ sign and commas
Number Only	4200	Digits only — no letters, spaces, or symbols
Integer Only	-42	Whole numbers, including negative
Letters Only	Smith	Alphabetic characters only — no digits or symbols
Alphanumeric	AB12CD	Letters and digits combined — no spaces or symbols
Date (MM/DD/YYYY)	03/15/2026	US-format dates
Date (YYYY-MM-DD)	2026-03-15	ISO 8601 date format
Order / Reference Number	ORD-AB12-3456	Uppercase letters, digits, and hyphens
SSN (XXX-XX-XXXX)	123-45-6789	US Social Security Number format
Card Last 4 Digits	1234	Exactly four digits — for PCI-safe card references
X/Twitter Handle	@velaro	Twitter/X username beginning with @
LinkedIn Profile URL	https://linkedin.com/in/name	Full LinkedIn profile URLs
Custom Regex	(any pattern you define)	Any format not covered by the presets above

How to apply a preset: Open Settings → Custom Fields → edit the field → set Validation Preset to the desired option → save.

Custom error message: You can override the default error text with your own plain-English message. Example: instead of "Value does not match the required format," show agents: "Enter a 10-digit US phone number, like (555) 123-4567."

---

Custom Regex Validation

When none of the 19 presets fits your data format, choose Custom Regex and enter your own regular expression pattern.

When to use custom regex:

• Internal account codes with a unique format (e.g., ACCT-0001-2026)
• Product SKUs with a company-specific structure
• Employee or badge IDs
• Any format not covered by the built-in presets

Common character classes for building patterns:

Pattern	Matches
[0-9]	Any digit
[A-Z]	Uppercase letters
[a-z]	Lowercase letters
[A-Za-z]	Any letter
[A-Za-z0-9]	Any letter or digit
\d	Any digit (same as [0-9])
\w	Letter, digit, or underscore
.	Any character
{3}	Exactly 3 of the preceding
{2,5}	Between 2 and 5 of the preceding
+	One or more of the preceding
*	Zero or more of the preceding
?	Zero or one of the preceding
^	Start of value
$	End of value
-	Literal hyphen (inside brackets)

Example: To match account codes in the format ACCT-0001-2026 (letters, hyphen, 4 digits, hyphen, 4 digits):

^[A-Z]+-\d{4}-\d{4}$

You do not need to include the / delimiters — enter the pattern only.

---

Copilot-Assisted Validation Setup

Velaro's built-in Copilot AI can help you choose the right validation preset and configure it without any technical knowledge. Describe what you want in plain English:

"Set up phone validation on the Phone field"

Copilot recognizes this as a formatting requirement and asks whether you need US-only or international numbers. It then suggests the Phone (US) preset (example: (555) 123-4567) or Phone (International) (example: +44 20 7946 0958), and walks you to the field settings page.

"Make the URL field require https"

Copilot suggests the URL / Website preset, which already requires https:// or http:// as part of the pattern. If you specifically need https-only, Copilot can suggest a custom regex: ^https://.*

"Restrict the order number field to uppercase letters and digits"

Copilot suggests the Order / Reference Number preset (example: ORD-AB12-3456). If your format differs — for example, no hyphens — Copilot can suggest the Alphanumeric preset or help you build a custom regex.

"I need to validate Canadian postal codes"

Copilot suggests the Postal Code (Canada) preset (example: K1A 0A9) and confirms the format covers all provinces including special Ottawa codes.

"Validate that email fields are real addresses"

Copilot suggests the Email Address preset and explains that it checks the format only (user@domain.tld) — it does not verify that the address is active or deliverable. For deliverability verification, that is handled at the channel level, not in the field.

---

Rollback and Changing Validation

Changing or removing validation on a field never deletes or modifies existing contact records. Existing values are preserved exactly as they were entered.

• Add validation to an existing field: All contacts with that field already saved keep their current values. Only future saves must match the new format.
• Change the preset: Same behavior — existing values are not re-validated.
• Remove validation: The field becomes free-form again. Existing values are unaffected.

This means you can add validation at any time without worrying about breaking historical data or triggering bulk updates.

---

Common Validation Patterns in Plain English

These describe what each preset actually enforces — without regex notation:

• Phone (US): Must be a 10-digit number. Accepts parentheses around the area code and hyphens or spaces between groups. Example: (555) 123-4567 or 555-123-4567.
• Email Address: Must contain exactly one @ sign, with text before it and a domain with at least one dot after it. Does not check if the address exists.
• URL / Website: Must start with http:// or https://, followed by a domain name.
• ZIP Code (US): Must be exactly 5 digits, or 5 digits, a hyphen, and 4 more digits.
• Postal Code (Canada): Must follow the alternating letter-digit-letter space digit-letter-digit pattern (A1A 1A1).
• Alphanumeric: Only letters A–Z (upper or lower) and digits 0–9. Spaces, hyphens, and special characters are not allowed.
• Order / Reference Number: Uppercase letters and digits only, hyphens allowed between groups.
• Currency (USD): Must start with a $ sign, followed by digits with optional comma separators, and an optional decimal with two cents digits.
• Date (MM/DD/YYYY): Must match the pattern 2 digits, slash, 2 digits, slash, 4 digits. Does not verify that the date is a real calendar date.
• SSN: Must match exactly 3 digits, hyphen, 2 digits, hyphen, 4 digits.

---

Common Questions

Q: Can validation be bypassed by a visitor filling out an embed form?

A: No. Validation is enforced on the server when the value is saved. If a value is submitted from an embed form, bot, or API that does not match the required format, the save is rejected. The agent or system submitting the value must correct it.

Q: What happens if an agent tries to save a value that fails validation?

A: The field shows the validation error message (your custom message if set, or the default format description) and the save does not proceed until the value is corrected. Other fields are not affected.

Q: Can I use validation on Number or Checkbox fields?

A: Validation presets apply to Text fields only. Number fields already enforce numeric input by type, and Checkbox fields are binary — no additional validation is needed.

Q: Is there a limit to how many custom fields I can create?

A: Your subscription plan sets the maximum number of custom fields. Contact your administrator to review your current limit and usage. The current usage and limit are visible in Settings → Custom Fields.

Q: Can I make a custom field required?

A: Yes. When a field is marked Required, agents cannot save or close the conversation without filling it in. Required fields are marked with an asterisk in the conversation panel.