Managing Contacts in brayv.ai

Overview

Contacts are the foundation of brayv.ai. Every lead, customer, and person you interact with is stored as a contact. Contacts contain all the information about your customers including their contact details, conversation history, appointments, opportunities, and more.

Prerequisites

• Access to a brayv.ai account
• Appropriate permissions to view and manage contacts

Accessing Contacts

Navigate to Contacts from the main sidebar. You'll see a list of all your contacts with options to search, filter, and manage them.

Creating a New Contact

Step 1: Open Contact Creation

Click the "New Contact" or "Create Contact" button at the top of the Contacts page.

Step 2: Enter Basic Information

You must provide at least one of the following:

• First Name OR Last Name (at least one is required)
• Email OR Phone (at least one is required)

Step 3: Fill in Additional Details (Optional)

You can add extensive information about your contact:

Contact Details:

• Phone: Primary phone number (10-digit US format)
• Email: Primary email address
• Additional Phone Numbers: Add multiple phone numbers
• Additional Email Addresses: Add multiple email addresses

Address Information:

• Street Address
• City
• State
• ZIP Code
• Country

General Information:

• Business Name: Company or business name
• Website: Contact's website URL
• Hook: A brief description of what the contact is interested in (e.g., "pool installation", "electrical services")
• Friendly Source: A human-readable description of how they found you (e.g., "our website", "Facebook ad")
• Birthday: Contact's birthday
• Timezone: Contact's timezone for scheduling

Step 4: Set Custom Fields

If you've created custom fields for your account, they'll appear here. Fill in any relevant custom field values.

Step 5: Add Tags

Tags help organize and categorize your contacts. Type to add existing tags or create new ones on the fly.

Step 6: Save

Click "Create" to save the contact. If a contact with the same phone number already exists, you'll be prompted to merge the contacts.

Editing an Existing Contact

Step 1: Open the Contact

Click on any contact from the Contacts list to open their detail page.

Step 2: Edit Fields

Simply click into any field and start typing. The system tracks your changes and shows a "Save Changes" bar at the bottom of the screen.

Step 3: Save Changes

Click "Save Changes" in the bottom bar to commit your updates, or "Cancel" to discard them.

Contact Detail Page Sections

Left Panel: Contact Information

Contains all editable contact details organized into sections:

• Names
• Contact Details (phone, email, address)
• General Information (business, website, hook, friendly source)
• DND Preferences
• Voice AI
• Tags
• Attribution data (source, UTM parameters, click IDs)

Middle Panel: AI & Assignment

Contact Owner: Assign a team member as the owner of this contact. The owner is typically responsible for managing the relationship with this contact.

AI Text Agent: Toggle to enable or disable AI text messaging for this contact. When enabled:

• The contact will receive AI-powered text message responses
• If no specific agent is assigned, they'll use your default "global" agent
• If they're enrolled in a Journey with an AI agent, that agent will be assigned automatically
• Toggling the AI off will not end the contact's active journey (if they have one), but enables you to temporarily disable AI so you can jump into the conversation yourself. You can turn it back on at any time, and the AI text agent will pick up where it left off. If you'd like to end the journey (contact is no longer an active opportunity, use the opportunities section below.)

Assigned Text Agent: Shows which AI agent is currently handling this contact's text conversations (if any).

Next Follow-up Send: If a follow-up message is scheduled, you'll see the scheduled time and attempt number here.

Appointments: Quick view of upcoming and past appointments with this contact.

Opportunities: View and manage Journey opportunities associated with this contact.

• Click on a current or past opportunity to see more details
• You can choose to mark an opportunity as "lost" or "won" which will end the customer "journey" (no more AI follow ups, opportunity no longer "open")
• If you see the status is "ended" or "completed" the journey opportunity is already closed (AI is not pursuing the journey goal with the contact for that opportunity). In this case you can still mark as "won" or "lost" for your own tracking purposes.

Right Panel: Activity History

A chronological feed of all interactions with this contact:

