Contacts

Objective

Keep every customer relationship in one place, from first lead to loyal customer. Contacts (labeled CRM in the app) gives you a searchable list, a drag-and-drop sales pipeline, custom fields, per-contact timelines, tasks and notes, and optional AI lead scoring. Your AI agents read and update these same contacts during conversations, and the unified inbox links every conversation to its CRM record.

Access

Sidebar -> Customers -> CRM

Routes:

• List / Pipeline: /app/{tenant}/contacts
• Contact detail: /app/{tenant}/contacts/{id}
• Pipeline stages: /app/{tenant}/contacts/pipeline
• Custom fields and status labels: /app/{tenant}/contacts/fields
• AI lead scoring: /app/{tenant}/contacts/ai
• Import from CSV: /app/{tenant}/contacts/import
• Audiences and consent: /app/{tenant}/contacts/audiences

In the page header, CSV import/export is grouped under the CSV dropdown, and the overflow (…) menu holds Pipeline stages, Customize Fields, AI Scoring, and Audiences and consent. A Docs link opens this page.

Roles

• owner, admin, agent — the CRM appears in the sidebar and is fully usable (view, create, edit, archive, import/export).
• viewer — the CRM is not shown.
• Renaming status labels (see Contact status labels) is restricted to owner and admin; agents see those labels read-only.
• Audiences and consent activates with the campaigns module, which is part of a gradual rollout. If it is not yet enabled for your workspace, contact support.

Prerequisites

• No setup is needed to browse contacts.
• To create, edit, or archive contacts, your account email must be verified, and your subscription must be active.
• AI lead scoring runs on your workspace's AI configuration: if your workspace uses your own OpenAI API key (BYOK), that key must be connected first. Nightly scoring also requires a plan that includes it. See AI lead scoring.

Views

Use the view switcher at the top of the page to move between two layouts of the same contacts:

The list shows four server-side stat cards — Total, Leads, Active, Customers — counting all non-archived contacts, not just the current page.

Create a contact (Add Contact)

1. Press Add Contact.
2. Complete the form.
3. Press Create Contact.

Fields:

Edit and archive

• Edit — open the three-dot menu on a row (or Edit on the detail page), adjust fields, and press Save Changes.
• Archive — open the three-dot menu and press Archive, then confirm. Archiving is a soft delete: the contact leaves your active list, search, stats, and export, but its data is preserved.

Search, filter, and sort

• Search matches name, email, phone, and company, plus any custom field marked Include in agent search. Input is debounced as you type.
• Filters (Filter button) let you narrow by:
  • Status — All, Lead, Active, Customer.
  • Tag — any tag in use.
  • Owner — All owners, My contacts, Unassigned, or a specific team member.
  • Sort — Recently updated (default), or Lead score (high → low) when AI scoring is enabled.
• On desktop the list columns are Name, Company, Stage, Score (when scoring is on), Owner, and Updated.
• Use Load more to page through results (50 per page).

Bulk actions

Select rows with the row checkboxes, or use Select all matching contacts to select every contact that matches the current filters (up to 5,000). The floating action bar then offers:

Large selections are processed in batches; if a batch fails partway, the list refreshes to show what was applied.

Contact detail

Open a contact to see its full record and history. The header shows the name, status, email and phone (with copy buttons), company, job title, tags, and an owner picker, plus WhatsApp and Email quick actions.

Tabs:

Campaign consent

The Campaign consent panel on the Overview tab keeps a per-channel, per-category (Marketing / Utility) record of whether the contact has opted in or out of campaign messages. Entries come from keyword replies (such as STOP), web forms, CSV imports, and manual records you add with Record consent. Consent tracking activates with the campaigns module; until then the panel shows a note and nothing needs configuring.

From Conversations to the CRM and back

The unified inbox (Conversations) shows a contact card next to each conversation: lifecycle status, AI score and next best action (when scoring is on), a Pipeline stage selector you can change without leaving the inbox, the owner, and tags. Open in CRM jumps to the full contact record — and the contact page's back button then returns you to the exact conversation you came from, not the contacts list.

Pipeline stages

The Pipeline (Kanban) view groups contacts into stages, with an Unstaged column for contacts not yet placed. Drag a card to another stage to move it — fully keyboard accessible, with spoken announcements while dragging. Cards cannot be dropped back into Unstaged. AI score and suggested next action appear on cards when scoring is enabled.

Manage stages at /app/{tenant}/contacts/pipeline (Pipeline stages in the overflow menu):

• Add stage, and drag to reorder.
• Click a stage to rename or change its color.
• Mark a stage as Won or Lost to classify outcomes.
• The default stage cannot be deleted. Deleting any other stage un-stages its contacts.

Deal values

On the Pipeline board, press Track deal values to add a currency field to your contacts. You can then click a card to enter an amount, and the board shows per-stage totals plus an Open and Won summary based on your Won/Lost stage flags.

