Crea, edita y publica automatizaciones

Este tutorial crea un borrador que envía un enlace cuando un contacto comenta una palabra clave. Todos los ID, fechas, textos y URL siguientes son ilustrativos. Sustituye el ID de cuenta por uno devuelto en Listar cuentas. Usa una clave de API con los permisos necesarios.

1. Crea un borrador

Envía este cuerpo a POST /api/v1/automations con Authorization: Bearer <API_KEY> y Content-Type: application/json. La creación exige automations:write. El nombre permite de 1 a 120 valores escalares Unicode, sin espacios en los extremos ni caracteres de control.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "name": "Guide request",
  "status": "draft",
  "configuration": {
    "contact_filter": "anyone",
    "trigger": {
      "type": "comment",
      "publication": {
        "mode": "all"
      },
      "keywords": {
        "mode": "specific",
        "match_mode": "whole_word",
        "values": [
          "guide"
        ]
      }
    },
    "opening": {
      "public_reply": {
        "enabled": false
      },
      "direct_message": {
        "delay_seconds": 0,
        "message": {
          "text": "Here is the guide you asked for.",
          "buttons": [
            {
              "type": "url",
              "title": "Open the guide",
              "url": "https://example.com/guide"
            }
          ]
        }
      }
    },
    "follow_up": null,
    "extras": {
      "cooldown": {
        "mode": "none"
      }
    }
  }
}

Respuesta: HTTP 201

{
  "automation": {
    "id": "00000000-0000-4000-8000-000000000002",
    "account_id": "00000000-0000-4000-8000-000000000001",
    "name": "Guide request",
    "status": "draft",
    "has_unpublished_changes": false,
    "draft_updated_at": null,
    "created_at": "2026-09-01T12:00:00.000000Z",
    "updated_at": "2026-09-01T12:00:00.000000Z",
    "trigger_type": "comment",
    "configuration": {
      "contact_filter": "anyone",
      "trigger": {
        "type": "comment",
        "publication": {
          "mode": "all"
        },
        "keywords": {
          "mode": "specific",
          "match_mode": "whole_word",
          "values": [
            "guide"
          ]
        }
      },
      "opening": {
        "public_reply": {
          "enabled": false
        },
        "direct_message": {
          "delay_seconds": 0,
          "message": {
            "text": "Here is the guide you asked for.",
            "buttons": [
              {
                "type": "url",
                "title": "Open the guide",
                "url": "https://example.com/guide"
              }
            ]
          }
        }
      },
      "follow_up": null,
      "extras": {
        "cooldown": {
          "mode": "none"
        }
      }
    },
    "authoring_compatibility": "public_v1"
  }
}

El contenedor es automation, no data. Una escritura correcta guarda la automatización; no demuestra que se haya enviado un mensaje. Guarda id y la cadena exacta de updated_at. No redondees ni reformatees las fechas.

2. Consulta antes de editar

Llama a GET /api/v1/automations/{automationId}?account_id=... con automations:read. HTTP 200 devuelve el mismo contenedor completo mostrado arriba. Empieza siempre una edición con una consulta actualizada.

3. Renombra o sustituye la configuración

Para renombrar, envía este cuerpo a PATCH /api/v1/automations/{automationId}. Sustituye la fecha del ejemplo por el valor de la consulta actualizada.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "expected_updated_at": "2026-09-01T12:00:00.000000Z",
  "name": "Updated guide request"
}

Para cambiar el comportamiento, envía también el objeto configuration completo y modificado. Sustituye la configuración guardada; los objetos y arrays internos no se fusionan. Puedes enviar el nombre, la configuración o ambos, pero no status. HTTP 200 devuelve el contenedor completo de automation, incluido el nuevo updated_at. En una automatización activa, consulta has_unpublished_changes. Cuando es verdadero, el nombre y la configuración devueltos describen el borrador, mientras la versión publicada anteriormente sigue ejecutándose. draft_updated_at es informativo; el control de concurrencia siempre usa updated_at.

4. Publica o pausa

Después de revisar el borrador guardado, envía el siguiente cuerpo a POST /api/v1/automations/{automationId}/activate. Usa la versión más reciente de una nueva consulta. La activación exige automations:activate.

{
  "account_id": "00000000-0000-4000-8000-000000000001",
  "expected_updated_at": "2026-09-01T12:00:00.000000Z"
}

HTTP 200 devuelve el contenedor completo con status: "live" y la configuración publicada. Para pausar el procesamiento de nuevos triggers, envía el mismo formato de cuerpo con una versión actualizada a POST /api/v1/automations/{automationId}/deactivate; HTTP 200 devuelve status: "paused". Crear con status: "live" publica inmediatamente y también exige el permiso de activación.

Recupera sin duplicar escrituras

409 con api_automation_version_conflict: consulta de nuevo, concilia los cambios más recientes y reconstruye la edición.
422 con api_automation_invalid_configuration: consulta error.details.issues y corrige las rutas indicadas.
api_automation_committed_response_unavailable con committed: true y retryable: false: la escritura se aplicó. Consulta la automatización, o la lista después de crear, antes de decidir el siguiente paso.
Un resultado incierto de creación no debe repetirse a ciegas: la creación no es idempotente.

Ejemplo de respuesta de conflicto

HTTP 409.

{
  "error": {
    "code": "api_automation_version_conflict",
    "message": "The automation changed after the supplied version."
  }
}

Usa la guía de errores para el contenedor de respuesta, ID de correlación, fallos de autenticación y decisiones de reintento. Eliminar archiva la automatización y devuelve HTTP 204 sin cuerpo; no intentes interpretarlo como JSON.

Descripción general

Primeros pasos

Guías

Webhooks

Crea, edita y publica automatizaciones

1. Crea un borrador

Respuesta: HTTP 201

2. Consulta antes de editar

3. Renombra o sustituye la configuración

4. Publica o pausa

Recupera sin duplicar escrituras

Ejemplo de respuesta de conflicto

​1. Crea un borrador

​Respuesta: HTTP 201

​2. Consulta antes de editar

​3. Renombra o sustituye la configuración

​4. Publica o pausa

​Recupera sin duplicar escrituras

​Ejemplo de respuesta de conflicto

1. Crea un borrador

Respuesta: HTTP 201

2. Consulta antes de editar

3. Renombra o sustituye la configuración

4. Publica o pausa

Recupera sin duplicar escrituras

Ejemplo de respuesta de conflicto