Как добавить WhatsApp в SaaS с помощью Embedded Signup и Coexistence
SaaS добавляет WhatsApp, подключая номер каждого клиента через Embedded Signup в режиме Coexistence от Meta. Номер продолжает работать в приложении WhatsApp Business. С Partner API от easyCoexistence одна сессия подключения на клиента проводит этот процесс на размещённой странице. Meta доставляет сообщения номера на указанный вами webhook_url, а ваш бэкенд отвечает через Cloud API с токеном самого клиента.
Фиксированная пропускная способность номера, который используется и в приложении WhatsApp Business, и в Cloud API.
Самая ранняя версия приложения WhatsApp Business, с которой номер клиента может подключиться через Coexistence.
На какой срок назад Meta может передать историю чатов при подключении; синхронизировать её нужно в течение 24 часов.
Окно обслуживания клиентов WhatsApp после сообщения или звонка пользователя; каждое новое сообщение сбрасывает его.
Дата, с которой Meta объявила устаревшими Embedded Signup v2 и v3; интеграции переведены на v4.
Из каких частей состоит интеграция с WhatsApp?
Их пять. easyCoexistence берёт на себя первую и последнюю. Ваш продукт отвечает за логику диалога, входящие и то, что пишут ваша модель или сотрудники ваших клиентов, а Meta передаёт сообщения между номером и вашим сервером:
Что меняет Coexistence для ваших клиентов?
Они сохраняют свой номер и свой телефон. Приложение WhatsApp Business продолжает работать рядом с Cloud API: сотрудники отвечают с телефона, а ваш продукт отвечает через API. Всё, что отправлено из приложения, приходит на ваш webhook_url как smb_message_echoes. С этим связаны три ограничения: номер отправляет с фиксированной скоростью 20 сообщений в секунду, шаблоны может отправлять только API, а Meta отключает номер, если телефон неактивен около 14 дней.
Как выглядит шаг подключения в вашем продукте?
Кнопка «Подключить WhatsApp» вызывает POST /connect-sessions с вашего бэкенда и передаёт redirect_url, id клиента как external_ref, а также webhook_url с webhook_verify_token. Так Meta с первой минуты направляет номер к вам. Клиент подтверждает короткий чек-лист на размещённой странице, проходит всплывающее окно Meta, сканирует QR-код приложением WhatsApp Business и возвращается к вам с connection_id. Вопрос о том, запускать ли Embedded Signup из собственного приложения Tech Provider, разобран в руководстве по Embedded Signup.
Как сообщения попадают на ваш бэкенд?
От Meta напрямую на webhook_url, без остановки в easyCoexistence и без хранения копии. Поле messages содержит то, что пишут клиенты, и статусы отправленного вами, а smb_message_echoes содержит то, что сотрудники отправляют из приложения. Meta подписывает каждую доставку app secret easyCoexistence, который никому не передаётся, поэтому для аутентификации используется длинный случайный секрет в пути URL. Два номера в одном WhatsApp Business Account используют один адрес назначения: маршрутизируйте по value.metadata.phone_number_id.
Как ваш бэкенд отвечает и отправляет шаблоны?
Через Graph API Meta и токен клиента из GET /connections/{id}?credentials=1, который также возвращает send_endpoint. Свободный текст уходит в течение 24 часов после последнего сообщения человека; после этого проходит только шаблон, одобренный Meta:
- Ответ: POST /<
PHONE_NUMBER_ID>/messages с type text, в пределах окна. - Шаблон: тот же вызов с type template, именем шаблона и кодом языка.
- Создание шаблона: POST /<
WABA_ID>/message_templates, затем опрашивайте его статус, так как результаты проверки не поступают наwebhook_url. - Медиа: POST /<
PHONE_NUMBER_ID>/media для загрузки; входящие медиа приходят как ID, который забирается тем же токеном.
curl -X POST "$SEND_ENDPOINT" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511987654321",
"type": "text",
"text": { "body": "Your table for 4 is booked for 8 pm." }
}'Может ли ваш продукт импортировать существующие чаты клиента?
Один раз, при подключении. Если в сессии задан webhook_url, easyCoexistence просит Meta передать контакты номера и, если клиент согласится в приложении, историю чатов за последние 180 дней. Она приходит как события smb_app_state_sync и history. Meta разрешает это только в течение 24 часов после подключения, поэтому эндпоинт должен отвечать до отправки ссылки. Руководство по истории чатов описывает форматы данных.
Кто платит Meta за сообщения?
Ваш клиент. Meta выставляет счёт за сообщения, которые ваш бэкенд отправляет через API, на WhatsApp Business Account самого клиента, с платёжным методом, который он добавляет там. Бизнес без платёжного метода не может отправлять маркетинговые шаблоны. easyCoexistence списывает плату с вашего аккаунта за каждый подключённый номер, не берёт плату за сообщения и работает без наценки на цены Meta.
Что происходит, когда номер отключается?
Ваш events URL получает событие connection.disconnected с причиной от Meta, если она известна. PRIMARY_INACTIVITY означает правило 14 дней; новая сессия подключения для этого клиента возвращает тот же номер. connection.token_missing означает, что номер подключился без токена клиента: он получает сообщения, но не может отправлять, пока новая сессия его не переподключит.
Распространённые ошибки
- Отправка ссылки подключения до того, как ваш эндпоинт начнёт отвечать. Импорт истории выполняется один раз, в течение 24 часов после подключения, и содержимое, отправленное до того, как ваш URL заработает, теряется.
- Ответ свободным текстом после закрытия окна. Когда с последнего сообщения человека проходит 24 часа, проходит только одобренный шаблон.
- Рассылка с одного номера на полной скорости. Номер Coexistence отправляет 20 сообщений в секунду, поэтому ставьте отправки каждого номера в очередь с этой скоростью.
- Ожидание, что сотрудники будут отправлять шаблоны с телефона. В Coexistence шаблоны отправляет только API, поэтому организуйте отправку шаблонов в вашем продукте.
easyCoexistence добавляет WhatsApp в ваш SaaS с Embedded Signup и Coexistence от Meta на размещённой странице с вашим названием. Клиенты сохраняют свой номер и приложение WhatsApp Business. Meta доставляет сообщения на ваш сервер, а события приходят подписанными. Тот же API подключает Instagram, Facebook, TikTok, YouTube, LinkedIn, а также другие каналы: их число растёт. От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений, первые 3 дня бесплатно.
Часто задаваемые вопросы
Может ли клиент подключить номер, который уже работает у другого провайдера WhatsApp API?
Пока номер там работает, нет. Размещённый чек-лист требует номер без другого провайдера API и без инструментов автоматизации, поэтому клиент сначала отключает номер у того провайдера.
Может ли мой SaaS отправлять шаблоны WhatsApp для своих клиентов?
Да, через Cloud API с токеном каждого клиента: создайте шаблон в WhatsApp Business Account клиента, дождитесь проверки Meta, затем отправьте его.
Читает ли easyCoexistence сообщения клиентов WhatsApp?
Нет. Meta доставляет сообщения номера напрямую на указанный вами webhook_url. Номер без webhook_url уходит на адрес обратного вызова easyCoexistence, где сообщения отбрасываются без сохранения.
Сколько стоит easyCoexistence за один номер WhatsApp?
От US$ 9 до US$ 0,75 за номер в месяц, по ступени общего числа подключений, первые 3 дня бесплатно. Плату Meta за сообщения получает WhatsApp Business Account каждого клиента.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на