Saltar al contenido principal
Nota: force_first_message no es un endpoint independiente. Es un campo del cuerpo de la solicitud de Crear Lead. Envíalo en POST /leads junto con un workflow_id. Sobreescribe el primer alcance al crear un lead y asignarlo a un agente. En lugar del primer contacto por defecto del agente (contacto caliente, templates iniciales o primer paso de cadencia), tu mensaje personalizado se envía inmediatamente por el canal especificado. El resto de la secuencia de cadencia continúa normalmente desde el segundo punto de contacto en adelante. Esto es útil cuando importas leads desde CRMs externos o plataformas de anuncios donde quieres enviar un primer mensaje personalizado mientras aprovechas el motor de cadencia completo para los seguimientos.

​
Cómo Funciona

Usa el campo force_first_message en el cuerpo de la solicitud de Crear Lead junto con un workflow_id: 
curl -X POST https://api.getnexor.ai/api/public/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "first_name": "Tony",
    "last_name": "Stark",
    "email": "tony.stark@gmail.com",
    "phone": "+56912345678",
    "workflow_id": "uuid-of-workflow",
    "force_first_message": {
      "channel": "email",
      "subject": "Seguimiento de tu solicitud",
      "content": "Hola Tony, te escribo para dar seguimiento a tu consulta."
    }
  }'

​
Campos de force_first_message

CampoTipoRequeridoDescripción
channel"whatsapp" | "email"SíCanal para enviar el primer mensaje forzado
contentstringSíCuerpo del mensaje. Texto plano para WhatsApp, renderizado como HTML para email
subjectstringRequerido para emailAsunto del email
sender_idstring (uuid)NoID del remitente de email verificado del cliente. Recurre al remitente de email configurado en el agente

​
Canales Soportados

​
Email

Envía un email desde el dominio de remitente verificado del cliente. El remitente se resuelve en este orden:
  1. sender_id proporcionado en force_first_message (explícito)
  2. email_sender_id configurado en los ajustes del agente (fallback)
El email se rastrea en mail_logs con estado de entrega completo (enviado, entregado, abierto, rebotado). El lead debe tener un campo email. 
{
  "force_first_message": {
    "channel": "email",
    "subject": "Welcome to our program",
    "content": "Hi Tony, thanks for your interest. Here are the next steps..."
  }
}

​
WhatsApp

Envía un mensaje de texto libre vía WhatsApp. El lead debe tener un campo phone. Nota: Los mensajes de texto libre de WhatsApp requieren una ventana de sesión de 24 horas abierta. Como típicamente es un lead nuevo que no ha enviado mensaje primero, el envío puede fallar si no existe interacción previa. Si el envío falla, la respuesta incluirá force_first_message.sent: false con el error, y la cadencia continuará normalmente. 
{
  "force_first_message": {
    "channel": "whatsapp",
    "content": "Hola! Gracias por tu interes. Te cuento sobre nuestras opciones."
  }
}

​
Comportamiento de la Cadencia

Cuando se proporciona force_first_message:
Modo de CadenciaQué Se OmiteQué Continúa
Cadencia por bloquesContacto caliente (1 template + 1 llamada)Bloque 0 y todos los bloques subsecuentes se ejecutan normalmente
Cadencia legacyMensajes iniciales + primer intentoLa cadencia continúa desde el intento 2 del paso 0 (o paso 1 si el paso 0 solo tiene 1 intento)
El mensaje forzado se registra como un punto de contacto, así que workflow_runs.total_touchpoints será 1 antes de que la siguiente acción de la cadencia se ejecute.

​
Respuesta

La respuesta incluye un objeto force_first_message junto con los datos estándar de lead y workflow_run: Exitoso: 
{
  "success": true,
  "lead": { "id": "uuid", "first_name": "Tony", "..." : "..." },
  "workflow_run": { "id": "uuid", "..." : "..." },
  "force_first_message": {
    "sent": true,
    "channel": "email"
  }
}
Envío fallido (la cadencia aún comienza): 
{
  "success": true,
  "lead": { "id": "uuid", "..." : "..." },
  "workflow_run": { "id": "uuid", "..." : "..." },
  "force_first_message": {
    "sent": false,
    "channel": "email",
    "error": "Sender is not verified. Verify DNS records first"
  }
}

​
Manejo de Errores

  • Si el mensaje forzado falla al enviarse, la cadencia aún comienza desde el segundo punto de contacto. La respuesta indica sent: false con el mensaje de error para que el llamador pueda decidir si reintentar.
  • El lead siempre se crea y se asigna al agente sin importar el resultado del mensaje forzado.

​
Errores de Validación

CondiciónError
force_first_message sin workflow_idworkflow_id is required when using force_first_message
Canal inválidoforce_first_message.channel must be 'whatsapp' or 'email'
Contenido faltanteforce_first_message.content is required
Canal email sin asuntoforce_first_message.subject is required for email channel
Canal email sin email del leadlead email is required when force_first_message channel is 'email'
Canal WhatsApp sin teléfono del leadlead phone is required when force_first_message channel is 'whatsapp'
Sin remitente de email configuradoNo email sender configured, provide sender_id or set email_sender_id in workflow config
Última modificación el 17 de junio de 2026