> ## 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.

# Implementar um endpoint de WhatsApp Flow

> Gerencie verificações de integridade (health checks), notificações de erro, troca de dados, navegação e conclusão de Flows por meio da YCloud.

Use um endpoint de Flow quando precisar carregar telas dinamicamente ou processar dados
enviados por um usuário do WhatsApp. Configure sua URL pública HTTPS como `endpointUri`
ao criar um Flow ou atualizar seus metadados.

Este guia descreve as requisições em JSON simples que a YCloud encaminha para o seu endpoint.
Ele não descreve uma conexão direta com o endpoint de dados criptografados da Meta.
Consulte [Gerenciar WhatsApp Flows](/pt/api-reference/guides/whatsapp-platform/manage-whatsapp-flows)
para criação, pré-visualização, publicação e gerenciamento do ciclo de vida de Flows.

## Antes de começar

* Disponibilize um endpoint público HTTPS que aceite requisições `POST`.
* Retorne o JSON em até 15 segundos.
* Defina as telas e seus campos de dados no JSON do seu Flow.
* Gere um `flow_token` ao enviar a mensagem do Flow para poder correlacionar
  a interação com a sessão da sua aplicação.
* Use validação no lado do servidor antes de aceitar os dados enviados.

## Fluxo de requisição

1. O usuário abre ou interage com um Flow no WhatsApp.
2. A YCloud encaminha uma requisição JSON para o endpoint configurado.
3. Seu endpoint lê `action` e processa a requisição.
4. Sua resposta JSON seleciona uma tela e fornece seus dados, ou conclui o Flow.

## Processar uma verificação de integridade (health check)

Um health check contém `action: ping`:

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

Retorne:

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

Mantenha esse caminho leve. Não execute transações de negócio durante um health check.

## Processar uma notificação de erro

As notificações de erro incluem `data.error` e `data.error_message`. Elas podem usar
`INIT` ou `data_exchange` como a ação. Verifique a existência desses dados de erro antes de rotear
requisições comuns por ação.

```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"
  }
}
```

Registre o erro para investigação e retorne uma confirmação:

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

## Processar a troca de dados

```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"
}
```

| Campo | Significado |
| - | - |
| `version` | Versão da Data API, `3.0` nestas requisições. |
| `action` | `INIT` ao abrir o Flow, `data_exchange` ao enviar uma tela ou `BACK` ao navegar de volta. |
| `screen` | ID da tela atual. Pode estar ausente para `INIT` ou `BACK`. Não nomeie uma tela de Flow como `SUCCESS`; esse valor é reservado para conclusão. |
| `data` | Campos da tela ou dados enviados. Pode estar ausente para `INIT` ou `BACK`. |
| `flow_token` | Token de sessão fornecido por você na mensagem do Flow. |

Processe cada ação de acordo com as telas que você definiu:

| Ação | Comportamento de resposta |
| - | - |
| `INIT` | Retorne a tela inicial e seus dados de partida. |
| `data_exchange` | Valide os dados enviados e, em seguida, retorne a próxima tela ou um erro de validação na mesma tela. |
| `BACK` | Retorne a tela anterior com os dados necessários. |

### Navegar para uma tela

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

O `screen` deve existir no JSON do seu Flow. Seu esquema de dados declarado deve aceitar
os campos em `data`.

### Retornar um erro de validação

Permaneça na tela atual e retorne um campo de erro que sua tela exibe:

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

### Concluir o Flow

Retorne `screen: SUCCESS` com `extension_message_response.params`. Inclua o
`flow_token` original e quaisquer campos de resultado adicionais que desejar na mensagem
de resposta do 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"
      }
    }
  }
}
```

Isso encerra o Flow e envia uma mensagem de resposta do Flow para a conversa. Analise o
resultado a partir do [webhook de resposta de Flow recebida](/pt/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples#inbound-interactive-flow-response-message).

## Exemplo de implementação

Este exemplo em Express processa todas as três categorias de requisição. Faça a correspondência dos
IDs de tela e campos de resposta com o seu próprio JSON do Flow. Configure quaisquer controles de acesso
ao endpoint utilizados pela sua implantação antes deste manipulador.

```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);
```

## Verificar o endpoint

Teste `ping`, confirmação de erro, `INIT` sem `screen` ou `data`, envios válidos
e inválidos, `BACK` e conclusão com `SUCCESS`. Verifique o limite de resposta
de 15 segundos e confirme se o webhook de conclusão transporta o seu
`flow_token` original. Visualize o Flow antes de publicá-lo.


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