Custom fields

Define extra fields for your CRM at /app/{tenant}/contacts/fields (Customize Fields). Custom fields appear in the contact form, on the detail page, and are available to your AI agents.

Each field has a Label, an auto-generated Field Key (lowercase letters, numbers, and underscores; locked after creation), a Type, an optional placeholder and group, and three toggles: Required, Show in list view, and Include in agent search.

Field types:

Deleting a field preserves the data already stored on contacts, but it no longer appears in the UI.

Contact status labels

On the same Customize Fields page, the Contact status labels card lets you rename the four lifecycle statuses (Lead, Active, Customer, Archived) to match your business — for example, a clinic renaming Customer to Patient. Leave a field blank to keep the default. Only the displayed label changes; the underlying values, automations, and agent behavior are unaffected. Editing is limited to owners and admins.

AI lead scoring

AI lead scoring is off by default. When enabled, every contact gets a 0-100 score, a suggested next action, and an AI Insights card that labels the score Cold, Warm, Hot, or Customer and lists Why this score — up to four concrete signals behind the number. Use Compute (or Refresh) on the card to score one contact on the spot.

Configure it at /app/{tenant}/contacts/ai (AI Scoring in the overflow menu):

• Scoring runs on your workspace's AI configuration. If your workspace uses your own OpenAI API key (BYOK), connect it first — the page shows Connect your OpenAI API key first until a key is available. Cost is a fraction of a cent per contact.
• Nightly scoring requires a plan that includes it. The per-plan nightly budget is:

• The nightly job runs daily at 04:00 UTC. It scores contacts with recent activity whose score is missing or a few days old, skips contacts with no activity in the last 30 days, and never exceeds the plan budget. Recent runs are listed with their status and counts.
• You can also rescore on demand: Rescore with AI in the list's bulk actions uses the same daily budget and reports how many contacts were scored, skipped (budget reached, inactive, or archived), or failed. Archived contacts are never scored.

AI agents and the CRM

Agents get CRM access through the CRM capability in the agent editor, with granular per-agent actions:

Search, View Details, Create, and Update are the base set; everything else is opt-in per agent. Helio can also propose these grants when you build agents with it.

Import from CSV

Bulk-import contacts at /app/{tenant}/contacts/import (Import CSV).

1. Drag a .csv file onto the dropzone, or press Choose CSV file. The first row must contain column headers.
2. Review the preview and the column mapping. Standard columns — name, email, phone, company, job_title, notes, status, and tags (comma-separated) — are auto-matched. Any other column can be mapped to a custom field or skipped; a custom column matches by field label or by the custom_ prefix the export writes.
3. A badge shows whether a "Custom field" column resolves to a real field or will be skipped as Unmapped.
4. Press Import.

Each row needs at least a name, email, or phone. Rows are skipped (and reported per row) when they are missing all three, have a duplicate email, carry an invalid status, or fail a required or invalid custom-field value. Rows without a status default to Lead. Unmapped columns are listed in the result.

Export to CSV

Use CSV -> Export CSV in the header to download all non-archived contacts as contacts-YYYY-MM-DD.csv. The file includes the standard fields, tags, source, ai_score, timestamps, and one column per custom field (prefixed custom_).

Audiences and consent

Audiences and consent in the overflow menu opens the Audiences page: saved segments — rule-based groups built on the same filters as the contacts list (Status, Pipeline stage, Owner, Tag, Text search) with a live Preview count — plus an opt-in import that feeds the consent ledger campaigns use. This module activates with the campaigns module, which is part of a gradual rollout; if it is not available in your workspace, contact support.

Good practices

• Keep status and pipeline stage current so your stats, filters, and agents reflect reality.
• Fill in email and phone to unlock the WhatsApp and email quick actions.
• Use tags and custom fields to capture what matters for your business, and mark the fields your agents should search.
• Mark stages as Won or Lost so the pipeline can total open and won deal value.
• Grant agents only the CRM actions they need — stage moves, tags, and owner changes are opt-in for a reason.
• Rename status labels to match your vertical instead of forcing generic terms.

Common errors

• A contact with this email already exists — emails must be unique; edit the existing contact instead.
• If your account email is unverified, creating, editing, and archiving are blocked until you verify it.
• Connect your OpenAI API key first — on a BYOK workspace, AI scoring stays off until the key is connected; nightly scoring also needs a plan that includes it.
• On import, rows missing name/email/phone, with a duplicate email, an invalid status, or a bad required custom-field value are skipped and listed in the result.
• A custom field's Field Key cannot be changed after the field is created.
• The default pipeline stage cannot be deleted, and Kanban cards cannot be dragged back into Unstaged.
• Archived contacts are hidden from the list, search, stats, and export, and are never AI-scored, but their data is retained.

Related

• Conversations
• Agents
• Campaigns