Guia de fluxos

O que é um fluxo, como o grafo de nós e conexões é montado, como usar variáveis, testar, publicar, acompanhar execuções e iniciar um fluxo por webhook.

Um fluxo (na API, workflow) é uma automação desenhada como um grafo: um ou mais gatilhos iniciam a execução, e cada nó faz uma coisa (enviar uma mensagem, consultar uma API, decidir um caminho, esperar uma resposta) e passa a vez ao próximo pelas conexões. Você monta o grafo em JSON, publica, e a Vozko executa cada ocorrência do gatilho como uma execução.

Cada tipo de nó tem a própria configuração, as próprias saídas e as próprias chaves de saída. Todos estão no Catálogo de nós, gerado a partir do mesmo catálogo que GET /workflows/node-types devolve. As rotas estão no grupo Fluxos da Referência da API.

Conceitos

ConceitoO que é
FluxoO recurso workflow: nome, tipo, departamento, rascunho (graph) e a versão publicada.
Tipomessages para conversas (WhatsApp, Instagram, Telegram e os demais canais) ou voice para ligações. O tipo decide quais nós e gatilhos o fluxo aceita.
GatilhoO nó que inicia a execução: mensagem recebida, primeira mensagem, entrada numa etapa, webhook, formulário respondido, chamada por agente de IA, aniversário ou ligação recebida.
NóUm passo do fluxo, com type e config.
SaídaUm caminho que sai de um nó, identificado por um id (por exemplo true e false numa condição, sucesso e erro numa ação).
ConexãoUma ligação de um nó a outro. O label da conexão é o id da saída de onde ela parte.
RascunhoO grafo que você edita e salva. Salvar nunca muda o que está rodando.
Versão publicadaA cópia do rascunho que roda. Cada publicação cria uma versão numerada.
ExecuçãoUma passagem pelo fluxo, iniciada por um gatilho, com estado próprio e o registro de cada etapa.

O grafo

O grafo fica no campo graph do fluxo, com duas listas: nodes e edges.

Nós

CampoO que é
idIdentificador do nó, único no grafo. É o id que as conexões e as variáveis citam.
typeO tipo do nó, uma das chaves do Catálogo de nós.
positionx e y no editor visual. Não altera a execução.
configA configuração do nó, com os campos que o catálogo lista para o tipo.
pinnedOpcional. Uma saída fixada, usada só nos testes (veja Testar).
testInputsOpcional. Cenários de entrada salvos para testes.

A publicação remove pinned e testInputs da versão publicada, então produção nunca os lê.

Conexões

CampoO que é
sourceO id do nó de onde a conexão sai.
targetO id do nó para onde ela vai.
labelO id da saída de source de onde a conexão parte.

Como escolher o label:

  • Nós com saídas listadas no catálogo (por exemplo condition_branch, com true e false): cada conexão leva no label o id de uma dessas saídas. Toda saída marcada como obrigatória precisa de uma conexão para o fluxo ser publicado.
  • Nós de saída única (sem saídas listadas, como action_send_text): a conexão vai sem label, ou com default.
  • Nós com saídas dinâmicas (botões de action_send_interactive, ferramentas de action_ai_agent, casos de condition_text_match, teclas de wait_dtmf): as saídas nascem da configuração. Preencha a configuração antes de ligar as conexões e use o id exato de cada saída. POST /workflows/resolve-handles devolve as saídas atuais de cada nó, e GET /workflows/{id} traz o mesmo cálculo no campo handles.

Um label que não corresponde a nenhuma saída atual do nó bloqueia a publicação com EDGE_BAD_HANDLE_LABEL.

Regras do grafo

