Execute

Execute Channel

Send a message or initiate a call to a lead. The execution is asynchronous — the response confirms the request was queued. Use schedule_for to schedule for a future time.

Authentication

X-API-Keystring
Your API key from [Dashboard → Settings → API Keys](https://dashboard.bookedin.ai/settings)

Request

This endpoint expects an object.
lead_idstringRequired
The lead to contact
agent_idstringRequired
The agent to use for the conversation
channelenumRequired
Communication channel to use
from_numberstringOptional

Phone number to use as caller ID (for voice/SMS). Auto-selected if not provided.

schedule_fordatetimeOptional

Schedule execution for a future time (ISO 8601 format). If not provided, executes immediately.

dynamic_instructionsstringOptional
Custom instructions for this specific execution. Appended to the agent's prompt.
static_messagestringOptional

Send a specific message instead of AI-generated. Supports variables: {{first_name}}, {{last_name}}, {{email}}, {{phone}}

static_subjectstringOptional

Email subject line (for gmail/outlook channels). Supports variable substitution.

attachment_urlstringOptionalformat: "uri"

URL of attachment to send (supported on WhatsApp, iMessage, SMS MMS, email)

execution_contextmap from strings to anyOptional

Additional context metadata for tracking (e.g., appointment_id, reminder_type)

Response

Execution queued or scheduled
thread_idstring or null
Unique execution thread ID for tracking
statusenum or null
Execution status
Allowed values:
messagestring or null

Human-readable status message

execution_idstring or null

Message ID (for immediate executions)

correlation_idstring or null
Correlation ID for tracing

Errors