> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Обрабатывайте проверки работоспособности (health checks) Flow, уведомления об ошибках, обмен данными, навигацию и завершение через YCloud.

Используйте эндпоинт Flow, когда вам требуется динамически загружать экраны или обрабатывать данные,
отправленные пользователем WhatsApp. Настройте ваш публичный HTTPS URL в качестве `endpointUri`
при создании Flow или обновлении его метаданных.

В этом руководстве описываются обычные JSON-запросы, которые YCloud пересылает на ваш эндпоинт.
Оно не описывает прямое подключение к зашифрованному эндпоинту данных Meta.
Информацию о создании, предварительном просмотре, публикации и управлении жизненным циклом Flow см. в руководстве [Управление WhatsApp Flows](/ru/api-reference/guides/whatsapp-platform/manage-whatsapp-flows).

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

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

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

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

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

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "action": "ping"
}
```

Верните:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "status": "active"
  }
}
```

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

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

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "version": "3.0",
  "flow_token": "FLOW_SESSION_TOKEN",
  "action": "data_exchange",
  "data": {
    "error": "ERROR_KEY",
    "error_message": "Error details"
  }
}
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "acknowledged": true
  }
}
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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` | Верните предыдущий экран с необходимыми для него данными. |

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "screen": "CONFIRMATION",
  "data": {
    "user_email": "customer@example.com"
  }
}
```

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

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

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "screen": "DETAILS",
  "data": {
    "error_message": "Please enter a valid email address."
  }
}
```

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

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "screen": "SUCCESS",
  "data": {
    "extension_message_response": {
      "params": {
        "flow_token": "FLOW_SESSION_TOKEN",
        "appointment_id": "APPOINTMENT_ID"
      }
    }
  }
}
```

Это действие закрывает Flow и отправляет ответное сообщение Flow в чат. Извлеките
результат из [входящего вебхука с ответом Flow](/ru/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples#inbound-interactive-flow-response-message).

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

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

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 перед его публикацией.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.