Salvar o rascunho aceita um grafo incompleto. Publicar exige que ele passe nestas regras, entre outras que o catálogo e cada nó definem:

  • pelo menos um nó, no máximo 200 nós e 400 conexões;
  • pelo menos um gatilho, todos compatíveis com o tipo do fluxo e no máximo um de cada tipo;
  • nenhum gatilho recebe conexões, e pelo menos um está ligado ao resto do fluxo;
  • pelo menos um nó que encerra o caminho (end, ou action_reply_to_agent nos fluxos chamados por agente);
  • todo nó que não é gatilho recebe ao menos uma conexão, e todo nó que não encerra o caminho tem ao menos uma conexão de saída;
  • todo nó é alcançável a partir de um gatilho;
  • um ciclo só é aceito se passar por uma espera (wait_duration, wait_for_reply, wait_schedule, wait_dtmf) ou por um action_loop, e se puder sair do ciclo e chegar a um fim;
  • os campos obrigatórios de cada nó estão preenchidos e os números estão dentro dos limites do campo;
  • os recursos citados (agente, template, etiqueta, etapa, funil, departamento, atendente, modelo, número, mídia, planilha, coleção MCP e base de conhecimento) existem no workspace.

Os nós de decoração (decoration_background) ficam fora dessas regras: não executam e não precisam de conexões.

Exemplo

Um fluxo de conversa que responde a cada mensagem: se o texto contém "cancelar", avisa que um atendente vai falar com o cliente; senão, confirma o recebimento.

curl -X POST "https://api.vozkoia.com/workflows" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "X-Workspace-ID: SEU_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d @fluxo.json

fluxo.json:

{
  "name": "Triagem de cancelamento",
  "type": "messages",
  "triggerType": "trigger_message_received",
  "graph": {
    "nodes": [
      { "id": "t1", "type": "trigger_message_received", "position": { "x": 0, "y": 0 }, "config": {} },
      {
        "id": "n1",
        "type": "condition_branch",
        "position": { "x": 280, "y": 0 },
        "config": { "variable": "{{message}}", "operator": "contains_ci", "value": "cancelar" }
      },
      {
        "id": "n2",
        "type": "action_send_text",
        "position": { "x": 560, "y": -120 },
        "config": { "text": "Recebemos seu pedido de cancelamento. Um atendente vai falar com você." }
      },
      {
        "id": "n3",
        "type": "action_send_text",
        "position": { "x": 560, "y": 120 },
        "config": { "text": "Olá! Recebemos sua mensagem: {{message}}" }
      },
      { "id": "fim", "type": "end", "position": { "x": 840, "y": 0 }, "config": {} }
    ],
    "edges": [
      { "source": "t1", "target": "n1" },
      { "source": "n1", "target": "n2", "label": "true" },
      { "source": "n1", "target": "n3", "label": "false" },
      { "source": "n2", "target": "fim" },
      { "source": "n3", "target": "fim" }
    ]
  }
}

O que o exemplo mostra:

  • t1 é o gatilho Mensagem recebida, que deixa o texto do cliente em {{message}}.
  • n1 é uma condição. Ela tem duas saídas obrigatórias, true e false, e por isso as duas conexões que saem dela levam esses ids no label.
  • n2 e n3 enviam texto e têm saída única, então as conexões até fim vão sem label.
  • fim encerra o caminho.

A resposta 201 traz o fluxo criado em rascunho (status: draft), com version: 1. Esse version é a revisão do rascunho que você manda como revision ao salvar de novo. Um fluxo de departamento exige departmentId quando quem cria pertence a mais de um departamento.

Para conferir um grafo sem gravar nada, use POST /workflows/validate com type e graph: valid é true quando nada bloqueia a publicação, e issues lista cada problema com code, severity (blocking, advisory ou info), nodeId, o campo e uma dica (hint).

Variáveis e expressões

Os textos da configuração aceitam referências no formato {{caminho}}, trocadas pelo valor no momento em que o nó executa. Espaços dentro das chaves são aceitos ({{ message }}).

O caminho usa só letras, dígitos, _, . e colchetes. Não há operadores, filtros nem funções dentro das chaves: para calcular ou formatar um valor, use um nó (action_set_variable, action_format_date, action_code) e leia a saída dele.

