Партнёское приложение WhatsApp Cloud

Создание партнёрского приложения доступно:

1. пользователям со статусом "интегратор"
2. на странице создания приложения

Описание поле формы:

1. API token - ваш токен для входящих запросов на наш сервер
   1. Для авторизации используйте заголовок
      Authorization: Token <API token>
2. Название - произвольное название вашего приложения
3. Webhook URL (CALLBACK_URL) - адрес вашего обработчика для приёма входящих вебхуков с сервера Facebook
4. Redirect URL - адрес на который будет переадресован пользователь после завершения процедуры привязки номера. В случае успеха будет передан URL параметр waba_id.

На ваш обработчик Webhook URL (CALLBACK_URL) вы будете получать следующие события:

• messages
• message_echoes
• calls
• consumer_profile
• messaging_handovers
• group_lifecycle_update
• group_participants_update
• group_settings_update
• group_status_update
• smb_message_echoes
• smb_app_state_sync
• history
• account_settings_update

После сохранения приложения вы получите:

1. App ID - уникальный идентификатор приложения. Необходим для получения URL авторизации Embedded Signup.
   1. Для получения URL авторизации используйте адрес https://separator.biz/api/waba/es-link/
   2. В теле запроса передайте ваш App ID в параметре partner_app_id
      
2. Verify token - необходим для подтверждения вашего адреса Webhook URL. Meta отправит GET запрос на ваш Webhook URL. Вы должны ответить на этот запрос.
   1. Валидация. Чтобы проверить GET-запросы, сравните значение `hub.verify_token` в запросе со строкой верификации, сохранённой на вашем сервере. Если значения совпадают — запрос валиден, если нет — невалиден.
   2. Ответ. Если запрос валиден, верните HTTP-статус `200` и значение `hub.challenge`. Если запрос невалиден, верните HTTP-статус уровня `400` или любой другой статус, кроме `200`.

Примеры использования:

1. Базовый адрес API: https://separator.biz/api/
2. Авторизация через HTTP-заголовок: Authorization: Token <API_TOKEN>

Получение URL авторизации Embedded Signup

Запрос выполняется методом `POST`.

POST https://separator.biz/api/waba/es-link/
Authorization: Token <API_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "partner_app_id": "<PARTNER_APP_UUID>"
}

Пример ответа:

{
  "url": "https://www.facebook.com/v25.0/dialog/oauth?..."
}

Поле `url` - это URL авторизации Embedded Signup.

На этот адрес нужно перенаправить пользователя для авторизации Facebook и подключения WhatsApp Business Account.

После завершения Facebook callback на стороне separator.biz пользователь будет перенаправлен на Redirect URL партнерского приложения.

В query-параметре будет передан `waba_id`:

https://partner.example.com/callback?waba_id=<WABA_ID>

Endpoint для проверки webhook партнерского приложения

Facebook проверяет Webhook URL, указанный в партнерском приложении.

Endpoint партнера должен вернуть `hub.challenge` обычным текстом, если `hub.verify_token` совпадает с verify token партнерского приложения.

Пример запроса от Facebook:

GET https://partner.example.com/webhook?hub.mode=subscribe&hub.challenge=123456&hub.verify_token=<PARTNER_APP_VERIFY_TOKEN>

Минимальная логика обработчика:

if request.GET["hub.mode"] == "subscribe" and request.GET["hub.verify_token"] == PARTNER_APP_VERIFY_TOKEN:
    return HttpResponse(request.GET["hub.challenge"], content_type="text/plain")

return HttpResponse("Forbidden", status=403)

Получение номеров по `waba_id`

Используйте `waba_id`, который был получен в Redirect URL после Embedded Signup.

GET https://separator.biz/api/waba/partner/<WABA_ID>/phone_numbers
Authorization: Token <API_TOKEN>
Accept: application/json

На стороне separator.biz этот запрос будет отправлен в Meta как:

GET https://graph.facebook.com/v{APP_API_VERSION}.0/<WABA_ID>/phone_numbers
Authorization: Bearer <WABA_ACCESS_TOKEN_FROM_SEPARATOR_DB>

separator.biz возвращает чистый ответ Meta.

Proxy-запросы к Meta API

Proxy сохраняет формат тела запроса как в Meta Cloud API.

Отличия:

• адрес запроса - https://separator.biz/api/waba/partner/
• используется API token партнера;
• Meta Graph API version берется из настроек WABA App в separator.biz;
• Meta access token берется из базы separator.biz.

Отправка текстового сообщения

POST https://separator.biz/api/api/waba/partner/<PHONE_NUMBER_ID>/messages
Authorization: Token <API_TOKEN>
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "77010000000",
  "type": "text",
  "text": {
    "body": "Hello from partner"
  }
}

Загрузка media

POST https://separator.biz/api/api/waba/partner/<PHONE_NUMBER_ID>/media
Authorization: Token <API_TOKEN>
Content-Type: multipart/form-data

messaging_product=whatsapp
file=@image.jpg

Получение настроек телефона

GET https://separator.biz/api/api/waba/partner/<PHONE_NUMBER_ID>/settings
Authorization: Token <API_TOKEN>
Accept: application/json

Отправка CTWA conversion event

POST https://separator.biz/api/api/waba/partner/<DATASET_ID>/events
Authorization: Token <API_TOKEN>
Content-Type: application/json

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1710000000,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "page_id": "<PAGE_ID>"
      },
      "custom_data": {
        "currency": "USD",
        "value": 10.0
      }
    }
  ]
}

Примечания

• Партнер использует token separator.biz, а не Meta token.
• Статус и тело ответа возвращаются от Meta без дополнительной обработки.
• Для phone endpoints object id - это PHONE_NUMBER_ID.
• Для WABA endpoints object id - это WABA_ID
• Для events object id - это DATASET_ID.
• Документация на сервере Facebook

Обновлено: 18.05.2026 09:06