Contact Management Feature¶

Overview¶

Contact Management (/contacts) is the core CRM feature of ConnectGain, providing comprehensive contact database management with advanced search, filtering, tagging, custom fields, and integration with deals, conversations, and tasks. It enables businesses to organize, segment, and manage customer relationships effectively.

The contact list, with search, filters and bulk actions.

On this page: Features · Use Cases · Test Cases · API Integration · Best Practices · Troubleshooting

Features¶

1. Contact Management¶

Create Contacts: - Add new contacts manually with: - First name, last name - Multiple phone numbers - Multiple email addresses - Company association - Tags - Custom fields - Opt-in status - Notes - Create deal option during contact creation

Marketing Opt-in

New contacts start opted in, so a contact you add by hand can receive campaigns straight away. Untick the opt-in switch while adding or editing someone if they have asked not to hear from you.

A contact who is opted out is left out of every broadcast audience — including All Contacts and tag targeting — and does not appear in the contact picker while you are building a campaign. So if a campaign's recipient count is lower than the number of contacts you expect, opt-outs are the first thing to check.

People are also opted out automatically when they use an unsubscribe link, reply to stop receiving messages, or their email address bounces. You can set it for many contacts at once from Bulk Actions.

Edit Contacts: - Update contact information - Modify all contact fields - Update relationships

Delete Contacts: - Remove contacts (with cascade protection) - Bulk delete operations

Bulk Operations: - Bulk import from CSV - Bulk export to CSV - Bulk delete - Bulk merge - Bulk marketing opt-in / opt-out - Bulk add / remove tags

Contact Details View: - Comprehensive contact profile - All contact information - Communication history - Related deals - Related tasks - Notes timeline - Activity log

2. Search & Filtering¶

Advanced Search: - Search by: - Name (first, last, full) - Phone number (partial matching) - Email address - Company name - Tags - Custom fields - Real-time search results

Tag Filtering: - Filter by contact tags - All tags dropdown - Multiple tag selection

Additional Info Filtering: - Open Additional Info next to the tag and source filters - Type the name of the field (for example role, level or current company) and the text it must contain, then choose Add filter; the field name suggestions come from your own contacts - Add as many filters as you need: a contact must match all of them, together with any tag and source filters you have chosen - Remove a single filter with its ×, or use Clear all - "Select all" and bulk actions apply to exactly the contacts the filters show

Open-deal counts appear as badges on contacts for reference; they are not a filter option.

Sorting Options: - Alphabetical (A-Z, Z-A) - Newest added (newest first, oldest first)

3. View Modes¶

Grid View (default): - Card-based layout - Contact cards with key info - Quick action buttons - Visual tags - Company badges

Table View: - Spreadsheet-style layout - Bulk selection - Inline actions - Export capabilities

(Only Grid and Table views exist. On mobile, Grid is used.)

4. Contact Organization¶

Tags System: - Flexible tagging - Create custom tags - Multiple tags per contact - Tag-based filtering - Auto-tagging by country - Tag management

Lists (contacts grouped by tag): - Open Lists to see every tag with its number of contacts, then choose a tag to see the contacts that carry it - Select a contact's name in the list to open that contact's card, with its details, Additional Info, files and activity, without leaving the list - Changes you make on the card (for example editing tags) are reflected in the list when you close it

Company Association: - Link contacts to companies - Company selection - Company creation from contact - Company details view

Custom Fields: - Extend contact data - Text fields - Number fields - Date fields - Dropdown fields

Social profiles — every field is optional, and you can fill in as few as you like:

Field	Accepts
LinkedIn	a profile URL, or just the handle (`jane-doe`)
Telegram	the username, with or without the leading `@`
WhatsApp username	3–30 characters starting with a letter, then letters, digits, `.` or `_`
TikTok	the username
Facebook	a profile URL, or the handle
Instagram	the username

Facebook and Instagram handles are reference notes. Those two channels do not attach a contact to a conversation, so filling these in does not link a thread to this contact — it just records where to find them.

WhatsApp usernames are the one entry here that also helps route messages, so a username already used by another contact in your organization is rejected when you save. Change it on the other contact first.

Lifetime value is shown on the contact and is calculated for you — it is the total of that contact's closed-won deals. It is not a field you type in, so it can never fall out of step with the deals behind it. Deals in different currencies are listed separately rather than added together, because there is no exchange rate to convert between them. Note this differs from the total on the Deals tab, which counts every deal whatever its outcome.

If your pipeline uses a custom won stage (for example "Won — Renewal"), those deals are not counted. Only the standard closed-won stages are.

