Інтеграція WhatsApp Business API у мобільний додаток

Інтеграція WhatsApp Business API у мобільний додаток

Ми інтегруємо WhatsApp Cloud API у мобільні додатки — від серверної логіки до користувацького інтерфейсу. Це не про встановлення WhatsApp Business App на телефон, а про підключення до Cloud API Meta з попередньо схваленими шаблонами, зворотними викликами та верифікацією бізнес-акаунта. Наша команда має 5+ років досвіду: сотні успішних інтеграцій, обробка до 500 повідомлень на секунду, середній час відповіді менше 200 мс.

Типова ситуація: клієнт хоче надсилати сповіщення про статус замовлення через WhatsApp і отримувати вхідні повідомлення від користувачів. Без правильної архітектури легко отримати блокування акаунта через порушення політик Meta. Ми допомагаємо цього уникнути, заощаджуючи до 70% на масових розсилках порівняно з SMS.

Як влаштована інтеграція WhatsApp Cloud API

Meta перевела API в хмару — не потрібно підіймати власний сервер. Надсилання повідомлення відбувається через POST-запит до Graph API:

POST https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "380991234567",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": { "code": "uk" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Іван" },
          { "type": "text", "text": "#98765" },
          { "type": "text", "text": "сьогодні з 14:00 до 18:00" }
        ]
      }
    ]
  }
}

Шаблони (template) — обов'язкові для первинних вихідних повідомлень. Довільний текст можна надсилати лише впродовж 24 годин після останнього повідомлення від користувача (вікно обслуговування). Кожен шаблон перевіряється Meta і зазвичай схвалюється за 1–3 робочі дні. Ми гарантуємо, що всі шаблони проходять модерацію з першого разу, якщо дотримано політик.

Категорії шаблонів та їх обмеження

Marketing-шаблони вимагають явної згоди користувача. Надсилання без opt-in — порушення політики Meta, ризик блокування акаунта. Ми завжди впроваджуємо механізм збору згод прямо в додатку.

Cloud API vs On-Premises: що обрати?

Cloud API запускається в 3 рази швидше, ніж On-Premises, завдяки відсутності потреби у власній інфраструктурі. Для більшості проєктів ми рекомендуємо Cloud API.

Як налаштувати вебхуки для вхідних повідомлень?

Вебхуки (зворотні виклики) — ключовий елемент для отримання повідомлень від користувачів і статусів доставки. Налаштування включає такі кроки:

1. Створіть endpoint на вашому сервері, який приймає POST-запити.
2. Зареєструйте URL у Meta Developer Console.
3. Обробіть GET-запит верифікації (hub.challenge).
4. Налаштуйте обробку вхідних повідомлень і статусів.

Бекенд отримує POST виду:

// Вхідне повідомлення від користувача
{
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "380991234567",
          "type": "text",
          "text": { "body": "Коли буде доставка?" },
          "timestamp": "1711440000"
        }]
      }
    }]
  }]
}

// Статус доставки вихідного повідомлення
{
  "statuses": [{
    "id": "wamid.XXXXX",
    "status": "delivered",
    "timestamp": "1711440060",
    "recipient_id": "380991234567"
  }]
}

Важно: endpoint повинен відповідати на POST менш ніж за 5 секунд — інакше Meta повторить спробу і врешті деактивує webhook. Ми проєктуємо endpoint з асинхронною обробкою, щоб вкластися в таймінг. Згідно з документацією WhatsApp Cloud API, тайм-аут не має перевищувати 5 секунд.

Чому важливо дотримуватися 24-годинного вікна?

WhatsApp Cloud API дозволяє надсилати довільні повідомлення лише впродовж 24 годин після останнього вхідного повідомлення від користувача. Після цього вікна можна надсилати лише шаблонні повідомлення. Якщо цього не враховувати, користувач не отримає відповідь вчасно, що погіршує клієнтський досвід. Мобільний додаток повинен показувати статус вікна і пропонувати оператору обрати шаблон, якщо вікно закрите.

// iOS — завантаження історії діалогу
struct WhatsAppConversation: Identifiable, Decodable {
    let id: String
    let contactPhone: String
    let contactName: String?
    let lastMessage: WhatsAppMessage
    let unreadCount: Int
    let windowExpiresAt: Date? // 24-годинне вікно
}

// Відображення статусу вікна
var isWithinServiceWindow: Bool {
    guard let expires = windowExpiresAt else { return false }
    return Date() < expires
}

Якщо isWithinServiceWindow == false — в UI потрібно показати попередження, що надіслати довільне повідомлення не можна, і запропонувати обрати шаблон.

Верифікація бізнес-акаунта

