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

# WhatsApp

Номер WhatsApp Business компанії підключається до Helomi через Cloud API від Meta: повідомлення клієнтів на цей номер з'являються в «Переписках», відповідь звідти йде з того самого номера, а написати клієнту першим можна з «Переписок» затвердженим шаблоном. Кожен номер — свій акаунт картки з трьома ключами з Meta for Developers; підключає адміністратор, без розробника.

## Можливості
- Номер WhatsApp Business за ключами з Meta for Developers; кілька номерів — окремі акаунти картки («+»).
- Повідомлення клієнтів у «Переписках» з підписом акаунта; відповідь із «Переписок» іде з того самого номера.
- Текст, фото, документи, голосові й відео клієнта — у стрічці чату з копією в Helomi; локація, контакт, натиснута кнопка й реакція — текстом.
- Відповідь протягом 24 годин після повідомлення клієнта — звичайним текстом, фото чи документом; пізніше — затвердженим шаблоном Meta.
- «Написати» клієнту першим з «Переписок» — шаблоном (із вашим текстом у змінній, якщо шаблон її має).
- Адресу вебхука перевіряє сама Meta; кожну подію Meta підписує, і Helomi приймає лише підписані.
- «Перевірити» показує номер, назву компанії з Meta та якість номера.

> [!IMPORTANT]
> Особистий WhatsApp і звичайний застосунок WhatsApp Business до Helomi не підключаються — Meta не дає для них API. Потрібен номер, зареєстрований у WhatsApp Business Platform (Cloud API): це може бути новий номер або ваш нинішній, переведений у Cloud API (тоді він перестає працювати в застосунку на телефоні).

## 1. Підключити номер
Підключення — три ключі з Meta for Developers і адреса вебхука, яку ви вписуєте в Meta. Підключає адміністратор.

1. Відкрийте Meta for Developers (developers.facebook.com), створіть застосунок типу «Business» і додайте в нього продукт «WhatsApp»; прив'яжіть бізнес-портфоліо компанії та номер телефону компанії.
2. У «WhatsApp → API Setup» скопіюйте «Phone number ID» номера.
3. У Meta Business (business.facebook.com → «Налаштування бізнесу → Системні користувачі») створіть системного користувача з правами на застосунок і WhatsApp-акаунт і згенеруйте для нього постійний токен з дозволами `whatsapp_business_messaging` і `whatsapp_business_management`. Тимчасовий токен з «API Setup» живе 24 години — для роботи він не годиться.
4. У «Налаштування застосунку → Основне» скопіюйте «App secret».
5. Відкрийте «Налаштування → Інтеграції й автоматизація → Повідомлення → WhatsApp», вкладку «Підключення».
6. У рядках ключів натисніть «Ввести» й збережіть: «WHATSAPP_TOKEN» — токен, «WHATSAPP_PHONE_ID» — Phone number ID, «WHATSAPP_APP_SECRET» — App secret.
7. Натисніть «Перевірити» — відповідь «номер +380…, назва «…», якість висока» означає, що ключі правильні.
8. У блоці «Отримання повідомлень» скопіюйте «Адресу вебхука» і «Ключ перевірки». У Meta for Developers відкрийте «WhatsApp → Configuration → Webhooks», натисніть «Edit», вставте адресу як Callback URL, ключ — як Verify token, збережіть і підпишіться на поле «messages».
9. Щойно Meta перевірить адресу, стан у Helomi стане «вебхук активний». Напишіть на номер з WhatsApp — повідомлення з'явиться в «Переписках».

> [!NOTE]
> Поки застосунок Meta у режимі розробки, писати можна лише номерам зі списку тестових одержувачів («API Setup → To»). Щоб писати всім, переведіть застосунок у режим «Live» і пройдіть перевірку бізнесу в Meta Business.

## 2. Написати клієнту першим
Поза вікном 24 годин Meta приймає від компанії лише затверджений шаблон — текст, який ви заздалегідь погодили в WhatsApp Manager. Шаблон із змінною `{{1}}` дозволяє вставити в нього ваш текст.

