Ciclo de vida de las secuencias

La página de Secuencias cubre las operaciones básicas (listar, obtener, ejecutar, pausar/reanudar y gestionar los contactos inscritos). Esta página describe los endpoints de ciclo de vida que se usan para crear e inspeccionar una secuencia de extremo a extremo, normalmente lo que necesita una CLI o una herramienta de compilación.

Todos los endpoints comparten el prefijo /sequences y requieren una clave de API de tipo Bearer.

Endpoint	Método	Descripción
`/sequences`	POST	Crear una secuencia (con pasos y canales opcionales)
`/sequences/{id}/preview`	GET	Leer secuencia, pasos y canales (sin inscripción)
`/sequences/{id}`	PATCH	Actualizar metadatos de la secuencia
`/sequences/{id}/steps/{step_id}`	PATCH	Actualizar un único paso
`/sequences/{id}/pause`	POST	Pausar una secuencia activa
`/sequences/{id}/resume`	POST	Reanudar una secuencia pausada
`/sequences/{id}/analytics`	GET	Informe completo de analíticas
`/sequences/{id}`	DELETE	Eliminación temporal (archivar) de una secuencia

Una secuencia en estado transitional (scheduling, pausing, resuming, terminating) no admite PATCH: se obtendrá 409 Conflict. Espere a que la operación se estabilice.

Para esquemas legibles por máquina, consulte la documentación interactiva de la API.

Crear secuencia

POST /sequences

Crea una secuencia en estado drafted. De forma opcional puede incluir steps[] y channels[] en la misma llamada.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre de la secuencia
`user_email`	string	Sí	Dirección de correo del propietario
`description`	string	No	Descripción libre
`finish_on_reply`	boolean	No (predeterminado `true`)	Detener el contacto al recibir respuesta
`send_in_same_thread`	boolean	No	Enviar los seguimientos en el mismo hilo de correo
`wait_for_new_contacts`	boolean	No	Mantener la secuencia a la espera de nuevas inscripciones
`associated_list_id`	integer	No	Lista de contactos que se asociará
`steps`	object[]	No	Configuración de los pasos. Consulte Configuración de paso
`channels`	object[]	No	Configuración de los canales. Consulte Configuración de canal
`campaign_id`	string	No	Campaña de AI Studio que se vinculará

Configuración de paso

Campo	Tipo	Descripción
`step_order`	integer	Orden dentro de la secuencia
`step_type`	string	`EMAIL`, `PHONE`, `SMS`, `LINKEDIN`, etc.
`input_type`	string	`ON_DEMAND` o `TEMPLATE` (predeterminado `ON_DEMAND`)
`time_interval`	integer	Retraso en segundos después del paso anterior
`step_data`	object	Datos de plantilla o contenido del paso (asunto, cuerpo, etc.)

Configuración de canal

Campo	Tipo	Descripción
`channel_id`	integer	ID del recurso (ID de buzón, ID de teléfono, etc.)
`channel_value`	string	La dirección o número en sí
`channel_type`	string	`EMAIL`, `PHONE`, `SMS`, `LINKEDIN`, `WHATSAPP`
`channel_data`	object	Metadatos opcionales

Ejemplo

cURL

curl -X POST "https://be.graph8.com/api/v1/sequences" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Outbound",
    "user_email": "[email protected]",
    "associated_list_id": 5,
    "steps": [
      {
        "step_order": 1,
        "step_type": "EMAIL",
        "input_type": "TEMPLATE",
        "time_interval": 0,
        "step_data": {"subject": "Quick intro", "body": "Hi {{first_name}}..."}
      }
    ],
    "channels": [
      {
        "channel_id": 12,
        "channel_value": "[email protected]",
        "channel_type": "EMAIL"
      }
    ]
  }'

Respuesta `201 Created`

{
  "data": {
    "id": "seq_abc",
    "name": "Q2 Outbound",
    "status": "drafted",
    "created_at": "2026-04-15T10:00:00Z"
  }
}

Errores

Estado	Significado
`400`	Configuración de paso o canal no válida

Vista previa de secuencia

GET /sequences/{sequence_id}/preview

Vista de solo lectura de una secuencia con todos sus pasos y canales. No inscribe a ningún contacto.

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/sequences/seq_abc/preview" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": {
    "id": "seq_abc",
    "name": "Q2 Outbound",
    "status": "drafted",
    "description": null,
    "steps": [
      {
        "id": "stp_1",
        "step_order": 1,
        "step_type": "EMAIL",
        "input_type": "TEMPLATE",
        "time_interval": 0,
        "step_data": {"subject": "Quick intro", "body": "..."}
      }
    ],
    "channels": [
      {"id": "ch_1", "channel_id": 12, "channel_value": "[email protected]", "channel_type": "EMAIL"}
    ]
  }
}

