Skip to main content

Campaign contacts

Contacts upload

The contact file is uploaded in the Contacts upload block — at the Contacts step when you create a campaign, and in the card of a campaign in the Draft status. The file can be replaced only in a draft as well:
  • every new upload replaces the contacts of the previous one — the cabinet asks you to confirm the replacement; the upload history is kept;
  • after a replacement you need a new decision on do-not-call matches (see the “Do-not-call screening” section below) and a new attestation signature — a signature made under the previous file version does not count.
Numbers are added to a running campaign only as batches — with the Add a batch of calls block, see Adding calls to a running campaign.
Download the sample with the “Download the sample file” button. The sample is built from the published version of the campaign agent — it already contains the columns that agent uses in its prompts. Without a chosen agent the button is unavailable: “Pick an agent — the sample is built from its variables”. It is the fastest way to avoid empty variables during the conversation.
Contacts upload and Import results blocks

Contact file requirements

Format and limits

  • CSV and XLSX are accepted. The legacy XLS format is not supported — re-save the file.
  • CSV: UTF-8 encoding (with or without BOM) or Windows-1251; the separator ,, ; or tab is detected automatically.
  • XLSX: only the first sheet is read.
  • The first row holds the headers; data starts on the second row.
  • Limits: up to 50,000 rows and up to 10 MB; a file over the limit is rejected in full, not truncated.

Phone number

The phone number is the only column required on every market. Under the US market profile (us_tcpa) a contact_zip or contact_state column is required too — see US campaigns.
  • The platform finds the column by header: phone, contact_phone, phone_number, mobile, cell, tel, telephone, msisdn, телефон, номер, номер_телефона, and similar.
  • When no recognizable header exists, the column is detected by content: the one where at least 80% of the values look like phone numbers. If there is no such column, the file is rejected.
  • A number is readable when it has at least 10 digits. A row with an unreadable number is not dropped silently: it appears in the import report with its row number.
  • Numbers are compared by their last 10 digits: +7 701 123 45 67 and 8 701 123 45 67 are the same number.

Name

The contact name is taken from a name, full_name or фио column; without one it is assembled from a pair of columns: contact_first_name + contact_last_name, first_name + last_name, or имя + фамилия. The assembled name reaches the agent as the {{name}} variable.

Time zone

A timezone column (also tz, time_zone, contact_timezone, часовой_пояс) sets the contact’s zone in IANA format, for example Asia/Almaty. An unknown zone is a warning in the report, not a rejected row: the contact is called in the campaign time zone. An empty zone means the campaign time zone too.

Variables

Any other column becomes a call variable: amount owed, payment date, and so on.
  • The variable key comes from the header: case does not matter, spaces and hyphens become _ — “Amount Due” becomes amount_due.
  • When two headers give the same key, the first column wins and the report gets a “Column name collision” warning.
  • The phone, time zone, contract and role columns do not become variables.
Variables ticked In signature on the agent are checked against the file at launch: a missing column blocks the launch.

Contract groups

To tie several numbers to one contract (the borrower and third parties), add two columns:
  • contract_id (also contract, договор, номер_договора) — the contract id, up to 64 characters;
  • role (also роль) — borrower or third_party.
A row is rejected when the contract id is longer than 64 characters, when a contract id is set but the role is empty or unknown, or when a role is set without a contract id. Rows with neither are ordinary contacts outside any group. Members of one group are dialed in parallel. After a successful conversation with the borrower, the contacts of the same contract still waiting to be dialed in every launched campaign of the organization are suppressed with the reason “Contract group consent”. A conversation counts as successful when its goal is achieved if the agent has a success criterion, and any conversation that took place if it has none.

US campaigns

Under the us_tcpa market profile the file must have a contact_zip or contact_state column. A row whose location is not recognized or whose geography is not callable is rejected on its own; ZIP, state and city mismatches are warnings. Details are on the US campaigns page.

Duplicate numbers

The same person may appear in the file several times; the Duplicate numbers setting decides what happens:
  • Reject duplicates (to report) (the default) — the first occurrence stays, the rest go into the report as errors. Repeated rows usually mean the export from your system is misbehaving, and that is worth knowing.
  • Keep first occurrence — repeats are dropped and go into the report as warnings.
  • Keep last occurrence — the last row stays; for when corrected rows are appended to the end of the file.
Within one file a number enters the campaign at most once. A batch added to a running campaign with a number the campaign already has is accepted as a new contact, and the number is dialed again.
Why a file may be rejected in full: the phone column was not found or cannot be identified unambiguously; the file has no data rows or not a single usable row; the 50,000-row or 10 MB limit is exceeded; an unsupported format (XLS included) or a corrupted file; under the us_tcpa profile neither contact_zip nor contact_state is present. The reason and advice on what to fix are shown in the File refused block.
The contacts upload block: file limits and the per-agent sample file button

Import results

