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

# Force First Message

**Note:** `force_first_message` is not a standalone endpoint. It is a field on the [Create Lead](/docs/en/api/leads/create-lead) request body. Send it on `POST /leads` together with a `workflow_id`.

Override the first outreach when creating a lead and assigning it to a workflow. Instead of the workflow's default first contact (hot contact, initial templates, or first cadence step), your custom message is sent immediately via the specified channel. The rest of the cadence sequence continues normally from the second touchpoint onward.

This is useful when importing leads from external CRMs or ad platforms where you want to send a personalized first message while still leveraging the full cadence engine for follow-ups.

## How It Works

Use the `force_first_message` field in the [Create Lead](/docs/en/api/leads/create-lead) request body alongside a `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."
    }
  }'
```

## `force_first_message` Fields

| Field       | Type                      | Required           | Description                                                                             |
| ----------- | ------------------------- | ------------------ | --------------------------------------------------------------------------------------- |
| `channel`   | `"whatsapp"` \| `"email"` | **Yes**            | Channel to send the forced first message                                                |
| `content`   | string                    | **Yes**            | Message body. Plain text for WhatsApp, rendered as HTML for email                       |
| `subject`   | string                    | Required for email | Email subject line                                                                      |
| `sender_id` | string (uuid)             | No                 | Client's verified email sender ID. Falls back to the workflow's configured email sender |

## Supported Channels

### Email

Sends an email from the client's verified sender domain. The sender is resolved in this order:

1. `sender_id` provided in `force_first_message` (explicit)
2. `email_sender_id` configured in the workflow settings (fallback)

The email is tracked in `mail_logs` with full delivery status (sent, delivered, opened, bounced). The lead must have an `email` field.

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

Sends a free-form text message via WhatsApp. The lead must have a `phone` field.

**Note:** Free-form WhatsApp messages require an open 24 hour session window. Since this is typically a new lead who hasn't messaged first, the send may fail if no prior interaction exists. If the send fails, the response will include `force_first_message.sent: false` with the error, and the cadence will still continue normally.

```json theme={null}
{
  "force_first_message": {
    "channel": "whatsapp",
    "content": "Hola! Gracias por tu interes. Te cuento sobre nuestras opciones."
  }
}
```

## Cadence Behavior

When `force_first_message` is provided:

| Cadence Mode       | What Gets Skipped                 | What Continues                                                                      |
| ------------------ | --------------------------------- | ----------------------------------------------------------------------------------- |
| **Block cadence**  | Hot contact (1 template + 1 call) | Block 0 and all subsequent blocks run normally                                      |
| **Legacy cadence** | Initial messages + first attempt  | Cadence continues from attempt 2 of step 0 (or step 1 if step 0 only has 1 attempt) |

The forced message is recorded as a touchpoint, so `workflow_runs.total_touchpoints` will be `1` before the cadence's next action fires.

## Response

The response includes a `force_first_message` object alongside the standard lead and workflow\_run data:

**Success:**

```json theme={null}
{
  "success": true,
  "lead": { "id": "uuid", "first_name": "Tony", "..." : "..." },
  "workflow_run": { "id": "uuid", "..." : "..." },
  "force_first_message": {
    "sent": true,
    "channel": "email"
  }
}
```

**Send failed (cadence still starts):**

```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"
  }
}
```

## Error Handling

* If the forced message fails to send, the **cadence still starts** from the second touchpoint. The response flags `sent: false` with the error message so the caller can decide whether to retry.
* The lead is always created and assigned to the workflow regardless of the forced message result.

## Validation Errors

| Condition                                   | Error                                                                                     |
| ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `force_first_message` without `workflow_id` | `workflow_id is required when using force_first_message`                                  |
| Invalid channel                             | `force_first_message.channel must be 'whatsapp' or 'email'`                               |
| Missing content                             | `force_first_message.content is required`                                                 |
| Email channel without subject               | `force_first_message.subject is required for email channel`                               |
| Email channel without lead email            | `lead email is required when force_first_message channel is 'email'`                      |
| WhatsApp channel without lead phone         | `lead phone is required when force_first_message channel is 'whatsapp'`                   |
| No email sender configured                  | `No email sender configured, provide sender_id or set email_sender_id in workflow config` |