Реализация эндпоинта WhatsApp Flow

Используйте эндпоинт Flow, когда вам требуется динамически загружать экраны или обрабатывать данные, отправленные пользователем WhatsApp. Настройте ваш публичный HTTPS URL в качестве endpointUri при создании Flow или обновлении его метаданных. В этом руководстве описываются обычные JSON-запросы, которые YCloud пересылает на ваш эндпоинт. Оно не описывает прямое подключение к зашифрованному эндпоинту данных Meta. Информацию о создании, предварительном просмотре, публикации и управлении жизненным циклом Flow см. в руководстве Управление WhatsApp Flows.

Перед началом работы

Предоставьте публичный эндпоинт HTTPS, принимающий запросы POST.
Возвращайте JSON в течение 15 секунд.
Определите экраны и их поля данных в JSON вашего Flow.
Сгенерируйте flow_token при отправке сообщения Flow, чтобы сопоставить взаимодействие с сессией вашего приложения.
Используйте валидацию на стороне сервера перед принятием отправленных данных.

Поток обработки запросов

Пользователь открывает Flow или взаимодействует с ним в WhatsApp.
YCloud пересылает JSON-запрос на ваш настроенный эндпоинт.
Ваш эндпоинт считывает action и обрабатывает запрос.
Ваш JSON-ответ выбирает экран и предоставляет для него данные, либо завершает Flow.

Обработка проверки работоспособности (health check)

Проверка работоспособности содержит action: ping:

{
  "action": "ping"
}

Верните:

{
  "data": {
    "status": "active"
  }
}

Сохраняйте этот путь легковесным. Не выполняйте бизнес-транзакции во время проверки работоспособности.

Обработка уведомления об ошибке

Уведомления об ошибках содержат data.error и data.error_message. В качестве действия они могут использовать INIT или data_exchange. Проверяйте наличие данных об этих ошибках перед маршрутизацией обычных запросов по действию (action).

{
  "version": "3.0",
  "flow_token": "FLOW_SESSION_TOKEN",
  "action": "data_exchange",
  "data": {
    "error": "ERROR_KEY",
    "error_message": "Error details"
  }
}

Зафиксируйте ошибку для расследования и верните подтверждение:

{
  "data": {
    "acknowledged": true
  }
}

Обработка обмена данными

{
  "version": "3.0",
  "screen": "DETAILS",
  "action": "data_exchange",
  "data": {
    "email": "customer@example.com"
  },
  "flow_token": "FLOW_SESSION_TOKEN"
}

Поле	Значение
`version`	Версия Data API, `3.0` в этих запросах.
`action`	`INIT` при открытии Flow, `data_exchange` при отправке экрана или `BACK` при переходе назад.
`screen`	Идентификатор текущего экрана. Может отсутствовать для `INIT` или `BACK`. Не называйте экран Flow значением `SUCCESS` — это значение зарезервировано для завершения.
`data`	Поля экрана или отправленные входные данные. Может отсутствовать для `INIT` или `BACK`.
`flow_token`	Токен сессии, указанный вами в сообщении Flow.

Обрабатывайте каждое действие в соответствии с определенными вами экранами:

Действие	Поведение ответа
`INIT`	Верните начальный экран и его исходные данные.
`data_exchange`	Выполните валидацию отправленных данных, затем верните следующий экран или ошибку валидации на том же экране.
`BACK`	Верните предыдущий экран с необходимыми для него данными.

Переход к экрану

{
  "screen": "CONFIRMATION",
  "data": {
    "user_email": "customer@example.com"
  }
}

screen должен присутствовать в вашем JSON Flow. Объявленная для него схема данных должна принимать поля из data.

Возврат ошибки валидации

Останьтесь на текущем экране и верните поле ошибки, отображаемое вашим экраном:

{
  "screen": "DETAILS",
  "data": {
    "error_message": "Please enter a valid email address."
  }
}

Завершение Flow

Верните screen: SUCCESS со значением extension_message_response.params. Включите исходный flow_token и любые дополнительные поля результатов, которые требуются в ответном сообщении Flow.

{
  "screen": "SUCCESS",
  "data": {
    "extension_message_response": {
      "params": {
        "flow_token": "FLOW_SESSION_TOKEN",
        "appointment_id": "APPOINTMENT_ID"
      }
    }
  }
}

Это действие закрывает Flow и отправляет ответное сообщение Flow в чат. Извлеките результат из входящего вебхука с ответом Flow.

Пример реализации

В этом примере для Express обрабатываются все три категории запросов. Сопоставьте идентификаторы экранов и поля ответов с вашим собственным Flow JSON. Подключите все механизмы контроля доступа к эндпоинту, используемые в вашей среде, до этого обработчика.

import express from "express";

const app = express();
app.use(express.json({ limit: "256kb" }));

app.post("/flow-endpoint", (req, res) => {
  if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
    return res.status(400).json({ error: "Expected a JSON object" });
  }
  const { action, screen, flow_token: flowToken } = req.body;
  const data = req.body.data ?? {};

  if (action === "ping") {
    return res.json({ data: { status: "active" } });
  }
  if (data.error) {
    // Record the error without logging sensitive form data or session tokens.
    return res.json({ data: { acknowledged: true } });
  }
  if (!flowToken) {
    return res.status(400).json({ error: "Missing flow_token" });
  }
  if (action === "INIT" || action === "BACK") {
    return res.json({ screen: "DETAILS", data: {} });
  }
  if (action === "data_exchange" && screen === "DETAILS") {
    if (typeof data.email !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
      return res.json({
        screen: "DETAILS",
        data: { error_message: "Please enter a valid email address." }
      });
    }
    return res.json({ screen: "CONFIRMATION", data: { user_email: data.email } });
  }
  if (action === "data_exchange" && screen === "CONFIRMATION") {
    return res.json({
      screen: "SUCCESS",
      data: { extension_message_response: { params: { flow_token: flowToken } } }
    });
  }
  return res.status(400).json({ error: "Unsupported action or screen" });
});

app.listen(3000);

Проверка эндпоинта

Проверьте ping, подтверждение ошибок, INIT без screen или data, корректную и некорректную отправку данных, BACK, а также завершение SUCCESS. Проверьте 15-секундный лимит ответа и убедитесь, что завершающий вебхук содержит ваш исходный flow_token. Выполните предварительный просмотр Flow перед его публикацией.

Начало работы

Руководства

Конечные точки

Webhooks

Реализация эндпоинта WhatsApp Flow

Перед началом работы

Поток обработки запросов

Обработка проверки работоспособности (health check)

Обработка уведомления об ошибке

Обработка обмена данными

Переход к экрану

Возврат ошибки валидации

Завершение Flow

Пример реализации

Проверка эндпоинта

​Перед началом работы

​Поток обработки запросов

​Обработка проверки работоспособности (health check)

​Обработка уведомления об ошибке

​Обработка обмена данными

​Переход к экрану

​Возврат ошибки валидации

​Завершение Flow

​Пример реализации

​Проверка эндпоинта

Перед началом работы

Поток обработки запросов

Обработка проверки работоспособности (health check)

Обработка уведомления об ошибке

Обработка обмена данными

Переход к экрану

Возврат ошибки валидации

Завершение Flow

Пример реализации

Проверка эндпоинта