The Import results block shows the outcome of an upload:
  • the Accepted, With warnings, Rejected and Duplicates found counters;
  • a red Blocked (DNC): N badge when the file has numbers from the registry — the number of contacts that will not be dialed. Such rows are red in Row issues too: In the do-not-call registry;
  • Phone column — found “by header” or “detected automatically”, with the column name; for CSV, the Encoding;
  • Row issues — the issues grouped by kind, with row numbers;
  • the file version, the source file storage state and the Download source file button;
  • the Variables table: the file column, the variable key and the Fill rate as “N of M”;
  • the agent variables that have no column in the file: their values will be empty in the conversation.
When a file is rejected in full, a File refused block replaces the summary, with the reason, advice on what to fix, and “No contacts were created.”

Import report

For an accepted upload the Download report (CSV) and Download report (XLSX) buttons are always shown. A rejected file has no report, with two exceptions: every row was rejected by geography, or a batch of calls was refused. The report has one line per issue: row number, severity (error or warning), code, reason text, the values sent, and — for duplicates — the row the line repeats. In XLSX the lines and the summary are on the Rows and Summary sheets; in CSV the summary block follows the lines.

Upload history

With more than one upload, the Upload history block appears: file, upload time, version (the launched one is marked “launched”), the number of accepted rows or the “Refused” mark, and the Download source file button when the source is stored. Clicking a line opens the results of that upload.

Adding calls to a running campaign

A batch of numbers can be added to any campaign that has not ended, with the Add a batch of calls block in the campaign card. A batch is accepted or refused as a whole, and each batch carries its own attestation. Details are on the Adding calls page.

File retention

Only accepted uploads are kept: the attestation signature points at a specific document, and until the retention period expires the file is downloaded with the Download source file button. Rejected files are not kept. The full retention period is counted from the campaign launch and is configured per organization. The file of a campaign that was never launched is kept only briefly — two weeks by default. Retention can be switched off entirely: only the file’s metadata and checksum remain, but you lose the ability to produce the very file you attested the right to call under. When the period expires the file is deleted, and that is recorded too: its metadata and the deletion date are kept.

Do-not-call screening

The uploaded file is screened against the do-not-call registry, and the Matches against the do-not-call registry block shows the whole result of that screening:
  • readable rows checked — how many rows of the file had a readable phone and were screened;
  • rows not screened — the phone could not be read; these rows do not count as clean and are named separately;
  • a red N contacts blocked by DNC badge — how many contacts will not be dialed. When a number appears in the file more than once and there are more matched rows than contacts, the row count is shown beside it as a caption;
  • a table of matches with the columns Row, Number, Name, Reason and In registry since — quoted in full, not hinted at. When there are many matches the preview is truncated, and a Download exact list button appears beside it — it downloads CSV.
With a zero result the block does not stay silent — it states that there are no matches and how many rows were checked. Do-not-call screening before launch: two matches quoted in full and the decision to make A decision is required before launch: Block the launch — I will remove the matches from the file (the default) or Skip them and launch the campaign without them. The decision is made only in a draft and only for the current file. It is written to the campaign audit — who, when, how many contacts, and for which file; a new upload voids the previous decision. The decision is kept: when you come back to the contacts step, you see the same choice. If no callable contact remains, skipping is unavailable. At launch the file is screened against the current state of the registry. If the registry changed after a decision to skip the matches, the launch is blocked again: “The registry changed after the decision — review the match list again”. The file itself is not modified: the rows stay as they are. Matched contacts get the Suppressed state right at launch and do not wait for their turn. Numbers added to the registry later, and contacts added after launch, are excluded at dial time. After launch the screen is frozen and labelled “As of launch” — the grounds on which the campaign went dialing are not recomputed after the fact. The same block after launch: the "As of launch" label and the frozen list of matches The suppression phases themselves — at launch and during the campaign — are counted in the “Scheduler state” block on the campaign card, next to the “Suppressed by policy” line. Scheduler state: contacts by state, holds and the DNC suppression phases The cabinet and the Web API run this screening through the same code, so the result and its evidence are identical no matter where the campaign was launched from. A member can decide on do-not-call matches as well, since they run the whole campaign lifecycle — see Roles.

Campaign contacts

The Campaign contacts table contains the contacts loaded into the campaign. Above it are Search by number, Search by contract and the total count. Table columns:
  • Phone — the number as it was in the file;
  • Name;
  • Contract and Role — for contacts of a contract group;
  • Time zone — an empty zone is shown as “campaign time zone”;
  • State — Waiting, Dialing, Awaiting evaluation, Done, Exhausted or Suppressed. Under the state of a waiting or suppressed contact the reason is shown — for example, “Outside working hours”, “Frequency cap reached”, “On the do-not-call list (DNC)”, “Contract group consent”, “Withdrawn at the client’s request” — and a waiting contact also shows “Retry no earlier than” with a date;
  • Attempts.
Clicking a row expands the Contact variables. Campaign contacts table

Withdrawing contacts from dialing

Contacts are withdrawn from dialing at the client’s request only through the Web API: POST /v1/campaigns/{id}/contacts/withdraw — in one campaign, by numbers or contact IDs; POST /v1/contacts/withdraw — in every launched campaign of the organization, by numbers. A withdrawn contact moves to the Suppressed state with the reason “Withdrawn at the client’s request”. Details are in Withdrawing a contact from dialing.