Force First Message

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 POST /leads request body alongside a 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": "Carlos",
    "last_name": "Mendoza",
    "email": "carlos@example.com",
    "phone": "+56912345678",
    "workflow_id": "uuid-of-workflow",
    "force_first_message": {
      "channel": "email",
      "subject": "Seguimiento de tu solicitud",
      "content": "Hola Carlos, 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.

{
  "force_first_message": {
    "channel": "email",
    "subject": "Welcome to our program",
    "content": "Hi Carlos, 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.

WhatsApp 24-hour Window

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.

{
  "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:

{
  "success": true,
  "lead": { "id": "uuid", "first_name": "Carlos", "..." : "..." },
  "workflow_run": { "id": "uuid", "..." : "..." },
  "force_first_message": {
    "sent": true,
    "channel": "email"
  }
}

Send failed (cadence still starts):

{
  "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