Chatbots (fluxos)

Leia, crie, altere e ative fluxos de chatbot para WhatsApp, Instagram e chat do site. Um fluxo é um grafo de nós (mensagem, pergunta com opções, condição, horário de atendimento, ação, delay, fim…). Leitura exige `chatbots:read`; escrita exige `chatbots:write`.

Base URLhttps://app.syncro.chat/api/v1AuthX-API-Key: crm_SUA_CHAVE_AQUI

Conceitos importantes

Envelope versionado. O fluxo trafega num único objeto envelope — { syncro_chatbot_flow, schema_version, channel, flow, graph } — o mesmo que o GET devolve e o POST/PUT aceita de volta.
Nasce inativo. Fluxos criados pela API começam desativados. Ativar (PATCH /chatbots/{id}/toggle) faz o bot passar a responder conversas reais — confirme com o usuário antes.
Canal imutável. Depois de criado, o canal do fluxo não muda. Um PUT com canal diferente retorna channel_mismatch.
PUT substitui o grafo inteiro. Faça um GET antes e envie o envelope completo.
validate_only: true faz dry-run (sempre 200, com errors/warnings, sem gravar).
Recursos do plano. Requer a feature chatbot ligada; canal website requer também website_chat.

Listar fluxos

GET/chatbots

Permissão: chatbots:read

Paginado. Aceita filtros por canal, status e busca por nome.

Parâmetros de query

channelstringopcional

whatsapp, instagram ou website

is_activebooleanopcional

Somente fluxos ativos ou inativos

searchstringopcional

Busca por nome

pageintegeropcional

Página

per_pageintegeropcional

Itens por página

Requisição

curl "https://app.syncro.chat/api/v1/chatbots?channel=whatsapp&is_active=true" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Resposta

{
  "success": true,
  "data": [
    {
      "id": 12,
      "name": "Boas-vindas",
      "channel": "whatsapp",
      "is_active": true,
      "is_catch_all": false,
      "trigger_type": "keyword",
      "trigger_keywords": [
        "oi",
        "menu"
      ],
      "whatsapp_instance_id": null,
      "completions_count": 340,
      "updated_at": "2026-07-19T18:00:00-03:00"
    }
  ],
  "meta": {
    "total": 1,
    "per_page": 30,
    "current_page": 1,
    "last_page": 1,
    "has_more": false
  }
}

Detalhar um fluxo

GET/chatbots/12

Permissão: chatbots:read

Devolve o status do fluxo mais o envelope re-importável.

Requisição

curl "https://app.syncro.chat/api/v1/chatbots/12" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Resposta

{
  "success": true,
  "data": {
    "id": 12,
    "is_active": true,
    "is_catch_all": false,
    "whatsapp_instance_id": null,
    "completions_count": 340,
    "updated_at": "2026-07-19T18:00:00-03:00",
    "envelope": {
      "syncro_chatbot_flow": true,
      "schema_version": 1,
      "channel": "whatsapp",
      "flow": {
        "name": "Boas-vindas",
        "channel": "whatsapp",
        "trigger_type": "keyword",
        "trigger_keywords": [
          "oi",
          "menu"
        ]
      },
      "graph": {
        "nodes": [],
        "edges": []
      }
    }
  }
}

Criar um fluxo

POST/chatbots

Permissão: chatbots:write

O fluxo nasce inativo. Use PATCH /chatbots/{id}/toggle para ativá-lo depois.

Parâmetros do body

envelopeobjectobrigatório

Envelope versionado { syncro_chatbot_flow, schema_version, channel, flow, graph }

whatsapp_instance_idintegeropcional

Instância de WhatsApp vinculada ao fluxo

is_catch_allbooleanopcional

Fluxo de fallback do canal

validate_onlybooleanopcional

*Dry-run*: valida e devolve errors/warnings sem gravar

Requisição

curl -X POST "https://app.syncro.chat/api/v1/chatbots" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope": {
      "syncro_chatbot_flow": true,
      "schema_version": 1,
      "channel": "whatsapp",
      "flow": {
        "name": "Boas-vindas",
        "channel": "whatsapp",
        "trigger_type": "keyword",
        "trigger_keywords": [
          "oi",
          "menu"
        ]
      },
      "graph": {
        "nodes": [
          {
            "id": "n1",
            "type": "message",
            "position": {
              "x": 300,
              "y": 200
            },
            "data": {
              "text": "Olá! Como posso ajudar?"
            }
          },
          {
            "id": "n2",
            "type": "end",
            "position": {
              "x": 600,
              "y": 200
            },
            "data": {}
          }
        ],
        "edges": [
          {
            "id": "e1",
            "source": "n1",
            "sourceHandle": "default",
            "target": "n2"
          }
        ]
      }
    }
  }'

