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 contacts. Add Contact Individual Pn

​
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.
Create Contact Save Pn

​
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.
Contact Details Pn

​
Import Contacts in Bulk via CSV

​
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: Use our sample contact import .csv template here.

​
1. Go to Contacts → Import Contacts

Click Import Contacts (top-right). Clean Shot2025 08 26at12 14 33 Pn

​
2. Select your CSV

Pick your .csv file from your computer.
File picker accepts CSV only.
CleanShot 2025-08-26 at 12.16.41.png

​
3. Map columns to MessageDesk fields

Fields auto-map when names match. You can adjust mapping and include custom properties. Clean Shot2025 08 26at12 17 54 Pn

​
4. Fix duplicates & errors (preview step)

MessageDesk validates your data and flags issues before import. Invalid rows are skipped. Clean Shot2025 08 26at12 18 42 Pn

​
Validation rules (what we check)

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

​
How imports run (under the hood)

  • Batching: processed in batches up to 5,000 (aligned with the row limit).
  • Async processing: large uploads are staged and processed server-side for reliability.
  • CSV only: the importer accepts .csv; 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 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 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.