FormaDe onde vem o valor
{{nome}} ou {{var.nome}}Variável do fluxo: dados do gatilho (por exemplo {{message}} e {{contact_number}} nos gatilhos de mensagem), variáveis gravadas por action_set_variable e variáveis de campanha.
{{node.<id>.<chave>}}Chave de saída do nó <id>. É a forma mais explícita e estável. As chaves de cada tipo estão no catálogo.
{{last.<chave>}}A chave gravada mais recentemente por qualquer passo anterior.
{{ai.<chave>}}Saídas do agente de IA que rodou por último; {{ai.response}} é o texto da resposta.
{{sys.date}}, {{sys.time}}, {{sys.timestamp}}Data (AAAA-MM-DD) e hora (HH:MM:SS) atuais em UTC, e o timestamp Unix em segundos.
{{secret.<nome>}}Um segredo do workspace. Só é trocado no nó de requisição HTTP (veja Segredos).

Acesso profundo: use pontos para entrar em objetos e listas, como {{node.n4.dados.0.nome}} ou {{webhook.body.pedido.id}}. Colchetes são equivalentes: {{node.n4.dados[0].nome}}.

Algumas regras práticas:

  • Só leia saídas de nós que vêm antes no caminho. Uma referência a um nó que não é anterior gera o aviso DATA_REF_DANGLING na validação.
  • Uma referência que não resolve fica no texto como foi escrita. Alguns nós tratam a falta de outro jeito, e o catálogo descreve esses casos (por exemplo, action_set_variable não grava a variável quando o valor cita algo que não existe).
  • O nó de código (action_code) não interpola {{...}} no JavaScript: leia a saída do nó anterior com input.<campo>, a de outro nó com state.get('node.<id>.<campo>') e um segredo com secrets.get('<nome>').

Para saber exatamente o que um nó pode usar, peça GET /workflows/{id}/nodes/{nodeId}/variables: o servidor calcula, a partir do grafo, cada referência disponível naquele ponto, com tipo, exemplo e se ela existe em todos os caminhos (always) ou só em alguns (some_paths).

Segredos do workspace

Senhas, tokens e chaves de API não devem ficar no grafo, que é salvo e exportado em texto. Guarde esses valores como segredos do workspace e cite pelo nome.

RotaO que faz
PUT /workspace-secrets/{name}Cria ou substitui o segredo. Corpo: {"value": "..."}.
GET /workspace-secretsLista nome, data da última alteração e quem alterou. Nunca devolve o valor.
DELETE /workspace-secrets/{name}Apaga o segredo.
  • O nome usa só letras minúsculas, dígitos e _, com 1 a 64 caracteres; o valor tem até 8 KB.
  • No nó action_http_request, use {{secret.<nome>}} na URL, nos parâmetros, nos cabeçalhos, no corpo ou na autenticação. No nó action_code, use secrets.get('<nome>').
  • Se um segredo citado não existe, o nó falha com um erro que cita o nome, sem enviar a requisição.
  • O valor é mascarado na saída gravada da etapa.
  • A validação avisa com NODE_SECRET_IN_PLAIN_TEXT quando encontra uma credencial em texto puro num cabeçalho, no token, no corpo, numa variável sensível, no código ou num cenário de teste.

As rotas exigem workflows:update ou agents:update. /workflow-secrets é o mesmo recurso com o nome antigo.

Testar

Nenhum teste grava em execuções de produção.

FerramentaRotaPara quê
ValidarPOST /workflows/validateVer tudo o que bloquearia a publicação, sem salvar.
Dados do testeGET, PUT e DELETE /workflows/{id}/test-valuesVer as variáveis que um teste precisa receber e guardar valores para elas.
Analisar um nóGET /workflows/{id}/nodes/{nodeId}/analyzeSaber como o teste do nó vai rodar e quais valores simulados ele precisa.
Testar um nóPOST /workflows/{id}/nodes/{nodeId}/testExecutar um único nó com um estado simulado.
Testar o fluxo/ws/workflows/{id}/simulateSimular o fluxo inteiro numa conexão de tempo real.

Dados do teste

GET /workflows/{id}/test-values lista as variáveis que o fluxo usa e que um teste precisa receber (as variáveis de campanha que os passos leem e as dos agentes que o fluxo usa), com os valores que você salvou. Cada pessoa tem os próprios valores, e eles só valem nos testes.

