Saltar al contenido principal
Las secuencias son campañas de cold-outreach. Defines una audiencia con criterios de leads, un throttle que controla el ritmo y el horario hábil, y luego lanzas la secuencia para enrolar los leads que coincidan en una cola de despacho por contacto. Cada endpoint en esta página opera dentro del tenant de la organización que llama — no puedes leer ni escribir secuencias de otra organización con la misma key.
call y whatsapp son canales despachables. Una secuencia whatsapp es un drip de varios pasos: un channelConfig a nivel de secuencia nombra la cuenta remitente, y una lista ordenada de steps lleva el contenido del mensaje y los delays de cada paso. SequenceChannel también define email, pero ese canal sigue diferido.

Ciclo de vida

Una secuencia atraviesa un conjunto fijo de estados SequenceStatus:
  • draft — recién creada. Editable y eliminable. Aún no se encola nada.
  • running — lanzada. El worker de despacho está procesando la cola de contactos.
  • paused — detenida temporalmente. Reanuda para continuar donde quedó.
  • completed — se establece automáticamente cuando la cola se vacía (cada contacto alcanzó un estado terminal). Terminal.
Reglas de transición — las transiciones ilegales devuelven 400 BAD_REQUEST:

Listar secuencias

Scope: sequences:read. Devuelve todas las secuencias de la organización, las más recientes primero. Este endpoint no está paginado — devuelve un array plano data.
Una credencial personal solo recibe secuencias activas (running) como { id, name, channel, status }. El query status se ignora. No incluye channelConfig, criterios, throttle ni progress. Crear, lanzar o pausar una secuencia completa no está disponible.

Query parameters

Response 200

Cada secuencia incluye un objeto progress derivado de su cola de contactos.

El objeto progress

Conteos de contactos por SequenceContactStatus. total es la suma del resto.

Crear una secuencia

Scope: sequences:write. Crea una secuencia en estado draft. No se encola nada hasta que la lanzas.

Request body

criteria — filtro de audiencia

Todos los campos son opcionales y se combinan con AND. Un objeto vacío {} matchea todos los leads de la organización.

channelConfig — requerido para WhatsApp

Requerido cuando channel es whatsapp; omítelo (o envía {}) para call. Es el remitente de todo el drip — ya no contiene el mensaje (eso pasó a steps).

steps — requerido para WhatsApp

Una secuencia de WhatsApp es un drip: un array ordenado de 1–10 pasos. Cada lead enrolado avanza por los pasos a lo largo del tiempo, y su posición en el drip es el estado de seguimiento por secuencia. El channelConfig de cada paso lleva el contenido del mensaje; delayValue/delayUnit programan cuándo se dispara. El channelConfig de cada paso (el contenido del mensaje):
Los mensajes del drip de WhatsApp se envían desde la cuenta de WhatsApp conectada de la organización y se hilan en el inbox. El drip se detiene para un lead que responde (cualquier WhatsApp entrante), se da de baja con una palabra clave (BAJA, STOP, CANCELAR, UNSUBSCRIBE) o llega a una etapa won/lost — el lead se marca como stopped y omite los pasos restantes. Las bajas también quedan excluidas de futuro outreach por WhatsApp (whatsappOptOut). Los envíos por paso son internos — no son requests separados a la API, y el lanzamiento cobra la cuota por leads enrolados, no por pasos.

throttle — ritmo y horario hábil

Todos los campos son requeridos.

Request — drip de WhatsApp

Una secuencia whatsapp con un channelConfig remitente y un drip steps de 3 pasos: un intro inmediato, un seguimiento 2 días después (con ±2h de jitter) y un último recordatorio 3 días más tarde que mueve el lead a una etapa del pipeline. Aquí criteria.leadIds apunta a un único lead explícito:

Response 201

Errores comunes

  • 400 VALIDATION_ERROR — body inválido (p. ej. name vacío, channel desconocido, throttle malformado, o channel: "whatsapp" sin un channelConfig válido y al menos un elemento en steps).

Obtener una secuencia

Scope: sequences:read. Devuelve la misma forma que un ítem del listado, incluyendo el objeto progress. 404 NOT_FOUND si la secuencia no existe o pertenece a otra org. Para los drips de WhatsApp, la respuesta incluye además los steps ordenados, un conteo progress.stopped, un stepFunnel y un objeto whatsappReceipts — acuses de entrega y lectura en vivo del proveedor:
steps refleja la definición del drip (cada entrada gana un stepOrder de base cero). stepFunnel reporta cuántos leads enrolados recibieron cada paso (acumulado — stepOrder 0 es el mayor, y los conteos bajan a medida que los leads se detienen o siguen esperando). whatsappReceipts agrega a través de todos los mensajes de los pasos:

Actualizar una secuencia

