API Reference

Channels

Connect, monitor, refresh, and disconnect WhatsApp, Telegram, Instagram, and LinkedIn channels via the API.

The Channel object

Every connect, status, and refresh endpoint returns a channel object:

{
  "id": 5,
  "type": "whatsapp",
  "username": "+966501234567",
  "is_connected": true,
  "sync_status": "OK",
  "last_synced_at": "2026-03-11T10:00:00+03:00"
}

Field	Type	Description
`id`	integer	Channel setting ID
`type`	string	`whatsapp`, `telegram`, `instagram`, or `linkedin`
`username`	string\|null	Phone number or Instagram username
`is_connected`	boolean	Whether the channel is currently active
`sync_status`	string	Live connection status — see table below
`last_synced_at`	string\|null	ISO 8601 timestamp of last sync

`sync_status` values

Value	Meaning
`OK`	Connected and healthy
`CONNECTING`	Account is initializing
`SYNC_SUCCESS`	Sync completed successfully
`CREDENTIALS`	Password changed - re-connect required
`ERROR`	Generic error - try refresh or re-connect
`STOPPED`	Account paused
`CREATION_FAIL`	QR connection attempt failed

WhatsApp uses a QR code flow. Your app generates a QR code and the end user scans it with their WhatsApp mobile app.

Connect WhatsApp

POST /api/v1/channels/whatsapp/connect

Generates a QR code for WhatsApp login. Returns the raw QR string and an account_id to poll with. Returns 409 if WhatsApp is already connected - disconnect first.

curl -X POST https://dashboard.skylightchat.com/api/v1/channels/whatsapp/connect \
  -H "X-Api-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "account_id": "wa_abc123",
    "qr_code": "2@AbCdEfGh...,1234..."
  },
  "message": "QR code generated. Scan with WhatsApp on your phone..."
}

Rendering the QR code: Pass the qr_code string to any standard QR library (e.g. qrcode.js, python-qrcode). The string is in WhatsApp's multi-device format - do not treat it as a URL.

Get WhatsApp status

GET /api/v1/channels/whatsapp/status

Poll this endpoint after the user scans the QR code. Pass the account_id returned by the connect call.

Query parameters

Parameter	Type	Description
`account_id`	string	Optional. Returned by `/connect`. Omit to get the current connected account.

curl "https://dashboard.skylightchat.com/api/v1/channels/whatsapp/status?account_id=wa_abc123" \
  -H "X-Api-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": 5,
    "type": "whatsapp",
    "username": "+966501234567",
    "is_connected": true,
    "sync_status": "OK",
    "last_synced_at": "2026-03-11T10:00:00+03:00",
    "completed": true,
    "in_progress": false
  }
}

`completed`	`in_progress`	Meaning
`false`	`true`	Waiting for QR scan - keep polling every 2-3 seconds
`true`	`false`	Connected successfully

Refresh WhatsApp status

POST /api/v1/channels/whatsapp/refresh

Pulls the latest account status from SkyLight Chat and updates local records. Useful after a disruption or to verify the account is healthy.

curl -X POST https://dashboard.skylightchat.com/api/v1/channels/whatsapp/refresh \
  -H "X-Api-Key: YOUR_API_KEY"

Returns the updated channel object.

Disconnect WhatsApp

POST /api/v1/channels/whatsapp/disconnect

Permanently disconnects the WhatsApp account and deletes local settings. Returns 204 No Content on success.

Returns 422 if an outreach campaign is currently running or paused on this channel - cancel it first.

curl -X POST https://dashboard.skylightchat.com/api/v1/channels/whatsapp/disconnect \
  -H "X-Api-Key: YOUR_API_KEY"

Telegram also uses a QR code flow. The user scans via Telegram app → Settings → Devices → Link Desktop Device.

Telegram connection is confirmed asynchronously after the QR scan. Keep polling the status endpoint until completed: true — this usually takes 5–15 seconds after the QR is scanned.

Connect Telegram

POST /api/v1/channels/telegram/connect

curl -X POST https://dashboard.skylightchat.com/api/v1/channels/telegram/connect \
  -H "X-Api-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "account_id": "tg_xyz789",
    "qr_code": "tg://login?token=ABCDEFGHIJ..."
  },
  "message": "QR code generated. Open Telegram → Settings → Devices → Link Desktop Device, then scan."
}

Get Telegram status

GET /api/v1/channels/telegram/status

Same polling interface as WhatsApp. Pass ?account_id=<id> from the connect response.

curl "https://dashboard.skylightchat.com/api/v1/channels/telegram/status?account_id=tg_xyz789" \
  -H "X-Api-Key: YOUR_API_KEY"

`completed`	`in_progress`	Meaning
`false`	`true`	Waiting - keep polling
`true`	`false`	Connected
`false`	`false`	Failed - generate a new QR code

Refresh Telegram status

POST /api/v1/channels/telegram/refresh

Returns the updated channel object.

Disconnect Telegram

POST /api/v1/channels/telegram/disconnect

Returns 204 No Content on success.

Instagram

Instagram uses credential-based authentication — no QR code. You pass the username and password directly to the API. Instagram 2FA is handled inline.

Connect Instagram