PUT substitui os seus valores, por nome de variável ({"values": {"curso": "Administração"}}). Um valor vazio apaga o valor salvo. Só são aceitas variáveis que o fluxo usa (test_value_not_needed), com até 2000 caracteres (test_value_invalid) e no formato do tipo declarado (test_value_type_invalid). O teste do fluxo inteiro só começa quando todas as variáveis têm valor salvo; o teste de nó usa esses valores como ponto de partida.

Teste de nó

O corpo de POST /workflows/{id}/nodes/{nodeId}/test aceita:

CampoO que faz
mockedStateValores simulados para as referências que o nó lê.
triggerVarsDados simulados do gatilho.
confirmRealCallsSem ele, requisições HTTP, código com fetch, e-mail e agenda falham com real_call_not_confirmed em vez de chamar o serviço de verdade. Mensagens são sempre simuladas.
skipExecutionSó resolve a configuração, sem executar efeitos.
continueWaits e waitAnswersSeguem por esperas no caminho, com o timer pulado e as respostas informadas.
trigger{nodeId, input}: começa pelo gatilho escolhido, com a entrada no formato dele. Entrada inválida responde 422 trigger_input_invalid.
fromRun{runId, stepId}: parte do estado que uma execução real registrou antes daquela etapa do nó.

A resposta traz em step o mesmo registro de etapa da produção (parâmetros usados, saída, erro, tempos e a saída seguida). Quando o caminho não chega ao nó, path_stop explica onde parou. O teste inteiro tem limite de 60 segundos.

Saídas fixadas

Um nó com pinned devolve nos testes a saída fixada sem executar, o que poupa chamadas reais repetidas enquanto você ajusta os passos seguintes. Fixe à mão salvando o rascunho com o campo pinned do nó, ou copie a saída de uma execução real com POST /workflows/{id}/nodes/{nodeId}/pin-from-run. A publicação remove todas as saídas fixadas.

Salvar, publicar e versões

Salvar o rascunho

PUT /workflows/{id} grava o rascunho e exige revision, que é o version do fluxo que você leu:

  • Se outra sessão salvou antes, a resposta é 409 draft_conflict, com a revisão atual em details.revision, e nada é gravado. Leia de novo com GET /workflows/{id} e reaplique a sua mudança.
  • Sem revision, a resposta é 400 draft_revision_required.
  • A resposta traz a nova revisão em version.

Salvar aceita um grafo incompleto: gatilho sem conexão, falta de fim e campos vazios só bloqueiam a publicação.

Publicar

POST /workflows/{id}/publish valida o rascunho salvo com todas as regras que bloqueiam, grava uma nova versão com o próximo número e deixa o fluxo ativo:

  • Novas execuções usam a nova versão; execuções em andamento continuam na versão em que começaram.
  • Se o rascunho é igual à versão publicada, nenhuma versão nova é criada.
  • Quando algo bloqueia, a resposta é 422 workflow_not_publishable, com todos os problemas em details.issues. Avisos (advisory) nunca bloqueiam.

Antes de publicar, GET /workflows/{id}/publish-preview mostra o que o fluxo vai rodar: cada gatilho, onde ele dispara e por que uma condição não rodaria.

Ativar e pausar

RotaO que faz
POST /workflows/{id}/pausePara de iniciar novas execuções. A versão publicada fica guardada.
POST /workflows/{id}/activateSem versão publicada, publica o rascunho. Com versão publicada e pausado, volta a rodar essa versão, sem publicar o rascunho.

Versões e restauração

O servidor guarda as 50 versões mais recentes de cada fluxo, além da versão publicada e das versões com execuções em andamento.

Execuções

Cada ocorrência de um gatilho de um fluxo ativo inicia uma execução da versão publicada.

StatusSignificado
runningExecutando os nós.
waitingParada numa espera: tempo, resposta do contato, formulário ou nova tentativa.
completedChegou ao fim.
errorParou por erro.
cancelledFoi cancelada.
RotaO que faz
POST /workflows/{id}/runsInicia uma execução numa conversa (entryId, entryType e, opcionalmente, message), como se o cliente tivesse mandado a mensagem. Só vale para fluxos com o gatilho Mensagem recebida ou Primeira mensagem; os demais recusam com 422 workflow_needs_message_trigger.
GET /workflows/{id}/runsLista as execuções do fluxo, com filtro por entryId e por status.
GET /workflow-runs/{runId}Traz a execução com o estado e as etapas, paginadas por stepsOffset e stepsLimit (até 1000).
POST /workflow-runs/{runId}/cancelCancela uma execução ativa. Uma execução já encerrada responde 409 run_terminal.
GET /conversations/{entryType}/{entryId}/workflow-runsLista as execuções de todos os fluxos numa conversa.