Regras do grafo

Um único nó inicial — exatamente um nó sem aresta de entrada (é o início do fluxo).
Ramos (opções) usam handles branch-N (com hífen: branch-0, branch-1…), únicos por nó, e cada aresta de ramo precisa de um sourceHandle correspondente.
Limites do runtime: delay de 1 a 30s; botões nativos ≤ 3 (rótulo ≤ 20 caracteres); listas ≤ 10 itens (rótulo ≤ 24, descrição ≤ 72); no máx. 200 nós / 400 arestas; payload ≤ 2 MB.

Alterar um fluxo

PUT/chatbots/12

Permissão: chatbots:write

Substitui o grafo inteiro. Faça um GET antes e envie o envelope completo.

Parâmetros do body

envelopeobjectobrigatório

Envelope completo — substitui todos os nós e arestas

validate_onlybooleanopcional

*Dry-run*: valida e devolve errors/warnings sem gravar

O canal é imutável: um PUT com canal diferente do original retorna channel_mismatch.

Requisição

curl -X PUT "https://app.syncro.chat/api/v1/chatbots/12" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope": {
      "syncro_chatbot_flow": true,
      "schema_version": 1,
      "channel": "whatsapp",
      "flow": {
        "name": "Boas-vindas",
        "channel": "whatsapp",
        "trigger_type": "keyword",
        "trigger_keywords": [
          "oi",
          "menu"
        ]
      },
      "graph": {
        "nodes": [
          {
            "id": "n1",
            "type": "message",
            "position": {
              "x": 300,
              "y": 200
            },
            "data": {
              "text": "Olá! Como posso ajudar?"
            }
          },
          {
            "id": "n2",
            "type": "end",
            "position": {
              "x": 600,
              "y": 200
            },
            "data": {}
          }
        ],
        "edges": [
          {
            "id": "e1",
            "source": "n1",
            "sourceHandle": "default",
            "target": "n2"
          }
        ]
      }
    }
  }'

Ativar / desativar fluxo

PATCH/chatbots/12/toggle

Permissão: chatbots:write

Envie { "is_active": true }. Se is_active estiver ausente, o estado atual é invertido. Ativar faz o bot passar a responder conversas reais.

Parâmetros do body

is_activebooleanopcional

Estado desejado; ausente inverte o estado atual

Ativar recheca as features do plano: retorna 403 se faltar chatbot (ou website_chat, no canal website).

Requisição

curl -X PATCH "https://app.syncro.chat/api/v1/chatbots/12/toggle" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": true
  }'

Excluir fluxo

DELETE/chatbots/12

Permissão: chatbots:write

Requisição

curl -X DELETE "https://app.syncro.chat/api/v1/chatbots/12" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Resposta

{
  "success": true
}

Descobrir o que é válido

GET/chatbots/capabilities

Permissão: chatbots:read

Devolve tipos de nó por canal, subtipos de ação, regras de handle, limites e um envelope de exemplo — é a fonte única do validador. Consulte antes de montar um fluxo.

Requisição

curl "https://app.syncro.chat/api/v1/chatbots/capabilities" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Tipos de nó e ações

Tipos de nó (9): message, input, condition, business_hours, action, delay, end, disable_chatbot, cards (só site).

Subtipos de ação (nó action): change_stage, save_variable, close_conversation, send_whatsapp, add_tag, remove_tag, assign_human, assign_random_user, send_webhook, set_custom_field, assign_ai_agent, create_task, enroll_sequence, transfer_conversation, create_lead (site), redirect (site).

Formato de erro

422 com errors: [{ path, code, message }]. Ex.: path: "graph.nodes[3].data.branches[1].handle", code: "invalid_handle".

Códigos comuns: feature_missing, limit_reached, channel_mismatch, no_start_node, multiple_start_nodes, invalid_handle, duplicate_handle, cap_exceeded, fk_not_found, payload_too_large.