A note on channel IDs. Contacts connected to Telegram, LinkedIn, TikTok or WhatsApp also carry hidden channel identifiers. These are how incoming messages find the right contact and where replies are sent, so they are not editable — the social profile fields above are the ones to fill in.

6. Custom Fields¶

Field Types: - Text - Number - Date - Boolean - Dropdown - Multi-select

Use Cases: - Store industry-specific data - Track custom attributes - Integration with external systems

On the contact card: every field appears under Additional Info. Any web address in a value (a LinkedIn profile, a Drive link) is a clickable link that opens in a new tab, and values that hold several items read as plain text. Use the Additional Info filter on the contact list to find contacts by these values.

7. Contact Import¶

CSV Import: - Bulk import contacts - Column mapping - Data validation - Duplicate detection - Import progress tracking - Error reporting

HubSpot Import: - CSV import using a HubSpot-export column mapping (no direct HubSpot API/OAuth connection; routed through the standard import-contacts function)

Duplicate Detection: - Find and merge duplicates - Automatic duplicate detection - Manual merge options - Merge conflict resolution

8. Contact Actions¶

Quick Actions: - View contact details - Edit contact - Delete contact - Send message - Make phone call - Open WhatsApp - Copy phone number - Copy email address

Opening a contact from a link or notification: - A link to a contact, such as a contact notification, opens that contact's details straight away, even if the contact is not on the page of the list you are looking at - If the contact was deleted, or you do not have access to it, a message says so

Bulk Actions: - Export selected contacts - Delete selected contacts - Merge selected contacts - Add / remove tags on selected contacts - Set marketing opt-in / opt-out

9. Contact Analytics¶

Deal Count: - Number of open deals per contact

Notes Count: - Number of notes per contact

Activity Timeline: - Recent activity tracking

Engagement Metrics: - Message frequency - Last contact date

10. Pagination¶

50 Contacts Per Page: - Efficient loading - Page navigation - Total count display

11. Auto-Tagging¶

Country-Based Tagging: - Automatically tag contacts by country - Phone number analysis - Country code detection - Batch processing - Progress tracking - Completion notifications

12. Call Tracking¶

Call Features: - Initiate calls from contact card - Initiate calls from contact details - Call event tracking - Call history per contact - Call status tracking (INITIATED, CONNECTED, COMPLETED, MISSED, FAILED) - Call duration tracking - Call notes - Link calls to conversations

Call Actions: - Click phone icon to initiate call - Opens device phone dialer - Automatically records call event - Tracks call status and duration - Add call notes after completion

13. Contact Relationships¶

Relationships: - Company association - Deal association - Conversation association - Task association - Note association

14. Contact Assignment¶

Assignment Features: - Assign a contact to a team member via the contact form ("Assign To") - Reassign by editing the contact

15. Files & Photo¶

Files: - Open a contact and find the Attachments section on its card - Upload one or more files (for example a CV or a signed form) by choosing Upload Files or dragging them in - Preview, download or delete a file from its row - Files are private to your workspace. Anyone on your team can see and add files; a file can be deleted by the person who uploaded it or by an owner or admin

Photo: - When a contact has a profile photo, it appears on the contact card and at the top of the contact's details; otherwise the contact's initials are shown

Use Cases¶

Use Case 1: Import Existing Customer Database¶

Scenario: Company wants to migrate 5,000 contacts from Excel to ConnectGain.

Steps: 1. Export contacts from Excel to CSV 2. Go to Contacts → Import 3. Upload CSV file 4. Map CSV columns to ConnectGain fields 5. Review import preview 6. Configure duplicate handling 7. Start import 8. Review import results 9. Fix any errors 10. Verify imported contacts

Expected Outcome: All contacts imported successfully with proper field mapping.

Use Case 2: Find Contact by Phone Number¶

Scenario: Customer calls, agent needs to find contact quickly.

Steps: 1. Go to Contacts 2. Enter phone number in search 3. View search results 4. Click on matching contact 5. View contact details and history

Expected Outcome: Contact found instantly with full history visible.

Use Case 3: Tag Contacts for Campaign¶

Scenario: Marketing wants to send campaign to "VIP Customers" only.

Steps: 1. Go to Contacts 2. Filter contacts by criteria (e.g., deals > $10,000) 3. Select all filtered contacts 4. Add tag "VIP Customer" 5. Go to Broadcast (/broadcast) 6. Create a campaign targeting the "VIP Customer" tag 7. Send campaign

Expected Outcome: Campaign sent only to VIP customers.

Use Case 4: Merge Duplicate Contacts¶

Scenario: System has duplicate contacts that need merging.

