Implementar um endpoint de WhatsApp Flow

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

O usuário abre ou interage com um Flow no WhatsApp.
A YCloud encaminha uma requisição JSON para o endpoint configurado.
Seu endpoint lê action e processa a requisição.
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:

{
  "action": "ping"
}

Retorne:

{
  "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.

{
  "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:

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

Processar a troca de dados

{
  "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

{
  "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:

{
  "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.

{
  "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.

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.

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.

Primeiros passos

Guias

Endpoints

Webhooks

Implementar um endpoint de WhatsApp Flow

Antes de começar

Fluxo de requisição

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

Processar uma notificação de erro

Processar a troca de dados

Navegar para uma tela

Retornar um erro de validação

Concluir o Flow

Exemplo de implementação

Verificar o endpoint

​Antes de começar

​Fluxo de requisição

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

​Processar uma notificação de erro

​Processar a troca de dados

​Navegar para uma tela

​Retornar um erro de validação

​Concluir o Flow

​Exemplo de implementação

​Verificar o endpoint

Antes de começar

Fluxo de requisição

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

Processar uma notificação de erro

Processar a troca de dados

Navegar para uma tela

Retornar um erro de validação

Concluir o Flow

Exemplo de implementação

Verificar o endpoint