AI Agents

Create conversational AI agents with chat capabilities

AI Agents provide conversational interfaces powered by LLMs. Create agents with custom prompts, connect them to messaging channels (Telegram, Instagram, WhatsApp), and manage chat sessions.

Create Agent

POST /v1/stores/{storeId}/agents

SDK: sdk.agent.createAgent()

const agent = await sdk.agent.createAgent({
  key: 'support-bot',
  prompt: 'You are a helpful profile support agent for an e-commerce store. Be friendly and concise.',
  model_id: 'gpt-4',
  status: 'active',
  channel_ids: ['integration_telegram_123'],
  tools: ['integration', 'memory'],
});

Parameters

Name	Type	Description
`key` required	`string`	Unique agent identifier
`prompt` required	`string`	System prompt that defines agent behavior
`model_id` required	`string`	LLM model ID to use (e.g. gpt-4, claude-3)
`status` optional	`active \| disabled`	Agent status (default: active)
`channel_ids` optional	`string[]`	Integration IDs for messaging channels
`tools` optional	`string[]`	Tool IDs available to this agent. Omit or pass [] for no tools.

Tip

The model must come from a configured AI integration on the store (OpenAI, DeepSeek). See Integrations.

Get Agent

GET /v1/stores/{storeId}/agents/{id}

SDK: sdk.agent.getAgent()

const agent = await sdk.agent.getAgent({ id: 'agent_abc123' });

List Agents

GET /v1/stores/{storeId}/agents

SDK: sdk.agent.getAgents()

const { items, cursor } = await sdk.agent.getAgents({
  limit: 20,
});

Parameters

Name	Type	Description
`limit` optional	`number`	Items per page
`cursor` optional	`string`	Pagination cursor

Update Agent

PUT /v1/stores/{storeId}/agents/{id}

SDK: sdk.agent.updateAgent()

All fields other than id are optional — only provided fields are updated.

await sdk.agent.updateAgent({
  id: 'agent_abc123',
  prompt: 'Updated prompt with new instructions...',
  status: 'disabled',
  tools: ['memory'],
});

Parameters

Name	Type	Description
`id` required	`string`	Agent ID
`key` optional	`string`	Agent key
`prompt` optional	`string`	Updated system prompt
`status` optional	`active \| disabled`	Agent status
`model_id` optional	`string`	LLM model ID
`channel_ids` optional	`string[]`	Updated channel integrations
`tools` optional	`string[]`	Updated tool IDs available to this agent

Delete Agent

DELETE /v1/stores/{storeId}/agents/{id}

SDK: sdk.agent.deleteAgent()

Deletes the agent and all associated chats and messages.

await sdk.agent.deleteAgent({ id: 'agent_abc123' });

Send Message

POST /v1/stores/{storeId}/agents/{id}/chats/messages

SDK: sdk.agent.sendMessage()

Send a message to an agent. Creates a new chat or continues an existing one.

// Start a new conversation
const response = await sdk.agent.sendMessage({
  id: 'agent_abc123',
  message: 'Hi, I need help with my order',
});

// Continue existing chat
const followUp = await sdk.agent.sendMessage({
  id: 'agent_abc123',
  message: 'Can you check order #12345?',
  chat_id: response.chat_id,
});

// Direct mode (no chat history, single request/response)
const directResponse = await sdk.agent.sendMessage({
  id: 'agent_abc123',
  message: 'What are your opening hours?',
  direct: true,
});

Response:

{
  "response": "Sure, I can help with that...",
  "chatId": "chat_xyz789"
}

Parameters

Name	Type	Description
`id` required	`string`	Agent ID
`message` required	`string`	User message
`chat_id` optional	`string`	Existing chat ID to continue conversation
`direct` optional	`boolean`	Direct mode — no chat history, single exchange

List Chats

GET /v1/stores/{storeId}/agents/{id}/chats

SDK: sdk.agent.getChats()

List chat sessions for an agent.

const { items, cursor } = await sdk.agent.getChats({
  id: 'agent_abc123',
  limit: 20,
});

Get Chat

GET /v1/stores/{storeId}/agents/{id}/chats/{chatId}

SDK: sdk.agent.getChat()

const chat = await sdk.agent.getChat({
  id: 'agent_abc123',
  chat_id: 'chat_xyz789',
});

Get Chat Messages

GET /v1/stores/{storeId}/agents/{id}/chats/{chatId}/messages

SDK: sdk.agent.getChatMessages()

const messages = await sdk.agent.getChatMessages({
  id: 'agent_abc123',
  chat_id: 'chat_xyz789',
  limit: 50,
});

Update Chat

PUT /v1/stores/{storeId}/agents/{id}/chats/{chatId}

SDK: sdk.agent.updateChat()

Update chat status (e.g. mark as resolved).

await sdk.agent.updateChat({
  id: 'agent_abc123',
  chat_id: 'chat_xyz789',
  status: 'resolved',
});

Rate Chat

POST /v1/stores/{storeId}/agents/{id}/chats/{chatId}/rate

SDK: sdk.agent.rateChat()

Allow users to rate a chat experience.

await sdk.agent.rateChat({
  id: 'agent_abc123',
  chat_id: 'chat_xyz789',
  rating: 5,
  comment: 'Very helpful!',
});

Parameters

Name	Type	Description
`id` required	`string`	Agent ID
`chat_id` required	`string`	Chat ID
`rating` required	`number`	Rating (1-5)
`comment` optional	`string`	Optional feedback comment

List Store Chats

GET /v1/stores/{storeId}/chats

SDK: sdk.agent.getStoreChats()

List all chats across all agents for a store. Supports filtering by agent, status, and search query.

const { items, cursor } = await sdk.agent.getStoreChats({
  agent_id: 'agent_abc123',
  status: 'active',
  query: 'refund',
  sort_field: 'createdAt',
  sort_direction: 'desc',
  limit: 50,
});

Parameters

Name	Type	Description
`agent_id` optional	`string`	Filter by agent
`status` optional	`active \| archived`	Filter by chat status
`query` optional	`string`	Search within chat messages
`sort_field` optional	`string`	Sort field (createdAt)
`sort_direction` optional	`asc \| desc`	Sort direction
`limit` optional	`number`	Items per page
`cursor` optional	`string`	Pagination cursor