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.
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": "Sarah Johnson",
"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 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.