> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ukrgsm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# База контактів
> Де живуть номери та дані про клієнтів, як завантажувати нові файли і як працює стоп-лист.
Уся робота з номерами відбувається в розділі **«База контактів»**. Кампанія власних номерів не має — вона завжди дзвонить тим, що лежать тут.
## Довідник і списки
**Довідник** — це база номерів одного клієнта. У ньому зберігаються дані кожного запису (ім'я, сума, номер рахунку — будь-які колонки з вашого файлу) і стоп-лист номерів. Сам довідник нікому не дзвонить.
**Список номерів** — один завантажений файл усередині довідника. Саме списки обираються при створенні кампанії.
Різниця важлива: дані зберігаються **один раз, у довіднику**, а список лише пам'ятає, які записи в ньому були. Тому кампанія, створена зі списку тижневої давності, усе одно дзвонить із найсвіжішими даними — тими, що в довіднику зараз.
## Запис — одиниця набору
**Запис — це один рядок вашого файлу.** Саме запис, а не номер, кампанія набирає: один дзвінок на запис.
Навіщо: на один номер телефону може припадати кілька справ — кілька рахунків, кілька замовлень, кілька звернень. Якщо в файлі номер зустрічається тричі, платформа зателефонує тричі, щоразу з даними свого рядка.
Що робить записи різними — **пара «ідентифікатор + номер»**, де ідентифікатор береться з колонки `ext_customer_id`:
| У файлі | Результат |
| - | - |
| один ідентифікатор, кілька номерів | запис на кожен номер — байдуже, окремими колонками чи окремими рядками |
| один номер, різні ідентифікатори | різні записи, кілька дзвінків на цей номер |
| та сама пара вдруге | оновлення даних, нового запису не зʼявляється |
| колонки `ext_customer_id` немає | запис один на номер, один дзвінок — як було завжди |
Правило одним реченням: **запис — це пара «ідентифікатор + номер»; номер обовʼязковий, ідентифікатор може бути відсутній**.
Тому форма файлу не має значення. Ці два файли дають однакові три записи:
```
ext_customer_id; phone; ext_customer_id; phone; phone_work; phone_home
D-100; 0671111111 D-100; 0671111111; 0501112233; 0441234567
D-100; 0501112233
D-100; 0441234567
```
Якщо колонка `ext_customer_id` у файлі є, вона має бути заповнена **в кожному рядку**. Рядки з порожньою клітинкою відхиляються, і платформа окремо покаже, скільки їх було.
Номер телефону при цьому лишається номером: **стоп-лист працює по номеру** і замовкають усі його записи одразу.
Номер, якого в новому файлі немає, з довідника не зникає: режим «Оновити» лише додає й оновлює. Щоб перелік номерів став рівно таким, як у файлі, потрібен режим «Замінити».
## Перейменувати довідник
Олівець біля назви на сторінці довідника. Міняється **лише назва** — адреса, яку агент
викликає на вхідному дзвінку (`lookup_path` зі слагом), лишається тією самою, тож
перейменування нічого не ламає й нічого не треба міняти в сценаріях.
Назва має бути унікальною в межах організації. Кампанії, зібрані з цього довідника,
підхоплюють нову назву самі.
## Файл із номерами
Звичайна таблиця, збережена як CSV (можна зробити в Excel або Google Таблицях).
Розпізнаються за назвою і нічого не потребують налаштовувати:
| Колонка | Призначення |
| - | - |
| `phone_number` | номер телефону — обов'язкова |
| `ext_customer_id` | ваш внутрішній ID — разом із номером утворює ключ запису (див. вище) |
| `stop_list` | заборона дзвонити |
Будь-які інші колонки — дані про клієнта; вони підставляються в розмову агента як змінні.
| phone\_number | customer\_name | debt\_words |
| - | - | - |
| 380501234567 | Олена Іваненко | 6539 гривень |
| 380671234567 | Ігор Петренко | 1200 гривень |
**Номер телефону** можна писати як зручно — платформа сама зводить його до єдиного вигляду `+380671234567`. Однаково приймаються `380671234567`, `+380671234567`, `0671234567`, `067 123-45-67`, `(067) 123 45 67`, `00380671234567` і навіть `671234567`. Номер з іншим кодом країни зберігається як є. Не приймається лише те, що не схоже на номер: порожня клітинка, текст без цифр, надто короткий або надто довгий рядок — такі рядки потрапляють у «Відхилено».
## Налаштування довідника
Як читати файли цього довідника — задається **один раз**, а не при кожному завантаженні. Кнопка **«Налаштування»** вгорі сторінки довідника; поточні значення видно там само, у картці під назвою.
| Налаштування | Що означає | Коли можна змінити |
| - | - | - |
| **Колонки з номерами** | де у файлі шукати номери, через кому й у порядку набору | будь-коли |
| **Ідентифікатор** | колонка, значення якої разом із номером утворює ключ запису | лише поки довідник порожній, далі — через «Замінити» |
| **Вимагати ідентифікатор** | файл без цієї колонки не імпортується, рядки з порожнім значенням відхиляються | будь-коли; на вже збережені записи не впливає |
| **Колонка стоп-списку** | будь-яке значення в ній означає «не дзвонити» | будь-коли |
Порожнє поле означає «розпізнавати стандартні назви» (`phone_number`, `ext_customer_id`, `stop_list`). Перший завантажений список задає ці налаштування автоматично — з того, що ви вказали в діалозі завантаження.
Колонку з номерами, яка є у файлі, але **не оголошена** тут, платформа вважала б звичайними даними — номери з неї не набиралися б. Тому файл, у якому бракує оголошеної колонки з номерами, відхиляється з поясненням ще до запису першого рядка.
## Завантаження файлу
Максимальний розмір файлу — **50 МБ**. Більший реєстр розділіть на кілька списків: вони все одно лежатимуть в одному довіднику й одна кампанія може набирати їх разом.
1. Відкрийте довідник і натисніть **«Завантажити файл»**.
2. Оберіть режим (див. нижче). Колонки вказувати не треба — вони беруться з налаштувань довідника; для першого списку діалог запитає їх один раз.
3. Натисніть **«Перевірити файл»** — платформа прочитає його і покаже колонки, перші рядки й кількість номерів, нічого ще не змінюючи.
4. Якщо все правильно — **«Застосувати»**.
### Два режими
**Оновити** (за замовчуванням) — записи з файлу додаються, дані по вже наявних оновлюються. Нічого не видаляється.
**Замінити** — вміст довідника стає рівно таким, як у файлі: старі списки видаляються, а записи, яких у файлі немає, прибираються з довідника. Є запобіжник: якщо база різко зменшується, платформа попросить підтвердження.
«Замінити» доступний, **лише коли всі кампанії довідника завершені**, і видаляє старі списки. Інакше кампанія продовжувала б дзвонити номерам, яких у довіднику вже немає.
Перейти з ключування номером на `ext_customer_id` (або назад) можна **тільки режимом «Замінити»**. У режимі «Оновити» такий файл буде відхилено з поясненням: під двома ключами та сама справа існувала б двічі й продзвонилась би двічі.
Те саме стосується довідників, заповнених до правила пари: вони ключовані лише ідентифікатором, і перший файл за новим правилом теж треба застосувати режимом «Замінити». Платформа скаже про це сама, якщо спробувати «Оновити».
## Колонки довідника
Колонки задає **перший список** довідника. Далі правило просте:
* **кожен наступний файл має містити всі оголошені колонки** — якщо якоїсь бракує, файл не застосується, а перевірка назве, якої саме;
* **нові колонки додавати можна** — вони приєднуються до оголошених і стають доступні агентові;
* **оголосити іншу структуру** можна лише файлом у режимі **«Замінити»**.
Приклад. Перший список дав колонки `name`, `amount`:
| Файл | Колонки | Результат |
| - | - | - |
| Оновити | `name`, `amount` | ✅ застосується |
| Оновити | `name`, `amount`, `due_date` | ✅ застосується, `due_date` додається до довідника |
| Оновити | `name` | ❌ «У файлі немає колонок, які оголошені в довіднику: «amount»» |
| Замінити | `name` | ✅ тепер довідник оголошує лише `name` |
Навіщо: якщо списки одного довідника мають різні колонки, кампанія падає вже при створенні — агент читає змінну, якої частина записів не має. Тепер це видно одразу в діалозі завантаження, до того як щось записалось.
Оголошені колонки видно на сторінці довідника; помилка при створенні кампанії теж називає **список і колонку**, якої в ньому бракує.
## Що можна подивитися
Сторінка довідника має вкладки:
* **Списки номерів** — усі завантаження. Клік на назву відкриває записи списку з **актуальними** даними; кнопка **«Оригінальний файл»** віддає файл у тому вигляді, в якому його завантажували.
* **Кампанії** — кампанії, зібрані з цього довідника.
* **Стоп-список** — номери, яким дзвонити заборонено, з причиною.
* **Вміст довідника** — усі записи з пошуком і посторінковим переглядом.
* **Пошук по номеру** — знайти контакт за номером або за зовнішнім ID.
У таблиці списків: **Записів** — скільки рядків файл дав, **Відхилено** — рядки з неправильним форматом номера, а якщо ідентифікатор обовʼязковий — то й рядки з порожнім ідентифікатором (їх кількість показана окремо), **Оновлено** — скільки разів та сама пара «ідентифікатор + номер» трапилась у файлі двічі: запис один, дані беруться з останнього такого рядка (це не помилка, а дубль у файлі), **У стоп-списку** — скільки записів списку зараз не набирається.
## Архів списків
За кілька місяців довідник збирає десятки завантажень, і при створенні кампанії доводиться шукати потрібний серед історії. Кнопка **«Архівувати»** прибирає список із цього вибору — і більше нічого не робить: номери лишаються в довіднику, кампанії, які вже його набирають, працюють далі.
Архівовані списки збираються в секцію **«Архів»** унизу сторінки, звідки їх можна **«Відновити»**.
Два випадки, коли архівувати не вийде:
* список **використовується в кампанії** — платформа скаже це, коли ви натиснете «Архівувати»; спочатку приберіть його зі списків кампанії або архівуйте саму кампанію (архівна кампанія списки вже не тримає);
* список завантажений у режимі **«Замінити»** — у нього немає кнопки «Архівувати» взагалі: він один на довідник, і сховати його означало б лишити вибір порожнім.
## Архів довідників
Довідників теж накопичується багато — на клієнта, на експеримент, на рік. Кнопка **«В архів»** у рядку довідника на сторінці «База контактів» прибирає його із загального списку і з вибору при створенні кампанії. Архівовані довідники — у згорнутій секції **«Архів»** унизу, кнопка **«Відновити»** повертає довідник назад.
Нічого не видаляється: записи, списки, стоп-лист і історія імпортів на місці, сторінка довідника відкривається за посиланням і читається повністю.
Що змінюється:
* довідник **не пропонується** при створенні кампанії й при зміні списків кампанії;
* довідник **не приймає нові списки** — кнопка «Завантажити файл» неактивна, поруч із назвою зʼявляється позначка «В архіві»;
* **вхідні дзвінки працюють як раніше** — `lookup-by-phone` відповідає і для архівного довідника. Архів прибирає довідник з очей оператора, а не з експлуатації.
Архівувати не вийде, поки є **незавершена кампанія** з цього довідника — платформа назве такі кампанії. Завершіть їх або [архівуйте самі кампанії](/core-concepts/campaigns): архівна кампанія довідник уже не тримає.
## Стоп-лист
Стоп-лист діє **лише на вихідні дзвінки** і лише в межах свого довідника.
Номер потрапляє в нього двома шляхами: з колонки `stop_list` у файлі (порожня клітинка — дзвонимо, будь-яке значення — ні, і саме це значення стає причиною) або вручну на вкладці «Стоп-список».
Щойно номер туди внесли, він **одразу виходить із черг усіх кампаній** цього довідника — навіть тих, що вже працюють, і разом з усіма своїми записами. Повернути його в набір можна, прибравши зі стоп-листа.
На **вхідному** дзвінку номер зі стоп-листа все одно впізнається й обслуговується: відмова дзвонити не означає відмову розмовляти, коли людина телефонує сама.
## Далі
Як зі списків будується обдзвін
Зміна списків, пауза, новий раунд