Chatbots (flujos)

Lee, crea, modifica y activa flujos de chatbot para WhatsApp, Instagram y chat del sitio web. Un flujo es un grafo de nodos (mensaje, pregunta con opciones, condición, horario de atención, acción, delay, fin…). La lectura exige `chatbots:read`; la escritura exige `chatbots:write`.

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

Conceptos importantes

Envelope versionado. El flujo viaja en un único objeto envelope — { syncro_chatbot_flow, schema_version, channel, flow, graph } — el mismo que GET devuelve y POST/PUT acepta de vuelta.
Nace inactivo. Los flujos creados por la API empiezan desactivados. Activarlo (PATCH /chatbots/{id}/toggle) hace que el bot pase a responder conversaciones reales — confírmalo con el usuario antes.
Canal inmutable. Una vez creado, el canal del flujo no cambia. Un PUT con un canal distinto devuelve channel_mismatch.
PUT reemplaza el grafo entero. Haz un GET antes y envía el envelope completo.
validate_only: true hace un dry-run (siempre 200, con errors/warnings, sin guardar).
Recursos del plan. Requiere la feature chatbot activada; el canal website requiere también website_chat.

Listar flujos

GET/chatbots

Permiso: chatbots:read

Paginado. Acepta filtros por canal, estado y búsqueda por nombre.

Parámetros de query

channelstringopcional

whatsapp, instagram o website

is_activebooleanopcional

Solo flujos activos o inactivos

searchstringopcional

Búsqueda por nombre

pageintegeropcional

Página

per_pageintegeropcional

Ítems por página

Solicitud

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

Respuesta

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

Detallar un flujo

GET/chatbots/12

Permiso: chatbots:read

Devuelve el estado del flujo más el envelope reimportable.

Solicitud

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

Respuesta

{
  "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": []
      }
    }
  }
}

Crear un flujo

POST/chatbots

Permiso: chatbots:write

El flujo nace inactivo. Usa PATCH /chatbots/{id}/toggle para activarlo después.

Parámetros del body

envelopeobjectobligatorio

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

whatsapp_instance_idintegeropcional

Instancia de WhatsApp vinculada al flujo

is_catch_allbooleanopcional

Flujo de respaldo del canal

validate_onlybooleanopcional

*Dry-run*: valida y devuelve errors/warnings sin guardar

Solicitud

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

Reglas del grafo

Un único nodo inicial — exactamente un nodo sin arista de entrada (es el inicio del flujo).
Las ramas (opciones) usan handles branch-N (con guion: branch-0, branch-1…), únicos por nodo, y cada arista de rama necesita un sourceHandle correspondiente.
Límites del runtime: delay de 1 a 30s; botones nativos ≤ 3 (etiqueta ≤ 20 caracteres); listas ≤ 10 ítems (etiqueta ≤ 24, descripción ≤ 72); como máx. 200 nodos / 400 aristas; payload ≤ 2 MB.

Modificar un flujo

PUT/chatbots/12

Permiso: chatbots:write

Reemplaza el grafo entero. Haz un GET antes y envía el envelope completo.

Parámetros del body

envelopeobjectobligatorio

Envelope completo — reemplaza todos los nodos y aristas

validate_onlybooleanopcional

*Dry-run*: valida y devuelve errors/warnings sin guardar

El canal es inmutable: un PUT con un canal distinto del original devuelve channel_mismatch.

Solicitud

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

Activar / desactivar flujo

PATCH/chatbots/12/toggle

Permiso: chatbots:write

Envía { "is_active": true }. Si is_active está ausente, el estado actual se invierte. Activar hace que el bot pase a responder conversaciones reales.

Parámetros del body

is_activebooleanopcional

Estado deseado; ausente invierte el estado actual

Activar vuelve a comprobar las features del plan: devuelve 403 si falta chatbot (o website_chat, en el canal website).

Solicitud

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

Eliminar flujo

DELETE/chatbots/12

Permiso: chatbots:write

Solicitud

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

Respuesta

{
  "success": true
}

Descubrir qué es válido

GET/chatbots/capabilities

Permiso: chatbots:read

Devuelve tipos de nodo por canal, subtipos de acción, reglas de handle, límites y un envelope de ejemplo — es la fuente única del validador. Consúltalo antes de armar un flujo.

Solicitud

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

Tipos de nodo y acciones

Tipos de nodo (9): message, input, condition, business_hours, action, delay, end, disable_chatbot, cards (solo sitio web).

Subtipos de acción (nodo 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 (sitio web), redirect (sitio web).

Formato de error

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

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