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.