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
• 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
• Emails
• Notes
• Appointments
• Status changes
• Journey enrollments
• Form submissions

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: To mark that the contact has asked not to be called
• 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.

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)
• 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) (beta feature, may not yet be available in your acount)
• 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. These contacts:

• Cannot have their name or email edited (synced from user account - name, email, etc can be edited from Settings > Team)
• Display a special notice at the top of their contact page
• Contact records for internal team members allow you to have internal communications with your staff, see message history (i.e. text notifications they received, etc.)

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 or email on internal staff contact

Solution: Internal staff contacts are synced with user accounts. Edit the user's information in the Team Settings instead.

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