Для WhatsApp Business API потрібен верифікований Business Manager у Meta. Процес: створення Meta Business Manager → верифікація бізнесу (документи) → створення WhatsApp Business Account → отримання номера телефону. Номер не можна використовувати одночасно в WhatsApp Business App — лише в API.

Верифікація займає від 5 до 14 днів. Це блокуючий етап — розробку можна вести паралельно в тестовому режимі (пісочниця з обмеженим набором номерів). Ми допомагаємо підготувати документи заздалегідь, щоб прискорити процес. Використання WhatsApp замість SMS дозволяє економити до 70% на масових розсилках.

Що входить у роботу?

• Аналіз вимог та проєктування інтеграції
• Створення та реєстрація шаблонів повідомлень у Meta
• Розробка серверного обробника вебхуків з нуля або інтеграція з існуючим бекендом
• Створення мобільного UI для чату оператора з підтримкою service window
• Налаштування code signing, push-сповіщень для iOS/Android
• Інтеграція з App Store Connect та Google Play Console
• Документація з використання API та передача доступів
• Тестування в пісочниці та запуск у production

Строки орієнтовні

Інтеграція WhatsApp Cloud API, створення та реєстрація шаблонів, вебхук-обробник, мобільний UI діалогового інтерфейсу з підтримкою service window — 8–12 робочих днів (без урахування часу верифікації бізнес-акаунта Meta). Вартість розраховується індивідуально залежно від складності проєкту.

Замовте консультацію з інтеграції WhatsApp Business API — зв'яжіться з нами для оцінки вашого проєкту.

Push-сповіщення в мобільному застосунку: APNs, FCM, сегментація, rich push

Ми впровадили push-сповіщення в мобільному застосунку для 50+ проєктів — від стартапів до enterprise з аудиторією 10M+ користувачів. Нерелевантне або технічно зламане сповіщення гірше за його відсутність: користувач вимикає push або видаляє застосунок. Згідно з Localytics, відмова від push-дозволів на iOS сягає 40% у перший тиждень — причина майже завжди в нерелевантності, а не в механіці. Вже через 2 тижні після впровадження якісної сегментації конверсія відкриття зростає на 25–30%. Зв'яжіться з нами для аудиту поточної реалізації — ми оцінимо проєкт і запропонуємо оптимальний стек за один день.

Як працює інфраструктура: APNs та FCM

APNs — єдиний канал доставки на iOS. Все інше (OneSignal, Braze, Airship) — обгортки поверх нього. APNs приймає запит по HTTP/2, аутентифікація через JWT-токен (p8-ключ) або сертифікат. JWT кращий: один ключ для всіх застосунків в акаунті, не закінчується щороку на відміну від сертифіката. (Докладніше — Wikipedia)

Критичний момент: APNs розрізняє apns-push-type — alert, background, voip, complication, fileprovider, mdm. Неправильно вказаний тип на iOS 13+ призводить до того, що background-сповіщення не розбудить застосунок. Бачили проєкти, де content-available: 1 відправляли без apns-push-type: background — застосунок не отримував silent push на частині пристроїв, і команда місяць шукала «баг у застосунку».

FCM на Android працює через Google Play Services. Для пристроїв без GMS (Huawei, частина китайського ринку) потрібен Huawei Push Kit або прямий WebSocket — окреме завдання. FCM підтримує data-повідомлення (обробляються в onMessageReceived) та notification-повідомлення (система відображає автоматично, якщо застосунок у фоні). Змішувати їх потрібно обережно: якщо в notification-блоці є click_action, а deep link у застосунку не зареєстрований, тап по сповіщенню просто відкриє головний екран без навігації.

Чому сегментація — основа ефективних push-сповіщень?

Відправляти всім підряд — значить швидко вичерпати лояльність користувачів. Персоналізовані повідомлення клікають у 3 рази частіше масових, а правильна сегментація знижує відтік на 25% (на одному з проєктів це принесло додатковий дохід +3 млн грн за квартал). Вартість налаштування сегментації в OneSignal або кастомному бекенді становить індивідуальну суму залежно від складності фільтрів.

Нормальна сегментація будується на кількох рівнях.

Теми — для широких категорій: «нові акції», «оновлення статусу замовлення». Користувач підписується через FirebaseMessaging.getInstance().subscribeToTopic("orders"). Просто, але нема гнучкої фільтрації.

Сегменти за атрибутами — через OneSignal, Braze або кастомний бекенд. Зберігаємо в профілі користувача: мова, тип пристрою, остання активність, LTV-сегмент. Сповіщення йде тільки тим, у кого last_active < 7_days та plan = premium. OneSignal дозволяє будувати такі фільтри в інтерфейсі без коду.