Steps: 1. Go to Contacts → Find Duplicates 2. Review duplicate suggestions 3. Select contacts to merge 4. Choose primary contact 5. Review merged data 6. Confirm merge 7. Verify merged contact

Expected Outcome: Duplicates merged into single contact with all data preserved.

Use Case 5: Assign Contacts to Sales Team¶

Scenario: Sales manager wants to distribute contacts evenly among team.

Steps: 1. Go to Contacts 2. Filter contacts (e.g., no assignee, tag "Lead") 3. Select contacts to assign 4. Click "Assign" 5. Select team member 6. Confirm assignment 7. Verify assignments

Expected Outcome: Contacts distributed evenly among sales team.

Test Cases¶

Test Case 1: Create Contact¶

Test: Verify contact creation

Steps: 1. Go to Contacts 2. Click "New Contact" 3. Fill in required fields: - First Name: "John" - Last Name: "Doe" - Phone: "+1234567890" - Email: "john@example.com" 4. Add optional fields: - Company: "Acme Inc" - Tags: ["Customer", "VIP"] - Custom Fields: { "Industry": "Technology" } 5. Click "Save" 6. Verify contact appears in list 7. Open contact details 8. Verify all data saved correctly

Expected Result: Contact created successfully with all data preserved

Test Case 2: Search Contact by Name¶

Test: Verify name search functionality

Steps: 1. Create test contact: "John Doe" 2. Go to Contacts 3. Enter "John" in search 4. Verify contact appears in results 5. Enter "Doe" in search 6. Verify contact appears 7. Enter "John Doe" in search 8. Verify contact appears 9. Enter "Doe John" in search 10. Verify contact appears (reversed name)

Expected Result: Contact found by first name, last name, full name, and reversed name

Test Case 3: Search Contact by Phone¶

Test: Verify phone number search

Steps: 1. Create contact with phone: "+1234567890" 2. Search for "1234567890" 3. Verify contact found 4. Search for "234567890" 5. Verify contact found (partial match) 6. Search for "+1-234-567-890" 7. Verify contact found (formatted number)

Expected Result: Contact found by full phone, partial phone, and formatted phone

Test Case 4: Bulk Import Contacts¶

Test: Verify CSV import functionality

Steps: 1. Create CSV file with 100 contacts 2. Go to Contacts → Import 3. Upload CSV file 4. Map columns: - First Name → first_name - Last Name → last_name - Email → emails - Phone → phones 5. Review preview 6. Start import 7. Wait for import completion 8. Verify import results: - Success count: 100 - Error count: 0 9. Verify contacts in list 10. Check imported data accuracy

Expected Result: All contacts imported successfully with correct data mapping

Test Case 5: Update Contact¶

Test: Verify contact update functionality

Steps: 1. Create contact 2. Open contact details 3. Click "Edit" 4. Update fields: - Change first name - Add phone number - Add tag - Update custom field 5. Save changes 6. Verify updates reflected 7. Check updated_at timestamp

Expected Result: Contact updated successfully with all changes preserved

Test Case 6: Delete Contact¶

Test: Verify contact deletion

Steps: 1. Create contact 2. Create related conversation 3. Create related deal 4. Create related task 5. Delete contact 6. Verify contact deleted 7. Verify cascade deletion: - Conversation deleted - Deal deleted - Task deleted

Expected Result: Contact and all related data deleted (cascade)

Test Case 7: Tag Management¶

Test: Verify tagging functionality

Steps: 1. Create contact 2. Add tag "Customer" 3. Add tag "VIP" 4. Verify tags displayed 5. Remove tag "Customer" 6. Verify tag removed 7. Filter contacts by tag "VIP" 8. Verify contact appears in filtered list 9. Bulk tag multiple contacts 10. Verify all contacts tagged

Expected Result: Tag management works correctly for single and bulk operations

Test Case 8: Custom Fields¶

Test: Verify custom fields functionality

Steps: 1. Go to Contacts 2. Edit a contact 3. Add a custom field (e.g. "Industry" = "Technology") 4. Save contact 5. Verify custom field saved 6. Reopen the contact and verify the custom field persists

Expected Result: Custom fields can be added to a contact and saved

Test Case 9: Contact Assignment¶

Test: Verify contact assignment

Steps: 1. Create contact 2. Verify no assignee 3. Assign to user "John Smith" 4. Verify assignee set 5. Filter contacts by assignee 6. Verify contact appears 7. Reassign to "Jane Doe" 8. Verify assignee updated 9. Bulk assign multiple contacts 10. Verify all contacts assigned

Expected Result: Contact assignment works for single and bulk operations

