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

# Gerenciar WhatsApp Flows

> Crie, valide, visualize, publique e desative experiências estruturadas no WhatsApp.

## O que é

Os WhatsApp Flows são experiências de várias telas executadas diretamente no WhatsApp. Use-os para tarefas estruturadas, como cadastro, agendamento de consultas, captação de leads, feedback ou configuração de produtos.

## Antes de começar

* Conecte a WABA que será a proprietária do Flow.
* Projete as telas e o modelo de dados em um documento Flow JSON válido.
* Decida se o Flow precisa de um endpoint de dados.
* Escolha categorias que descrevam o caso de uso do Flow.
* Mantenha o novo trabalho em `DRAFT` até que a validação e a visualização prévia estejam concluídas.

## Como funciona

1. Crie um Flow com metadados e, opcionalmente, sua estrutura JSON.
2. Recupere o Flow e corrija todos os erros de validação.
3. Atualize os metadados ou envie um arquivo Flow JSON revisado.
4. Gere uma URL pública de pré-visualização para testes com partes interessadas.
5. Publique o Flow quando ele estiver pronto para mensagens.
6. Desative um Flow publicado quando ele não dever mais ser utilizado.

Flows em rascunho podem ser editados ou excluídos. Flows publicados possuem regras de ciclo de vida mais rígidas, portanto, teste antes de publicar.

## Requisição

### Criar um Flow

`POST /whatsapp/flows`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/whatsapp/flows \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "wabaId": "WABA_ID",
    "name": "Appointment booking",
    "categories": ["APPOINTMENT_BOOKING"],
    "flowJson": "{\"version\":\"5.0\",\"screens\":[]}",
    "publish": false,
    "endpointUri": "https://example.com/whatsapp/flow"
  }'
```

### Atualizar a estrutura do Flow

`PATCH /whatsapp/flows/{flowId}/assets`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PATCH \
  https://api.ycloud.com/v2/whatsapp/flows/FLOW_ID/assets \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --form "flowJson=@./flow.json;type=application/json"
```

### Visualizar e publicar

Gere uma pré-visualização com `GET /whatsapp/flows/{flowId}/preview` e, em seguida, publique com `POST /whatsapp/flows/{flowId}/publish`.

## Resposta

A criação retorna o novo ID do Flow e o resultado da operação.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "FLOW_ID",
  "success": true
}
```

A recuperação retorna o estado do ciclo de vida do Flow e os detalhes de validação.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "FLOW_ID",
  "name": "Appointment booking",
  "status": "DRAFT",
  "categories": ["APPOINTMENT_BOOKING"],
  "validationErrors": []
}
```

## Ciclo de vida do Flow

| Estado | Significado |
| - | - |
| `DRAFT` | O Flow pode ser editado, validado, pré-visualizado ou excluído. |
| `PUBLISHED` | O Flow pode ser referenciado por mensagens. |
| `DEPRECATED` | O Flow não deve mais ser utilizado para novas interações. |
| `BLOCKED` ou `THROTTLED` | A Meta restringiu o Flow; inspecione os detalhes de status. |

Use Webhooks `whatsapp.flow.status_change` para processar atualizações assíncronas do ciclo de vida.

## Limites e solução de problemas

* Trate cada apontador de erro de validação como um local a ser corrigido no Flow JSON.
* As URLs de pré-visualização são públicas; não inclua segredos de produção ou dados
  de teste confidenciais.
* A publicação é um limite de ciclo de vida. Confirme o conteúdo e o comportamento do endpoint
  primeiro.
* Exclua um Flow apenas quando o estado atual dele permitir a exclusão.
* Crie versões do Flow JSON e do comportamento do endpoint juntos quando eles trocarem dados.

<CardGroup cols={2}>
  <Card title="API de Criação de Flow" icon="diagram-project" href="/api-reference/whatsapp-flows/create-a-flow">
    Inspecione metadados, JSON, opções de clonagem e de publicação.
  </Card>

  <Card title="Webhooks de Flows" icon="webhook" href="/pt/api-reference/guides/examples/webhook-examples/whatsapp-flow-webhook-examples">
    Processe alterações de status do Flow.
  </Card>
</CardGroup>

Para verificações de integridade, troca de dados, validação e respostas de conclusão, siga [Implementar um endpoint de WhatsApp Flow](/pt/api-reference/guides/whatsapp-platform/implement-a-whatsapp-flow-endpoint).


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