Skip to main content

​
Add Individual Contacts One-by-One, or Import Many via CSV

You can quickly create a single contact or bring in thousands at once with a CSV—here’s exactly how (and the limits to avoid errors).

​
Add an Individual Contact

​
1. Go to Contacts

Click + Add Contact.
Contacts Add Contact

​
2. Enter details

Add First name, Last name, and Phone, then click + Create Contact.
First name, last name, and phone number are required when creating contacts. Phone numbers without names are treated as anonymous contacts until you add contact details later.
If the phone number already belongs to another contact, you’ll see an error. Phone numbers are unique identifiers in MessageDesk (one number → one contact). A single contact can have multiple numbers.
Contacts Create Contact

​
3. View & edit the contact

From the contact panel, you can:
  1. Add additional phone numbers.
  2. Copy the contact’s number.
  3. Send a message from the Inbox.
  4. Unlink (“delete”) a number from the profile.
  5. Block the contact from messaging your workspace.
Changing a contact’s primary phone may unlink past conversations from the profile.
Contacts Detail

​
Delete a contact

To permanently remove a contact from your workspace:
  1. Go to Contacts.
  2. Find and select the contact(s) you want to delete.
  3. Click the trash can icon to delete the contact.
  4. Confirm the deletion when prompted.
Deleting a contact is permanent and cannot be undone. The contact’s conversation history will be preserved, but will appear as an anonymous contact.
Contacts Delete 1

​
Filter Contacts

The contacts module makes it easy to filter contacts based on their properties saved in MessageDesk. You can use Criteria and Conditions to create various types of filters.
Contacts Create Filter

​
Add Criteria

Criteria are a set of conditions. You can add as many criteria as you like to a filter. As you add criteria, you’ll see a filter preview. Criteria work in two ways: creating AND and OR statements.
  • Selecting Match All (AND) means all criteria must meet the filter’s conditions.
  • Selecting Match ANY (OR) means any criteria must meet the filter’s conditions.

​
Add Conditions

Conditions are based on data fields saved and populated as part of the contact’s profile in MessageDesk. You set your filter on conditions on standard fields like:
  • First Name
  • Last Name
  • Last Outbound Message Time
  • Last Inbound Message Time
You can also set filter conditions based on custom properties added to MessageDesk.

​
Condition Operators

Use Condition Operators to create logical expressions for your filters. The types of condition operators available will depend on the field’s data type (true/false, dropdown, date, number, phone, and text).

​
Available Condition Operators:

  • Contains
  • Equals
  • In
  • Is Empty
  • > (greater than)
  • >= (greater than or equal to)
  • < (less than)
  • <= (less than or equal to)
  • NOT Contains (does not contain)
  • NOT Equals (does not equal)
Once you’re satisfied with your filter, click Apply Filter to view a list of contacts matching your filter conditions and criteria.
**Coming Soon: **You’ll soon be able to save filters within the contacts module after creating them. This will make it easy to access pre-saved lists of contacts for faster messaging.

​
Import Contacts in Bulk via CSV

MessageDesk makes it easy to upload contact lists in bulk. This is a handy feature if you have a large amount of contact information that needs to live in MessageDesk.

​
CSV limits & requirements (read first)

TL;DR
  • Row count: up to 5,000 rows per CSV (hard limit)
  • File size: up to 10 MB
  • Platform: Web-only (imports aren’t supported on mobile/desktop apps)
  • Format: must use .csv files with a header row, UTF-8 encoding
  • Required per row: Email or Phone (at least one)
Your CSV must:
  • Include a header row (first line in .csv file).
  • Use consistent columns on every row (same number of columns as the header).
  • Include at least one contact method: Email or Phone per row.
  • Preferred: Use E.164 format for phone number formatting (e.g., +15551234567).
Download: Make a copy of our sample contact import .csv template here.

​
1. Go to Contacts → Import Contacts

Click Import Contacts.
Note: You can also access the contact import feature from Settings → Workspace Settings → Data Center
Contacts Import

​
2. Select your .CSV

Select a .csv file from your computer or make a copy of our shared Google Sheet (MessageDesk Contact Import Template)
Note: The file picker only accepts .CSV type files.
Contacts Import Dialog

​
3. Identify contacts by mapping properties in MessageDesk to columns in your file

You can adjust the field mapping manually, but in most cases, fields will auto-map when column names match properties in MessageDesk. Click + Add Custom Property to map custom properties from your .csv file to custom properties in MessageDesk.
Note: Email or Phone is a required property for every contact uploaded to MessageDesk.
Contacts Identify

​
4. Fix duplicates & errors (preview step)

Click Preview Import to confirm that your fields are properly matched. MessageDesk validates your data and flags issues before import. Invalid rows are skipped. Clean Shot2025 08 26at12 18 42 Pn

​
Validation rules and what we check

  • Email: must be a valid email address (name@example.com).
  • Phone: must be in E.164 format (e.g., +15551234567).
  • Custom properties: must match defined types and constraints.
  • Duplicates: checked by email and phone to prevent dupes.

​
How imports run

  • Batching: processed in batches up to 5,000 (aligned with the row limit).
  • Async processing: large uploads are staged and processed on the server for reliability.
  • CSV only: the importer accepts .csv files; other formats aren’t supported.

​
Common Errors & Fixes

  • “CSV file is too large.”
    Split your file so each CSV has ≤ 5,000 rows and ≤ 10 MB.
  • “CSV imports are only supported on the desktop web platform. Please use the web interface for importing contacts.”
    Switch to the web app to run the import.
  • “Invalid phone format.”
    Convert to E.164 (country code + number, no spaces).
  • “Invalid email address.”
    Correct typos or remove invalid emails.
  • “Row has an inconsistent number of columns.”
    Ensure every row matches the header’s column count.
  • “Missing contact method.”
    Add Email or Phone for that row.

​
Best practices

  • Normalize phones to E.164 before uploading.
  • Deduplicate by email/phone first to avoid partial merges.
  • Test with 25 rows to confirm mapping and validation.
  • Use custom properties intentionally—ensure data types match your definitions.
  • Keep under limits (≤ 5,000 rows, ≤ 10 MB) for smooth importing.

​
FAQ

Can I import from my phone or desktop app?
No. CSV imports are web-only. Can I import other data (conversations, labels, messages, opt-outs)?
Yes. You can import messages via the Data Center. This doc covers Contacts CSV. What happens to skipped rows?
Invalid rows are skipped. Fix the CSV and re-import those rows separately. Can I update existing contacts?
By default, CSV imports will not overwrite existing contacts. Contacts are deduplicated by phone number, and duplicates are flagged rather than updated. To update existing contacts (e.g., fix a misspelled name or update contact details), you need to use the import flow that supports updates.