API Reference

Partners

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

The Partners API is available on the Agency and Enterprise plans. You must be enrolled in the SkyLight Chat Partner Program to receive a partner API key.

The Partners API allows resellers, agencies, and white-label operators to programmatically manage client workspaces under their partner account. Use it to provision new clients, monitor usage, pull billing data, and automate onboarding workflows.

Authentication

Partner API calls use a dedicated partner API key, separate from regular workspace keys. Obtain yours from Partner Dashboard → API & Integrations.

curl https://dashboard.skylightchat.com/api/v1/partner/... \
  -H "X-Partner-Key: pk_live_••••••••••••"

All partner endpoints are prefixed with /api/v1/partner/.

The Partner object

{
  "id": 7,
  "company_name": "Rawabi Digital",
  "slug": "rawabi-digital",
  "email": "api@rawabidigital.sa",
  "plan": "agency",
  "status": "active",
  "client_seats": { "used": 14, "max": 50 },
  "created_at": "2025-09-01T08:00:00.000000Z"
}

Field	Type	Description
`id`	integer	Unique partner account ID
`company_name`	string	Partner company name
`slug`	string	Unique URL-safe identifier
`email`	string	Primary contact email
`plan`	string	Partner plan: `agency` or `enterprise`
`status`	string	`active`, `suspended`, or `pending`
`client_seats.used`	integer	Number of active client workspaces
`client_seats.max`	integer	Maximum allowed client workspaces on this plan
`created_at`	string	ISO 8601 timestamp

Get partner profile

GET /api/v1/partner/profile

Returns your partner account details and current seat usage.

curl https://dashboard.skylightchat.com/api/v1/partner/profile \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response

{
  "success": true,
  "data": {
    "id": 7,
    "company_name": "Rawabi Digital",
    "slug": "rawabi-digital",
    "email": "api@rawabidigital.sa",
    "plan": "agency",
    "status": "active",
    "client_seats": { "used": 14, "max": 50 },
    "branding": {
      "logo_url": "https://dashboard.skylightchat.com/storage/partners/7/logo.png",
      "primary_color": "#1a73e8",
      "custom_domain": "chat.rawabidigital.sa"
    },
    "created_at": "2025-09-01T08:00:00.000000Z"
  }
}

The Client object

A client is a fully isolated workspace provisioned under your partner account.

{
  "id": 101,
  "partner_id": 7,
  "company_name": "Al-Madar Retail",
  "slug": "al-madar-retail-4x8z",
  "plan": "business",
  "status": "active",
  "primary_user": {
    "id": 202,
    "first_name": "Sara",
    "last_name": "Hassan",
    "email": "sara@almadar.sa",
    "phone": "+966501112233"
  },
  "usage": {
    "contacts": 3820,
    "messages_this_month": 9400,
    "team_members": 5
  },
  "created_at": "2026-01-10T09:00:00.000000Z",
  "suspended_at": null
}

Field	Type	Description
`id`	integer	Unique client workspace ID
`partner_id`	integer	Your partner account ID
`company_name`	string	Client company name
`slug`	string	Unique workspace slug (used in dashboard URL)
`plan`	string	The plan assigned to this workspace
`status`	string	`active`, `suspended`, or `pending_setup`
`primary_user`	object	The main admin user for this workspace
`usage`	object	Live usage counters for this billing period
`created_at`	string	ISO 8601 creation timestamp
`suspended_at`	string\|null	Timestamp of suspension, or `null`

List clients

GET /api/v1/partner/clients

Returns a paginated list of all client workspaces under your partner account.

Query parameters

Parameter	Type	Description
`page`	integer	Page number (default: `1`)
`per_page`	integer	Results per page (default: `15`, max: `100`)
`status`	string	Filter by status: `active`, `suspended`, `pending_setup`
`search`	string	Search by company name, email, or slug
`plan`	string	Filter by plan slug (e.g., `business`, `pro`)

Example

curl "https://dashboard.skylightchat.com/api/v1/partner/clients?status=active&per_page=25" \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response

{
  "success": true,
  "data": [
    {
      "id": 101,
      "company_name": "Al-Madar Retail",
      "slug": "al-madar-retail-4x8z",
      "plan": "business",
      "status": "active",
      "primary_user": {
        "email": "sara@almadar.sa"
      },
      "usage": {
        "contacts": 3820,
        "messages_this_month": 9400
      },
      "created_at": "2026-01-10T09:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 25,
    "total": 14
  }
}

Create a client

POST /api/v1/partner/clients

Provisions a new workspace and immediately creates the primary admin user. An invitation email is sent to the admin unless skip_invite is set.

Request body

{
  "company_name": "Gulf Logistics",
  "plan": "pro",
  "admin": {
    "first_name": "Khalid",
    "last_name": "Nasser",
    "email": "khalid@gulflogistics.sa",
    "phone": "+966507654321"
  },
  "timezone": "Asia/Riyadh",
  "country_id": 194,
  "skip_invite": false
}

Field	Required	Type	Description
`company_name`	✓	string	Client company name
`plan`	✓	string	Plan slug: `starter`, `pro`, `business`
`admin.first_name`	✓	string	Admin first name
`admin.last_name`	✓	string	Admin last name
`admin.email`	✓	string	Admin email address (must be unique)
`admin.phone`	—	string	Admin phone (E.164 format)
`timezone`	—	string	IANA timezone (defaults to `UTC`)
`country_id`	—	integer	Country ID
`skip_invite`	—	boolean	Skip sending the welcome email (default: `false`)

Example

curl -X POST https://dashboard.skylightchat.com/api/v1/partner/clients \
  -H "X-Partner-Key: pk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Gulf Logistics",
    "plan": "pro",
    "admin": {
      "first_name": "Khalid",
      "last_name": "Nasser",
      "email": "khalid@gulflogistics.sa"
    }
  }'

