> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Flows que respondem com dados ao vivo
> Configure um Flow cujas telas são decididas por um sistema seu enquanto o cliente preenche o formulário — o que é preciso, em que ordem, o que pode dar errado e o que o cliente vê quando dá.
Um **Flow com dados ao vivo** é um formulário dentro do WhatsApp cuja próxima tela é decidida por um sistema seu, enquanto a pessoa ainda está preenchendo. A Meta chama isso de `data_exchange`, e a diferença para um formulário comum é que agora o formulário *responde*: ele mostra os horários que estão realmente livres, avisa que o código digitado não existe, ou calcula o preço do que a pessoa acabou de escolher.
Esta página é para quem configura o Flow e quer entender o que está acontecendo. O contrato requisição por requisição, para quem vai programar, está em [Conecte a sua API a um Flow](/pt-BR/guides/flow-data-exchange).
## Um formulário simples coleta; um Flow ao vivo conversa
| | Formulário simples (`NAVIGATE`) | Dados ao vivo (`data_exchange`) |
| -------------------------------------- | ----------------------------------------- | --------------------------------------------------------- |
| O que as telas mostram | O que você escreveu no formulário | O que o seu sistema decidir, tela a tela |
| Quando você fica sabendo das respostas | Uma vez só, no fim, quando a pessoa envia | A cada tela, conforme ela avança |
| O que precisa | Nada além do próprio formulário | Um sistema seu que responda, mais a ligação descrita aqui |
| Bom para | Cadastro, pesquisa, captura de lead | Agendamento, consultas, validação, preços |
A maioria dos Flows é do tipo simples e não precisa de nada disto. Use dados ao vivo só quando uma tela tiver que mostrar algo que você não tem como saber de antemão.
## Quando vale a configuração extra
* **Mostrar o que está mesmo livre.** A pessoa escolhe um dia e a tela seguinte lista os horários ainda abertos naquele instante — não uma lista fixa que envelhece.
* **Conferir antes de aceitar.** Número de pedido, matrícula, cupom: a pessoa digita e o formulário já diz se vale.
* **Calcular conforme ela escolhe.** Tamanho, quantidade, frete: o preço da tela seguinte é a resposta do seu sistema, não uma tabela que você mantém em dois lugares.
* **Levar pessoas diferentes por caminhos diferentes.** Quem já é cliente vê uma tela, quem é novo vê outra. Quem nomeia a próxima tela é o seu sistema.
## O que é preciso ter, na ordem
Cada passo abaixo só funciona se o anterior estiver feito. Pular um deixa você com um Flow que parece configurado, não levanta erro em lugar nenhum e simplesmente nunca é chamado.
Flows só existem em números oficiais da Meta (Cloud API). Um número não oficial não consegue enviá-los. Veja [Oficial vs Não Oficial](/pt-BR/concepts/official-vs-unofficial).
Abra o Flow no painel e procure a caixa **Chave deste NÚMERO**. Clique em **Gerar par novo**, ou em **Importar chave existente** se você já usa uma.
A chave é do **número**, não deste Flow: todos os Flows com dados ao vivo desse número usam a mesma. Gerar uma nova substitui a que a Meta tem para aquele número — então, se outro formulário do mesmo número já está funcionando, gere com cuidado. Importar não muda nada na Meta, e é a opção segura nesse caso.
Qualquer endereço seu capaz de receber uma mensagem e responder em poucos segundos — o seu backend, uma ferramenta de automação, o que você já tiver no ar. Precisa ser acessível por `https://`, porque o que mandamos para lá é o que o cliente acabou de digitar.
Na caixa **Destino deste Flow**, cole esse endereço e clique em **Gravar destino**. Este é por Flow: outro formulário do mesmo número pode apontar para um lugar completamente diferente.
Se o campo estiver cinza, é porque o número ainda não tem chave — volte ao passo 2. Ele é bloqueado de propósito: um destino gravado num número sem chave nunca seria chamado.
A Meta só chama um endereço que ela tem registrado no Flow, e gravar o destino não registra nada — é essa separação que impede que a correção de um erro de digitação roube um Flow que o sistema de outra pessoa está respondendo hoje.
No mesmo painel, em **Apontar a Meta para cá**, clique em **Registar na Meta**. Depois de feito — ou se a Meta já apontava para nós — o painel diz *"A Meta já aponta para cá. Nada a fazer."*, e o botão passa a **Registar de novo**. Clicar uma segunda vez não faz mal: um Flow que já está registrado conosco não muda nada.
O botão fica cinza enquanto o número não tiver chave, pelo mesmo motivo do campo de destino.
Só agora. **A Meta se recusa a publicar um Flow com dados ao vivo que não tenha endereço registrado** — ela responde *"Publishing without specifying 'endpoint\_uri' is forbidden"*. Publicar é irreversível: um Flow publicado nunca mais pode ser editado, só clonado numa versão nova.
**Se a Meta já estiver apontando este Flow para outro lugar, o botão pergunta antes de agir.** Abre uma caixa dizendo *"A Meta já aponta este Flow para outro endereço"*, mostra esse endereço e avisa que continuar passa **todas** as trocas deste Flow para a Pilot Status — quem responde naquele endereço deixa de recebê-las, e a Meta não guarda o valor anterior. Dois botões: **Assumir mesmo assim** e **Cancelar**.
Leia o endereço antes de continuar. Se você não o reconhecer, cancele e descubra de quem é: nada avisa o sistema do outro lado de que ele parou de ser chamado.
Na rara ocasião em que a Meta recusa sem nomear esse endereço, **a pergunta é feita do mesmo jeito** — só que sem o endereço na tela. Não existe caminho por este painel que assuma um Flow ativo em silêncio.
Times que automatizam a configuração podem fazer o mesmo ato pela API, em vez do painel — veja a [Referência da API de Flows](/pt-BR/api/flows). O caminho normal é o painel.
## O que o Pilot Status faz por você
A Meta não manda as respostas do cliente em texto puro para o seu sistema. Ela criptografa cada chamada, e espera a resposta criptografada de volta de um jeito bem específico — é essa parte que normalmente impede os times de colocar um formulário interativo no ar.
**O endereço que a Meta chama é o Pilot Status.** A cada tela que o cliente preenche:
1. A Meta manda a chamada criptografada para nós.
2. A gente descriptografa.
3. A gente repassa o conteúdo puro para o seu endereço, com um cabeçalho de assinatura — `x-pilot-status-signature` — para o seu sistema conseguir provar que a mensagem veio de nós e não de alguém que adivinhou a sua URL.
4. A gente criptografa a sua resposta e devolve para a Meta, que desenha a tela que você nomeou.
Você nunca encosta na criptografia. É o mesmo cabeçalho de assinatura dos [webhooks do Pilot Status](/pt-BR/concepts/webhooks), então, se o seu sistema já confere aqueles, ele não precisa de nada novo.
O **segredo de assinatura** aparece exatamente uma vez, na gravação que o cria, com um botão para copiar. Copie ali — ele fica guardado criptografado e não pode ser lido de novo, e o painel não tem como mostrá-lo outra vez. Substituir um segredo perdido ou vazado é uma chamada de API (`rotateSecret`), e depois o seu sistema precisa ser atualizado com o valor novo.
## O que o seu sistema tem de devolver
Uma resposta pequena, sempre: o **nome da próxima tela** e as informações que essa tela precisa.
```json theme={null}
{
"screen": "PICK_SLOT",
"data": { "slots": ["09:00", "11:30", "16:00"] }
}
```
Os nomes das telas são os do seu próprio Flow. Para encerrar o formulário, responda com a tela reservada `SUCCESS`.
**Uma resposta que não nomeia tela é tratada como falha, de propósito.** A Meta desenha uma resposta sem tela como *nada* — a pessoa fica olhando para um formulário que não avança nem dá erro, e nada em lugar nenhum reporta isso. Preferimos mostrar a ela um erro com opção de tentar de novo e registrar a troca como falha.
## O tempo é a restrição de verdade
A Meta segura a chamada aberta enquanto uma pessoa olha para um indicador de carregamento no celular, e **ela não tenta de novo**. Uma resposta lenta não é uma tela atrasada; é uma tela falhada.
A gente desiste do seu sistema depois de **8 segundos** (o padrão) e mostra um erro ao cliente. É bem mais apertado que um webhook comum, e por um bom motivo: um webhook comum é um aviso que ninguém está esperando, e aqui tem alguém parado esperando.
Faça o trabalho demorado *depois* de responder. Responda a tela primeiro; agendar, cobrar ou gravar no banco vem depois.
## Quando alguma coisa está errada
O cliente nunca vê os seus servidores. Seja qual for a falha — destino não gravado, o seu sistema fora do ar, demora demais, uma resposta que não conseguimos ler — ele recebe um erro genérico, com opção de tentar de novo, **na mesma tela em que já está**, e nada do que ele digitou se perde. A única exceção é uma falha num momento em que a Meta não nomeou tela nenhuma — a abertura do formulário, ou a pessoa voltando uma tela — em que não existe tela para colocar o erro e a Meta mostra a dela.
| O que você vê | O que significa | O que fazer |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| O campo do destino está cinza | O **número** não tem chave de endpoint, então a Meta não tem com o que criptografar e nunca conseguiria chegar até nós | Gere ou importe a chave em **Chave deste NÚMERO**, logo acima do campo |
| **"A Meta não está a chamar-nos para este Flow"** | A Meta tem um endereço registrado neste Flow e ele não é o nosso. As respostas estão indo para outro lugar, ou para lugar nenhum | Clique em **Registar na Meta** (passo 5) e leia o endereço na caixa de confirmação antes de continuar — assumir faz aquele endereço parar de ser chamado, sem nenhum aviso para quem o mantém |
| Um aviso dizendo que **não há destino** | O Flow não tem endereço gravado, então não há para onde repassar | Grave o destino (passo 4) |
| A publicação é recusada, falando em `endpoint_uri` | O Flow nunca foi registrado na Meta | Clique em **Registar na Meta** (passo 5) e publique |
| O cliente relata uma tela de erro no meio do formulário | O seu sistema respondeu devagar demais, estava fora do ar, ou devolveu algo inutilizável | Abra as trocas recentes do Flow — a falha está registrada ali, com o status que o seu sistema devolveu e quanto tempo levou |
| A submissão chega sem resposta nenhuma dentro dela | Normal num Flow com dados ao vivo. O que a Meta devolve no fim carrega só o token do formulário: as respostas foram para **o seu sistema**, tela a tela, e nunca voltaram pela Meta | Leia-as no `submitted` da submissão — veja [Respostas de Flow](/pt-BR/guides/flow-responses) |
**Um Flow com dados ao vivo mal ligado falha em silêncio, não com barulho.** Nada dá erro do seu lado, nada dá erro no painel, e o formulário simplesmente nunca chama você. É por isso que o painel do Flow mostra **Avisos desta ligação** mesmo depois de a gravação dar certo — leia essa lista antes de considerar o trabalho feito, e mantenha na tela qualquer aviso que você não reconheça em vez de descartá-lo.
## Conferir o que realmente aconteceu
A tela do Flow no painel lista as trocas recentes: qual tela, se deu certo, o que o seu sistema respondeu e quanto tempo levou. O conteúdo das trocas que **falharam** é guardado para você ver o que aconteceu; o das que deram certo guarda só tempo e formato. Todo esse registro expira em **24 horas** — é uma ajuda para diagnosticar, não um arquivo.
**Esse é o registro da ligação, não o das respostas.** O que a pessoa digitou fica guardado, e guardado de verdade: vai junto com a submissão, no `submitted`, tela a tela, cada entrada com o momento em que foi preenchida, e permanece por 31 dias — um dia a mais que a própria submissão, para que nenhuma submissão seja servida depois de as trocas que a alimentaram já terem expirado.
Só entram nessa lista as telas que alguém de fato respondeu. Abrir o formulário e voltar uma tela não são respostas e não são guardadas — é por isso que ela é mais curta que as trocas acima. Isso é o desenho, não perda.
Para as respostas em si — o formato delas e como lê-las — veja [Respostas de Flow](/pt-BR/guides/flow-responses).
## Relacionados
* [Flows](/pt-BR/concepts/flows) — o que é um Flow e o seu ciclo de vida
* [Conecte a sua API a um Flow](/pt-BR/guides/flow-data-exchange) — o contrato técnico para quem vai programar o sistema que responde
* [Respostas de Flow](/pt-BR/guides/flow-responses) — as respostas que as pessoas enviam
* [Referência da API de Flows](/pt-BR/api/flows)