SyncroDocumentação da API
Voltar ao site
Syncro

Automações

Crie, leia, altere e ative automações de forma programática. Uma automação executa **ações** (aplicar tag, mover etapa, enviar WhatsApp, criar tarefa, chamar webhook…) quando um **gatilho** acontece (lead criado, mensagem recebida, etapa mudou, data, recorrência…). Leitura exige a permissão `automations:read`; escrita exige `automations:write`.

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

Conceitos importantes

  • Dois formatos de escrita. Você pode enviar a automação em flat (recomendado) — {name, trigger_type, trigger_config, conditions, actions} — e o servidor gera o grafo; ou em graph — {name, nodes, edges} — fiel ao editor visual. O GET /automations/{id} sempre devolve os dois dentro de spec, e esse mesmo objeto é aceito de volta no POST/PUT.
  • Nasce inativa. Toda automação criada pela API começa desativada (is_active: false). Ativar é um passo separado (PATCH /automations/{id}/toggle) — ativar tem efeito real (a automação passa a disparar mensagens de WhatsApp aos clientes). Confirme com o usuário antes de ativar.
  • Simulação com validate_only. Envie "validate_only": true em qualquer POST/PUT para um dry-run: a API valida e devolve errors/warnings sem gravar nada (responde sempre 200).
  • Validação rígida. Um spec inválido retorna 422 com errors: [{ path, code, message }] apontando o campo exato a corrigir (ex.: actions[0].config.tags).

Listar automações

GET/automations
Permissão: automations:read

Paginado. Filtros via query string.

Parâmetros de query

is_activebooleanopcional
Somente ativas ou somente inativas
trigger_typestringopcional
Filtra pelo gatilho (ver GET /automations/capabilities)
searchstringopcional
Busca por nome
pageintegeropcional
Página
per_pageintegeropcional
Itens por página (padrão 30, máx 100)
Requisição
curl "https://app.syncro.chat/api/v1/automations?is_active=true" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"
Resposta
{
  "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
  }
}

Detalhar uma automação

GET/automations/42
Permissão: automations:read

Devolve o status + o spec re-importável (flat + graph).

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

Criar uma automação

POST/automations
Permissão: automations:write

Formato flat (recomendado). A automação nasce inativa.

Parâmetros do body

namestringobrigatório
Nome da automação (único)
trigger_typestringobrigatório
Gatilho que dispara a automação (ex.: lead_created)
actionsarrayobrigatório
Ações executadas, no formato { "type": "...", "config": { ... } }
trigger_configobjectopcional
Configuração do gatilho (chaves aceitas em GET /automations/capabilities)
conditionsarrayopcional
Condições no formato { "field": "...", "operator": "...", "value": "..." }
validate_onlybooleanopcional
*Dry-run*: valida e devolve errors/warnings sem gravar nada
i

Cada ação tem a forma { "type": "...", "config": { ... } }.

i

Cada condição (opcional) tem a forma { "field": "message_body", "operator": "contains", "value": "orçamento" }.

i

Enviar um name que já existe retorna 422 name_conflict — o POST nunca sobrescreve; use o PUT para alterar.

Requisição
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"
          ]
        }
      }
    ]
  }'
Resposta
{
  "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 gravar (`validate_only`)

Envie "validate_only": true em qualquer POST/PUT: a API valida o spec e devolve errors/warnings sem gravar nada (responde sempre 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": []
}

Atualizar uma automação

PUT/automations/42
Permissão: automations:write

Substitui o spec inteiro (envie o objeto completo; faça um GET antes). Não altera o is_active (ativação é só pelo toggle).

Requisição
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"
          ]
        }
      }
    ]
  }'

Ativar / desativar

PATCH/automations/57/toggle
Permissão: automations:write

Body opcional { "is_active": true } (ausente = inverte o estado atual).

i

Ativar tem efeito real: a automação passa a disparar mensagens aos clientes. Confirme com o usuário antes.

Requisição
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
  }'
Resposta
{
  "success": true,
  "id": 57,
  "is_active": true
}

Excluir

DELETE/automations/57
Permissão: automations:write
Requisição
curl -X DELETE "https://app.syncro.chat/api/v1/automations/57" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"
Resposta
{
  "success": true
}

Descobrir o que é válido

GET/automations/capabilities
Permissão: automations:read

Devolve, de forma legível por máquina, todos os gatilhos, ações e chaves de config aceitas (a mesma fonte que o validador usa — a doc nunca fica desatualizada). Sempre consulte este endpoint antes de montar uma automação.

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

Gatilhos e ações disponíveis

Gatilhos disponíveis (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.

Ações disponíveis (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 (só API Oficial), send_whatsapp_buttons (só API Oficial), send_instagram_message.

Listar modelos prontos

GET/automations/templates
Permissão: automations:read

Lista os modelos oficiais.

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

Instalar um modelo

POST/automations/templates/etiquetar-novos-leads/install
Permissão: automations:write

Instala um modelo oficial (idempotente por nome; instalado inativo).

Requisição
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 erro

Toda escrita rejeitada retorna 422 com:

{
  "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 comuns: invalid_trigger, unknown_action, missing_config_key, fk_not_found, name_conflict, duplicate_handle, limit_reached. Warnings (não bloqueiam): unknown_token, unreachable_node.