Executa um fluxo em modo de teste, sem enviar mensagens nem fazer ligações de verdade. Você faz o papel do contato: responde mensagens, aperta teclas e acompanha cada nó executado.
Conectar
wss://SUA_URL_BASE/ws/workflows/{id}/simulate?ticket=SEU_TICKETid: ID do fluxo.- Permissão:
workflows:updateno workspace.
O modo depende do tipo do fluxo: fluxos voice simulam uma ligação; os demais simulam uma conversa de mensagens.
await_start=1(opcional): o servidor enviasim_readye só começa depois de umstartou de umreproduce_run. Use para ligar pontos de parada e confirmar chamadas reais antes do primeiro passo. Sem ele, a execução começa logo pelo gatilho principal, como umstartsemdata(ou depois doreplyinicial em fluxos disparados por mensagem). Se esse gatilho exige campos de entrada, nada roda: chegacommand_refusedcomcode: "trigger_input_invalid"eissues, e a sessão espera umstart(oureproduce_run) como comawait_start=1, semsim_ready.
Depuração
- O simulador usa o rascunho. Um nó com
pinned(saída fixada) devolve essa saída e segue a conexão fixada, sem executar; a etapa vem compinned: true. - Chamadas reais: nós de requisição HTTP sem saída fixada, nós de código que usam
fetch, e-mail e agenda (agendar, reagendar, consultar disponibilidade) chamam serviços externos de verdade. Eles aparecem emrealCallNodese só executam depois deconfirm_real_calls(vale para a sessão inteira). Sem a confirmação o nó falha comerrorKind: "real_call_not_confirmed". Envios de mensagem já são simulados. - Pontos de parada ficam só nesta sessão (não são gravados no fluxo). A pausa acontece antes de executar o nó. Uma pausa sem comando por 10 minutos encerra com
run_cancelledereason: "paused_timeout". - Saída fixada de produção (
source: "run:<id>") só vale para quem pode ver a conversa daquela execução (mesma regra da caixa de entrada). Para os demais, o nó roda como se não tivesse saída fixada (inclusive a regra de chamadas reais) e a etapa vem comnotice: "saída fixada indisponível para você". - Nós que mexem no CRM (etiqueta, etapa, atribuir membro, transferir departamento, negociação e campos do lead) não gravam nada: conferem o alvo no workspace (etiqueta, etapa, membro, departamento, funil ou campo) e devolvem o que fariam. A etapa vem com
simulated: trueeoutput.would_do: lista de{"kind": "label" \| "stage" \| "member" \| "department" \| "deal" \| "lead_field", "action": string, "target_id"?: string, "target_name"?: string, "field"?: string, "value"?: any, "description": string}. Um alvo que não existe (ou é de outro workspace) faz o nó falhar pela saída de erro, semwould_do. - Cada etapa que enviou mensagens traz, em
output, a listasent_messagescom as mesmas mensagens demessage_sent, no formatomessagedescrito abaixo. - Reproduzir uma execução de produção (
reproduce_run) exigeworkflows:reade poder ver a conversa da execução (mesma regra da caixa de entrada). O teste começa com os dados do gatilho daquela execução, fixa a saída e a conexão gravadas de cada nó HTTP, de código ou com efeito externo que rodou nela (só nesta sessão, sem gravar no rascunho) e pausa antes do primeiro passo. Nós que não rodaram na execução seguem a regra de chamadas reais. Valores mascarados na execução continuam mascarados. Só para fluxos de mensagens.
Entrada do gatilho
Cada item de sim_ready.triggers (TriggerInputSpec) é {"nodeId": string, "triggerType": string, "label": string, "shape": "fields" | "json" | "message" | "none", "fields": [TriggerInputField], "sample": object | null, "readKeys": [string], "issues": [{"code": string, "key": string}], "window": "open" | "closed" | null, "windowEditable": boolean, "acceptedEvents": [string]}. label é o nome dado ao nó (vazio sem nome). acceptedEvents lista os eventos que o webhook aceita, normalizados como a produção compara (minúsculas, sem espaços nas pontas); vazia quando o webhook aceita qualquer evento e em todo gatilho que não é webhook. window é a janela de atendimento de 24 h com que o gatilho costuma começar em produção: open para mensagens recebidas, chamado por agente e formulário respondido; closed para webhook, aniversário e entrada em etapa; null quando o gatilho não tem janela (ligação). windowEditable diz se o teste pode escolher a janela: false para mensagem recebida e primeira mensagem (a mensagem do próprio cliente abre a janela, como em produção) e para ligação; true para webhook, aniversário, entrada em etapa, formulário respondido e chamado por agente. Durante o teste, toda mensagem do cliente (a mensagem inicial, respostas, seleções, mídia, localização e formulário respondido) abre a janela pela mesma regra de produção (24 h desde a última mensagem do cliente). TriggerInputField é {"key": string, "type": "text" | "number" | "boolean" | "object" | "list", "required": boolean, "description": string, "example": string, "options"?: [{"value": string, "label": string}], "readBy": [string]}; readBy lista os nós que leem o campo e readKeys as chaves lidas pelo fluxo.
fields:inputé um objeto plano porkey. Chamado por agente IA: os campos declarados maisagent.name(vazio vira "Agente de teste"); formulário:form.<chave>como a produção grava as respostas, maisform_idquando o gatilho aceita mais de um formulário; etapa:stage_id(uma dasoptions); aniversário:birthday(AAAA-MM-DD, vazio usa hoje).json(webhook):inputé o corpo;sampleé um corpo com os caminhos que o fluxo lê e o primeiro evento aceito emevent.message:inputé ignorado; chegawaiting_triggere o primeiroreplycomeça a execução.none:inputé ignorado e a execução começa direto.
A entrada é validada como em produção e a execução é semeada pelo mesmo construtor de dados do gatilho. Antes do gatilho, o teste recebe em campvars os dados do teste salvos por quem testa (PUT /workflows/{id}/test-values), no mesmo lugar em que a produção põe os valores da campanha e da conversa, mais lead_name, lead_number e campaign_name do contato de teste; o start é recusado com automation_test_values_missing enquanto alguma variável que o fluxo usa não tem valor. Códigos em issues: required (campo obrigatório vazio; o agente também não consegue chamar sem ele), wrong_type, unknown_field, event_not_accepted (o webhook filtra eventos), unknown_option, too_large (mais de 64 KB). Em triggers[].issues, read_not_declared aponta uma chave lida pelo fluxo que o gatilho não declara (sempre vazia em produção); ela nunca bloqueia o início. trigger_input_unavailable aparece quando os formulários ou as etapas do gatilho não puderam ser lidos.
Mensagens que você envia
Formato: {"type": "...", "data": {...}}.
Fluxos de mensagens
| type | data | O que faz |
|---|---|---|
reply | {"text": string} (obrigatório) | Mensagem de texto do contato. Dispara o fluxo depois de waiting_trigger ou responde um waiting_reply. Em mensagens interativas, o texto ainda é usado como o id da opção escolhida (compatibilidade); prefira reply_selection. |
reply_selection | {"kind": "button" | "list", "id": string, "title": string} (todos obrigatórios) | O contato tocou um botão ou uma linha de lista, como o webhook entrega: message = title, message_type: "text", selected_option_id, selected_option_title e selected_option_type (button ou list). O ramo segue a saída com o id da opção, senão no_match. |
reply_location | {"latitude": number, "longitude": number, "name"?: string, "address"?: string} | O contato enviou uma localização: message = "📍 nome, endereço (lat, lng)" e message_type: "text", como no webhook. |
reply_media | {"kind": "image" | "video" | "audio" | "document" | "sticker", "url": string, "mime"?: string, "filename"?: string, "caption"?: string} | O contato enviou uma mídia: message_type: "media" e media_type (áudio: message_type: "audio"). message é a legenda (imagem, vídeo), o nome do arquivo (documento), vazio (figurinha) ou a legenda como transcrição (áudio). |
set_variable | {"key": string, "value": any} | Grava uma variável no estado da execução antes do próximo passo. |
form_reply | {"answers": {chave_do_campo: valor}} ou {"outcome": "no_reply"} | Responde um waiting_form: as respostas ficam nas variáveis form.<chave>; no_reply segue a saída Sem resposta. Um reply de texto não conclui o formulário. |
cancel | sem data | Cancela a execução. O servidor responde run_cancelled. |
Depuração (mensagens e voz)
| type | data | O que faz |
|---|---|---|
start | sem data ou {"triggerNodeId"?: string, "input"?: object, "windowOpen"?: boolean} | Com await_start=1 (ou depois da recusa do início automático sem ele): começa o teste depois do sim_ready, pelo gatilho triggerNodeId (sem ele, o defaultTriggerNodeId) com a entrada input, validada pelas regras de produção do gatilho (veja Entrada do gatilho). windowOpen escolhe a janela de atendimento com que o teste começa quando o gatilho tem windowEditable: true; sem ele vale o window do gatilho, e com windowEditable: false ele é ignorado (a mensagem do cliente decide). Com a janela fechada, todo envio livre (texto, mídia, botões, formulário, resposta do agente de IA) falha como em produção, com errorKind: "window_closed" na etapa, sem novas tentativas (recusa permanente, como contato bloqueado, descadastrado ou número inválido); só templates saem. Se for recusado, chega command_refused com code e a sessão continua esperando. |
reproduce_run | {"runId": string} | Com await_start=1 (ou durante waiting_trigger): começa o teste reproduzindo a execução. Se for recusado, chega command_refused e a sessão continua esperando. |
set_breakpoints | {"nodeIds": [string]} | Troca os pontos de parada da sessão. A execução pausa antes de cada um desses nós. |
run_until | {"nodeId": string} | Para uma vez antes desse nó. Se estiver pausado, continua até ele. |
step | sem data | Pausado: executa um nó e pausa antes do próximo. |
continue | sem data | Pausado: segue até o próximo ponto de parada. |
confirm_real_calls | sem data | Libera as chamadas reais pelo resto da sessão. Pode ser enviado a qualquer momento, inclusive antes do start. |
Fluxos de voz
| type | data | O que faz |
|---|---|---|
key | {"key": string} | Tecla do telefone: um caractere entre 0-9, * e #. |
cancel | sem data | Desliga a ligação simulada. O servidor responde run_cancelled. |
Fechar a conexão tem o mesmo efeito de cancel.
Mensagens que você recebe
Formato: {"type": "...", "payload": {...}}.
| type | payload | Quando |
|---|---|---|
sim_ready | {"workflowId": string, "triggerType": string, "realCallNodes": [string], "triggers": [TriggerInputSpec], "defaultTriggerNodeId": string} | Só com await_start=1: a sessão espera start ou reproduce_run. triggers descreve cada gatilho do rascunho (o principal primeiro) e o que ele recebe. |
waiting_trigger | {"triggerType": string, "nodeId": string} | O gatilho escolhido é de mensagem (shape: "message"): envie um reply para começar. |
sim_started | {"runId": string, "workflowId": string, "realCallNodes": [string], "trigger": {"nodeId": string, "triggerType": string}, "reproducing"?: {"runId": string, "workflowVersion"?: number, "pinnedNodes": [string]}} | A execução começou pelo gatilho trigger (ao reproduzir, o gatilho da execução quando ele ainda existe no rascunho). realCallNodes lista os nós que fariam chamadas reais; reproducing aparece ao reproduzir uma execução, com os nós fixados nesta sessão. |
state_update | {"vars": object} | Antes e depois de cada passo, com todas as variáveis. |
node_executed | Registro da etapa, o mesmo de GET /workflow-runs/{runId} (id, runId, nodeId, nodeType, status, input?, output?, error?, executedAt, attempt, startedAt?, finishedAt?, durationMs, branch?, errorKind?, errorChain?, stack?, scriptLogs?, http?), com valores sensíveis mascarados, mais stepIndex (número da etapa na sessão, a partir de 0), pinned? (true quando veio de uma saída fixada), simulated? (true quando um nó de CRM só descreveu o que faria, em output.would_do), notice? (por exemplo a saída fixada indisponível) e, quando o nó enviou mensagens, output.sent_messages | Um nó terminou. |
paused | {"nodeId": string, "nodeType": string, "stepIndex": number, "reason": "breakpoint" | "run_until" | "step", "state": object} | A execução parou antes desse nó. stepIndex é o número que a próxima etapa terá; state são as variáveis naquele momento, mascaradas. Responda step, continue, run_until ou cancel. |
command_refused | `{"command": string, "error": string, "code"?: "trigger_input_invalid" | "trigger_not_found" |
message_sent | {"direction": "outbound", "text": string, "msgType": string, "nodeId"?: string, "nodeName"?: string, "messageId": string, "audioBase64"?: string, "audioMime"?: string, "audioUrl"?: string, "message"?: object} | O fluxo enviou uma mensagem ou, em voz, tocou um áudio (msgType: "audio" com audioUrl). Em fluxos de mensagens, nodeId e nodeName (o nome dado ao nó, senão o nome do tipo no catálogo) são do nó que enviou, e a mensagem chega antes do node_executed desse nó. Em fluxos de mensagens, message é a mensagem como a conversa do CRM a guardaria (formato abaixo); text continua com o resumo antigo. |
message_received | {"direction": "inbound", "message": object} | Uma resposta sua (reply, reply_selection, reply_location, reply_media) como a conversa do CRM a guardaria. |
reply_ignored | {"nodeId": string, "reason": "interactive_reply_unhandled"} | A mensagem interativa não tem saída para essa resposta (nem no_match, nem saída padrão). Como em produção, o fluxo continua esperando. |
waiting_reply | {"nodeId": string, "timeoutSeconds": number} | O fluxo espera uma resposta do contato. |
waiting_form | {"nodeId": string, "formId": string, "timeoutSeconds": number} | O fluxo enviou um formulário do WhatsApp e espera as respostas: envie um form_reply. |
wait_skipped | {"nodeId": string, "reason": "duration" | "event"} | Uma espera por tempo ou evento foi pulada para agilizar o teste. |
waiting_key | {"timeoutSeconds": number} | Voz: o fluxo espera uma tecla. |
call_transferred | {"queueId": string, "queueName": string, "notes"?: string} | Voz: a ligação foi para a fila. Na simulação ela é considerada atendida e o fluxo termina. |
run_completed | {"vars": object} | A execução terminou. |
run_cancelled | {"reason": "cancelled" | "paused_timeout"} | A execução foi cancelada: pelo cancel (ou pela conexão fechada) ou por uma pausa abandonada por 10 minutos. |
run_error | {"error": string, "status"?: "error" | "cancelled"} | A execução parou com erro. |
error | {"error": string} | Não foi possível simular (fluxo inexistente, de outro workspace ou sem gatilho). A conexão é encerrada. |
Valores de msgType em fluxos de mensagens: text, button, list, media, audio, template, form, flow e call_permission_request.
Formato de message
messageO mesmo das mensagens de GET /conversations/... (o CRM renderiza com os mesmos componentes): id (igual a messageId), entryId, entryType, channel, messageType (ai_response, media, template, user_message, audio), direction (OUTBOUND ou INBOUND), sentBy, from, to, text, deliveryStatus (sent), createdAt e, quando houver:
mediaType(image,video,audio,document,sticker) emedia:{"url": string, "mimeType"?: string, "filename"?: string, "size"?: number, "layout": object}; a legenda fica emtext.metadata.buttons:{"header_text"?: string, "body_text": string, "footer_text"?: string, "buttons": [{"id": string, "title": string}]}(botões e também as linhas de uma lista, achatadas).metadata.list:{"header_text"?: string, "body_text": string, "footer_text"?: string, "button_text": string, "sections": [{"title"?: string, "rows": [{"id": string, "title": string, "description"?: string}]}]}.- Template (
messageType: "template"):metadatacomtemplate_name,language,category,body_text(corpo com os parâmetros),components(com os botões) eheader_media_url?;texté o corpo renderizado. metadata.form:{"kind": "message", "formId": string, "formName": string, "sendId": string, "cta": string}(formulário do WhatsApp;formNamevem vazio no teste).location:{"latitude": number, "longitude": number, "name"?: string, "address"?: string, "candidate": boolean}.
As respostas segmentadas do nó de IA chegam como um message_sent por segmento.
A sessão termina depois de run_completed, run_cancelled, run_error ou error.
Autenticação
Abra a conexão com um ticket de tempo real no parâmetro ticket: peça um em POST /v1/realtime/tickets logo antes de conectar. O ticket vale 30 segundos e abre uma única conexão; a cada reconexão, peça outro. Clientes fora do navegador também podem enviar o cabeçalho Authorization: Bearer SEU_ACCESS_TOKEN. O token na URL (?token=) e o cookie accessToken não abrem WebSockets. Um ticket inválido, vencido ou já usado recusa a conexão com realtime_ticket_invalid.
Workspace
Com o ticket, o workspace e o departamento são os do pedido do ticket (cabeçalhos X-Workspace-ID e X-Department-ID): não é preciso repeti-los na URL, e um workspaceId, workspace_id ou departmentId diferente é recusado com workspace_mismatch ou department_mismatch. Com o cabeçalho Authorization, informe o workspace em X-Workspace-ID, como nas rotas HTTP.
Formato das mensagens
Cada quadro de texto carrega um único objeto JSON com o tipo da mensagem. Datas são strings RFC 3339. Antes de abrir o WebSocket, erros de autenticação, workspace e permissão voltam como HTTP comum (401, 400, 403, 429, 501).
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||