Интеграция 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": "ru" },
    "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).