Automatizaciones

Cree, lea, modifique y active automatizaciones de forma programática. Una automatización ejecuta **acciones** (aplicar etiqueta, mover etapa, enviar WhatsApp, crear tarea, llamar a un webhook…) cuando ocurre un **disparador** (lead creado, mensaje recibido, etapa cambiada, fecha, recurrencia…). La lectura exige el permiso `automations:read`; la escritura exige `automations:write`.

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

Conceptos importantes

Dos formatos de escritura. Puede enviar la automatización en flat (recomendado) — {name, trigger_type, trigger_config, conditions, actions} — y el servidor genera el grafo; o en graph — {name, nodes, edges} — fiel al editor visual. GET /automations/{id} siempre devuelve ambos dentro de spec, y ese mismo objeto se acepta de vuelta en POST/PUT.
Nace inactiva. Toda automatización creada por la API comienza desactivada (is_active: false). Activarla es un paso aparte (PATCH /automations/{id}/toggle) — activar tiene efecto real (la automatización pasa a enviar mensajes de WhatsApp a los clientes). Confirme con el usuario antes de activar.
Simulación con validate_only. Envíe "validate_only": true en cualquier POST/PUT para un dry-run: la API valida y devuelve errors/warnings sin grabar nada (responde siempre 200).
Validación estricta. Un spec inválido devuelve 422 con errors: [{ path, code, message }] señalando el campo exacto a corregir (ej.: actions[0].config.tags).

Listar automatizaciones

GET/automations

Permiso: automations:read

Paginado. Filtros mediante query string.

Parámetros de query

is_activebooleanopcional

Solo activas o solo inactivas

trigger_typestringopcional

Filtra por el disparador (ver GET /automations/capabilities)

searchstringopcional

Búsqueda por nombre

pageintegeropcional

Página

per_pageintegeropcional

Ítems por página (predeterminado 30, máx 100)

Solicitud

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

Respuesta

{
  "success": true,
  "data": [
    {
      "id": 42,
      "name": "Etiquetar novos leads",
      "trigger_type": "lead_created",
      "is_active": true,
      "run_count": 128,
      "last_run_at": "2026-07-19T14:03:11-03:00",
      "updated_at": "2026-07-18T09:20:00-03:00"
    }
  ],
  "meta": {
    "total": 1,
    "per_page": 30,
    "current_page": 1,
    "last_page": 1,
    "has_more": false
  }
}

Detallar una automatización

GET/automations/42

Permiso: automations:read

Devuelve el estado + el spec reimportable (flat + graph).

Solicitud

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

Respuesta

{
  "success": true,
  "data": {
    "id": 42,
    "is_active": true,
    "run_count": 128,
    "last_run_at": "2026-07-19T14:03:11-03:00",
    "updated_at": "2026-07-18T09:20:00-03:00",
    "spec": {
      "name": "Etiquetar novos leads",
      "trigger_type": "lead_created",
      "trigger_config": {},
      "conditions": [],
      "actions": [
        {
          "type": "add_tag_lead",
          "config": {
            "tags": [
              "Novo"
            ]
          }
        }
      ],
      "nodes": [],
      "edges": []
    }
  }
}

Crear una automatización

POST/automations

Permiso: automations:write

Formato flat (recomendado). La automatización nace inactiva.

Parámetros del body

namestringobligatorio

Nombre de la automatización (único)

trigger_typestringobligatorio

Disparador que activa la automatización (ej.: lead_created)

actionsarrayobligatorio

Acciones ejecutadas, con el formato { "type": "...", "config": { ... } }

trigger_configobjectopcional

Configuración del disparador (claves aceptadas en GET /automations/capabilities)

conditionsarrayopcional

Condiciones con el formato { "field": "...", "operator": "...", "value": "..." }

validate_onlybooleanopcional

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

Cada acción tiene la forma { "type": "...", "config": { ... } }.

Cada condición (opcional) tiene la forma { "field": "message_body", "operator": "contains", "value": "orçamento" }.

Enviar un name que ya existe devuelve 422 name_conflict — el POST nunca sobrescribe; use el PUT para modificar.

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/automations" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Etiquetar novos leads",
    "trigger_type": "lead_created",
    "trigger_config": {},
    "conditions": [],
    "actions": [
      {
        "type": "add_tag_lead",
        "config": {
          "tags": [
            "Novo"
          ]
        }
      }
    ]
  }'

