Номер WhatsApp Business компанії підключається до Helomi через Cloud API від Meta: повідомлення клієнтів на цей номер з'являються в «Переписках», відповідь звідти йде з того самого номера, а написати клієнту першим можна з «Переписок» затвердженим шаблоном. Кожен номер — свій акаунт картки з трьома ключами з Meta for Developers; підключає адміністратор, без розробника.
На цій сторінці
Можливості
- Номер WhatsApp Business за ключами з Meta for Developers; кілька номерів — окремі акаунти картки («+»).
- Повідомлення клієнтів у «Переписках» з підписом акаунта; відповідь із «Переписок» іде з того самого номера.
- Текст, фото, документи, голосові й відео клієнта — у стрічці чату з копією в Helomi; локація, контакт, натиснута кнопка й реакція — текстом.
- Відповідь протягом 24 годин після повідомлення клієнта — звичайним текстом, фото чи документом; пізніше — затвердженим шаблоном Meta.
- «Написати» клієнту першим з «Переписок» — шаблоном (із вашим текстом у змінній, якщо шаблон її має).
- Адресу вебхука перевіряє сама Meta; кожну подію Meta підписує, і Helomi приймає лише підписані.
- «Перевірити» показує номер, назву компанії з Meta та якість номера.
Особистий WhatsApp і звичайний застосунок WhatsApp Business до Helomi не підключаються — Meta не дає для них API. Потрібен номер, зареєстрований у WhatsApp Business Platform (Cloud API): це може бути новий номер або ваш нинішній, переведений у Cloud API (тоді він перестає працювати в застосунку на телефоні).
1Підключити номер
Підключення — три ключі з Meta for Developers і адреса вебхука, яку ви вписуєте в Meta. Підключає адміністратор.
- Відкрийте Meta for Developers (developers.facebook.com), створіть застосунок типу «Business» і додайте в нього продукт «WhatsApp»; прив'яжіть бізнес-портфоліо компанії та номер телефону компанії.
- У WhatsApp›API Setup«WhatsApp → API Setup» скопіюйте «Phone number ID» номера.
- У Meta Business (business.facebook.com → Налаштування бізнесу›Системні користувачі«Налаштування бізнесу → Системні користувачі») створіть системного користувача з правами на застосунок і WhatsApp-акаунт і згенеруйте для нього постійний токен з дозволами
whatsapp_business_messagingіwhatsapp_business_management. Тимчасовий токен з «API Setup» живе 24 години — для роботи він не годиться. - У Налаштування застосунку›Основне«Налаштування застосунку → Основне» скопіюйте «App secret».
- Відкрийте Налаштування›Інтеграції й автоматизація›Повідомлення›WhatsApp«Налаштування → Інтеграції й автоматизація → Повідомлення → WhatsApp», вкладку «Підключення».
- У рядках ключів натисніть «Ввести» й збережіть: «WHATSAPP_TOKEN» — токен, «WHATSAPP_PHONE_ID» — Phone number ID, «WHATSAPP_APP_SECRET» — App secret.
- Натисніть «Перевірити» — відповідь «номер +380…, назва «…», якість висока» означає, що ключі правильні.
- У блоці «Отримання повідомлень» скопіюйте «Адресу вебхука» і «Ключ перевірки». У Meta for Developers відкрийте WhatsApp›Configuration›Webhooks«WhatsApp → Configuration → Webhooks», натисніть «Edit», вставте адресу як Callback URL, ключ — як Verify token, збережіть і підпишіться на поле «messages».
- Щойно Meta перевірить адресу, стан у Helomi стане «вебхук активний». Напишіть на номер з WhatsApp — повідомлення з'явиться в «Переписках».
Поки застосунок Meta у режимі розробки, писати можна лише номерам зі списку тестових одержувачів (API Setup›To«API Setup → To»). Щоб писати всім, переведіть застосунок у режим «Live» і пройдіть перевірку бізнесу в Meta Business.
2Написати клієнту першим
Поза вікном 24 годин Meta приймає від компанії лише затверджений шаблон — текст, який ви заздалегідь погодили в WhatsApp Manager. Шаблон із змінною {{1}} дозволяє вставити в нього ваш текст.
- У WhatsApp Manager (Meta Business → «Шаблони повідомлень») створіть шаблон категорії «Utility» (наприклад, «Вітаємо! {{1}}») і дочекайтеся затвердження.
- У Helomi відкрийте вкладку «Підключення» картки номера → «Налаштування бота»: впишіть назву шаблону, мову (uk) і поставте позначку «шаблон має змінну для нашого тексту», натисніть «Зберегти».
- У «Переписках» натисніть «Написати», оберіть канал «WhatsApp» (і номер, якщо їх кілька), впишіть телефон клієнта в міжнародному форматі та текст — він піде у змінну шаблону.
- Коли клієнт відповість, вікно 24 годин відкриється — далі пишіть як у звичайному чаті.
Без свого шаблону працює тестовий «hello_world» (мова en_US) — він надсилає лише свій текст, ваш не передає.
3Відповісти клієнту
- Відкрийте «Переписки» і чат з підписом акаунта номера.
- Напишіть текст у полі внизу й натисніть «Надіслати» — фото піде картинкою з підписом, документ — файлом.
- Якщо з останнього повідомлення клієнта минуло понад 24 години, Helomi надішле шаблон з вашим текстом у змінній; якщо шаблон без змінної — покаже, що зробити.
4Кілька номерів
Кожен номер — окремий акаунт картки зі своїми ключами, перемикачем, налаштуваннями й журналом. Розмови підписані назвою акаунта, відповідь іде саме з того номера, на який написав клієнт.
- У картці «WhatsApp» натисніть «+» унизу праворуч, вкажіть назву (наприклад, «Магазин сумок») і три ключі.
- Увімкніть перемикач у шапці картки нового акаунта — вимкнений акаунт повідомлень не записує.
- Впишіть адресу вебхука й ключ перевірки цього акаунта в тому ж застосунку 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«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").
Додаткова інформація
Цю саму статтю читають ШІ-співробітники Helomi: help("int-whatsapp")