Execuções só aparecem para quem pode ver a conversa delas (a mesma regra de departamento e de responsável da caixa de entrada) e tem acesso ao departamento do fluxo.

Limites que o motor aplica:

  • Quando um nó falha por um erro inesperado, a execução tenta de novo até 3 vezes e depois termina com error. Não há nova tentativa no nó de código, durante uma ligação nem em recusas permanentes.
  • Um nó visitado mais de 3 vezes sem uma espera no meio encerra a execução com error. Os nós dentro de um action_loop e os ciclos com um agente de IA têm limites maiores.
  • Uma execução tem no máximo 10.000 etapas no total.

Alertas de execução

O servidor acompanha as execuções, as chamadas ao webhook e as ferramentas dos agentes, recalcula os alertas a cada 2 minutos e avisa na central de notificações quem pode editar fluxos.

AlertaQuando abre
workflow_called_inactiveO fluxo foi chamado pelo webhook ou por um agente enquanto não está ativo ou nunca foi publicado.
node_failingUm nó falhou em pelo menos 3 das suas últimas 10 execuções nas últimas 24 horas.
webhook_rejectingO webhook recusou pelo menos 5 chamadas pelo mesmo motivo em 1 hora.
run_stuckUma execução ficou parada e foi encerrada com erro.
agent_tool_failingUma ferramenta de um agente falhou pelo menos 3 vezes em 1 hora.
inbound_lookup_failedMensagens ficaram sem resposta automática porque não foi possível verificar se algum fluxo esperava a resposta. Não pertence a um fluxo.

Cada alerta traz fixAction, o que fazer: publish, open_run, open_node, view_deliveries, open_agent ou open_conversation. Leia os alertas de um fluxo com GET /workflows/{id}/alerts (abertos e resolvidos nas últimas 24 horas) ou os abertos de todo o workspace com GET /workflow-alerts.

Gatilho de webhook

O gatilho trigger_webhook deixa um sistema externo (uma loja, um CRM, um gateway de pagamento) iniciar o fluxo com uma chamada HTTP.

Configure

  1. Adicione o nó trigger_webhook ao grafo. Em config.start_on, escolha conversation (o padrão) ou lead. Em config.events, opcionalmente, liste os nomes de evento aceitos.
  2. Crie a URL com POST /workflows/{id}/webhook. O corpo é opcional: auth_mode (padrão header_token), header_name e method.
  3. Publique o fluxo. O webhook só inicia execuções de um fluxo ativo cuja versão publicada tem o gatilho.

A resposta traz url (com o token) e, quando o modo pede, o secret. GET /workflows/{id}/webhook devolve os dois só para quem tem workflows:update. PUT /workflows/{id}/webhook muda o modo, o cabeçalho e active, mantendo a URL; POST /workflows/{id}/webhook/rotate gera um token e um segredo novos, e as integrações antigas param até serem atualizadas.

Autenticação

O token na URL identifica o webhook. Além dele:

auth_modeComo o chamador se autenticaCabeçalho padrão
noneSó o token da URL.
header_tokenEnvia o secret como valor do cabeçalho.X-Webhook-Token
hmacEnvia sha256= seguido do HMAC-SHA256 do corpo bruto, em hexadecimal, calculado com o secret.X-Signature-256

Falha de autenticação responde 401 unauthorized.

Chame

curl -X POST "https://api.vozkoia.com/webhooks/workflow/SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Token: SEU_SECRET" \
  -d '{"event": "abandoned_cart", "external_id": "cart-9", "phone": "5511999990000", "name": "Ana", "cart_url": "https://loja.example/c/9"}'

A rota é pública (sem Authorization), aceita só POST, lê até 1 MB do corpo e tem limite próprio de 120 chamadas por minuto por endereço IP.

