> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnexor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Forzar Primer Mensaje

**Nota:** `force_first_message` no es un endpoint independiente. Es un campo del cuerpo de la solicitud de [Crear Lead](/docs/es/api/leads/create-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](/docs/es/api/leads/create-lead) junto con un `workflow_id`:

```bash theme={null}
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:

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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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` |