# Bulk Import

<br />

> Upload a CSV, create WhatsApp chats in bulk for thousands of contacts at once, and — in the same flow — schedule a first outbound message to every one of them.

> **TL;DR**
>
> * **What it is —** a full-page wizard that takes a CSV and creates **chats** (up to 5,000 per pass) → auto-selects them for a **scheduled bulk message** (up to 100,000 target chats per schedule). Different from the Contacts-module bulk dialog, which creates **contact records** without scheduling.
> * **Who it's for —** admins onboarding a new customer list and wanting a first outbound touch in the same pass.
> * **Top outcome —** new lists land in the CRM *and* get their welcome (or first) message queued — without switching to Campaigns.

## At a glance

|                    |                                                                                                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plan tier**      | All paid tiers.                                                                                                                                                                     |
| **Who can use it** | Account Owners, Admins, and Users. Practically an admin / manager workflow.                                                                                                         |
| **Channels**       | WhatsApp (Official or Unofficial) for chat creation; the schedule step supports text plus one media attachment (image, video, or PDF).                                              |
| **Integrations**   | Shares the underlying chat-create and message-schedule engines used by [Campaigns](campaigns.md) and the inbox's scheduled messages.                                                |
| **Top limits**     | 10 MB CSV · 5,000 rows per chat-create request · 100,000 target chats per schedule request · 1 – 10 retry attempts (default 3) · schedule must be at least 5 minutes in the future. |
| **API**            | Yes — partner API for bulk chat creation and bulk message scheduling.                                                                                                               |

## How to find it

**Sidebar → Bulk Import.**

**Direct URL:** `https://app.lodgestory.com/crm/bulk-import`

Related surfaces, deliberately separate:

