# Builder de fluxos do WhatsApp

> Crie, importe, valide e visualize fluxos do WhatsApp por projeto no Console da Polymorfa.

Use **Fluxos** em um projeto para criar uma experiência do WhatsApp com várias telas. Os rascunhos de fluxo são recursos compartilhados do projeto, então projetos com a Cloud API e com dispositivos vinculados usam o mesmo editor e o mesmo identificador de fluxo.

A tabela **Fluxos** lista o nome, a quantidade de telas, a versão e a última
atualização de cada rascunho. Abra o cabeçalho de uma coluna para ordenar ou
filtrar por essa propriedade. Arraste a borda de um cabeçalho para
redimensionar a coluna. Clique com o botão direito em uma linha para abrir as
mesmas ações que aparecem em **Mais**.

## Criar um fluxo

1. Abra um projeto e selecione **Fluxos**.
2. Selecione **Novo fluxo**.
3. Renomeie o rascunho, adicione telas e adicione componentes a cada tela.
4. Selecione uma tela na lista **Telas** para editá-la ou ver os destinos dela.

O fluxo abre na aba **Editor**. Em telas mais estreitas, alterne entre **Telas**, **Edição** e **Prévia** no topo da aba.

O Console salva um rascunho novo assim que o editor abre. As edições seguintes são salvas depois de um curto intervalo. **Salvo** confirma que a versão exibida chegou à Polymorfa. **Conflito**, com a mensagem "Isto mudou desde que você abriu.", significa que alguém salvou uma versão mais nova. O Console para de salvar suas edições; selecione **Exportar** para mantê-las e depois **Atualizar** para carregar a versão mais recente.

Os rascunhos aceitam documentos de fluxo incompletos. O status das verificações no resumo aponta IDs de tela duplicados, destinos de rota ausentes, nomes de campo duplicados, telas finais que navegam e falhas de limite de recursos antes do upload.

Excluir um fluxo na tabela **Fluxos** remove o rascunho do projeto. As cópias já enviadas ao WhatsApp não são excluídas.

## Publicar no WhatsApp

Abra a aba **Publicar** de um fluxo salvo. Ela lista cada número do projeto com o status do fluxo no WhatsApp para aquele número (**Rascunho**, **Publicado**, **Descontinuado**, **Limitado**, **Bloqueado** ou **Sem upload**), o resultado do último upload e o ID do fluxo no WhatsApp, usado como `flow_id` no envio.

- **Fazer upload** envia o rascunho salvo ao número. O primeiro upload, ou um upload depois de descontinuar, pede uma categoria. O WhatsApp verifica o fluxo de novo no upload e lista os erros de validação abaixo do número.
- **Publicar** fica disponível para um rascunho enviado sem erros de validação. Um fluxo publicado não pode ser alterado nem excluído.
- **Descontinuar** impede que um fluxo publicado seja enviado. Isso não pode ser desfeito.
- **Excluir do número** remove do número um rascunho não publicado. Seu rascunho salvo continua aqui.
- **Sincronizar** lê o status atual no WhatsApp. Use quando o Console mostrar que o WhatsApp não confirmou a última alteração.

Salve suas alterações antes de fazer o upload ou publicar. Fazer upload e Publicar ficam indisponíveis enquanto uma edição está sendo salva, depois de uma falha ou de um conflito ao salvar e enquanto o JSON do fluxo está inválido.

## Usar a prévia do destinatário

A prévia renderiza a tela do fluxo selecionada dentro de uma conversa do WhatsApp. Você pode preencher campos, selecionar opções, seguir a navegação local entre telas e testar as ações de conclusão. As interações da prévia ficam no seu navegador e não enviam mensagens, não abrem links incorporados nem salvam os dados enviados no formulário.

> **Warning**
>
> A **Prévia local** é uma ajuda para a criação. A Meta valida o esquema
> completo do fluxo e oferece a própria prévia hospedada, com prazo de
> validade, depois que um fluxo é enviado para um número compatível da Cloud
> API. Use essa prévia hospedada como a verificação final de renderização
> antes da publicação.

A prévia local renderiza títulos, texto do corpo, legendas, campos de texto, áreas de texto, listas suspensas, grupos de botões de opção e de caixas de seleção, seletores de data, opt-ins, links incorporados, formulários e ações de rodapé. Um componente mais novo ou sem suporte aparece como um cartão de diagnóstico e permanece inalterado no JSON salvo.

## Editar ou mover o JSON do fluxo

