Conversation Automations - /external/message

Optimly now routes every conversational automation through the /external/message namespace so leads, appointment intents, and human handoffs stay tied to their chat timeline. The payloads below mirror the MessageCore, ChatBase, and Message schemas in api_versions/v3.yaml to keep request/response fields authoritative.

Legacy /external/tools/*

The /external/tools/* routes no longer exist in the OpenAPI spec. If you previously relied on them, point your integrations to the /external/message/* endpoints summarized below. A site-wide redirect keeps old bookmarks working, but new development must target the message namespace.

Supported flows

Automation	Endpoint	Primary schema	When to use
Lead capture message	POST /external/message/new-message	MessageCore request → Message response	Append structured lead metadata (name, email, company, deal context) to an existing chat and flag it as collected.
Appointment request	POST /external/message/new-message	MessageCore request → Message response	Capture desired time, duration, and channel so downstream scheduling bots can respond without losing chat context.
New lead chat	POST /external/message/new-chat	ChatBase request → Chat response	Start a dedicated conversation for each submission and pre-set lead_collected or attribution flags.
Email escalation	POST /external/message/email-handoff	JSON object	Transfer an in-flight chat to a human queue while preserving the prior transcript and metadata.

All endpoints accept the standard Optimly auth headers (Authorization, X-API-Key, or access_token_query) and inherit the rate limits described in the OpenAPI specification.

Append lead data to an active chat

Send the lead summary as a regular assistant message so the entire transcript remains queryable.

POST /external/message/new-message
Authorization: Bearer YOUR_AGENT_ACCESS_TOKEN
Content-Type: application/json

{
  "chat_id": "chat_123",
  "sender": "assistant",
  "content": "Lead captured for John Doe <john@example.com>",
  "metadata": {
    "form_type": "lead_capture",
    "company": "Acme Corp",
    "phone": "+1-555-123-4567",
    "lead_collected": true,
    "interest": "50 seat pilot"
  }
}

Response (Message schema)

{
  "message_id": "msg_987",
  "chat_id": "chat_123",
  "sender": "assistant",
  "content": "Lead captured for John Doe <john@example.com>",
  "created_at": "2025-06-16T10:30:00Z",
  "metadata": {
    "form_type": "lead_capture",
    "lead_collected": true,
    "interest": "50 seat pilot"
  }
}

Need per-submission threads? Set lead_collected: true while calling POST /external/message/new-chat so reporting and downstream workflows inherit the context without reprocessing the payload.

Create a dedicated lead chat

Use ChatBase fields to control AI routing and attribution the moment a form submits.

POST /external/message/new-chat

{
  "client_id": "web_form_47",
  "ai_enabled": true,
  "lead_collected": true,
  "metadata": {
    "source": "homepage hero",
    "campaign": "spring_launch"
  }
}

Response (Chat schema excerpt)

{
  "chat_id": "chat_456",
  "client_id": "web_form_47",
  "agent_id": "agent_main",
  "ai_enabled": true,
  "lead_collected": true,
  "metadata": {
    "source": "homepage hero",
    "campaign": "spring_launch"
  },
  "created_at": "2025-06-16T10:30:00Z"
}

Immediately follow this call with POST /external/message/new-message if you want to seed the transcript with the submission details shown to the agent.

Capture appointment requests

Appointment data rides through the same /external/message/new-message endpoint. Populate the metadata block with scheduling specifics so downstream automations can parse it deterministically.

{
  "chat_id": "chat_789",
  "sender": "user",
  "content": "Book a 30-minute onboarding call on 2025-06-20 at 14:00 for Jane Smith",
  "metadata": {
    "form_type": "appointment_request",
    "duration_minutes": 30,
    "email": "jane@company.com",
    "timezone": "America/New_York",
    "preferred_channel": "Zoom"
  }
}

Pair the message with an /external/agent (or /external/agent/v2) call so the agent confirms receipt while your scheduling stack proposes times.

Escalate to email

Use the dedicated handoff endpoint to signal that a human should take over via email while retaining the chat history for auditing.

POST /external/message/email-handoff
Authorization: Bearer YOUR_AGENT_ACCESS_TOKEN

{
  "chat_id": "chat_123",
  "customer_email": "enterprise-buyer@example.com",
  "reason": "Pricing approval",
  "context": "Lead qualified via chatbot, needs annual invoice",
  "metadata": {
    "priority": "high",
    "assigned_team": "Sales"
  }
}

Response

{
  "handoff_id": "handoff_789",
  "status": "queued",
  "chat_id": "chat_123"
}

Monitor the resulting email thread in your CRM or ticketing system while Optimly keeps the chat record immutable for analytics and auditing.