API Reference

AI Agents

Create and manage AI agent personas that drive automated responses across all messaging channels.

Overview

AI Agents are the personas behind SkyLight Chat's automated responses. Each agent is defined by a system prompt, optional instructions, a personality description, and response guidelines. You can have multiple agents per account and assign each one to specific contacts.

One agent can be set as the default — it is automatically assigned to every new contact unless you explicitly assign a different agent.

Agents combine your Knowledge Base (text, documents, voice transcripts, product catalogs, crawled sites) with the Media library so answers stay grounded and, when appropriate, include images, videos, or file links the customer can open in chat.

The AI Agent object

{
  "id": 5,
  "name": "Sales Assistant",
  "system_prompt": "You are a knowledgeable sales assistant for Nakheel Trading...",
  "instruction_prompt": "Always offer the premium plan first. Keep responses under 3 sentences.",
  "personality_prompt": "Friendly, concise, and professional. Use the customer's first name.",
  "response_guidelines": {
    "language": "Arabic",
    "tone": "formal",
    "max_length": "3 sentences"
  },
  "is_active": true,
  "is_default": true,
  "created_at": "2026-02-01T10:00:00.000000Z",
  "updated_at": "2026-03-01T14:22:00.000000Z"
}

Field	Type	Description
`id`	integer	Unique agent identifier
`name`	string	Internal display name
`system_prompt`	string	Core AI instructions
`instruction_prompt`	string\|null	Task-specific instructions appended after the system prompt
`personality_prompt`	string\|null	Tone and personality description
`response_guidelines`	object	Key/value pairs for formatting rules (language, tone, length, etc.)
`is_active`	boolean	Whether this agent is in use
`is_default`	boolean	Whether new contacts are automatically assigned to this agent

List AI agents

GET /api/v1/ai-agents

Returns all AI agents, ordered by most recently updated.

curl https://dashboard.skylightchat.com/api/v1/ai-agents \
  -H "X-Api-Key: ••••••••••••"

Create an AI agent

POST /api/v1/ai-agents

Request body

Field	Type	Required	Notes
`name`	string	✓	Internal label, max 255 chars
`system_prompt`	string	✓	Core instructions the AI follows
`instruction_prompt`	string	No	Additional task instructions
`personality_prompt`	string	No	Defines tone and personality
`response_guidelines`	object	No	Key/value formatting rules
`is_active`	boolean	No	Default: `true`
`is_default`	boolean	No	If `true`, sets this as the default and removes the flag from any existing default

curl -X POST https://dashboard.skylightchat.com/api/v1/ai-agents \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "system_prompt": "You are a helpful support agent for Nakheel Trading. Answer only questions about our products.",
    "personality_prompt": "Empathetic and solution-focused. Always end with asking if there is anything else you can help with.",
    "response_guidelines": {
      "language": "Arabic",
      "max_sentences": "4"
    },
    "is_default": true
  }'

Returns 201 Created.

Get an AI agent

GET /api/v1/ai-agents/{id}

Update an AI agent

PUT /api/v1/ai-agents/{id}

All fields are optional. Partial updates are supported.

Delete an AI agent

DELETE /api/v1/ai-agents/{id}

The default agent cannot be deleted. Set a different agent as default first, then delete the original.

Deleting an agent automatically removes the assignment from all contacts that use it. Returns 204 No Content.

Set an agent as default

POST /api/v1/ai-agents/{id}/set-default

Promotes this agent to be the default for all new contacts. The previous default agent automatically loses the is_default flag. The targeted agent is also set to is_active: true.

curl -X POST https://dashboard.skylightchat.com/api/v1/ai-agents/5/set-default \
  -H "X-Api-Key: ••••••••••••"

Assign an agent to contacts

POST /api/v1/ai-agents/{id}/assign

Bulk-assign this agent to one or more existing contacts.

Request body

Field	Type	Required	Notes
`contact_ids`	array	✓	Array of contact IDs (max 500 per request)

curl -X POST https://dashboard.skylightchat.com/api/v1/ai-agents/5/assign \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "contact_ids": [42, 43, 44, 45] }'

{
  "success": true,
  "data": { "updated_count": 4 },
  "message": "Prompt assigned to 4 contact(s)."
}

Lists & Segments

Organize contacts into named lists and dynamic segments for targeting campaigns and workflows.

Campaigns

Create and manage multi-day outreach campaigns across your connected messaging channels.