> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whatix.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Disparar flows

> Quando usar, como passar variáveis, a guarda de atendimento humano e a janela de 24h em disparo frio.

Um flow do FlowBuilder é uma automação publicada no painel (mensagens, condições, coleta de dados). [`POST /v1/flows/trigger`](/pt/referencia/flows/disparar-um-flow-do-flowbuilder-para-um-número) 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).

<Steps>
  <Step title="Dispare o flow">
    `flowId`, `whatsappId` (a conexão que vai enviar) e `number` são obrigatórios:

    ```bash theme={null}
    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:

    ```json theme={null}
    { "requestId": "...", "accepted": true, "ticketId": 933, "contactId": 501 }
    ```

    <Note>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](/pt/guias/conversas-e-mensagens) ou pelo efeito esperado no seu sistema (ex. o card mudou de etapa).</Note>
  </Step>

  <Step title="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`.

    <Warning>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.</Warning>

    ```bash theme={null}
    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" }] }'
    ```
  </Step>
</Steps>

## 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:

```json theme={null}
{ "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`:

```bash theme={null}
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

```bash theme={null}
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](/pt/erros-e-limites). Para orquestrar reativação com dados de cards, veja o caso guiado em [Cards e pipelines](/pt/guias/cards-e-pipelines).