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

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

WhatsApp Business API — це не WhatsApp Business App на телефоні. Це Cloud API (hosted by Meta) або On-Premises API для бізнесів з верифікованим аккаунтом, які хочуть відправляти сповіщення, вести діалоги та автоматизувати комунікацію через WhatsApp. Вся інтеграція — серверна, мобільний додаток виступає управляючим інтерфейсом.

Архітектура WhatsApp Cloud API

Meta перейшла на Cloud API в 2022 році — це hosted рішення без необхідності поднімати On-Premises інстанс. Отправка сообщения:

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 годин після останнього сообщення від користувача (customer service window). Кожен шаблон повинен бути узгоджений Meta — зазвичай 1–3 робочих дні.

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

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

Webhooks: вхідні сообщення та статусы

Webhooks настраїються в Meta Developer Console. Бекенд отримує POST на ваш endpoint:

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

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

Важливо: webhook endpoint повинен верифікуватися Meta (GET-запит з hub.challenge) та обробляти POST за < 5 секунд — інакше Meta повторить спробу та в итогу деактивує webhook.

Мобільна частина: діалоговий інтерфейс

Мобільний додаток у цій інтеграції — це операторський або адміністраторський інтерфейс:

// 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.

Верифікація займає від кількох днів до кількох тижнів. Це блокуючий етап — розробку можна вести паралельно в тестовому режимі (є sandbox з обмеженим набором номерів).

Терміни

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