Scope: sequences:write. Solo drafts — editar una secuencia lanzada devuelve 400 BAD_REQUEST.

Request body

Todos los campos opcionales; envía solo lo que quieras cambiar. channel no se puede cambiar.
criteria y throttle se reemplazan por completo cuando se envían — manda el objeto completo, no un patch parcial. Para un drip de WhatsApp, channelConfig (el remitente) y steps (el drip ordenado completo) también se reemplazan por completo — envía el array steps completo, no un solo paso.

Response 200

Errores comunes

  • 400 BAD_REQUEST — "Only draft sequences can be edited".
  • 400 VALIDATION_ERROR — body inválido.
  • 404 NOT_FOUND — secuencia desconocida.

Eliminar una secuencia

Scope: sequences:write. Solo drafts. Las secuencias lanzadas son dueñas de su cola e historial de contactos (a quién se llamó, resultados, referencias de proveedor), por lo que se conservan como registro y no se pueden eliminar.

Response 200

Errores comunes

  • 400 BAD_REQUEST — "Only draft sequences can be deleted; launched sequences keep their contact history".
  • 404 NOT_FOUND — secuencia desconocida.

Previsualizar la audiencia

Scope: sequences:read. Cuenta cuántos leads coinciden actualmente con un conjunto de criterios — sin crear ni lanzar nada. Úsalo para dimensionar una audiencia antes de comprometerte, y para confirmar que está por debajo del tope de 5000 leads del lanzamiento.

Request body

El objeto criteria sigue el mismo schema que en la creación.

Response 200


Lanzar una secuencia

Scope: sequences:write. Solo drafts. Resuelve la audiencia a partir de los criterios de la secuencia, enrola cada lead que coincide en la cola de contactos y pasa la secuencia a running.
Lanzar consume tu cuota mensual de API de forma proporcional al tamaño de la audiencia. A diferencia de todos los demás endpoints — que cuestan una unidad — un lanzamiento consume una unidad por cada contacto encolado. Un lanzamiento que enrola 1.200 leads cuesta 1.200 unidades de tu cuota mensual. Esta ponderación aplica a todos los canales, incluido WhatsApp. Previsualiza la audiencia primero, y consulta Rate limits para saber cómo se contabiliza el costo mensual ponderado.

Response 200

enqueued es la cantidad de contactos enrolados (la cantidad de unidades cobradas).

Errores comunes

  • 400 BAD_REQUEST — "Only draft sequences can be launched" (ya está running, paused o completed).
  • 400 BAD_REQUEST — "No eligible leads match this sequence's criteria" (audiencia vacía).
  • 400 BAD_REQUEST — "Audience too large (over 5000 eligible leads). Narrow the criteria before launching."
  • 404 NOT_FOUND — secuencia desconocida.

Pausar una secuencia

Scope: sequences:write. Solo running. Detiene el despacho; los contactos en vuelo terminan, pero no se toman nuevos contactos.

Response 200

Errores comunes

  • 400 BAD_REQUEST — "Only running sequences can be paused".

Reanudar una secuencia

Scope: sequences:write. Solo paused. Devuelve la secuencia a running y el worker continúa con los contactos pending restantes.

Response 200

Errores comunes

  • 400 BAD_REQUEST — "Only paused sequences can be resumed".

Listar participaciones de un lead

Scope: sequences:read. Devuelve las inscripciones de un lead. Con una credencial personal el lead debe estar en la cartera actual (404 si no).

Response 200


Inscribir un lead en una secuencia

Scope: sequences:write. Inscribe un lead en una secuencia running.

Request body

Response 201

Errores comunes

  • 400 SEQUENCE_INACTIVE — la secuencia no existe, no está running, o el canal no es soportado.
  • 400 INELIGIBLE — el lead no cumple la audiencia / reglas del canal.
  • 409 ALREADY_ENROLLED — ya está en esta secuencia (incluido un retiro previo).
  • 404 NOT_FOUND — el lead no existe o está fuera de la cartera del caller.

Pausar, reanudar o retirar una participación

Scope: sequences:write. Actúa sobre una inscripción, no sobre la secuencia completa.

Request body

action es uno de pause, resume, withdraw.
  • pause — pausa manual (pauseKind: "manual"). El progreso se conserva.
  • resume — quita esa pausa si la secuencia sigue running y el lead sigue siendo elegible. Conserva un scheduledAt futuro.
  • withdraw — pasa el status a stopped. El member no puede volver a inscribir ese lead.

Errores comunes

  • 400 NOT_PAUSED — resume sin una pausa manual.
  • 400 SEQUENCE_INACTIVE — la secuencia no está running.
  • 400 INELIGIBLE — el lead ya no es elegible al reanudar.
  • 409 WITHDRAWN — la participación ya terminó.
  • 404 NOT_FOUND — falta el lead o el contacto, o el lead está fuera de la cartera.