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

enabledbooleano
true traz só os ligados — que são os únicos que dá para iniciar.

Pedidocurl

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

RespostaJSON

{
  "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)

channelIdtextocom 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.
phonetextoobrigatório
DDI + DDD + número.

Pedidocurl

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"
  }'

RespostaJSON

{
  "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).

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.

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.

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.