API Reference

Messages

List conversations and send messages via WhatsApp, Telegram, and Instagram.

Overview

The Messages API lets you programmatically list conversations, retrieve message history for a contact, and send outbound messages across any of your connected channels (WhatsApp, Telegram, Instagram).

Messages can only be sent to contacts whose channel matches a connected account. Ensure your channel is connected in Settings → Channels before sending.

When AI auto-replies are on, inbound audio is transcribed and images are described for the agent, together with your Knowledge Base. Replies can include media from your Media library where the channel supports it.

The Message object

{
  "id": 201,
  "contact_id": 42,
  "direction": "outbound",
  "channel": "whatsapp",
  "content": "Hello Sarah, how can I help you today?",
  "status": "sent",
  "sent_at": "2026-03-04T12:00:00.000000Z",
  "created_at": "2026-03-04T12:00:00.000000Z"
}

Field	Type	Description
`id`	integer	Unique message ID
`contact_id`	integer	ID of the associated contact
`direction`	string	`inbound` or `outbound`
`channel`	string	`whatsapp`, `telegram`, `instagram`
`content`	string	Message text
`status`	string	`pending`, `sent`, `delivered`, `read`, `failed`
`sent_at`	string\|null	ISO 8601 timestamp
`created_at`	string	ISO 8601 creation timestamp

List conversations

GET /api/v1/conversations

Returns a paginated list of recent conversations, grouped by contact.

Query parameters

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Results per page (default: `15`)
`channel`	string	Filter by channel
`contact_id`	integer	Filter by contact

Example

curl "https://dashboard.skylightchat.com/api/v1/conversations?channel=whatsapp" \
  -H "Authorization: Bearer sk_live_••••••••••••"

Response

{
  "success": true,
  "data": [
    {
      "contact_id": 42,
      "contact_name": "Noura Al-Otaibi",
      "channel": "whatsapp",
      "last_message": "Hello Sarah, how can I help you today?",
      "last_message_at": "2026-03-04T12:00:00.000000Z",
      "unread_count": 0
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 15, "total": 38 }
}

List messages for a contact

GET /api/v1/contacts/{contact_id}/messages

Returns the full message history for a specific contact.

Query parameters

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Results per page
`direction`	string	`inbound` or `outbound`

curl "https://dashboard.skylightchat.com/api/v1/contacts/42/messages" \
  -H "Authorization: Bearer sk_live_••••••••••••"

Send a message

POST /api/v1/messages/send

Sends a message to a contact via their channel. SkyLight Chat automatically routes the message through the correct connected account.

Request body

{
  "contact_id": 42,
  "message": "Hello Sarah! Your appointment is confirmed for tomorrow at 2pm."
}

Field	Required	Description
`contact_id`	✓	ID of the target contact
`message`	✓	Message text to send

Example

curl -X POST https://dashboard.skylightchat.com/api/v1/messages/send \
  -H "Authorization: Bearer sk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 42, "message": "Your appointment is confirmed!"}'

Response `201 Created`

{
  "success": true,
  "data": {
    "id": 201,
    "contact_id": 42,
    "channel": "whatsapp",
    "content": "Your appointment is confirmed!",
    "status": "sent",
    "sent_at": "2026-03-04T12:00:00.000000Z"
  },
  "message": "Message sent successfully."
}

Failure response

If the message cannot be delivered (e.g., no channel connected), the record is saved with status: "failed":

{
  "success": false,
  "data": {
    "id": 202,
    "status": "failed",
    "error": "No whatsapp channel connected."
  },
  "message": "Message could not be delivered."
}

Supported channels

Channel	`type` value	Requirements
WhatsApp	`whatsapp`	WhatsApp account connected in Settings → Channels
Telegram	`telegram`	Telegram account connected in Settings → Channels
Instagram DM	`instagram`	Instagram account connected in Settings → Channels

Connect your channels in the dashboard under Settings → Channels before using the messaging API.

Contacts

Create, retrieve, update, delete, and organize your contacts.

Bookings

Create bookings, check available slots, and manage appointment resources.