Response `201 Created`

{
  "success": true,
  "data": {
    "id": 115,
    "company_name": "Gulf Logistics",
    "slug": "gulf-logistics-9k2p",
    "plan": "pro",
    "status": "active",
    "primary_user": {
      "id": 230,
      "email": "khalid@gulflogistics.sa"
    },
    "dashboard_url": "https://dashboard.skylightchat.com/login?workspace=gulf-logistics-9k2p",
    "created_at": "2026-03-14T11:00:00.000000Z"
  },
  "message": "Client workspace created successfully."
}

Get a client

GET /api/v1/partner/clients/{id}

Returns full details for a single client workspace.

curl https://dashboard.skylightchat.com/api/v1/partner/clients/101 \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response

{
  "success": true,
  "data": {
    "id": 101,
    "company_name": "Al-Madar Retail",
    "slug": "al-madar-retail-4x8z",
    "plan": "business",
    "status": "active",
    "primary_user": {
      "id": 202,
      "first_name": "Sara",
      "last_name": "Hassan",
      "email": "sara@almadar.sa",
      "phone": "+966501112233"
    },
    "usage": {
      "contacts": 3820,
      "messages_this_month": 9400,
      "team_members": 5
    },
    "branding_inherited": true,
    "created_at": "2026-01-10T09:00:00.000000Z",
    "suspended_at": null
  }
}

Update a client

PATCH /api/v1/partner/clients/{id}

Update the client's company name, plan, or timezone. Plan changes take effect on the next billing cycle unless immediate is passed.

Request body

{
  "company_name": "Al-Madar Retail International",
  "plan": "business",
  "timezone": "Europe/London"
}

Field	Type	Description
`company_name`	string	New display name
`plan`	string	New plan slug
`timezone`	string	IANA timezone
`immediate`	boolean	Apply plan change immediately (default: `false`)

Response

{
  "success": true,
  "data": { "id": 101, "company_name": "Al-Madar Retail International", "plan": "business" },
  "message": "Client updated successfully."
}

Suspend a client

POST /api/v1/partner/clients/{id}/suspend

Suspends the workspace — all API calls and logins for that workspace are blocked. Contacts, messages, and data are preserved.

curl -X POST https://dashboard.skylightchat.com/api/v1/partner/clients/101/suspend \
  -H "X-Partner-Key: pk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Non-payment"}'

Request body

Field	Required	Description
`reason`	—	Internal note about the suspension reason

Response

{
  "success": true,
  "data": {
    "id": 101,
    "status": "suspended",
    "suspended_at": "2026-03-14T12:00:00.000000Z"
  },
  "message": "Client workspace suspended."
}

Reactivate a client

POST /api/v1/partner/clients/{id}/reactivate

Lifts a suspension and restores full access to the workspace.

curl -X POST https://dashboard.skylightchat.com/api/v1/partner/clients/101/reactivate \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response

{
  "success": true,
  "data": { "id": 101, "status": "active", "suspended_at": null },
  "message": "Client workspace reactivated."
}

Delete a client

DELETE /api/v1/partner/clients/{id}

Permanently deletes a client workspace and all associated data. This action is irreversible.

Deleting a client workspace destroys all contacts, messages, bookings, campaigns, and settings for that account. This cannot be undone. Suspend the workspace instead if you may need to restore it.

curl -X DELETE https://dashboard.skylightchat.com/api/v1/partner/clients/101 \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response `204 No Content`

No response body.

Get client usage

GET /api/v1/partner/clients/{id}/usage

Returns detailed usage metrics for a client workspace, broken down by billing period.

Query parameters

Parameter	Type	Description
`period`	string	`current` (default) or `YYYY-MM` for a past month

curl "https://dashboard.skylightchat.com/api/v1/partner/clients/101/usage?period=2026-02" \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response