Selecione **JSON** para editar o documento completo. Um JSON inválido permanece no editor e não é aplicado à prévia visual. Enquanto ele estiver inválido, o resumo mostra **JSON inválido**, a última versão válida continua salva e **Exportar** baixa o texto como você o digitou. A Polymorfa preserva campos e objetos de componente desconhecidos em vez de remover dados que não entende.

Use **Importar** para substituir o documento em edição por um arquivo `.json`. Use **Exportar** antes de uma edição grande, ao resolver um conflito de revisão ou ao mover um rascunho entre sistemas.

Os rascunhos de fluxo têm estes limites de criação:

| Limite | Valor |
| --- | ---: |
| Documento JSON | 2 MB |
| Telas | 50 |
| Componentes | 1.000 |
| Profundidade de aninhamento do JSON | 32 |

A versão do fluxo continua sendo uma string editável. A Polymorfa não reescreve um documento importado para uma suposta versão mais recente da Meta.

## Gerenciar rascunhos pelo código

Os rascunhos de Fluxos são recursos do projeto. Listar e ler exigem
`sessions:read`; criar, atualizar e excluir exigem `sessions:manage`. Um token de
projeto alcança apenas o próprio projeto.

**API:**

Use [Listar rascunhos de fluxo](https://docs.polymorfa.com/api/flows/list-flow-drafts),
[Obter fluxo](https://docs.polymorfa.com/api/flows/get-flow),
[Criar rascunho de fluxo](https://docs.polymorfa.com/api/flows/create-flow-draft),
[Atualizar fluxo](https://docs.polymorfa.com/api/flows/update-flow) e
[Excluir fluxo](https://docs.polymorfa.com/api/flows/delete-flow) em `/platform/flows`.

```bash cURL
curl "https://api.polymorfa.com/platform/flows?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const drafts = await project.flows.list();
for (const draft of drafts.data) console.log(draft.id, draft.name, draft.status);

const created = await project.flows.create({
  name: "Booking",
  definition: { version: "7.0", screens: [] },
});

const current = await project.flows.retrieve(created.data.id);
if (current.data) {
  await project.flows.update(created.data.id, {
    expectedUpdatedAt: current.data.updatedAt,
    name: "Booking v2",
  });
}

await project.flows.delete(created.data.id);
```

```bash Graph API
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/flows" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

**Graph API:** Números da Meta Cloud API: Compatível em parte. Números com Dispositivos vinculados: Não compatível.

A Graph API trabalha com os fluxos da Meta de uma conta do WhatsApp Business, não
com os rascunhos do projeto. [Listar fluxos da WABA](https://docs.polymorfa.com/api/graph/flows/list-waba-flows)
exige `sessions:read`, e [Criar fluxo da WABA](https://docs.polymorfa.com/api/graph/flows/create-waba-flow)
recebe o corpo de fluxo da Meta e exige `messages:write`. Atualizar, publicar e
excluir um fluxo não estão disponíveis. Números com Dispositivos vinculados
recebem o erro de capacidade `131026`.

Uma atualização envia `expectedUpdatedAt`, o `updatedAt` do rascunho em
milissegundos Unix da sua última leitura. Se alguém salvou o rascunho desde
então, a atualização é recusada; leia o rascunho de novo antes de tentar outra
vez.

*TypeScript:*

Use um cliente de projeto, como `platform.project("<project-id>")`, ou um
cliente criado com um token de projeto. Os métodos de Fluxos retornam o próprio
rascunho em `response.data`. `list` retorna itens `FlowSummary`. `retrieve`
retorna um `FlowDraft`, que acrescenta a `definition`, ou `null` quando o
rascunho não existe.

## Projetos com a Cloud API e com dispositivos vinculados

Criação, armazenamento de rascunhos, importação, exportação, validação e prévia local funcionam da mesma forma nos dois tipos de conexão.

Um número da Cloud API pode vincular o rascunho do projeto a um recurso de fluxo da Meta para a prévia hospedada e as operações de ciclo de vida. Conexões com dispositivos vinculados podem enviar um fluxo já publicado pela Messaging API, mas o protocolo de dispositivos vinculados não oferece upload nem publicação de recursos de fluxo da Meta. O Console identifica as ações de ciclo de vida indisponíveis em vez de tratar um rascunho local como publicado.

Para enviar um fluxo publicado, consulte [Send a message](https://docs.polymorfa.com/api/messages/send-message?playground=open).