* [Contacts → Bulk import dialog](contacts.md#bulk-import-wizard) — contact-only, no chat creation, no scheduling.
* [Campaigns → Create wizard](campaigns.md#creation-wizard) — bulk messaging against an already-created audience (chats, contacts, or CSV) with full variable mapping.
* Bulk Schedule in [Home](home-unified-inbox.md) — schedule a bulk message against **existing** chats you select from a filtered list.

Bulk Import sits in the middle: it creates chats from a CSV *and* schedules against them in the same flow.

## What is Bulk Import?

### The problem it solves

Onboarding a fresh customer list from another tool usually means two tools and three mistakes. Tool 1 to import contacts; tool 2 to create a conversation thread per contact so the inbox isn't empty; then a manual nudge ("send a welcome") per contact. Names get lost, country codes get mangled, the CSV doesn't come back with what actually imported.

Bulk Import collapses all three into one wizard:

1. Upload the CSV (10 MB, up to 5,000 rows).
2. Preview with row-level validation — valid vs invalid rows separated.
3. Pick the WhatsApp channel; hit import; the system creates chats in seconds.
4. Optionally compose a first outbound (text + media) and queue it against every just-created chat.

### What you get

* **Four-step wizard** with a visible progress indicator. Upload → Preview → Import → Schedule (or skip the schedule step).
* **Sample CSV** pre-populated with 20 rows across country codes so you don't have to reverse-engineer the columns. Required columns: `name`, `phone`. Optional: `firstname`, `lastname`, `countrycode` (defaults to `91`).
* **Row-level validation.** Phone must parse to 10 – 15 digits after stripping non-digit characters.
* **Bulk chat creation** with deduplication — contacts already on the channel are returned as *updated* rather than *created*, and their IDs come back separately.
* **Auto-selected for scheduling.** Step 4 opens with every successfully-created and -updated chat ID preselected. Deselect individuals before firing.
* **Schedule a text or a media message.** One file per schedule (image, video, or PDF). The message flows through the same engine as campaign sends — so the same per-channel throttling applies (around 600 per minute for WhatsApp Official, around 6 per minute for Unofficial by default). See [Campaigns → rate limits](campaigns.md#campaign-rate-limits--why-unofficial-is-much-slower).

### How it's different

* **Creates chats, not contact records.** The Contacts bulk dialog creates contact records with custom fields. Bulk Import creates chats in the inbox with an initial system message. Both are valid; do contacts first if you need rich custom fields on the contacts, chats here if you want new inbox threads ready to message.
* **Scheduling in the same pass.** After import, you can compose a first outbound and schedule it to every just-created chat — without switching to Campaigns.
* **Fast.** 5,000 chats land in under a second of server work.

### Customer scenarios

* **New property going live.** Operations uploads 800 past-guest phone numbers with names. 800 chats appear in the inbox (empty threads, available for agents to start). The same wizard queues *"We've just launched our direct-booking channel — reply YES for a preview of winter rates"* as a message at 4 PM the next day.
* **Lead list bought and imported for outbound.** Sales uploads 3,000 leads. Schedules the first outbound nudge in the same flow. The schedule rate automatically throttles by channel type.

### How it fits with the rest of Lodgestory

**Upstream:** a CSV from any source that has `name` and `phone`. The channel picker consumes [Connections](../settings/connections.md). **Downstream:** the just-created chats appear in [Home](home-unified-inbox.md), and replies enter the normal inbox path (or a [Bot Journey](../settings/bot-journeys.md) if assigned). The scheduled message is managed the same as a campaign — track it in [Campaigns](campaigns.md) if needed.

## Core concepts

| Term                   | What it means                                                                                                                                                           |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Wizard step**        | One of Upload, Preview, Import, Schedule.                                                                                                                               |
| **Chat row**           | One CSV row turned into a pending chat create: name, phone, country code, channel.                                                                                      |
| **Created vs updated** | *Created* chats are brand-new; *updated* means a chat on this channel with the same WhatsApp ID already existed and was refreshed. Both are preselected for scheduling. |
| **Scheduled message**  | One queued outbound per chat in the recipient list. Same engine as [Campaigns](campaigns.md).                                                                           |

## Quick Start — import plus schedule in one pass (about 6 minutes)

### Step 1 — Upload

Sidebar → **Bulk Import**. Click **Download Sample CSV** if you don't have one; otherwise drag-drop your file (10 MB max).

### Step 2 — Preview and pick the channel

The parser runs client-side. Valid and invalid rows are shown in separate tabs. Fix any invalids in your source file and re-upload. Pick the WhatsApp channel from the dropdown — only connected channels appear.

### Step 3 — Import chats

Click **Import**. The system creates the chats and returns a summary: how many were created, how many were updated, and any errors. All of them are preselected for step 4.

### Step 4 (optional) — Schedule a first message

Switch to the **Compose message** tab:

* **Campaign name** (required).
* **Text body** (required unless you attach media).
* **Attach one file** if you want (image, video, or PDF).
* **Schedule time** — must be at least 5 minutes in the future.
* **Retry attempts** — 1 to 10 (default 3).

Switch to the **Recipients** tab to deselect any chats. Click **Schedule**.

> If you don't want to send anything right now, click **Finish** — the chats stay; you can schedule later from [Campaigns](campaigns.md) or the Bulk Schedule in Home.

## How it works

When you import a CSV, Lodgestory:

1. Parses and validates the file client-side (phone, country code, required name).
2. On **Import**, creates chats for valid rows in batches, de-duplicating against the channel's existing WhatsApp IDs.
3. Returns lists of created and updated chat IDs, plus any validation errors.

When you schedule a bulk message, Lodgestory:

1. Writes one queued message per recipient in the schedule table.
2. At the scheduled time, the same engine that powers campaigns releases messages at the channel's rate cap.

Replies to the sent messages arrive in [Home](home-unified-inbox.md) like any other inbound message.

## Features in depth

### Step 1 — Upload

* **Drag-drop or picker.** 10 MB cap.
* **Sample CSV** pre-filled with 20 realistic rows across country codes.
* **Required columns:** `name`, `phone`. Case-insensitive header matching. Optional: `firstname`, `lastname`, `countrycode` (defaults to `91`).

### Step 2 — Preview

* Row-level validation:
  * Phone must be 10 – 15 digits after stripping non-digits.
  * Invalid rows go to the Invalid tab with a reason.
* Channel picker populated from your organisation's connected WhatsApp channels.
* Searchable table — filter visible rows by name or phone.
* No column mapping step; header names must match the supported set.

### Step 3 — Bulk create chats

* Sends every valid row to the bulk chat-creation endpoint.
* Response summary: counts of created and updated, a list of validation errors, and a duplicates-skipped count.
* Auto-selects **both created and updated** chats for scheduling — either way, this chat is "fresh enough" to receive the intended first outbound.

### Step 4 — Schedule

* Two tabs: **Compose message** and **Recipients**.
* Compose:
  * Campaign name (required).
  * Text (required unless media attached).
  * One file — image, video, or PDF — with automatic type detection.
  * Schedule time must be at least 5 minutes in the future.
  * Retry attempts 1 – 10; default 3.
* Recipients:
  * Preselected with every created and updated ID.
  * Deselect individuals if needed.
* **Schedule** queues the messages; the send engine takes it from there.

### Success screen

Buttons: **Start new import** (reset the wizard) and **Open Chat Manager** (go to Home). The scheduled message starts firing at the send time; track progress in [Campaigns](campaigns.md) or in the chat's **Scheduled messages** list in the Home guest-details panel.

## Roles and permissions

| Action                  | Account Owner | Admin | User |
| ----------------------- | :-----------: | :---: | :--: |
| Open Bulk Import        |       ✓       |   ✓   |   ✓  |
| Bulk-create chats       |       ✓       |   ✓   |   ✓  |
| Schedule a bulk message |       ✓       |   ✓   |   ✓  |

In practice this is an admin workflow — gated by UI exposure and typical operating procedure.

## Cross-module workflows

### New property → seeded inbox → welcome message

Operations uploads 800 past guests → chats appear in the inbox → the same wizard schedules a welcome message for 4 PM the next day → replies arrive in the inbox over the following hours → assigned agents pick up the interested responses → any complex ones are escalated to tickets.

**Modules involved:** Bulk Import → Home → Bot Journeys (if assigned) → Tickets.

### Lead list → outbound drip

Sales uploads 3,000 leads → schedules a first outbound via the wizard → the send engine paces the broadcast over several hours (on Unofficial, several days) → replies route to a bot journey that classifies intent → sales works the *interested* queue.

**Modules involved:** Bulk Import → Home → Bot Journeys → Tickets / Campaigns.

## Limits a user will run into

| Limit                                | Value                          |
| ------------------------------------ | ------------------------------ |
| CSV max size                         | 10 MB                          |
| Max rows per chat-create             | 5,000                          |
| Max chats per schedule request       | 100,000                        |
| Retry attempts on scheduled messages | 1 – 10 (default 3)             |
| Minimum schedule time                | Now + 5 minutes                |
| Phone digits                         | 10 – 15                        |
| Country code                         | 1 – 4 digits; defaults to `91` |

## Errors & FAQ

### Error reference

| Where  | Message                                        | Cause                             | Fix                                                     |
| ------ | ---------------------------------------------- | --------------------------------- | ------------------------------------------------------- |
| Step 1 | *CSV file is empty*                            | No rows                           | Add rows                                                |
| Step 1 | *Missing required columns*                     | Required headers missing          | Use the sample CSV as a template; rename columns        |
| Step 1 | *Failed to parse CSV*                          | Malformed CSV (encoding, quoting) | Re-export as UTF-8 with standard quoting                |
| Step 1 | *Failed to read file*                          | Browser read error                | Retry                                                   |
| Step 2 | *Please select a channel to import chats into* | No channel picked                 | Pick a connected channel                                |
| Step 2 | *No valid chats to import*                     | All rows failed validation        | Fix the Invalid tab's rows and re-upload                |
| Step 3 | *Failed to import chats*                       | Server rejected the batch         | Keep under 5,000 rows; ensure phones are 10 – 15 digits |
| Step 4 | *Please select at least one chat*              | No recipients                     | Select recipients                                       |
| Step 4 | *Please enter a campaign name*                 | Missing name                      | Fill the name                                           |
| Step 4 | *Please enter message text or attach media*    | Empty payload                     | Add text or a file                                      |
| Step 4 | *Please select a schedule date and time*       | Empty schedule                    | Pick a datetime                                         |
| Step 4 | *Schedule time must be in the future*          | Past or too soon                  | Pick a later time (at least +5 minutes)                 |
| Step 4 | *Failed to schedule message*                   | Server validation                 | Read the error message; fix and retry                   |

### Frequently asked

**Why don't my contacts appear in the Contacts list after the import?**
Bulk Import creates chats, not contact records. Use the [Contacts bulk-import dialog](contacts.md#bulk-import-wizard) if you want to hydrate the contact database. You can do both — contacts first, then chats — if you need rich custom fields on the contacts.

**What's the difference between *created* and *updated*?**
A chat whose WhatsApp ID (country code + phone) already exists on the selected channel is *updated* — its existing record is refreshed. *Created* chats are brand-new. Both are preselected for the schedule step.

**Can I import more than 5,000 chats at once?**
Split the CSV and run the wizard multiple times. Each pass hits the cap independently.

**Can I use WhatsApp templates in the schedule step?**
The wizard supports text and media only. For templates, use the [Campaigns creation wizard](campaigns.md#creation-wizard) with the same audience.

**What happens to the scheduled message if an imported chat has no contact record linked?**
The message still goes out. Chats are addressable by their WhatsApp ID without requiring a contact link. Replies will lazily create the contact linkage during the normal inbound ingest.

## Related modules & next steps

* [Contacts → Bulk import dialog](contacts.md#bulk-import-wizard) — for contact records rather than chats.
* [Campaigns](campaigns.md) — template broadcasts and full variable mapping.
* [Home (Unified Inbox)](home-unified-inbox.md) — where the imported chats land and replies arrive.
* [Connections](../settings/connections.md) — prerequisite for the channel picker.
* [Bot Journeys](../settings/bot-journeys.md) — auto-handle replies on the newly created chats.

<br />