Send Message

POST /messages

Send a message to a lead through WhatsApp, email, or trigger an AI-powered phone call. The message is sent through the channel's configured provider for the given workflow.

Request Body

Field	Type	Required	Description
lead_id	string (uuid)	Yes	Lead to contact
workflow_id	string (uuid)	Yes	Workflow that determines channel configuration (WhatsApp number, email sender, voice agent)
channel	string	Yes	"whatsapp", "email", or "call"
content	string	Depends	Message body (plain text). Required for whatsapp (unless using template_id) and email. Use \n for line breaks
subject	string	No	Email subject line. Defaults to "Message from your advisor" if omitted
template_id	string (uuid)	No	WhatsApp template ID. When provided, sends a template message instead of free-form text
components	array	No	Template parameters in Meta format. Used with template_id
begin_message	string	No	Custom greeting for call channel. Overrides the workflow's default opening message

Channel requirements

Channel	Required fields	Lead must have
whatsapp	content or template_id	phone
email	content	email
call	(none beyond base fields)	phone

WhatsApp 24-hour window

Free-form WhatsApp messages (content) can only be sent within Meta's 24-hour conversation window. If the window has expired, use template_id to send an approved template message instead.

Examples

Send a WhatsApp text message

curl -X POST https://api.getnexor.ai/api/public/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "lead_id": "lead-uuid",
    "workflow_id": "workflow-uuid",
    "channel": "whatsapp",
    "content": "Hi John, just following up on our conversation."
  }'

Send a WhatsApp template

curl -X POST https://api.getnexor.ai/api/public/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "lead_id": "lead-uuid",
    "workflow_id": "workflow-uuid",
    "channel": "whatsapp",
    "template_id": "template-uuid",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          { "type": "text", "parameter_name": "nombre", "text": "John" },
          { "type": "text", "parameter_name": "agente", "text": "Sofia" },
          { "type": "text", "parameter_name": "empresa", "text": "Acme Corp" }
        ]
      }
    ]
  }'

Send an email

curl -X POST https://api.getnexor.ai/api/public/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "lead_id": "lead-uuid",
    "workflow_id": "workflow-uuid",
    "channel": "email",
    "subject": "Follow-up on your inquiry",
    "content": "Hi John, here is the information you requested.\n\nLet us know if you have any questions."
  }'

Trigger an AI phone call

curl -X POST https://api.getnexor.ai/api/public/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "lead_id": "lead-uuid",
    "workflow_id": "workflow-uuid",
    "channel": "call"
  }'

Trigger an AI phone call with custom greeting

curl -X POST https://api.getnexor.ai/api/public/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "lead_id": "lead-uuid",
    "workflow_id": "workflow-uuid",
    "channel": "call",
    "begin_message": "Hi Carlos, I am calling to follow up on your appointment."
  }'

Responses

200 — WhatsApp text message sent

{
  "success": true,
  "channel": "whatsapp",
  "type": "text",
  "message_id": "msg-uuid",
  "provider_message_id": "wamid.ABC123"
}

200 — WhatsApp template sent

{
  "success": true,
  "channel": "whatsapp",
  "type": "template",
  "message_id": "msg-uuid",
  "provider_message_id": "wamid.ABC123"
}

200 — Email sent

{
  "success": true,
  "channel": "email",
  "message_id": "rqe-message-id",
  "activity_id": "activity-uuid"
}

200 — Call initiated

{
  "success": true,
  "channel": "call",
  "call_id": "call-uuid",
  "call_status": "registered"
}

Response Fields

Field	Type	Description
success	boolean	Whether the message was sent successfully
channel	string	Channel used: whatsapp, email, or call
type	string	WhatsApp only: text or template
message_id	string	Internal message identifier
provider_message_id	string	WhatsApp only: Meta's message ID (wamid)
activity_id	string	Email only: delivery tracking ID
call_id	string	Call only: Retell call identifier
call_status	string	Call only: initial call status (registered)

400 — Validation or delivery error

{
  "error": "content or template_id is required for whatsapp"
}

Other possible errors:

• "lead_id, workflow_id, and channel are required"
• "channel must be 'whatsapp', 'email', or 'call'"
• "Lead has no phone number"
• "Lead has no email"
• "No email sender configured for this workflow"
• "No active WhatsApp channel assigned to this workflow"
• "Template not found"

422 — WhatsApp window expired

Returned when sending a free-form text message outside Meta's 24-hour conversation window. The lead must have replied within the last 24 hours for text messages to be delivered.

{
  "error": "whatsapp_window_expired",
  "message": "Lead has not replied in the last 24 hours. Free-form messages cannot be sent outside the conversation window.",
  "suggestion": "Use template_id to send an approved template message instead. See GET /templates for available templates.",
  "last_inbound_at": "2026-04-05T14:30:00Z"
}

tip

Use GET /templates to find an approved template, then send it with template_id and components. Template messages can be sent at any time regardless of the conversation window.

401 — Authentication error

See Authentication.

500 — Internal server error