{
  "success": true,
  "data": {
    "client_id": 101,
    "period": "2026-02",
    "contacts": {
      "total": 3820,
      "created_this_period": 340,
      "blacklisted": 12
    },
    "messages": {
      "sent": 8200,
      "received": 4100,
      "failed": 38
    },
    "campaigns": {
      "total": 6,
      "sent": 5,
      "paused": 1
    },
    "bookings": {
      "total": 91,
      "completed": 74,
      "cancelled": 9
    },
    "ai_agent_sessions": 512,
    "team_members": 5,
    "channels_connected": ["whatsapp", "telegram"]
  }
}

List usage across all clients

GET /api/v1/partner/usage

Aggregated usage report across all your client workspaces for the current or a past period. Useful for billing reconciliation and reporting.

Query parameters

Parameter	Type	Description
`period`	string	`current` (default) or `YYYY-MM`
`page`	integer	Page number (default: `1`)
`per_page`	integer	Results per page (default: `50`, max: `200`)

curl "https://dashboard.skylightchat.com/api/v1/partner/usage?period=2026-02" \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response

{
  "success": true,
  "data": {
    "period": "2026-02",
    "summary": {
      "total_clients": 14,
      "active_clients": 13,
      "total_messages_sent": 98400,
      "total_contacts": 42900,
      "total_ai_sessions": 6870
    },
    "clients": [
      {
        "client_id": 101,
        "company_name": "Al-Madar Retail",
        "plan": "business",
        "messages_sent": 8200,
        "contacts": 3820,
        "ai_agent_sessions": 512
      }
    ]
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 50,
    "total": 14
  }
}

POST /api/v1/partner/clients/{id}/impersonate

Generates a short-lived, single-use login URL so you can access a client's dashboard directly — useful for support and onboarding without asking for their credentials.

Impersonation tokens expire after 15 minutes and are single-use. All actions taken during an impersonated session are logged and attributed to the partner.

curl -X POST https://dashboard.skylightchat.com/api/v1/partner/clients/101/impersonate \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response

{
  "success": true,
  "data": {
    "login_url": "https://dashboard.skylightchat.com/partner-login?token=ipt_1a2b3c4d5e6f...",
    "expires_at": "2026-03-14T12:15:00.000000Z"
  }
}

List available plans

GET /api/v1/partner/plans

Returns all plans you are authorized to assign to client workspaces, including seat limits and pricing.

curl https://dashboard.skylightchat.com/api/v1/partner/plans \
  -H "X-Partner-Key: pk_live_••••••••••••"

Response

{
  "success": true,
  "data": [
    {
      "id": 2,
      "name": "Starter",
      "slug": "starter",
      "limits": {
        "contacts": 500,
        "messages_per_month": 5000,
        "team_members": 3,
        "channels": 1
      },
      "features": {
        "webhooks": false,
        "api_access": false,
        "booking": true,
        "ai_agents": false,
        "campaigns": false
      }
    },
    {
      "id": 3,
      "name": "Pro",
      "slug": "pro",
      "limits": {
        "contacts": 5000,
        "messages_per_month": 25000,
        "team_members": 10,
        "channels": 3
      },
      "features": {
        "webhooks": true,
        "api_access": true,
        "booking": true,
        "ai_agents": true,
        "campaigns": true
      }
    },
    {
      "id": 4,
      "name": "Business",
      "slug": "business",
      "limits": {
        "contacts": 10000,
        "messages_per_month": 50000,
        "team_members": 20,
        "channels": 5
      },
      "features": {
        "webhooks": true,
        "api_access": true,
        "booking": true,
        "ai_agents": true,
        "campaigns": true
      }
    }
  ]
}

Partner webhook events

The following webhook events fire on your partner-level webhook endpoint (configured in Partner Dashboard → Webhooks) when activity occurs on any client workspace:

Event	Trigger
`partner.client.created`	A new client workspace is provisioned
`partner.client.updated`	A client's plan or details change
`partner.client.suspended`	A client workspace is suspended
`partner.client.reactivated`	A suspended workspace is reactivated
`partner.client.deleted`	A client workspace is deleted
`partner.client.channel.connected`	A client connects a messaging channel
`partner.client.channel.disconnected`	A client's channel goes offline

Example payload

{
  "event": "partner.client.created",
  "timestamp": "2026-03-14T11:00:00.000000Z",
  "partner_id": 7,
  "data": {
    "client_id": 115,
    "company_name": "Gulf Logistics",
    "plan": "pro",
    "primary_email": "khalid@gulflogistics.sa"
  }
}

Partner webhook payloads are signed with X-SkyLight-Signature using HMAC-SHA256 — see Signature Verification for verification details.

Error codes

Code	Meaning
`401`	Invalid or missing `X-Partner-Key`
`403`	Your partner account is suspended, or you attempted an action your plan does not permit
`404`	Client workspace not found, or does not belong to your partner account
`409`	Email already in use when creating a client
`422`	Validation error — check the `errors` field in the response
`429`	Rate limit exceeded (120 requests per minute)

Example `422` response

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "admin.email": ["The email has already been taken."],
    "plan": ["The selected plan is invalid."]
  }
}

Channels

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

Contacts

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