Respuesta

{
  "success": true,
  "warnings": [],
  "data": {
    "id": 57,
    "is_active": false,
    "run_count": 0,
    "last_run_at": null,
    "updated_at": "2026-07-20T10:00:00-03:00",
    "spec": {}
  }
}

Simular antes de grabar (`validate_only`)

Envíe "validate_only": true en cualquier POST/PUT: la API valida el spec y devuelve errors/warnings sin grabar nada (responde siempre 200).

curl -X POST "https://app.syncro.chat/api/v1/automations" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" -H "Content-Type: application/json" \
  -d '{ "name": "Teste", "trigger_type": "lead_created",
        "actions": [ { "type": "add_tag_lead", "config": {} } ],
        "validate_only": true }'

{
  "success": true,
  "valid": false,
  "mode": "flat",
  "errors": [
    { "path": "actions[0].config.tags", "code": "missing_config_key", "message": "Action \"add_tag_lead\" requires config key \"tags\" (string[])." }
  ],
  "warnings": []
}

Actualizar una automatización

PUT/automations/42

Permiso: automations:write

Sustituye el spec entero (envíe el objeto completo; haga un GET antes). No altera el is_active (la activación es solo por el toggle).

Solicitud

curl -X PUT "https://app.syncro.chat/api/v1/automations/42" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Etiquetar novos leads",
    "trigger_type": "lead_created",
    "trigger_config": {},
    "conditions": [],
    "actions": [
      {
        "type": "add_tag_lead",
        "config": {
          "tags": [
            "Novo"
          ]
        }
      }
    ]
  }'

Activar / desactivar

PATCH/automations/57/toggle

Permiso: automations:write

Body opcional { "is_active": true } (ausente = invierte el estado actual).

Activar tiene efecto real: la automatización pasa a enviar mensajes a los clientes. Confirme con el usuario antes.

Solicitud

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

Respuesta

{
  "success": true,
  "id": 57,
  "is_active": true
}

Eliminar

DELETE/automations/57

Permiso: automations:write

Solicitud

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

Respuesta

{
  "success": true
}

Descubrir qué es válido

GET/automations/capabilities

Permiso: automations:read

Devuelve, de forma legible por máquina, todos los disparadores, acciones y claves de config aceptadas (la misma fuente que usa el validador — la doc nunca queda desactualizada). Consulte siempre este endpoint antes de montar una automatización.

Solicitud

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

Disparadores y acciones disponibles

Disparadores disponibles (17): message_received, conversation_created, lead_created, lead_stage_changed, lead_won, lead_lost, date_field, recurring, task_created, task_due_soon, calendar_event_created, calendar_event_canceled, calendar_event_starting_soon, appointment_confirmed, appointment_declined, stage_no_reply, stage_recurring.

Acciones disponibles (27): add_tag_lead, remove_tag_lead, add_tag_conversation, move_to_stage, set_lead_source, assign_to_user, assign_random_user, add_note, assign_ai_agent, assign_chatbot_flow, transfer_to_department, close_conversation, set_utm_params, create_task, enroll_sequence, ai_extract_fields, send_webhook, notify_user, send_whatsapp_message, send_whatsapp_group_message, schedule_whatsapp_message, send_whatsapp_notification, transfer_conversation, send_whatsapp_list, send_whatsapp_template (solo API Oficial), send_whatsapp_buttons (solo API Oficial), send_instagram_message.

Listar plantillas listas

GET/automations/templates

Permiso: automations:read

Lista las plantillas oficiales.

Solicitud

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

Instalar una plantilla

POST/automations/templates/etiquetar-novos-leads/install

Permiso: automations:write

Instala una plantilla oficial (idempotente por nombre; instalada inactiva).

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/automations/templates/etiquetar-novos-leads/install" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Formato de error

Toda escritura rechazada devuelve 422 con:

{
  "success": false,
  "message": "Automation spec failed validation. Fix the errors and retry (or use validate_only:true to iterate).",
  "errors": [ { "path": "actions[0].config.tags", "code": "missing_config_key", "message": "…" } ],
  "warnings": []
}

Códigos comunes: invalid_trigger, unknown_action, missing_config_key, fk_not_found, name_conflict, duplicate_handle, limit_reached. Warnings (no bloquean): unknown_token, unreachable_node.