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.",
  "booking_agent_instructions": "Always ask for location and vehicle photo before creating a booking.",
  "memory_agent_instructions": "Remember preferred contact time and favorite product category. Segment repeat buyers as VIP.",
  "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
`booking_agent_instructions`	string\|null	Free-text rules injected into the booking sub-agent (phases / mandatory fields). Does not replace system booking logic.
`memory_agent_instructions`	string\|null	Free-text rules injected into the memory agent (what to remember / how to segment). Does not replace system memory logic.
`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
`booking_agent_instructions`	string	No	Injected into the booking sub-agent
`memory_agent_instructions`	string	No	Injected into the memory / segmentation agent
`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.",
    "booking_agent_instructions": "Always collect location before creating a booking.",
    "memory_agent_instructions": "Remember preferred contact time. Segment repeat buyers as VIP.",
    "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 (including booking_agent_instructions and memory_agent_instructions). 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.