Campo do corpoUso
entry_id e entry_typeCom start_on: conversation, identificam a conversa pelo id interno.
phoneCom conversation, é resolvido para a conversa de WhatsApp mais recente do workspace com esse telefone. Com lead, encontra o lead pelo telefone ou cria um.
nameCom lead, o nome do lead criado.
emailCom lead, encontra um lead existente pelo e-mail.
eventComparado com config.events. Fora da lista, a chamada é aceita e ignorada.
external_idCom event, faz o mesmo evento iniciar uma única execução de lead mesmo se for reenviado.

O corpo inteiro fica disponível no fluxo em {{webhook.body}} (por exemplo {{webhook.body.cart_url}}), e o método em {{webhook.method}}. Com start_on: lead, o fluxo roda mesmo sem conversa, com {{lead_id}} e {{lead_name}}; nós que dependem de uma conversa seguem sem efeito.

Respostas

Statusstatus no corpoSignificado
202acceptedExecução iniciada; run_id traz o id.
202ignoredevent fora da lista do gatilho.
200duplicateA mesma chamada já foi recebida.
200already_runningJá há uma execução ativa desse gatilho na mesma conversa.

Para detectar repetições, o servidor usa o valor do primeiro destes cabeçalhos que vier preenchido: X-Idempotency-Key, X-Webhook-Id ou X-Event-Id. Sem nenhum deles, usa o corpo bruto. Uma repetição dentro de 6 horas responde duplicate.

Recusas trazem error, code e message:

StatuscodeQuando
400entry_requiredInício em conversa sem entry_id e entry_type, e sem phone.
400lead_contact_requiredInício em lead sem phone e sem email.
401unauthorizedCabeçalho de autenticação ausente ou errado.
403entry_forbiddenA conversa não pertence ao workspace do webhook.
404webhook_not_found ou webhook_inactiveToken desconhecido ou webhook desativado.
404entry_not_foundNenhuma conversa para o telefone.
404lead_not_foundNenhum lead com o e-mail.
405method_not_allowedMétodo diferente do configurado.
409workflow_not_activeO fluxo não está ativo.
422no_trigger_nodeA versão publicada não tem o gatilho de webhook.
422trigger_invalidA configuração do gatilho não é válida.
422lead_phone_invalidO phone não é um número válido.
429workspace_at_capacityO workspace atingiu o limite de execuções simultâneas.

GET /workflows/{id}/webhook/deliveries lista as chamadas recebidas nos últimos 30 dias, com o resultado, o motivo da recusa, a execução iniciada e só os nomes dos campos do corpo, nunca os valores.

Erros mais comuns

As recusas seguem o formato descrito em Erros.

StatuscodeQuando acontece
400name_requiredCriar sem name.
400invalid_trigger_type, invalid_workflow_type, trigger_not_allowedGatilho ou tipo desconhecidos, ou gatilho que não combina com o tipo.
400department_required, department_deniedDepartamento ausente para quem participa de vários, ou sem acesso.
400draft_revision_requiredSalvar ou restaurar sem revision.
403workflow_access_deniedO fluxo é de um departamento sem acesso.
404workflow_not_found, version_not_found, run_not_found, node_not_foundO recurso não existe ou não está visível.
409draft_conflictOutra sessão salvou o rascunho antes; a revisão atual vem em details.revision.
409workflow_not_active, run_terminal, run_already_exists, version_number_takenEstado que não permite a operação.
422workflow_not_publishablePublicar ou ativar com problemas que bloqueiam; a lista vem em details.issues.
422workflow_invalid ou um código do grafoO grafo enviado tem um valor inválido (por exemplo graph_duplicate_node_id ou invalid_node_type); o texto técnico vem em details.detail.
422workflow_needs_message_triggerIniciar pela API um fluxo sem gatilho de mensagem.
422trigger_input_invalidNo teste de nó, a entrada do gatilho não passa nas regras dele.

Referência

Todas as rotas estão no grupo Fluxos da Referência da API; os segredos ficam em Segredos do workspace, e o receptor público do webhook em Webhooks recebidos.