> Усі статті WIKI Helomi: /wiki/llms.txt

# SMS (TurboSMS)

Інтеграція з TurboSMS надсилає клієнтам SMS — як у KeepinCRM: автоматично, коли угода переходить на вибраний етап (шаблон зі змінними — ТТН, сума, ім'я, посилання на чек), вручну з картки угоди, масово з вибраних угод і з тригера. Підписи відправника, шаблони, баланс, тестова SMS і журнал відправок зі статусом доставки — в одній картці; кабінетів TurboSMS можна підключити кілька, і все налаштовується вручну, без розробника. ШІ-співробітники працюють з тими самими налаштуваннями своїми інструментами.

## Можливості
- Кілька кабінетів TurboSMS (акаунтів): у кожного свій токен, підписи, шаблони, перемикач автовідправки й журнал.
- Підписи відправника (альфа-імена) з перемикачем «Увімкнено»; один — основний. «Підтягнути з TurboSMS» показує імена, зареєстровані в кабінеті.
- Шаблони «етап угоди (+ лише для вибраних джерел) → текст зі змінними»: один раз на угоду або щоразу, коли угода знову приходить на етап; лічильник «Надіслано».
- Змінні групами, як у KeepinCRM: системні, по угоді, по клієнту, по документах (посилання на чек Checkbox), по доставці.
- Ручна відправка з угоди, масова з вибраних угод, з тригера (шаблон, підпис, акаунт, затримка).
- Журнал відправок: дата, клієнт, угода, від кого, текст, статус доставки з TurboSMS («доставлено», «не доставлено»…), який оновлюється сам.
- Тестова SMS і баланс кабінету («кредити»).

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → «Повідомлення» → картка «SMS (TurboSMS)».

1. Вкладка «Підключення» → «API токен» → «Ввести» → «Зберегти ключ». Токен — у кабінеті TurboSMS: «Шлюз (API)» → «Налаштування API» (увімкніть HTTP API). Зберігається зашифрованим і назад не показується.
2. «Перевірити» читає баланс: «баланс: N».
3. «Назва акаунта» — як підписати цей кабінет у перемикачі акаунтів (напр. Semenchenko); порожньо — «Основний».
4. Вкладка «Шаблони SMS» → «Підписи відправника» → «Підтягнути з TurboSMS» або впишіть альфа-ім'я → «Додати підпис» (розділ 2).
5. Там само — «+ Додати SMS шаблон» (розділ 3).
6. Блок «TurboSMS» → «Тестова SMS»: телефон і текст → «Надіслати», щоб перевірити ключ і підпис.
7. Перемикач «Інтеграція» у «Підключенні» = автовідправка за шаблонами цього кабінету. Поки SMS-шаблони працюють у KeepinCRM, лишайте вимкненим — інакше клієнт отримає два SMS. Ручна, масова й тригерна відправка працюють і з вимкненим перемикачем.

Усі зміни на вкладці «Шаблони SMS» зберігаються одразу (як у KeepinCRM); змінювати може лише адміністратор, інші бачать налаштування для читання.

## 2. Підписи відправника
Альфа-ім'я (до 20 символів) має бути зареєстроване у вашому кабінеті TurboSMS — інакше TurboSMS не прийме SMS.

1. «Підтягнути з TurboSMS» показує імена з кабінету зі станом: «активний» — можна додати кліком; «на модерації», «потребує змін», «відхилено» — ще ні.
2. Або впишіть ім'я в поле «новий підпис» → «Додати підпис» (Enter теж додає).
3. Перемикач у рядку: «Увімкнено» / «Вимкнено». Вимкненим підписом SMS не надсилаються (і з угоди, і за шаблонами).
4. «основний» — підпис для шаблонів і ручних SMS без свого підпису; «Зробити основним» — в іншому рядку. Основним може бути лише ввімкнений.
5. Кошик прибирає підпис. Підпис, що стоїть у шаблонах, не прибирається, поки в тих шаблонах не оберете інший.

## 3. Шаблони на етапи угоди (автовідправка)
Таблиця «Шаблони»: «Шаблон», «Етап угоди», «Джерело», «Текст SMS повідомлення», «Надіслано», перемикач, олівець і кошик.

1. «+ Додати SMS шаблон» (або олівець / клік по назві існуючого) — відкривається шторка «SMS шаблон».
2. «Назва» (напр. «Відправлено»), перемикач «Активний» / «Вимкнено».
3. «Етап угоди — коли надсилати»: один або кілька етапів (з усіх воронок). Без етапу шаблон надсилається лише вручну — з угоди, тригером чи масово.
4. «Джерело — лише для вибраних»: окремі шаблони для різних сайтів і маркетплейсів; порожньо — для всіх.
5. «Один раз на угоду» / «Щоразу, коли угода знову приходить на етап».
6. «Підпис відправника»: за замовчуванням (основний) або інший увімкнений.
7. «Текст SMS повідомлення» — до 1000 символів; під полем лічильник «N / 1000 симв. · M SMS» (кирилиця — 70 символів на одну SMS, довші йдуть частинами по 67).
8. Кнопки «Системні змінні», «Змінні по угоді», «Змінні по клієнту», «Змінні по документах», «Змінні по доставці» відкривають список змінних — клік вставляє змінну туди, де курсор (розділ 4).
9. «Перевірити на угоді»: впишіть № угоди — побачите, який текст і на який телефон піде, і чи є невідомі змінні.
10. «Зберегти».

Коли угода переходить на етап шаблону і кабінет увімкнено перемикачем, клієнт отримує SMS. Телефон — отримувача з останньої доставки, інакше основний телефон клієнта. Кожна SMS пишеться в журнал угоди («SMS «Відправлено» на 380…: текст»).

## 4. Змінні в тексті
Запис — як у KeepinCRM: `{{.група.поле}}`. Невідома змінна стає порожньою, у перевірці — попередження.

| Група | Змінні |
| --- | --- |
| Системні | `{{.now.date}}` — сьогодні, `{{.now.time}}` — зараз (Київ) |
| По угоді | `{{.agreement.id}}`, `{{.agreement.title}}` (№ замовлення), `{{.agreement.total}}`, `{{.agreement.paid}}`, `{{.agreement.credit}}` (до сплати), `{{.agreement.stage}}`, `{{.agreement.source}}`, `{{.agreement.responsible}}`, `{{.agreement.created_at}}`, `{{.agreement.items}}` (товари: назва × кількість) |
| По клієнту | `{{.client.name}}` (ПІБ або назва), `{{.client.person}}`, `{{.client.company}}`, `{{.client.phone}}`, `{{.client.email}}` |
| По документах | `{{.agreement.last_checkbox_receipt_url}}` — посилання на останній чек Checkbox угоди, `{{.agreement.last_checkbox_fiscal_code}}` — його фіскальний номер |
| По доставці | `{{.agreement.delivery_ttns}}` (усі ТТН), `{{.last_delivery.ttn}}`, `{{.last_delivery.service}}`, `{{.last_delivery.address}}`, `{{.last_delivery.recipient}}`, `{{.last_delivery.cod}}` (накладений платіж), `{{.last_delivery.cost}}`, `{{.last_delivery.status}}` |

Приклад: «Вітаємо {{.client.person}}, ваша ТТН: {{.last_delivery.ttn}}. Дякуємо!» → «Вітаємо Іван Тестовий, ваша ТТН: 20450000000001. Дякуємо!».

## 5. Надіслати SMS з угоди вручну
Картка угоди → «⋮» → «Надіслати SMS» → шторка: «Акаунт TurboSMS» (коли кабінетів з токеном кілька), «Шаблон» або «Текст (змінні угоди підставляться)», перегляд «Клієнт отримає…», «Інший телефон (необов'язково)», «Підпис» (коли ввімкнених кілька) → «Надіслати».

## 6. SMS клієнтам вибраних угод
У списку угод позначте угоди → панель «Вибрано: N» → «SMS» → шторка: «Акаунт TurboSMS» (коли кілька), «Шаблон» або свій текст зі змінними (кнопки над полем; старі `{client.name}`, `{deal.title}`, `{deal.total}` теж працюють) → «Надіслати» → підтвердження. Текст іде на основний телефон клієнта кожної угоди підписом за замовчуванням; угоди без клієнта чи телефону — у списку помилок. Кожна SMS — у журналі SMS і журналі угоди. Кнопка «SMS» сіра з підказкою, поки не задано токен або підпис.

## 7. SMS з тригера (складні умови й затримка)
Прості умови (етап, джерело) — шаблоном (розділ 3). Складніші — «Налаштування» → «Автоматизація» → «Тригери» → дія «Відправити SMS»: «Акаунт TurboSMS» (коли кілька), «SMS-шаблон» (або «— свій текст —» і текст зі змінними тригера `{{title}}`), «Підпис відправника», «Телефон» (порожньо — з доставки чи клієнта угоди); умова й затримка — у тригері (напр. «Прибув у відділення» + 4320 хв = нагадування через 3 дні). Як писати умови — [Тригери](settings-triggers.md).

## 8. Журнал відправок, статуси доставки й баланс
«Шаблони SMS» → «Журнал відправок»: «Дата», «Клієнт» і «Угода» (клік відкриває картку), «Від» (підпис; під ним — шаблон або «вручну · хто»), «Повідомлення», «Статус». Статус доставки береться з TurboSMS: «у черзі», «надіслано оператору», «доставлено», «прочитано», «не доставлено», «відхилено», «термін минув», «скасовано, кошти повернуто»; «не надіслано: …» — TurboSMS відмовив одразу (причина поруч).

- «Статуси доставки» → «Перевіряти автоматично»: сервер сам питає TurboSMS кожні 5 хвилин про SMS за останні 3 доби, доки статус не стане кінцевим. Вимкнено — «Лише кнопкою «Оновити статуси»».
- «Оновити статуси» — перевірити зараз.
- «Показати ще» — старіші записи.
- Баланс — блок «TurboSMS» → «Баланс» (кредити), кружечок поруч оновлює.

## 9. Кілька кабінетів TurboSMS
«+» унизу праворуч картки → назва і токен → новий кабінет у перемикачі під шапкою (поруч з основним). У кожного кабінету — своя вкладка «Підключення» (токен, перемикач автовідправки, «Перевірити», журнал подій) і «Шаблони SMS» (свої підписи, шаблони, журнал відправок). Автовідправка йде з кожного ввімкненого кабінету за його шаблонами. Вручну, масово й тригером — з вибраного кабінету (типово — основного).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Не задано TURBOSMS_TOKEN — введіть токен TurboSMS у картці інтеграції «SMS»» | Токен не введено (для додаткового кабінету — «… акаунта «назва»») | «Підключення» → «API токен» |
| «Ключ TurboSMS не задано — «Інтеграції → SMS (TurboSMS) → Підключення».» | Те саме, у шторці угоди | Введіть токен |
| «Не задано підпис відправника — додайте його в «Підписи відправника»» | Немає жодного ввімкненого підпису | Додайте альфа-ім'я |
| «Підпис «…» вимкнено в «Підписах відправника»» | Підпис вимкнено перемикачем | Увімкніть або оберіть інший |
| «Підпис «…» не додано в «Підписи відправника» цього акаунта» | Підпис з іншого кабінету чи вписаний вручну | Додайте його в цей кабінет |
| «Шаблон «…»: підпис «…» не додано в «Підписи відправника»» | Шаблон посилається на прибраний підпис | Оберіть у шаблоні інший |
| «Підпис «…» стоїть у шаблонах … — спершу оберіть там інший» | Прибираєте підпис, який використовують шаблони | Змініть підпис у шаблонах |
| «Нема телефону для SMS (у доставці чи клієнта угоди)» | В угоді нема телефону | Додайте телефон клієнту чи в доставку |
| «Невірний телефон «…» — потрібен український номер, напр. 0671234567» | Неправильний номер у полі «Інший телефон» | Виправте номер |
| «Шаблон не знайдено в цьому акаунті SMS» | Шаблон з іншого кабінету або видалений | Оберіть шаблон цього кабінету |
| «Текст довший за 1000 символів» / «Шаблон «…»: порожній текст» | Задовгий або порожній текст | Скоротіть / впишіть текст |
| «TurboSMS не прийняв SMS: REQUIRED_BALANCE» (або інший код) | Відмова TurboSMS: баланс, стоп-лист, дубль за 90 с | Поповніть баланс / перевірте номер |
| Статус «не доставлено» | Оператор не доставив (телефон вимкнено, номер неіснуючий) | Перевірте номер клієнта |

## Для ШІ-співробітників
Розділ у каталозі — `describe_section("sms")`, картка `/api/ai/sections/sms` (поля: акаунт, підписи, шаблони, змінні; приклади викликів). Читати можна з доступом «Угоди» або «Інтеграції».

- `sms_state` — налаштування кабінету: акаунти, підписи, шаблони з етапами й джерелами, лічильники, змінні за групами, воронки з етапами, джерела (`account` — інший кабінет).
- `sms_preview` — текст зі змінними угоди і телефон, без відправки.
- `sms_send` — надіслати SMS клієнту угоди шаблоном або своїм текстом (доступ «Угоди»). Це «відправка назовні»: типово чекає «Підтвердити» людини («Доступи → Спочатку запитати → Відправка назовні»); передавайте `idempotency_key` — повтор не надішле вдруге.
- `sms_messages` — журнал: що й коли надсилали, статус доставки; `sms_refresh_statuses` — оновити статуси з TurboSMS.
- `sms_balance`, `sms_senders_remote` — баланс і зареєстровані імена кабінету (доступ «Інтеграції»).
- `sms_settings_save` — змінити підписи й шаблони (налаштування цілком, як у `sms_state.settings`). Лише з доступом «Налаштування інтеграцій», який видає адміністратор у «Доступах» пульта ШІ, і завжди після «Підтвердити» адміністратора: картка показує, які підписи й шаблони додано, прибрано чи змінено. У журналі — «ШІ <ім'я> · підтвердив <адміністратор>».
- Токен TurboSMS ШІ не вводить і не бачить; перемикач автовідправки вмикає людина.
- Не вигадуйте id шаблонів і етапів — беріть з `sms_state`; не надсилайте вільний текст замість шаблону без потреби.

Статтю ШІ читає інструментом `help("int-sms")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Налаштування: тригери](settings-triggers.md), [Інтеграції](integrations.md), [Checkbox](int-checkbox.md), [ШІ-співробітники](ai-employees.md), [BlackBox](int-blackbox.md).