Test Case 10: Duplicate Detection¶

Test: Verify duplicate detection and merging

Steps: 1. Create contact: "John Doe", "+1234567890" 2. Create duplicate contact: "John Doe", "+1234567890" 3. Go to Contacts → Find Duplicates 4. Verify duplicates detected 5. Select both contacts 6. Choose primary contact 7. Merge contacts 8. Verify merged contact has all data 9. Verify duplicate contact deleted

Expected Result: Duplicates detected and merged correctly

Test Case 11: Contact Views¶

Test: Verify different view modes

Steps: 1. Go to Contacts 2. Switch to Grid view 3. Verify cards displayed 4. Switch to Table view 5. Verify table displayed 6. Test sorting in table view 7. Test filtering in both views 8. Verify data consistency

Expected Result: All view modes work correctly with consistent data

Test Case 12: Contact Export¶

Test: Verify contact export

Steps: 1. Create 10 test contacts 2. Go to Contacts 3. Click "Export" 4. Select export format: CSV 5. Select fields to export 6. Download file 7. Open CSV file 8. Verify all contacts exported 9. Verify data accuracy

Expected Result: Contacts exported correctly with accurate data

API Integration¶

Create Contact¶

Endpoint: POST /functions/v1/rest-api-proxy/contacts

Request:

{
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+15550100001"],
 "emails": ["john@example.com"],
 "tags": ["customer", "vip"],
 "custom_fields": {
 "industry": "Technology"
 }
}

For contacts that should also open a deal, use the Contacts & Deals API (create-lead) instead.

Search Contacts¶

Endpoint: POST /functions/v1/search-contacts

Request:

{
 "searchTerm": "John",
 "tags": ["customer"],
 "dealStatus": "open"
}

Bulk Import¶

Import a CSV from Contacts → Import in the app, or push records in bulk through the Contacts & Deals API.

Best Practices¶

Data Quality
Use consistent phone number format
Validate email addresses
Keep names standardized
Use tags consistently
Organization
Use tags for categorization
Assign contacts to team members
Link contacts to companies
Keep custom fields organized
Import
Clean data before import
Map fields carefully
Review preview before importing
Handle duplicates appropriately
Search
Use specific search terms
Combine filters for precision
Save frequently used searches
Use tags for quick filtering
Maintenance
Regular duplicate cleanup
Update contact information
Archive inactive contacts
Review and update tags

Troubleshooting¶

Import Errors¶

Issue: Contacts not importing

Solutions: - Check CSV format - Verify field mapping - Check data validation errors - Review import logs

Search Not Finding Contacts¶

Issue: Known contacts not appearing in search

Solutions: - Check search term spelling - Verify phone number format - Check organization filter - Try different search terms

Duplicate Contacts¶

Issue: Multiple entries for same contact

Solutions: - Use duplicate detection tool - Merge duplicates - Standardize import process - Use unique identifiers

More screens¶

A contact timeline: every message, deal and task in one history.

Saved lists for segmenting contacts.

ConnectGain — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. Open the app · Docs home

Contact Management Feature¶

Overview¶

Features¶

1. Contact Management¶

2. Search & Filtering¶

3. View Modes¶

4. Contact Organization¶

5. Social Profiles & Lifetime Value¶

6. Custom Fields¶

7. Contact Import¶

8. Contact Actions¶

9. Contact Analytics¶

10. Pagination¶

11. Auto-Tagging¶

12. Call Tracking¶

13. Contact Relationships¶

14. Contact Assignment¶

15. Files & Photo¶

Use Cases¶

Use Case 1: Import Existing Customer Database¶

Use Case 2: Find Contact by Phone Number¶

Use Case 3: Tag Contacts for Campaign¶

Use Case 4: Merge Duplicate Contacts¶

Use Case 5: Assign Contacts to Sales Team¶

Test Cases¶

Test Case 1: Create Contact¶

Test Case 2: Search Contact by Name¶

Test Case 3: Search Contact by Phone¶

Test Case 4: Bulk Import Contacts¶

Test Case 5: Update Contact¶

Test Case 6: Delete Contact¶

Test Case 7: Tag Management¶

Test Case 8: Custom Fields¶

Test Case 9: Contact Assignment¶

Test Case 10: Duplicate Detection¶

Test Case 11: Contact Views¶

Test Case 12: Contact Export¶

API Integration¶

Create Contact¶

Search Contacts¶

Bulk Import¶

Best Practices¶

Troubleshooting¶

Import Errors¶

Search Not Finding Contacts¶

Duplicate Contacts¶

See also¶

More screens¶