Disparar flows

Um flow do FlowBuilder é uma automação publicada no painel (mensagens, condições, coleta de dados). POST /v1/flows/trigger dispara um flow existente para um número, fora do fluxo normal de atendimento. Requer escopo flows:trigger.

Quando usar

Reativação: retomar contato com leads parados (ex.: cards perdidos há 30 dias) sem precisar de um atendente iniciando manualmente.
Pós-venda: disparar uma pesquisa de satisfação ou instruções de uso depois que um card fecha como won.
Qualquer disparo em massa orientado por evento do seu sistema (não por mensagem recebida — para isso, o flow já dispara sozinho pelas regras configuradas no painel).

Dispare o flow

flowId, whatsappId (a conexão que vai enviar) e number são obrigatórios:

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/flows/trigger \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flowId": 14,
    "whatsappId": 2,
    "number": "5534999990000",
    "contactName": "João Pereira",
    "variables": { "cupom": "VOLTA10" }
  }'

A resposta é 202 — o flow foi validado e aceito, mas roda em background:

{ "requestId": "...", "accepted": true, "ticketId": 933, "contactId": 501 }

202 significa “aceito pra execução”, não “executado com sucesso”. Não há webhook de conclusão hoje — se precisar confirmar o resultado, acompanhe pela conversa (ticketId retornado) com Conversas e mensagens ou pelo efeito esperado no seu sistema (ex. o card mudou de etapa).

O que o flow recebe como variável hoje

O flow sempre tem disponíveis as variáveis nativas {{nome}}, {{telefone}}, {{protocolo}}, {{data}} e {{hora}}, resolvidas automaticamente do contato e do ticket criado no disparo — não do variables que você manda no POST.

O variables do disparo (o cupom do exemplo acima) não fica disponível como {{variables.cupom}} nem de nenhuma outra forma dentro do flow hoje — ele é aceito pela API, mas não chega aos nós. Se o flow precisa de um dado específico da sua integração (cupom, ID externo, etc.), faça o upsert do contato antes de disparar, salvando o dado em extraInfo, e leia o campo dentro do flow pelos nós que consultam extraInfo do contato. Isso pode mudar em versões futuras da API.

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/contacts \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "number": "5534999990000", "extraInfo": [{ "name": "cupom", "value": "VOLTA10" }] }'

A guarda de atendimento humano (409)

Se o contato já tem uma conversa aberta com um atendente humano na conexão informada, o disparo é bloqueado por padrão — pra não atropelar quem já está atendendo:

{ "error": "ERR_TICKET_IN_HUMAN_SERVICE", "ticketId": 933 }

Isso vem com 409. Se você quer disparar mesmo assim (raro — normalmente significa que o flow vai brigar com o atendente), use force: true:

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/flows/trigger \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "flowId": 14, "whatsappId": 2, "number": "5534999990000", "force": true }'

Janela de 24h em disparo frio (WABA)

Em conexão WABA, se o número estiver fora da janela de 24h, o flow precisa começar com um nó de template. Se o primeiro nó for texto livre, a Meta rejeita com o erro 131047 e o lead não recebe nada — mesmo o disparo tendo sido aceito com 202. Monte o flow de reativação começando por um nó de template aprovado; os nós seguintes (texto livre, condições) rodam normalmente depois que o cliente responde e a janela reabre.

Flow inexistente ou despublicado

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/flows/trigger \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "flowId": 999, "whatsappId": 2, "number": "5534999990000" }'

Se flowId não existe na conta, 404 ERR_FLOW_NOT_FOUND. Se existe mas está inativo, despublicado ou sem nós, 422 ERR_FLOW_NOT_EXECUTABLE — publique o flow no FlowBuilder antes de disparar.

Erros comuns

Código	HTTP	Causa
`ERR_FLOW_ID_AND_WHATSAPP_ID_REQUIRED`	400	`flowId` e `whatsappId` são obrigatórios.
`ERR_VARIABLES_MUST_BE_OBJECT`	400	`variables` precisa ser um objeto JSON, não string nem array.
`ERR_FLOW_NOT_FOUND`	404	Flow inexistente ou de outra conta.
`ERR_FLOW_NOT_EXECUTABLE`	422	Flow inativo, despublicado ou sem nós.
`ERR_CONNECTION_NOT_FOUND`	404	`whatsappId` não corresponde a uma conexão desta conta.
`ERR_UNSUPPORTED_CHANNEL`	422	A conexão não é `whatsapp`/`waba`.
`ERR_TICKET_IN_HUMAN_SERVICE`	409	Contato em atendimento humano ativo; use `force: true` conscientemente.

Veja o catálogo completo de erros. Para orquestrar reativação com dados de cards, veja o caso guiado em Cards e pipelines.

Início

Guias

Referência

Disparar flows

Quando usar

A guarda de atendimento humano (409)

Janela de 24h em disparo frio (WABA)

Flow inexistente ou despublicado

Erros comuns

​Quando usar

​A guarda de atendimento humano (409)

​Janela de 24h em disparo frio (WABA)

​Flow inexistente ou despublicado

​Erros comuns

Quando usar

A guarda de atendimento humano (409)

Janela de 24h em disparo frio (WABA)

Flow inexistente ou despublicado

Erros comuns