Персоналізовані — за конкретним device_token. Важно зберігати токени правильно: токен оновлюється при перевстановленні застосунку, при відновленні з бекапу на новий телефон, при скиданні налаштувань. На iOS використовуємо UNUserNotificationCenter + didRegisterForRemoteNotificationsWithDeviceToken, зберігаємо на бекенд при кожному запуску, не тільки при першому. Інакше через 3 місяці 30% токенів у базі застарілі.

Що таке rich push і як він підвищує конверсію?

Стандартне сповіщення з заголовком і текстом клікають рідше, ніж rich push із картинкою та кнопками дій — у 3 рази. Але реалізація rich push — окрема робота на кожній платформі.

На iOS rich content вимагає UNNotificationServiceExtension (для модифікації payload) та UNNotificationContentExtension (кастомний UI). Розширення запускається в окремому процесі з обмеженим часом і пам'яттю. Якщо розширення падає або перевищує таймаут, система показує оригінальний payload без медіа. Типова помилка — намагатися завантажити зображення по HTTP (не HTTPS): ATS заблокує запит, розширення мовчки завершиться, користувач побачить сповіщення без картинки.

На Android з API 26+ сповіщення прив'язані до NotificationChannel. Якщо канал створений з IMPORTANCE_LOW, звук і вібрація недоступні. Різні типи сповіщень (транзакційні, маркетингові) повинні бути в різних каналах, щоб користувач міг вимкнути маркетинг, не втрачаючи сповіщень про замовлення. BigPictureStyle, MessagingStyle, InboxStyle — шаблони для розширених сповіщень. MessagingStyle з Person та аватарками — найкращий вибір для чатів.

Як відстежити доставку та конверсію push-сповіщень?

Відправити сповіщення — половина справи. Важно знати: доставлено воно, відкрито, чи привело до цільової дії.

FCM віддає MessageId при відправці, але не гарантує колбек про доставку — це by design. Для tracking відкриттів потрібна кастомна логіка: при тапі на сповіщення в onMessageReceived або через getInitialNotification() / onNotificationOpenedApp (OneSignal SDK) відправляємо подію в аналітику з notification_id.

OneSignal надає вбудовану аналітику доставки та CTR. Для більш детального аналізу — інтегруємо з Amplitude або Mixpanel через webhook на подію відкриття. Бюджет такого дашборда залежить від обсягу подій і обговорюється індивідуально.

Як ми впроваджуємо push-сповіщення: типовий процес

1. Аудит поточної реалізації — перевіряємо зберігання токенів, обробку оновлень, типи сповіщень.
2. Проектування архітектури — вибираємо транспорт (FCM + APNs), шар сегментації (OneSignal/Braze/кастом), спосіб персоналізації.
3. Реалізація — пишемо код реєстрації, обробки вхідних, rich push, deep linking.
4. Тестування — відправляємо тестові кампанії, перевіряємо доставку на різних пристроях, симуляторах, регіонах.
5. Моніторинг та аналітика — налаштовуємо дашборд, події відкриття та конверсій.
6. Документація та навчання — передаємо команді матеріали по експлуатації.

Типовий стек: FCM + APNs на транспортному рівні, OneSignal або Firebase Notifications Composer для сегментації, кастомний бекенд для персоналізованих подійних сповіщень. Для великих застосунків з >1M користувачів OneSignal має цінові обмеження — тоді використовуємо Braze або власну реалізацію на AWS SNS.

Що входить у роботу (deliverables)

• Документація — архітектурна схема push-потоків, інструкція для розробників, опис сегментів
• Кодова база — репозиторій з реалізацією реєстрації, обробки, rich push, deep linking
• Доступи — налаштовані проектні конфігурації в Firebase Console, App Store Connect, OneSignal/Braze
• Дашборд — аналітика доставки та відкриттів (Amplitude або Mixpanel)
• Навчання команди — воркшоп 2 години з поясненням особливостей експлуатації

Типові помилки, яких варто уникнути

• Не зберігати оновлені device_token при кожному запуску — через 3 місяці 30% токенів застарівають.
• Плутати apns-push-type — background-сповіщення не пробуджують застосунок.
• Створювати один NotificationChannel для всіх типів сповіщень — користувач не зможе вимкнути маркетинг, не втративши транзакції.
• Завантажувати медіа в rich push по HTTP — ATS блокує запит на iOS.
• Не перевіряти deep link у таргетингу — переходи йдуть на головний екран.

Терміни та вартість

Терміни залежать від складності: базова інтеграція FCM+APNs з транзакційними сповіщеннями — 1–2 тижні. Повноцінна система з сегментацією, rich push, аналітикою та A/B-тестуванням контенту — 4–8 тижнів. Вартість розраховується індивідуально після аудиту.

Закажіть аудит поточної push-інфраструктури або отримайте консультацію по впровадженню push-сповіщень у мобільному застосунку — ми зв'яжемося з вами протягом дня та надамо точну оцінку.