agents

​

Overview

​

Key Features

• Create conversations with agents defined in the app.
• Send messages from users to agents and receive AI-generated responses.
• Retrieve conversations individually or as filtered lists with sorting and pagination.
• Subscribe to realtime updates using WebSocket connections to receive instant notifications when new messages arrive.
• Attach metadata to conversations for tracking context, categories, priorities, or linking to external systems.
• Generate WhatsApp connection URLs for users to interact with agents through WhatsApp.

​

Conversation Structure

1. Conversations: Top-level containers that represent a dialogue with a specific agent. Each conversation has a unique ID, is associated with an agent by name, and belongs to the user who created it. Conversations can include optional metadata for tracking app-specific context like ticket IDs, categories, or custom fields.
2. Messages: Individual exchanges within a conversation. Each message has a role, content, and optional metadata like token usage, tool calls, file attachments, and reasoning information. Messages are stored as an array within their parent conversation.

​

Authentication Modes

• Anonymous or User authentication (base44.agents): Access is scoped to the current user’s permissions. Users must be authenticated to create and access conversations.
• Service role authentication (base44.asServiceRole.agents): Operations have elevated admin-level permissions. Can access all conversations that the app’s admin role has access to.

​

Generated Types

​

Methods

​

getConversations()

getConversations(): Promise<AgentConversation[]>

​

Returns

​

Example

const conversations = await base44.agents.getConversations();
console.log(`Total conversations: ${conversations.length}`);

​

See

• listConversations() for filtering, sorting, and pagination
• getConversation() for retrieving a specific conversation by ID

​

getConversation()

getConversation(conversationId): Promise<AgentConversation | undefined>

​

Parameters

​

Returns

​

Example

const conversation = await base44.agents.getConversation('conv-123');
if (conversation) {
  console.log(`Conversation has ${conversation.messages.length} messages`);
}

​

See

• getConversations() for retrieving all conversations
• listConversations() for filtering and sorting conversations

​

listConversations()

listConversations(filterParams): Promise<AgentConversation[]>

​

Parameters

​

Returns

​

Examples

const recentConversations = await base44.agents.listConversations({
  limit: 10,
  sort: '-created_date'
});

​

See

• getConversations() for retrieving all conversations without filtering
• getConversation() for retrieving a specific conversation by ID

​

createConversation()

createConversation(conversation): Promise<AgentConversation>

​

Parameters

​

Returns

​

Example

const conversation = await base44.agents.createConversation({
  agent_name: 'support-agent',
  metadata: {
    order_id: 'ORD-789',
    product_id: 'PROD-456',
    category: 'technical-support'
  }
});
console.log(`Created conversation: ${conversation.id}`);

​

addMessage()

addMessage(conversation, message): Promise<AgentMessage>

​

Parameters

​

Returns

​

Example

const message = await base44.agents.addMessage(conversation, {
  role: 'user',
  content: 'Hello, I need help with my order #12345'
});
console.log(`Message sent with ID: ${message.id}`);

​

subscribeToConversation()

subscribeToConversation(conversationId, onUpdate?): () => void

​

Parameters

​

Returns

​

Example

const unsubscribe = base44.agents.subscribeToConversation(
  'conv-123',
  (updatedConversation) => {
    const latestMessage = updatedConversation.messages[updatedConversation.messages.length - 1];
    console.log('New message:', latestMessage.content);
  }
);

// Later, clean up the subscription
unsubscribe();

​

getWhatsAppConnectURL()

getWhatsAppConnectURL(agentName): string

​

Parameters

​

Returns

​

Example

const whatsappUrl = base44.agents.getWhatsAppConnectURL('support-agent');
console.log(`Connect through WhatsApp: ${whatsappUrl}`);
// User can open this URL to start a WhatsApp conversation

​

Type Definitions

​

AgentName

AgentName = keyof AgentNameRegistry extends never ? string : keyof AgentNameRegistry

​

Example

// With generated types, you get autocomplete on agent names
const conversation = await base44.agents.createConversation({ agent_name: 'SupportBot' });

​

AgentNameRegistry