Importing contacts¶
Requires the "Databases" permission.
With the import you load into a database a list of new contacts from an Excel or CSV file. You open it from the Databases page with the Import contacts button. To update the data of contacts already present, use Correct database instead.
The wizard has two steps plus a final confirmation, shown at the top: 1. Fields → 2. File → 3. Confirm.
Before you start: prepare the file¶
| Requirement | Detail |
|---|---|
| Format | Excel .xlsx or .xls (the old Excel 97-2003 format), or CSV |
| Size | At most 26 MB (the limit is shown next to the file choice) |
| Phone | Every row must have at least one phone number. A row without a phone is discarded as an error |
| Headers | A first row with the column names is recommended (e.g. "Company name", "Phone", "City"): Thelgo uses it to propose the field matching automatically |
| CSV | UTF-8 encoding, comma or semicolon separator (recognized automatically) |
| Excel sheets | If the file has several sheets, you choose one during the import. One sheet is imported at a time. A file with a single sheet is read directly, without asking which to choose |
Opposition Register
The import does not check numbers against the Public Opposition Register and does not check whether a number has asked not to be called in another database. The check against the Register is done afterwards, per campaign, by extracting and re-importing the RPO list: it applies to databases created as RPO databases (see Public Opposition Register (RPO)).
Step 1: Fields¶
In this step you choose where to import and see which fields you will be able to load the file's columns onto.
- In Destination database choose the database. To create a new one press + New, write the name and press Create.
- If the database is already used by some campaign, Add contacts to campaigns already created (respecting the filters set) appears (see below). Once the database is chosen, this option lists the campaigns that use it with their filters.
- In Dynamic fields schema choose the schema with the extra fields you need, or No schema. With + New schema you go to the Dynamic database fields page to create one. After saving the new schema you automatically return to the import, with the database you had already chosen and the new schema already selected.
- Check the Preview of available fields: on the left the Standard fields, on the right the Dynamic (selected schema) ones. These are the fields onto which you will be able to map the columns in the next step. If the database is an RPO database, among the phones you only find Phone 1.
- Press Next.
The dynamic fields schema¶
- If the database already has a schema, the choice is locked and "The selected database already uses the schema "…": it cannot be changed." appears. All the contacts of a database share the same schema. From step 1 you cannot change it even if the database is still empty: to choose another schema, or none, on an empty database use Edit database on the Databases page and then return to the import.
- If the database does not have a schema yet and only one schema exists, Thelgo proposes it already selected.
- The chosen schema is linked to the database when you confirm the field matching in step 2, and from then on it stays fixed: with contacts imported, the database no longer allows changing the schema.
Adding contacts to existing campaigns¶
Normally imported contacts stay only in the database: campaigns already created do not receive them automatically. If you want them to enter one or more campaigns right away:
- Tick Add contacts to campaigns already created (respecting the filters set).
- The list of the database's campaigns (in any status) appears, all already ticked. Under each campaign you see its filters (e.g. "CAP: 10100, 10121 · Comune: Torino") or "No filter (whole database)".
- Untick the campaigns to exclude, or use All to select or deselect them all.
Each campaign receives only the newly imported contacts that meet all its filters. Contacts already in the database are not touched. If the campaign has active contact blocks, the new contacts that meet them enter the campaign already blocked. After the insertion, Thelgo starts an Ordering recalculation for each campaign that received contacts, so that the newcomers find their place according to the campaign's ordering: you see it in Operations together with the import.
If the database is an RPO database, the contacts enter the campaign blocked for RPO until the next import of that campaign's RPO list (see Public Opposition Register (RPO)).
You can also add contacts to a campaign later, from the campaign itself (see Campaign contacts).
Step 2: File¶
Uploading the file¶
- Import type: it is not a command but an indication. It shows Standard or Do-Not-Call Registry depending on how you created the destination database ("Set when the database was created (Phone1 only allowed), cannot be changed from here."). The validated RPO list, with the Register's reply, is not imported from here but from the page of each campaign (see Public Opposition Register (RPO)).
- In Excel or CSV file choose the file.
- Press Next. A bar shows the upload progress.
- If the Excel file has several sheets, "The file contains multiple sheets: choose which one to import" appears: click the name of the sheet. With a single sheet (or with a CSV) this step is skipped.
Do not leave the wizard half-done for too long
The uploaded file stays available for 30 minutes. If you wait longer, at confirmation a red warning appears at the bottom, "The import session has expired or was not found. Upload the file again.", and you have to start over.
Field matching¶
Thelgo shows one row for each column of the file: on the left the column name (the content of the file's first row), on the right the Thelgo field to load it into. The message "For each column in the file, choose the matching Thelgo field. Mapping at least one Phone field (*) is required." appears above. The Field mapping section also has the Options below: Skip first row and Check leading zero.
- Thelgo proposes the matching on its own when it recognizes the column name, even with different common names (the Italian column names it knows): for example "Tel", "Cellulare" or "Telefono" go to Phone 1, "Città" to City, "Azienda" to Company name, "Via" to Address, "Sito" to Website. The proposals concern the standard fields: the columns of dynamic fields must be matched by hand. Always check the proposals.
- A column left on Don't import is not imported.
- Each field can be used only once: a field already matched to another column appears disabled.
- You must match at least one column to a Phone field (phone fields are marked with *). As long as it is missing, "Select at least one column to map to a Phone field." appears and Next stays disabled.
Available fields¶
| Standard fields | Notes |
|---|---|
| Company name | |
| First name, Last name | In the list of fields they follow the Company name |
| Address, ZIP code, City, Province, Street number | Province: 2-letter abbreviation |
| Phone 1 … Phone 9 | Up to nine numbers per contact (only Phone 1 in an RPO database) |
| Email, Website | |
| Reference ID 1, Reference ID 2 | Free codes, for example the customer code in your management system |
Plus the dynamic fields of the schema chosen in step 1.
Phone numbers¶
Each number is cleaned before being saved: only the digits are kept (spaces, points, dashes and brackets are removed) and a leading "+" becomes "00". If a row has several numbers, in Preview campaigns the operator sees them all and chooses which to call (see The contact card in the operator manual).
Options¶
| Option | What it does |
|---|---|
| Skip first row (header row) (on by default) | Does not import the first row of the file. Leave it on if the first row contains headers. Turn it off only if the file contains data only |
| Check leading zero (on by default) | Restores the leading zero that Excel removes from numeric cells: adds a 0 in front of 9-digit phone numbers that do not start with 3 (Italian landlines) and of 4-digit ZIP codes. It is an automatic "common sense" correction: check the file anyway if you have foreign numbers |
Beware of Skip first row
The first row of the file is always used as the column names in the matching. Skip first row is on by default, so the header row is not imported. If your file does NOT have headers, remember to turn it off: otherwise the first contact in the file is skipped. If you turn it off for a file with headers, the header row ends up among the errors (or, worse, becomes a contact).
Press Next to go to the confirmation. With Back you return to the previous step without losing the choices made.
Step 3: Confirm¶
You see the Field mapping summary (Source field → Destination field). If everything is right, press Import.
The import starts in the background: you see a progress bar with the number of rows processed. As stated on screen, you can leave the page: the import continues even on large files ("You can leave this page open: the import continues even for large files."), and you find its progress and result on the Operations page.
The result¶
At the end Import completed (or Import failed) appears with four figures:
| Figure | Meaning |
|---|---|
| Total | Rows of the file processed (excluding the first, if you turned on Skip first row) |
| Imported | New contacts entered in the database |
| Discarded (duplicates) | Rows not imported because the phone number was already present |
| Errors | Rows not imported because they were not valid |
From here you can go back to the Databases page with Back to databases or open the Operations page with View operation log, where you find row by row what happened.
For each imported contact Thelgo sends the webhook event nominativo.creato to the connected systems (see External API): with large files the webhooks all go out at the end of the import.
When a row is a duplicate¶
Thelgo checks all the phone numbers of the row (from Phone 1 to Phone 9). The row is discarded as a duplicate if at least one of those numbers:
- has already appeared in a previous row of the same file, in any of its phones ("Telefono '…' duplicato nel file." (Phone '…' duplicated in the file.)), or
- is already present, in any of the nine phone fields, in a contact of the same database ("Telefono '…' già presente nel database." (Phone '…' already present in the database.)).
The message reports the first duplicate number found. If a row is discarded, none of its numbers counts for the following rows.
Duplicates do not update the existing contact: its data stay as they are. The same number can instead exist in different databases.
When a row is an error¶
| Message in the log | Cause |
|---|---|
| "Numero di telefono mancante." (Phone number missing.) | None of the row's phone fields has a value |
| "Valore troppo lungo per il campo '…' (massimo N caratteri)" (Value too long for the field '…' (maximum N characters)) | The value exceeds the allowed length (e.g. Province over 2 characters, ZIP code over 10, Company name over 200) |
| "Valore '…' non valido per il campo '…'" (Value '…' is not valid for the field '…') | The value is not of the dynamic field's type (e.g. text in a Number field; see Dynamic database fields) |
| "Numero di telefono riservato non valido." (Invalid reserved phone number.) | One of the row's phones is 9999999999, the number reserved for anonymized contacts |
Rows with an error do not block the others: the rest of the file is imported normally.
The final status¶
| Status (in Operations) | When |
|---|---|
| Completed | No row in error (any discarded duplicates do not count as errors) |
| Completed with errors | At least one row in error |
| Failed | The import stopped because of an unexpected problem. The contacts already entered up to that moment stay in the database: check the figures in Operations before trying again. If you re-import the same file, the rows already entered will be discarded as duplicates |
Every completed import is also recorded in the Audit log, with the number of imported, discarded and errors.