Actualizar secuencia

PATCH /sequences/{sequence_id}

Actualiza los metadatos de la secuencia. Envíe únicamente los campos que desee modificar.

Cuerpo de la solicitud

Campo	Tipo	Descripción
`name`	string	Nombre de la secuencia
`description`	string	Descripción
`is_shared`	boolean	Compartir con la organización
`finish_on_reply`	boolean	Finalizar al recibir respuesta
`send_in_same_thread`	boolean	Seguimientos en el mismo hilo
`wait_for_new_contacts`	boolean	Esperar nuevos contactos
`schedule_id`	string	ID de programación
`appointment_id`	integer	ID de cita

Ejemplo

cURL

curl -X PATCH "https://be.graph8.com/api/v1/sequences/seq_abc" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q2 Outbound v2", "send_in_same_thread": true}'

Errores

Estado	Significado
`404`	Secuencia no encontrada
`409`	La secuencia se encuentra en un estado transitional (`scheduling`, `pausing`, `resuming`, `terminating`)

Actualizar paso

PATCH /sequences/{sequence_id}/steps/{step_id}

Actualiza un único paso. Se aplica la misma regla 409 si la secuencia principal está en transición.

Cuerpo de la solicitud

Campo	Tipo	Descripción
`step_data`	object	Datos de plantilla o contenido
`time_interval`	integer	Retraso en segundos después del paso anterior
`step_type`	string	Tipo de paso
`input_type`	string	`ON_DEMAND` o `TEMPLATE`

Ejemplo

cURL

curl -X PATCH "https://be.graph8.com/api/v1/sequences/seq_abc/steps/stp_1" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_data": {"subject": "Quick intro v2", "body": "Updated..."}}'

Pausar y reanudar

POST /sequences/{sequence_id}/pause POST /sequences/{sequence_id}/resume

Pausa una secuencia activa (o reanuda una pausada). Devuelve la cantidad de contactos afectados.

Respuesta

{
  "data": {
    "sequence_id": "seq_abc",
    "status": "paused",
    "contacts_affected": 150
  }
}

Analíticas

GET /sequences/{sequence_id}/analytics

Devuelve un informe completo de analíticas: KPIs generales, rendimiento en el tiempo, desglose de engagement, distribución de contactos, métricas por paso y distribución por remitente. La estructura refleja el modelo interno SequenceReports.

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/sequences/seq_abc/analytics" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": {
    "overview": {"sent": 320, "opened": 180, "replied": 22},
    "performance": {"open_rate": 0.56, "reply_rate": 0.07},
    "engagement": {"by_day": [...]},
    "timeline": [...],
    "contact_distribution": {"active": 150, "completed": 100, "stopped": 70},
    "step_breakdown": [
      {"step_id": "stp_1", "sent": 320, "opened": 180}
    ],
    "step_creation_methods": [...],
    "sender_distribution": [...]
  }
}

Encontrará el esquema completo en /api/v1/docs, bajo SequenceAnalyticsResponse.

Eliminar (archivar)

DELETE /sequences/{sequence_id}

Realiza una eliminación temporal de una secuencia estableciendo is_archived = true. Las secuencias ya archivadas devuelven 400. Las secuencias en ciertos estados no terminales no pueden archivarse y devuelven 409.

Ejemplo

cURL

curl -X DELETE "https://be.graph8.com/api/v1/sequences/seq_abc" \
  -H "Authorization: Bearer $API_KEY"

Errores

Estado	Significado
`400`	La secuencia ya está archivada
`404`	Secuencia no encontrada
`409`	La secuencia no puede archivarse en su estado actual

Ciclo de vida de las secuencias

Crear secuencia

Cuerpo de la solicitud

Configuración de paso

Configuración de canal

Ejemplo

Respuesta 201 Created

Errores

Vista previa de secuencia

Ejemplo

Respuesta

Actualizar secuencia

Cuerpo de la solicitud

Ejemplo

Errores

Actualizar paso

Cuerpo de la solicitud

Ejemplo

Pausar y reanudar

Respuesta

Analíticas

Ejemplo

Respuesta

Eliminar (archivar)

Ejemplo

Errores

Respuesta `201 Created`