• Text messages (sent and received)
• Phone calls — shown as Call Made, Call Received, or Missed Call, with the AI's call summary for AI calls (Updated on July 7, 2026 - activity records for calls prior to update used the generic message type but were still recorded)
• Outbound AI call skipped — an AI call a journey queued but did not place because of the contact's Do Not Call or Voice AI settings, naming which setting stopped it
• Outbound AI call cancelled — an AI call a journey queued but dropped because the contact replied by text before the call was placed
• Emails
• Notes
• Appointments
• Status changes
• Journey enrollments
• Form submissions

Contact Notes

Open Notes from the contact page (also available from the Conversations info panel).

Creating a note:

1. Click Add Note
2. Write your note
3. Optionally enable Visible to AI agents — when on, AI text and voice agents can see this note as context when conversing with the contact
4. Click Save

Managing notes:

• Edit or Delete any note
• Notes marked visible to AI show an AI chip; hidden notes do not

Use AI-visible notes for facts the agent should remember (preferences, promises, special circumstances). Keep internal-only commentary with Visible to AI agents off.

Bulk Actions on the Contacts List

With one or more contacts selected (or Select all N filtered contacts):

• + Tag — Apply tags in bulk
• Reassign — Change contact owner for the selection
• + Journey — Bulk enroll in a journey (see Bulk Add to Journey)
• + Email Campaign — Enroll in a drip email campaign

Call Contact

From the contact detail page, use Call Contact to open the phone dialer and place an outbound call (desktop). Calls appear in the activity history.

If the contact is marked Do Not Call, the dialer refuses and tells you why instead of placing the call. Turn Do Not Call off on their contact record first if you have permission to do so. This applies however you reach the dialer, including typing the number by hand.

Schedule Custom Follow-up

When a journey agent is assigned, you can schedule a one-off follow-up from the contact page (same Schedule Custom control as on Conversations). Provide the message, date/time, and optional reason. The agent sends this message for you at the scheduled time. This overrides the next sequenced follow-up for that contact.

Do Not Disturb (DND) Preferences

You can set DND preferences to control how you communicate with a contact:

• Do Not Text: Prevents sending SMS messages
• Do Not Call: Prevents calling the contact. AI voice agents will not dial them, and the in-app dialer refuses the call with an explanation. Inbound calls from the contact still come through — they can always reach you
• Do Not Email: Prevents sending marketing emails (does not prevent sending notification emails, i.e. appointment confirmations)

Important: If a contact opts out at the carrier level (texts "STOP"), the Do Not Text option will be automatically enabled and locked. They must text "START" to your number to re-enable texting.

Voice AI Preferences

Below DND you'll find two checkboxes controlling how far AI voice agents may go with this contact. Both start on for new contacts (unless specifically disabled on lead submission)

• Voice AI: AI voice agents may handle this contact's calls at all. Turn it off and no agent will dial them, and when they call one of your Voice AI numbers the call forwards to that number's fallback number instead of reaching an agent
• Outbound Voice AI: AI voice agents may dial this contact. Turn it off and the AI stops calling them while they can still reach an agent when they call in

Disable (uncheck) Outbound Voice AI for "stop calling me, I'll call you," Voice AI for "I don't want to deal with the AI," and Do Not Call above for "nobody should call me." Neither Voice AI setting stops your team from calling by hand — only Do Not Call does that.

All three are enforced automatically. When a journey queues an outbound AI call for a contact one of these settings covers, the call is skipped rather than placed and the reason appears on their activity history. Your AI voice agents can also set these themselves during a call if you configure an action for it — see Voice Agent Conditional Tools.

Merging Duplicate Contacts

When creating a new contact, if someone with the same phone number already exists, you'll see a merge dialog showing:

• Existing contact information
• New information you're trying to add

Merge Behavior:

• New information updates the existing contact
• The existing email becomes an additional email
• All tags are preserved and combined
• Conversation history is maintained

Click "Merge Contacts" to proceed or "Cancel" to stop.

Contact Fields Reference

Standard Fields

Identity:

• First Name
• Last Name
• Full Name (auto-generated from first and last name)

Contact Methods:

