Forzar Primer Mensaje

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`

Campo	Tipo	Requerido	Descripción
`channel`	`"whatsapp"` \| `"email"`	Sí	Canal para enviar el primer mensaje forzado
`content`	string	Sí	Cuerpo del mensaje. Texto plano para WhatsApp, renderizado como HTML para email
`subject`	string	Requerido para email	Asunto del email
`sender_id`	string (uuid)	No	ID 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:

sender_id proporcionado en force_first_message (explícito)
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..."
  }
}

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 Cadencia	Qué Se Omite	Qué Continúa
Cadencia por bloques	Contacto caliente (1 template + 1 llamada)	Bloque 0 y todos los bloques subsecuentes se ejecutan normalmente
Cadencia legacy	Mensajes iniciales + primer intento	La 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ón	Error
`force_first_message` sin `workflow_id`	`workflow_id is required when using force_first_message`
Canal inválido	`force_first_message.channel must be 'whatsapp' or 'email'`
Contenido faltante	`force_first_message.content is required`
Canal email sin asunto	`force_first_message.subject is required for email channel`
Canal email sin email del lead	`lead email is required when force_first_message channel is 'email'`
Canal WhatsApp sin teléfono del lead	`lead phone is required when force_first_message channel is 'whatsapp'`
Sin remitente de email configurado	`No email sender configured, provide sender_id or set email_sender_id in workflow config`

Quick Start

WhatsApp

Agentes

Asistente

Avanzado

Referencia API

Leads

Agentes

Workflow Tools

Client Tools

Grupos

Campañas

Conversiones

Reportes

Conversaciones

Tags

Background Jobs

Mensajes

Reuniones

Equipo

Procesadores

Forzar Primer Mensaje

Cómo Funciona

Campos de `force_first_message`

Canales Soportados

Email

WhatsApp

Comportamiento de la Cadencia

Respuesta

Manejo de Errores

Errores de Validación

​Cómo Funciona

​Campos de force_first_message

​Canales Soportados

​Email

​WhatsApp

​Comportamiento de la Cadencia

​Respuesta

​Manejo de Errores

​Errores de Validación

Cómo Funciona

Campos de `force_first_message`

Canales Soportados

Email

WhatsApp

Comportamiento de la Cadencia

Respuesta

Manejo de Errores

Errores de Validación