SyncroAPI Documentation
Back to site
Syncro

Automations

Create, read, change and activate automations programmatically. An automation runs **actions** (apply a tag, move a stage, send a WhatsApp message, create a task, call a webhook…) when a **trigger** happens (lead created, message received, stage changed, date, recurrence…). Reading requires the `automations:read` permission; writing requires `automations:write`.

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

Key concepts

  • Two write formats. You can send the automation as flat (recommended) — {name, trigger_type, trigger_config, conditions, actions} — and the server builds the graph; or as graph — {name, nodes, edges} — faithful to the visual editor. GET /automations/{id} always returns both inside spec, and that same object is accepted back on POST/PUT.
  • It starts inactive. Every automation created through the API starts disabled (is_active: false). Activating it is a separate step (PATCH /automations/{id}/toggle) — activation has real-world effects (the automation starts sending WhatsApp messages to customers). Confirm with the user before activating.
  • Dry-run with validate_only. Send "validate_only": true on any POST/PUT for a dry-run: the API validates and returns errors/warnings without saving anything (always answers 200).
  • Strict validation. An invalid spec returns 422 with errors: [{ path, code, message }] pointing at the exact field to fix (e.g. actions[0].config.tags).

List automations

GET/automations
Permission: automations:read

Paginated. Filters via query string.

Query parameters

is_activebooleanoptional
Only active or only inactive ones
trigger_typestringoptional
Filters by trigger (see GET /automations/capabilities)
searchstringoptional
Search by name
pageintegeroptional
Page
per_pageintegeroptional
Items per page (default 30, max 100)
Request
curl "https://app.syncro.chat/api/v1/automations?is_active=true" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"
Response
{
  "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
  }
}

Fetch one automation

GET/automations/42
Permission: automations:read

Returns the status + the re-importable spec (flat + graph).

Request
curl "https://app.syncro.chat/api/v1/automations/42" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"
Response
{
  "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": []
    }
  }
}

Create an automation

POST/automations
Permission: automations:write

Flat format (recommended). The automation starts inactive.

Body parameters

namestringrequired
Automation name (unique)
trigger_typestringrequired
Trigger that fires the automation (e.g. lead_created)
actionsarrayrequired
Actions to run, shaped as { "type": "...", "config": { ... } }
trigger_configobjectoptional
Trigger configuration (accepted keys in GET /automations/capabilities)
conditionsarrayoptional
Conditions shaped as { "field": "...", "operator": "...", "value": "..." }
validate_onlybooleanoptional
*Dry-run*: validates and returns errors/warnings without saving anything
i

Each action is shaped as { "type": "...", "config": { ... } }.

i

Each condition (optional) is shaped as { "field": "message_body", "operator": "contains", "value": "orçamento" }.

i

Sending a name that already exists returns 422 name_conflict — POST never overwrites; use PUT to change it.

Request
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"
          ]
        }
      }
    ]
  }'
Response
{
  "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": {}
  }
}

Simulate before saving (`validate_only`)

Send "validate_only": true on any POST/PUT: the API validates the spec and returns errors/warnings without saving anything (always answers 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": []
}

Update an automation

PUT/automations/42
Permission: automations:write

Replaces the whole spec (send the complete object; do a GET first). It does not change is_active (activation happens only through the toggle).

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

Activate / deactivate

PATCH/automations/57/toggle
Permission: automations:write

Optional body { "is_active": true } (omitted = flips the current state).

i

Activation has real-world effects: the automation starts sending messages to customers. Confirm with the user beforehand.

Request
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
  }'
Response
{
  "success": true,
  "id": 57,
  "is_active": true
}

Delete

DELETE/automations/57
Permission: automations:write
Request
curl -X DELETE "https://app.syncro.chat/api/v1/automations/57" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"
Response
{
  "success": true
}

Discover what is valid

GET/automations/capabilities
Permission: automations:read

Returns, in a machine-readable form, all accepted triggers, actions and config keys (the same source the validator uses — the docs never go stale). Always check this endpoint before assembling an automation.

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

Available triggers and actions

Available triggers (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.

Available actions (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 (Official API only), send_whatsapp_buttons (Official API only), send_instagram_message.

List ready-made templates

GET/automations/templates
Permission: automations:read

Lists the official templates.

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

Install a template

POST/automations/templates/etiquetar-novos-leads/install
Permission: automations:write

Installs an official template (idempotent by name; installed inactive).

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

Error format

Every rejected write returns 422 with:

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

Common codes: invalid_trigger, unknown_action, missing_config_key, fk_not_found, name_conflict, duplicate_handle, limit_reached. Warnings (non-blocking): unknown_token, unreachable_node.