• Email (primary)
• Phone (primary)
• Additional Emails (array)
• Additional Phones (array)

Business Information:

• Business Name
• Website

Address:

• Street Address
• City
• State
• ZIP Code
• Country

Personal:

• Birthday
• Timezone

Other Standard Fields:

• Friendly Source (human-readable source, used extensively by AI in follow ups and in instructions. I.e. "You recently reached out to us via [our website], is now a good time to chat about your [Hook] request?" )
• Hook (what they're interested in - also used extensively by the AI, a quick easy way to reference what the contact expressed interest in generally)
• Service Description

Source & Attribution: These are typically automatically set when a contact is created/updated from a "Lead Source" (i.e. a webhook, a form submission, a chat widget message, or a facebook lead form. If you need to you can manually edit some of these, but typically the only one you should manually change, if needed, would be "Source")

• Source (lead source identifier)
• UTM Source
• UTM Medium
• UTM Campaign
• UTM Content
• UTM Keyword
• Facebook Click ID
• Google Click ID
• Facebook Lead ID
• Referrer URL

Communication Preferences:

• Do Not Text (DND SMS)
• Do Not Call (DND Calls) — blocks AI dialing and the in-app dialer
• Do Not Email (DND Email)
• Text Incapable (for landline/non-SMS numbers - automatically added by the system if a text is attempted and our telephony provider lets us know the number is not capable of receiving SMS. If you manually add a contact with a phone number that you know is a landline, you should mark as Do Not Text to prevent the system from even attempting an SMS later).

AI & Assignment:

• Has Text AI (boolean) if enabled, the AI can respond. (either the assigned text agent, if there is one, or the default global text agent for your account)
• Has Voice AI (boolean) AI voice agents may handle this contact's calls, in either direction. On for new contacts. Edited in the "Voice AI" section of the left panel.
• Outbound Voice AI (boolean) AI voice agents may dial this contact; calls the contact places to you are unaffected. On for new contacts. Edited in the same "Voice AI" section.
• Assigned Text Agent ID
• Contact Owner ID
• Default Inbound Voice Agent (contact level voice agent assignment is in beta and may not be available in your account yet)
• Default Outbound Voice Agent (contact level voice agent assignment is in beta and may not be available in your account yet)

Organization:

• Tags (enter any text you'd like. existing tags will show up if there is a match, or you can create one on the spot)
• Custom Fields (You can have any custom field you'd like. They will show up on the contact page. To create new custom fields, you must go to Settings > Custom Fields)

Status:

• Is Active (boolean)
• Is Internal Staff (boolean - for team members)

Integration IDs:

• (these are only relevant if you have an active integration with one of these connected CRMs)
• ServiceTitan Customer ID
• ServiceTitan Location ID
• HousecallPro Customer ID
• HousecallPro Address ID

Custom Fields

You can create unlimited custom fields specific to your business needs. Custom fields support:

• Text input
• Dropdown selections
• Checkboxes
• And more
• Go to Settings > Custom Fields to create new custom fields for your account

Custom fields appear in the "General Information" section of the contact detail page.

Internal Staff Contacts

Contacts marked as Internal Staff are linked to user accounts in your brayv.ai workspace. Every team member gets one automatically when they're added to the account. These contacts:

• Display a special notice at the top of their contact page
• Let you have internal communications with your staff and see their message history (text notifications they received, escalation alerts, and so on)
• Are what internal SMS and escalation alerts send to, which is why a team member needs one with a valid mobile phone number to receive those

Protected Identity Fields

Five fields are locked on a linked contact:

First Name · Last Name · Full Name · Email · Phone

These mirror the team member's user profile, so they can only be changed in one place: Settings > Team (or Settings > Myself for your own). Update the user there and the change flows down to their contact record in every account they belong to.

Everywhere else, an attempt to write one of these is accepted, ignored, and logged:

Why This Exists

Most of the time, the testing environment for voice agents and text agents gives you all the testing you need, but sometimes users want to run 'live' tests — submitting an actual form, chatting with an agent, calling a voice agent, getting enrolled in a journey and booking an appointment. Those tests only tell you anything if they run the real path, and people naturally type throwaway details like "Test Test" or "[email protected]" while doing it.

Without this rule, one test submission would rename a team member's contact and break the internal notifications that depend on it. With it, the whole flow runs end to end (other contact fields can still be modified, e.g. street_address, service description, etc.) but their identity is left alone.

Everything else still updates for real. Address, service description, tags, custom fields, journey enrollment, appointments, opportunities, AI conversations — a live test behaves exactly like a live lead. That's the point.

Seeing What Was Ignored

Every write to a contact leaves a Contact Updated entry on the contact's activity history showing where it came from, which fields changed, and which were not applied along with the values that were submitted. So after a test you can open the contact, see "Contact Updated: Form: Free Estimate", and read exactly what came in — including the dummy name that was correctly refused.

For AI extractions, the same detail also appears in the agent's conversation or call logs.

Tips & Best Practices

Add Tags for easy sorting later

Tags make it easy to segment contacts for campaigns, filters, and reporting. Common tags include:

• Lead status (e.g., "qualified", "cold-lead", "hot-lead")
• Service interest (e.g., "hvac", "plumbing", "electrical")
• Customer type (e.g., "residential", "commercial")
• Lead source (e.g., "facebook", "referral", "website")

Always Use Hook and Friendly Source

These fields help your AI agents provide more personalized conversations:

• Hook: What specifically are they interested in? ("new roof", "AC repair", "bathroom remodel")
• Friendly Source: How did they find you in plain English? ("our Facebook ad", "Google search", "referral from John")

Assign Contact Owners

Assigning a contact owner ensures accountability and helps team members know who is responsible for each relationship. When an appointment is booked, the team member who the appointment is booked with automatically becomes the contact owner.

Keep Email and Phone Current

Having accurate contact information ensures your messages reach the right person. Add additional emails/phones if someone has multiple contact methods.

Monitor Activity History

The activity feed on the right side shows everything that's happened with a contact. Review it before reaching out to understand the full context.

Leverage Custom Fields

Create custom fields for information specific to your business:

• Project value
• Property type
• Project Description
• Equipment type
• Service address (if you need to collect a different address from the main address)
• etc. you can have as many custom fields as you need.

Use DND Appropriately

Respect customer communication preferences by setting DND flags when requested. This helps maintain compliance and customer trust.

Troubleshooting

Problem: Can't save contact - validation error

Solution: Make sure you've provided:

• At least one name (first or last)
• At least one contact method (email or phone)
• Valid email format (must include @ and domain)
• Valid phone number (Only 10 digit US / Cananda numbers are accepted)

Problem: Contact already exists

Solution: Use the merge feature to combine the duplicate contact with the existing one, or cancel and edit the existing contact instead.

Problem: Can't text a contact

Solution: Check that:

• They have a valid phone number
• "Do Not Text" is not enabled
• The phone is not marked as "Text Incapable" (landline)
• They haven't opted out at carrier level

Problem: Can't edit name, email, or phone on an internal staff contact

Solution: Those five fields (first name, last name, full name, email, phone) are synced from the linked user account. Edit the user in Settings > Team — or Settings > Myself if it's your own — and the change flows down to their contact record. See the Internal Staff Contacts section above.

Problem: I submitted a test lead as myself and the name/email didn't save

Solution: Working as intended. Your contact is linked to your user account, so identity fields are protected against exactly this — see the Internal Staff Contacts section above. Everything else on the submission did save, and the contact's activity history shows what came in and what was ignored. To test with a fake name and email, submit as a made-up person with a phone number that isn't already on a contact.

Problem: AI not responding to contact

Solution: Verify that:

• "AI Text Agent" toggle is enabled
• Contact has a valid phone number
• Contact doesn't have "Do Not Text" enabled
• Your account has an active phone number configured and A2P approved
• Check the AI Text Agent Logs (AI Agents > Text Agent Logs) for any errors.

Related Features

• Bulk Importing Contacts - Upload multiple contacts via CSV
• AI Text Agents - Automate conversations with your contacts