WhatsApp: Flows da Meta

Telas nativas do WhatsApp (Flows da Meta): cadastro dos seus Flows, publicação, envio, IA, o pacote de Flows nativos e as chaves de criptografia.

Os Flows da Meta são telas nativas do WhatsApp: formulários, listas e seletores que abrem dentro da conversa, sem o cliente sair do aplicativo. Aqui você cadastra os seus próprios Flows, publica-os na conta da Meta, envia a clientes, e liga o pacote de Flows nativos da plataforma. Não confunda com os fluxos do bot, que são roteiros de mensagens.

Como funciona

Rascunho→Publicado na Meta→Enviado ao cliente

Desenhe
POST /meta-flows com o flow_json. Se quiser um ponto de partida, peça um rascunho a POST /meta-flows/generate.
Publique
POST /meta-flows/{id}/publish. O meta_flow_id é preenchido e o status vira published.
Confira
GET /meta-flows/{id}/preview devolve um link para ver o Flow como o cliente verá.
Envie
POST /meta-flows/{id}/send com o telefone do cliente.

Para o pacote pronto da plataforma, o caminho é outro: POST /native-flows/activate, acompanhar com GET /native-flows/status e, quando quiser, POST /native-flows/send.

Conceitos-chave

O formato do `flow_json`

É o JSON de Flows da Meta: version, e uma lista de screens, cada uma com id único e layout do tipo SingleColumnLayout cheio de children (componentes). A plataforma valida antes de gravar e recusa com 422 e a lista errors. As regras:

Regra	Limite
`version`	Obrigatória
Telas por Flow	De 1 a 20, ids únicos
Componentes por tela	Ao menos 1
Tipos de componente	`TextHeading`, `TextSubheading`, `TextBody`, `TextCaption`, `RichText`, `TextInput`, `TextArea`, `Dropdown`, `RadioButtonsGroup`, `CheckboxGroup`, `ChipsSelector`, `DatePicker`, `CalendarPicker`, `OptIn`, `EmbeddedLink`, `Image`, `ImageCarousel`, `PhotoPicker`, `DocumentPicker`, `NavigationList`, `Footer`
Ação (`on-click-action.name`)	`navigate`, `data_exchange`, `complete` ou `update_data`
`Form` e `Footer`	No máximo 1 de cada por tela; `Footer` por último; `Form` fora de `If`
`NavigationList`	No máximo 2 por tela, e sem outros componentes
`DocumentPicker`	No máximo 1 por tela, e não junto com `PhotoPicker`
`ImageCarousel`	Até 10 imagens, fora de `If`
`Dropdown`	Até 200 itens fixos
`RadioButtonsGroup`, `CheckboxGroup`, `ChipsSelector`	Até 20 itens fixos
`If` aninhado	Até 3 níveis

Cada componente também tem propriedades obrigatórias (por exemplo TextInput pede name e label; Footer pede label). A validação local cobre isso, mas a Meta tem regras próprias e pode recusar na publicação.

Flow da loja e Flow nativo

Os Flows da loja (/meta-flows) são os que você desenha e publica. Os Flows nativos (/native-flows) são o pacote pronto da plataforma, que a plataforma mesma cria e mantém na conta da Meta quando você ativa.

Quem fala com a Meta

Criar, ler, alterar e apagar um Flow da loja só mexe no painel. Publicar e pré-visualizar usam o token e a conta empresarial compartilhados da plataforma. Enviar usa o número de WhatsApp da loja.

Endpoints

Método	Caminho	Para que serve	Página
`GET`	`/api/v1/admin/whatsapp/meta-flows`	Lista os Flows da loja	Flows da loja
`POST`	`/api/v1/admin/whatsapp/meta-flows`	Cria um Flow da loja	Flows da loja
`GET`	`/api/v1/admin/whatsapp/meta-flows/{id}`	Lê um Flow da loja	Flows da loja
`PUT`	`/api/v1/admin/whatsapp/meta-flows/{id}`	Substitui um Flow da loja	Flows da loja
`DELETE`	`/api/v1/admin/whatsapp/meta-flows/{id}`	Apaga um Flow da loja	Flows da loja
`POST`	`/api/v1/admin/whatsapp/meta-flows/{id}/publish`	Publica um Flow na Meta	Publicar e enviar
`GET`	`/api/v1/admin/whatsapp/meta-flows/{id}/preview`	Gera o link de pré-visualização de um Flow	Publicar e enviar
`POST`	`/api/v1/admin/whatsapp/meta-flows/{id}/send`	Envia um Flow a um telefone	Publicar e enviar
`POST`	`/api/v1/admin/whatsapp/meta-flows/generate`	Gera um rascunho de Flow a partir de uma descrição	IA para Flows
`POST`	`/api/v1/admin/whatsapp/meta-flows/decide`	Escolhe (e opcionalmente envia) o Flow certo para uma mensagem	IA para Flows
`GET`	`/api/v1/admin/whatsapp/native-flows/status`	Mostra a situação dos Flows nativos da loja	Flows nativos
`POST`	`/api/v1/admin/whatsapp/native-flows/activate`	Liga os Flows nativos da loja	Flows nativos
`POST`	`/api/v1/admin/whatsapp/native-flows/deactivate`	Desliga os Flows nativos da loja	Flows nativos
`POST`	`/api/v1/admin/whatsapp/native-flows/send`	Envia um Flow nativo a um telefone	Flows nativos
`POST`	`/api/v1/admin/whatsapp/flow-keys/register`	Gera um par de chaves de Flow para um número	Chaves de Flow

Erros comuns

Esperar que POST /meta-flows publique: ele só grava no painel. Publique com /publish.
Usar PUT só para trocar o nome: ele regrava tudo e devolve o Flow para draft.
Tratar o id como UUID: o id do Flow da loja é um inteiro.
Enviar um Flow ainda em rascunho: sem meta_flow_id a resposta é 422 (a menos que passe flow_id).
Esperar que DELETE apague na Meta: ele só apaga o registro da loja.
Chamar POST /flow-keys/register à toa: cada chamada troca a chave ativa e pode quebrar Flows com troca de dados.
Ativar os Flows nativos sem número cadastrado: a resposta é 422 e blockers lista o que falta.
Esquecer a janela de 24 horas ao enviar: fora dela a Meta recusa.

Próximos passos

Flows da loja

Cadastrar o desenho.

Publicar e enviar

Levar o Flow até o cliente.

Flows nativos

O pacote pronto da plataforma.

IA para Flows

Gerar rascunhos e escolher o Flow.