API Reference

Web Chat

Monitor and manage live chat sessions from the embedded web widget.

Overview

The Web Chat API gives you programmatic access to sessions created through your embedded chat widget. You can list sessions, read message history, take over sessions from the AI, send agent replies, and pull analytics — all without touching the dashboard.

Web Chat must be enabled and the widget must be embedded on your site before sessions will appear here. Configure it in Settings → Web Chat.

The Session object

{
  "session_id": "sess_a1b2c3d4e5f6",
  "status": "active",
  "handled_by": "ai",
  "visitor_name": "Ahmad",
  "visitor_email": "ahmad@example.com",
  "visitor_phone": null,
  "visitor_ip": "1.2.3.4",
  "visitor_page_url": "https://yoursite.com/pricing",
  "visitor_referrer": "https://google.com",
  "has_visitor_messages": true,
  "human_requested_at": null,
  "human_took_over_at": null,
  "last_activity_at": "2026-03-08T14:22:00.000000Z",
  "created_at": "2026-03-08T14:15:00.000000Z"
}

Field	Type	Description
`session_id`	string	Unique session identifier
`status`	string	`active` or `ended`
`handled_by`	string	`ai`, `human`, or `pending`
`has_visitor_messages`	boolean	Whether the visitor has sent at least one message
`human_requested_at`	string\|null	When the visitor requested a human agent
`human_took_over_at`	string\|null	When a human agent took control

Analytics

GET /api/v1/web-chat/analytics

Returns aggregated statistics for your web chat widget.

Parameter	Type	Description
`period`	string	`today`, `week`, `month`, `year` (default: `month`)

curl "https://dashboard.skylightchat.com/api/v1/web-chat/analytics?period=week" \
  -H "X-Api-Key: ••••••••••••"

{
  "success": true,
  "data": {
    "total_chats": 142,
    "engaged_chats": 118,
    "active_chats": 7,
    "completed_chats": 111,
    "total_messages": 1043,
    "visitor_messages": 521,
    "bot_messages": 522,
    "avg_messages_per_chat": 7.3,
    "unique_visitors": 136,
    "chart_data": { ... }
  }
}

List sessions

GET /api/v1/web-chat/sessions

Parameter	Type	Description
`status`	string	`active`, `ended`
`handled_by`	string	`ai`, `human`, `pending`
`search`	string	Search visitor name, email, or phone
`per_page`	integer	Max 100 (default 25)

Get a session

GET /api/v1/web-chat/sessions/{session_id}

Returns the session object with the full message history.

{
  "session_id": "sess_a1b2c3d4e5f6",
  "status": "active",
  "handled_by": "human",
  "messages": [
    {
      "id": 1,
      "sender_type": "visitor",
      "message_text": "Hello! I'd like to know about pricing.",
      "message_type": "text",
      "media_url": null,
      "is_read": true,
      "created_at": "2026-03-08T14:15:30.000000Z"
    },
    {
      "id": 2,
      "sender_type": "bot",
      "message_text": "Hi! Our pricing starts at $29/month. Would you like to know more?",
      "message_type": "text",
      "is_read": true,
      "created_at": "2026-03-08T14:15:32.000000Z"
    }
  ]
}

sender_type values: visitor, bot, agent

Take over a session

POST /api/v1/web-chat/sessions/{session_id}/take-over

Transfers the session from AI to human control. The AI stops auto-responding immediately.

curl -X POST \
  https://dashboard.skylightchat.com/api/v1/web-chat/sessions/sess_a1b2c3d4e5f6/take-over \
  -H "X-Api-Key: ••••••••••••"

Release a session

POST /api/v1/web-chat/sessions/{session_id}/release

Returns the session to AI control. The AI will resume responding to new visitor messages.

Send a message

POST /api/v1/web-chat/sessions/{session_id}/messages

Send an agent reply into an active session. The message is delivered to the visitor in real time.

Field	Type	Required
`message`	string	✓ Max 4096 characters

curl -X POST \
  https://dashboard.skylightchat.com/api/v1/web-chat/sessions/sess_a1b2c3d4e5f6/messages \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hi Ahmad! I'm a live agent. How can I help you today?" }'

You cannot send messages to ended sessions.

Returns 201 Created with the message object.

End a session

POST /api/v1/web-chat/sessions/{session_id}/end

Closes the session. The visitor will see the chat as ended in their widget.

Support Tickets

Create and manage support tickets with your team.

Knowledge Base

Manage the AI knowledge base that powers automated responses across your channels.