1. У WhatsApp Manager (Meta Business → «Шаблони повідомлень») створіть шаблон категорії «Utility» (наприклад, «Вітаємо! {{1}}») і дочекайтеся затвердження.
2. У Helomi відкрийте вкладку «Підключення» картки номера → «Налаштування бота»: впишіть назву шаблону, мову (uk) і поставте позначку «шаблон має змінну для нашого тексту», натисніть «Зберегти».
3. У «Переписках» натисніть «Написати», оберіть канал «WhatsApp» (і номер, якщо їх кілька), впишіть телефон клієнта в міжнародному форматі та текст — він піде у змінну шаблону.
4. Коли клієнт відповість, вікно 24 годин відкриється — далі пишіть як у звичайному чаті.

Без свого шаблону працює тестовий «hello_world» (мова en_US) — він надсилає лише свій текст, ваш не передає.

## 3. Відповісти клієнту
1. Відкрийте «Переписки» і чат з підписом акаунта номера.
2. Напишіть текст у полі внизу й натисніть «Надіслати» — фото піде картинкою з підписом, документ — файлом.
3. Якщо з останнього повідомлення клієнта минуло понад 24 години, Helomi надішле шаблон з вашим текстом у змінній; якщо шаблон без змінної — покаже, що зробити.

## 4. Кілька номерів
Кожен номер — окремий акаунт картки зі своїми ключами, перемикачем, налаштуваннями й журналом. Розмови підписані назвою акаунта, відповідь іде саме з того номера, на який написав клієнт.

1. У картці «WhatsApp» натисніть «+» унизу праворуч, вкажіть назву (наприклад, «Магазин сумок») і три ключі.
2. Увімкніть перемикач у шапці картки нового акаунта — вимкнений акаунт повідомлень не записує.
3. Впишіть адресу вебхука й ключ перевірки цього акаунта в тому ж застосунку Meta (кожному номеру — свій рядок) або в окремому.

## 5. Що тарифікує Meta
Повідомлення в межах 24 годин після повідомлення клієнта безкоштовні; шаблони («Utility», «Marketing», «Authentication») і повідомлення поза вікном Meta тарифікує за своїм прайсом для країни одержувача й списує з платіжного методу бізнес-портфоліо. Helomi за WhatsApp окремо не бере.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «токен відхилено або прострочено» | Вставлено тимчасовий токен з «API Setup» або токен відкликано | Створіть постійний токен системного користувача і введіть його через «Змінити» |
| «не задано ID номера WhatsApp» | Не збережено «WHATSAPP_PHONE_ID» | «Підключення» → «Ввести» у рядку WHATSAPP_PHONE_ID |
| Стан вебхука не стає «активний» | Meta ще не перевірила адресу або ключ перевірки не збігається | Перевірте, що в Meta вставлено саме «Ключ перевірки» з картки, і натисніть «Verify and save» ще раз |
| Повідомлення не приходять, хоч вебхук активний | У Meta не підписано поле «messages» або акаунт вимкнено | Webhooks → «Manage» → підпишіться на «messages»; увімкніть перемикач акаунта |
| «номера нема серед дозволених тестових одержувачів» | Застосунок Meta ще в режимі розробки | Додайте номер у «API Setup → To» або переведіть застосунок у «Live» |
| «минуло понад 24 години… Meta приймає лише шаблон» | Вікно відповіді закрите, шаблон без змінної | Оберіть шаблон зі змінною в «Налаштуваннях бота» або дочекайтеся відповіді клієнта |
| «шаблону з такою назвою й мовою нема або його не затверджено» | Назва чи мова не збігаються з WhatsApp Manager | Звірте назву й код мови в «Шаблонах повідомлень» |
| «повідомлення не доставити — у клієнта нема WhatsApp» | На цьому номері нема WhatsApp або він заблокував номер | Напишіть іншим каналом |
| «Meta не відповіла — спробуйте ще раз» | Збій мережі чи Meta | Повторіть дію |

## Для ШІ-співробітників
ШІ з доступом до «Інтеграцій» бачить стан номера так само, як у Telegram- і Viber-бота: картки — `integrations_list`, журнал — `integrations_log`; ключі вводить і вебхук налаштовує лише людина-адміністратор, ключ перевірки й адресу з секретом ШІ не бачить. Розмови WhatsApp ШІ бачить у «Переписках» разом з іншими каналами. «Написати першим» (`POST /api/inbox/compose`, source `whatsapp`) — дія виду outbound: ШІ має спершу запитати людину. Статтю ШІ читає інструментом `help("int-whatsapp")`.

## Додаткова інформація
- Пов'язані статті: [Переписки](chats.md), [Telegram](int-telegram.md), [Viber](int-viber.md).