Force First Message

Note: force_first_message is not a standalone endpoint. It is a field on the 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 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": "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:

sender_id provided in force_first_message (explicit)
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 Tony, thanks for your interest. Here are the next steps..."
  }
}

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.

{
  "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": "Tony", "..." : "..." },
  "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`

Quick Start

WhatsApp

Agents

Assistant

Advanced

API Reference

Leads

Agents

Workflow Tools

Client Tools

Groups

Campaigns

Conversions

Reports

Conversations

Tags

Messages

Background Jobs

Meetings

Team

Processors

Force First Message

How It Works

`force_first_message` Fields

Supported Channels

Email

WhatsApp

Cadence Behavior

Response

Error Handling

Validation Errors

​How It Works

​force_first_message Fields

​Supported Channels

​Email

​WhatsApp

​Cadence Behavior

​Response

​Error Handling

​Validation Errors

How It Works

`force_first_message` Fields

Supported Channels

Email

WhatsApp

Cadence Behavior

Response

Error Handling

Validation Errors