CRUD Conversacional
Guia prático de ações e encadeamento de etapas para operar o FormFlow por instruções
O CRUD Conversacional permite executar operações de formulário usando etapas encadeadas. Em geral, você gera o plano com reasonFormFlowPlan e acompanha a execução step a step.
Antes de criar variáveis ou catálogos, consulte o que já existe com getFormFields e getFormCatalogs. Isso evita duplicatas e garante que o escopo (lead, conversation, global, form) seja atribuído corretamente.
Para que serve
- Criar e atualizar formulários sem montar chamadas manuais complexas
- Reaproveitar resultados de uma etapa na próxima
- Exibir progresso operacional para usuários e times internos
Ações disponíveis
Mutações
| Ação | Descrição |
|---|---|
createCatalog | Cria um novo formulário |
updateCatalog | Atualiza formulário existente |
createVariable | Cria uma nova variável |
updateVariable | Atualiza variável existente |
createFormField | Adiciona campo a um formulário |
updateFormField | Atualiza campo de formulário |
upsertFormItemValue | Insere ou atualiza um valor capturado |
upsertFormResponse | Insere ou atualiza uma resposta de formulário |
createFormItemResponse | Cria snapshot de resposta |
Queries
| Ação | Descrição |
|---|---|
queryFormCatalogs | Lista formulários do host |
queryFormVariables | Lista variáveis do host |
queryFormFields | Lista campos de um formulário |
queryFormItemsValues | Busca valores capturados |
queryFormResponses | Busca respostas de formulários |
queryFormItemsResponses | Busca snapshots de respostas |
Validação
| Ação | Descrição |
|---|---|
validateStepResult | Valida o resultado de uma etapa anterior antes de continuar |
Referências dinâmicas
Use $previous para aproveitar a saída da etapa anterior:
| Referência | O que acessa |
|---|---|
$previous | Objeto completo do resultado anterior |
$previous.id | Campo id do resultado anterior |
$previous.campo | Qualquer campo do resultado anterior |
$previous[0].id | Primeiro elemento quando o resultado é um array |
Exemplo: criar catálogo e logo depois associar uma variável ao ID gerado:
[
{
"stepNumber": 1,
"action": "createCatalog",
"generalInstructions": "Criar formulário Pré-vendas"
},
{
"stepNumber": 2,
"action": "updateCatalog",
"generalInstructions": "Associar variáveis ao formulário criado",
"params": {
"catalogId": "$previous.id",
"variableIds": ["uuid-email", "uuid-phone"]
}
}
]
Validação por etapa
Steps com requiresValidation: true são verificados automaticamente antes de prosseguir:
{
"stepNumber": 1,
"action": "createCatalog",
"generalInstructions": "Criar formulário de pré-vendas",
"requiresValidation": true,
"validationQuestion": "O formulário foi criado corretamente?",
"validationInstructions": "Verificar se o ID retornado é válido e o nome está correto"
}
realtimeInstructions
Durante a execução, cada step pode gerar mensagens em realtimeInstructions para orientar interface e operador:
{
"stepNumber": 1,
"action": "createCatalog",
"result": { "id": "abc-123", "name": "Pré-vendas" },
"realtimeInstructions": [
"✅ Formulário criado com sucesso!",
"📋 ID gerado: abc-123",
"📝 Nome: Pré-vendas"
]
}
Essas mensagens funcionam bem junto com o evento form_flow_step_executed para mostrar progresso em tempo real.