POST /api/v1/channels/instagram/connect

Request body

{
  "username": "my_brand_account",
  "password": "secretpassword",
  "country": "SA"
}

Field	Type	Required	Description
`username`	string	✓	Instagram username or email
`password`	string	✓	Instagram password
`country`	string	No	ISO 3166-1 alpha-2 country code. Default: `SA`. Used to route the connection geographically.

curl -X POST https://dashboard.skylightchat.com/api/v1/channels/instagram/connect \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my_brand", "password": "secret", "country": "SA"}'

Response - connected immediately

{
  "success": true,
  "data": {
    "id": 7,
    "type": "instagram",
    "username": "my_brand",
    "is_connected": true,
    "sync_status": "OK",
    "last_synced_at": "2026-03-11T10:00:00+03:00"
  }
}

Response - 2FA required

{
  "success": true,
  "data": {
    "requires_2fa": true,
    "account_id": "ig_abc123",
    "checkpoint_type": "OTP"
  },
  "message": "A verification code has been sent. Submit it to POST /channels/instagram/2fa."
}

When requires_2fa: true is returned, prompt your user for the verification code Instagram sent to their phone or email, then call the 2FA endpoint below.

Solve Instagram 2FA

POST /api/v1/channels/instagram/2fa

Submit the verification code during the Instagram connect flow.

Request body

{
  "account_id": "ig_abc123",
  "code": "123456"
}

Field	Type	Required	Description
`account_id`	string	✓	From the connect response
`code`	string	✓	The verification code the user received

Response - connected

{
  "success": true,
  "data": {
    "id": 7,
    "type": "instagram",
    "username": "my_brand",
    "is_connected": true,
    "sync_status": "CONNECTING"
  },
  "message": "Instagram connected successfully. Account is syncing."
}

Response - another verification round

{
  "success": true,
  "data": {
    "requires_2fa": true,
    "account_id": "ig_abc123",
    "checkpoint_type": "OTP"
  },
  "message": "Additional verification required. Submit your code again."
}

Resend Instagram 2FA code

POST /api/v1/channels/instagram/2fa/resend

Resends the verification code to the user's Instagram-registered phone or email.

Request body

{ "account_id": "ig_abc123" }

Response

{ "success": true, "message": "Verification code resent successfully." }

Get Instagram status

GET /api/v1/channels/instagram/status

Returns the current Instagram connection status from local records. Use /refresh to pull the latest status.

curl https://dashboard.skylightchat.com/api/v1/channels/instagram/status \
  -H "X-Api-Key: YOUR_API_KEY"

Returns the channel object.

Refresh Instagram status

POST /api/v1/channels/instagram/refresh

Syncs the account status with SkyLight Chat. Useful after a CREDENTIALS or ERROR state to see if the issue has been resolved.

Returns the updated channel object.

Disconnect Instagram

POST /api/v1/channels/instagram/disconnect

Disconnects the Instagram account and deletes local settings. Returns 204 No Content on success.

LinkedIn uses email + password authentication with optional 2FA (OTP, in-app approval, or CAPTCHA). Requires linkedin_access on your plan.

Connect LinkedIn

POST /api/v1/channels/linkedin/connect

Field	Type	Required
`username`	string	✓ - LinkedIn login email
`password`	string	✓
`country`	string	No - ISO country code, default `SA`

curl -X POST https://dashboard.skylightchat.com/api/v1/channels/linkedin/connect \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"YOUR_PASSWORD","country":"SA"}'

On success, returns the channel object with type: "linkedin". If 2FA is required:

{
  "success": true,
  "data": {
    "requires_2fa": true,
    "account_id": "211",
    "checkpoint_type": "OTP"
  }
}

Submit the code via POST /channels/linkedin/2fa with { "account_id", "code" }.

Endpoint	Description
`POST /channels/linkedin/2fa/resend`	Resend verification code
`GET /channels/linkedin/status`	Local connection status
`POST /channels/linkedin/refresh`	Sync status from provider
`POST /channels/linkedin/disconnect`	Remove account (204)

Connect flow summary

WhatsApp & Telegram (QR code)
────────────────────────────────────────────────────
1. POST /channels/{channel}/connect
   → { account_id, qr_code }

2. Render qr_code as a QR image for the user to scan

3. GET /channels/{channel}/status?account_id={id}
   Poll every 2-3 seconds until:
   → { completed: true }  ✓ Done

Instagram (credentials)
────────────────────────────────────────────────────
1. POST /channels/instagram/connect  { username, password }
   → Connected:    { is_connected: true }  ✓ Done
   → 2FA required: { requires_2fa: true, account_id, checkpoint_type }

2. (If 2FA) POST /channels/instagram/2fa  { account_id, code }
   → Connected:       { is_connected: true }  ✓ Done
   → Another round:   { requires_2fa: true }  → repeat step 2

LinkedIn (credentials - same pattern as Instagram)
────────────────────────────────────────────────────
1. POST /channels/linkedin/connect  { username, password, country }
2. (If 2FA) POST /channels/linkedin/2fa  { account_id, code }

Media

Upload and manage your image and video library via the API.

Partners

Manage client workspaces, usage reports, and billing as a SkyLight Chat reseller or agency partner.