---
title: "Fluxos"
slug: flows
group: "Referência da API"
source: https://linkzap.orion.moe/developers/flows
openapi: https://linkzap.orion.moe/openapi.json
---

# Fluxos

Um fluxo é a conversa automática que a sua equipe montou no builder. Pelo API você pode iniciá-lo para um telefone — o resto acontece sozinho.

## Listar fluxos

### `GET /api/v1/flows`
Os fluxos da organização, em ordem alfabética pelo nome. Devolve todos de uma vez — esta lista não é paginada.

**Parâmetros da URL**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `enabled` | booleano | `true` traz só os ligados — que são os únicos que dá para iniciar. |

Pedido:

```bash
curl "https://linkzap.orion.moe/api/v1/flows?enabled=true" \
  -H "Authorization: Bearer lz_SUA_CHAVE"
```

Resposta:

```json
{
  "data": [
    {
      "id": "flw_2c77...",
      "name": "Triagem",
      "enabled": true,
      "channelId": null,
      "isMain": true,
      "updatedAt": "2026-09-18T20:14:00.000Z"
    }
  ]
}
```

- `channelId: null` significa que o fluxo atende **qualquer** número — não que ele esteja sem canal. Por isso uma chave de canal enxerga tanto os fluxos daquele número quanto os sem número.
- `isMain` marca o fluxo principal: o que responde quando nenhum outro gatilho combina.

## Iniciar um fluxo

### `POST /api/v1/flows/{id}/start`
Coloca a conversa daquele telefone dentro do fluxo. Cria o contato e a conversa se não existirem.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `channelId` | texto | com chave de conta | Por qual número. Com uma **chave de canal** pode ser omitido — o escopo preenche. Com a chave da conta é obrigatório: faltando, a resposta é 422 `Informe channelId.` |
| `phone` | texto | obrigatório | DDI + DDD + número. |

Pedido:

```bash
curl -X POST https://linkzap.orion.moe/api/v1/flows/flw_2c77.../start \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "chn_9f2a...",
    "phone": "5592999990000"
  }'
```

Resposta:

```json
{
  "data": {
    "conversationId": "cnv_5ad2...",
    "flowId": "flw_2c77...",
    "result": "started"
  }
}
```

`result` tem dois valores: **`started`**, que vem com `201`, e **`skipped`**, que vem com `409` — a conversa não aceita automação agora (está pausada, bloqueada ou já dentro de outro fluxo).

> [!NOTE]
> **Este 409 é a única exceção da API**
>
> Quando `result` é `skipped`, o `409` vem com **corpo de sucesso** (`{ "data": … }`), e não com `{ "error": … }` como todos os outros erros. Nada deu errado: o pedido foi entendido e recusado por estado, e o `result` diz qual. Se o seu código trata todo não-2xx lendo `error`, trate este caso antes.

Antes disso, os `409` normais (com `error`): o fluxo está desligado, não atende aquele canal, ou o número não está pronto para enviar. `404` é fluxo ou canal que não é desta organização.

> [!NOTE]
> **Por que isso costuma ser melhor que mandar texto**
>
> Iniciar um fluxo entrega a conversa a algo que sabe esperar resposta, ramificar e passar para um humano na hora certa. Mandar uma mensagem solta deixa a resposta do contato caindo na fila sem contexto. Quando existir um fluxo para o caso, prefira iniciá-lo.

> [!WARNING]
> **Um fluxo em andamento não é interrompido**
>
> Se a conversa já está dentro de outro fluxo, esta chamada não atropela o que estava acontecendo — e devolve o motivo. Mandar de novo em laço não muda isso.