> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# agents

***

## Overview

Agents module for managing AI agent conversations.

This module provides methods to create and manage conversations with AI agents,
send messages, and subscribe to realtime updates. Conversations can be used
for chat interfaces, support systems, or any interactive AI app.

### Key Features

The agents module enables you to:

* **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

The agents module operates with a two-level hierarchy:

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

This module is available to use with a client in all 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. Each user can read and add messages only to conversations they created, even if the user is an admin.
* **Service role authentication** (`base44.asServiceRole.agents`): Operations are invoked with the service role for backend code that needs elevated permissions.

### Generated Types

If you're working in a TypeScript project, you can generate types from your agents to get autocomplete on agent names when creating conversations or subscribing to updates. See the [Dynamic Types](https://docs.base44.com/developers/references/sdk/getting-started/dynamic-types.md) guide to get started.

## Methods

### getConversations()

> **getConversations**(): `Promise`\<`AgentConversation`\[]>

Gets the current user's conversations with all agents in the app.

Retrieves every conversation the current user started, across all agents. Conversations that other users started aren't included, even if the user is an admin. Use [`listConversations()`](#listconversations) to filter which conversations are returned, apply sorting, or paginate results. Use [`getConversation()`](#getconversation) to retrieve a specific conversation by ID.

#### Returns

`AgentConversation`

An agent conversation containing messages exchanged with an AI agent.

Promise resolving to an array of conversations.

> [accordion] Properties
>
> **id** `string` *required*
>
> Unique identifier for the conversation.
>
> **app\_id** `string` *required*
>
> App ID.
>
> **agent\_name** `string` *required*
>
> Name of the agent in this conversation.
>
> **created\_by\_id** `string` *required*
>
> ID of the user who created the conversation.
>
> **created\_date** `string` *required*
>
> When the conversation was created.
>
> **updated\_date** `string` *required*
>
> When the conversation was last updated.
>
> **messages** `AgentMessage[]` *required*
>
> Array of messages in the conversation.
>
> > [accordion] Properties
> >
> > **id** `string` *required*
> >
> > Unique identifier for the message.
> >
> > **role** `"user" | "assistant" | "system"` *required*
> >
> > Role of the message sender.
> >
> > **created\_date** `string` *required*
> >
> > When the message was created.
> >
> > **updated\_date** `string` *required*
> >
> > When the message was last updated.
> >
> > **reasoning** `AgentMessageReasoning | null`
> >
> > Optional reasoning information for the message.
> >
> > > [accordion] Properties
> > >
> > > **start\_date** `string` *required*
> > >
> > > When reasoning started.
> > >
> > > **end\_date** `string`
> > >
> > > When reasoning ended.
> > >
> > > **content** `string` *required*
> > >
> > > Reasoning content.
> >
> > **content** `string | Record\<string, any\>`
> >
> > Message content.
> >
> > **file\_urls** `string[]`
> >
> > URLs to files attached to the message.
> >
> > **tool\_calls** `AgentMessageToolCall[]`
> >
> > Tool calls made by the agent.
> >
> > > [accordion] Properties
> > >
> > > **id** `string` *required*
> > >
> > > Tool call ID.
> > >
> > > **name** `string` *required*
> > >
> > > Name of the tool called.
> > >
> > > **arguments\_string** `string` *required*
> > >
> > > Arguments passed to the tool as JSON string.
> > >
> > > **status** `"error" | "success" | "running" | "stopped" | "waiting_for_user_input"` *required*
> > >
> > > Status of the tool call.
> > >
> > > **results** `string`
> > >
> > > Results from the tool call.
> >
> > **usage** `AgentMessageUsage`
> >
> > Token usage statistics.
> >
> > > [accordion] Properties
> > >
> > > **prompt\_tokens** `number`
> > >
> > > Number of tokens in the prompt.
> > >
> > > **completion\_tokens** `number`
> > >
> > > Number of tokens in the completion.
> >
> > **hidden** `boolean`
> >
> > Whether the message is hidden from the user.
> >
> > **custom\_context** `AgentMessageCustomContext[]`
> >
> > Custom context provided with the message.
> >
> > > [accordion] Properties
> > >
> > > **message** `string` *required*
> > >
> > > Context message.
> > >
> > > **data** `Record\<string, any\>` *required*
> > >
> > > Associated data for the context.
> > >
> > > **type** `string` *required*
> > >
> > > Type of context.
> >
> > **model** `string`
> >
> > Model used to generate the message.
> >
> > **checkpoint\_id** `string`
> >
> > Checkpoint ID for the message.
> >
> > **metadata** `AgentMessageMetadata`
> >
> > Metadata about when and by whom the message was created.
> >
> > > [accordion] Properties
> > >
> > > **created\_date** `string` *required*
> > >
> > > When the message was created.
> > >
> > > **created\_by\_email** `string` *required*
> > >
> > > Email of the user who created the message.
> > >
> > > **created\_by\_full\_name** `string` *required*
> > >
> > > Full name of the user who created the message.
> >
> > **additional\_message\_params** `Record\<string, any\>`
> >
> > Additional custom parameters for the message.
>
> **metadata** `Record\<string, any\>`
>
> Optional metadata associated with the conversation.

#### Example

```typescript Get the current user's conversations theme={null}
const conversations = await base44.agents.getConversations();
console.log(`Total conversations: ${conversations.length}`);
```

#### See

* [`listConversations()`](#listconversations) for filtering, sorting, and pagination
* [`getConversation()`](#getconversation) for retrieving a specific conversation by ID

***

### getConversation()

> **getConversation**(`conversationId`): `Promise`\<`AgentConversation` | `undefined`>

Gets a specific conversation by ID.

Retrieves a single conversation using its unique identifier. The conversation must belong to the current user. If another user created it, the request fails with a `403` error. If no conversation has that ID, the request fails with a `404` error. To retrieve
all of the current user's conversations, use [`getConversations()`](#getconversations). To filter, sort, or paginate conversations, use [`listConversations()`](#listconversations).

This function returns the complete stored conversation including full tool call results, even for large responses.

#### Parameters

**conversationId** `string` *required*

The unique identifier of the conversation.

#### Returns

`AgentConversation`

An agent conversation containing messages exchanged with an AI agent.

Promise resolving to the conversation.

> [accordion] Properties
>
> **id** `string` *required*
>
> Unique identifier for the conversation.
>
> **app\_id** `string` *required*
>
> App ID.
>
> **agent\_name** `string` *required*
>
> Name of the agent in this conversation.
>
> **created\_by\_id** `string` *required*
>
> ID of the user who created the conversation.
>
> **created\_date** `string` *required*
>
> When the conversation was created.
>
> **updated\_date** `string` *required*
>
> When the conversation was last updated.
>
> **messages** `AgentMessage[]` *required*
>
> Array of messages in the conversation.
>
> > [accordion] Properties
> >
> > **id** `string` *required*
> >
> > Unique identifier for the message.
> >
> > **role** `"user" | "assistant" | "system"` *required*
> >
> > Role of the message sender.
> >
> > **created\_date** `string` *required*
> >
> > When the message was created.
> >
> > **updated\_date** `string` *required*
> >
> > When the message was last updated.
> >
> > **reasoning** `AgentMessageReasoning | null`
> >
> > Optional reasoning information for the message.
> >
> > > [accordion] Properties
> > >
> > > **start\_date** `string` *required*
> > >
> > > When reasoning started.
> > >
> > > **end\_date** `string`
> > >
> > > When reasoning ended.
> > >
> > > **content** `string` *required*
> > >
> > > Reasoning content.
> >
> > **content** `string | Record\<string, any\>`
> >
> > Message content.
> >
> > **file\_urls** `string[]`
> >
> > URLs to files attached to the message.
> >
> > **tool\_calls** `AgentMessageToolCall[]`
> >
> > Tool calls made by the agent.
> >
> > > [accordion] Properties
> > >
> > > **id** `string` *required*
> > >
> > > Tool call ID.
> > >
> > > **name** `string` *required*
> > >
> > > Name of the tool called.
> > >
> > > **arguments\_string** `string` *required*
> > >
> > > Arguments passed to the tool as JSON string.
> > >
> > > **status** `"error" | "success" | "running" | "stopped" | "waiting_for_user_input"` *required*
> > >
> > > Status of the tool call.
> > >
> > > **results** `string`
> > >
> > > Results from the tool call.
> >
> > **usage** `AgentMessageUsage`
> >
> > Token usage statistics.
> >
> > > [accordion] Properties
> > >
> > > **prompt\_tokens** `number`
> > >
> > > Number of tokens in the prompt.
> > >
> > > **completion\_tokens** `number`
> > >
> > > Number of tokens in the completion.
> >
> > **hidden** `boolean`
> >
> > Whether the message is hidden from the user.
> >
> > **custom\_context** `AgentMessageCustomContext[]`
> >
> > Custom context provided with the message.
> >
> > > [accordion] Properties
> > >
> > > **message** `string` *required*
> > >
> > > Context message.
> > >
> > > **data** `Record\<string, any\>` *required*
> > >
> > > Associated data for the context.
> > >
> > > **type** `string` *required*
> > >
> > > Type of context.
> >
> > **model** `string`
> >
> > Model used to generate the message.
> >
> > **checkpoint\_id** `string`
> >
> > Checkpoint ID for the message.
> >
> > **metadata** `AgentMessageMetadata`
> >
> > Metadata about when and by whom the message was created.
> >
> > > [accordion] Properties
> > >
> > > **created\_date** `string` *required*
> > >
> > > When the message was created.
> > >
> > > **created\_by\_email** `string` *required*
> > >
> > > Email of the user who created the message.
> > >
> > > **created\_by\_full\_name** `string` *required*
> > >
> > > Full name of the user who created the message.
> >
> > **additional\_message\_params** `Record\<string, any\>`
> >
> > Additional custom parameters for the message.
>
> **metadata** `Record\<string, any\>`
>
> Optional metadata associated with the conversation.

#### Example

```typescript Get a specific conversation by ID theme={null}
const conversation = await base44.agents.getConversation('conv-123');
if (conversation) {
  console.log(`Conversation has ${conversation.messages.length} messages`);
}
```

#### See

* [`getConversations()`](#getconversations) for retrieving all of the current user's conversations
* [`listConversations()`](#listconversations) for filtering and sorting conversations

***

### listConversations()

> **listConversations**(`filterParams`): `Promise`\<`AgentConversation`\[]>

Lists the current user's conversations with filtering, sorting, and pagination.

Provides querying capabilities including filtering by fields, sorting, pagination, and field selection. Results only include conversations the current user created, even with a filter on `created_by_id`. For cases where you need all of the current user's conversations without filtering, use [`getConversations()`](#getconversations). To retrieve a specific conversation by ID, use [`getConversation()`](#getconversation).

#### Parameters

**filterParams** `ModelFilterParams` *required*

Filter parameters for querying conversations.

> [accordion] Properties
>
> **q** `Record\<string, any\>`
>
> Query object with field-value pairs for filtering.
>
> **sort** `string | null`
>
> Sort parameter. For example, "-created\_date" for descending order.
>
> **sort\_by** `string | null`
>
> Alternative sort parameter. Use either `sort` or `sort_by`.
>
> **limit** `number | null`
>
> Maximum number of results to return.
>
> **skip** `number | null`
>
> Number of results to skip. Used for pagination.
>
> **fields** `string[] | null`
>
> Array of field names to include in the response.

#### Returns

`AgentConversation`

An agent conversation containing messages exchanged with an AI agent.

Promise resolving to an array of filtered conversations.

> [accordion] Properties
>
> **id** `string` *required*
>
> Unique identifier for the conversation.
>
> **app\_id** `string` *required*
>
> App ID.
>
> **agent\_name** `string` *required*
>
> Name of the agent in this conversation.
>
> **created\_by\_id** `string` *required*
>
> ID of the user who created the conversation.
>
> **created\_date** `string` *required*
>
> When the conversation was created.
>
> **updated\_date** `string` *required*
>
> When the conversation was last updated.
>
> **messages** `AgentMessage[]` *required*
>
> Array of messages in the conversation.
>
> > [accordion] Properties
> >
> > **id** `string` *required*
> >
> > Unique identifier for the message.
> >
> > **role** `"user" | "assistant" | "system"` *required*
> >
> > Role of the message sender.
> >
> > **created\_date** `string` *required*
> >
> > When the message was created.
> >
> > **updated\_date** `string` *required*
> >
> > When the message was last updated.
> >
> > **reasoning** `AgentMessageReasoning | null`
> >
> > Optional reasoning information for the message.
> >
> > > [accordion] Properties
> > >
> > > **start\_date** `string` *required*
> > >
> > > When reasoning started.
> > >
> > > **end\_date** `string`
> > >
> > > When reasoning ended.
> > >
> > > **content** `string` *required*
> > >
> > > Reasoning content.
> >
> > **content** `string | Record\<string, any\>`
> >
> > Message content.
> >
> > **file\_urls** `string[]`
> >
> > URLs to files attached to the message.
> >
> > **tool\_calls** `AgentMessageToolCall[]`
> >
> > Tool calls made by the agent.
> >
> > > [accordion] Properties
> > >
> > > **id** `string` *required*
> > >
> > > Tool call ID.
> > >
> > > **name** `string` *required*
> > >
> > > Name of the tool called.
> > >
> > > **arguments\_string** `string` *required*
> > >
> > > Arguments passed to the tool as JSON string.
> > >
> > > **status** `"error" | "success" | "running" | "stopped" | "waiting_for_user_input"` *required*
> > >
> > > Status of the tool call.
> > >
> > > **results** `string`
> > >
> > > Results from the tool call.
> >
> > **usage** `AgentMessageUsage`
> >
> > Token usage statistics.
> >
> > > [accordion] Properties
> > >
> > > **prompt\_tokens** `number`
> > >
> > > Number of tokens in the prompt.
> > >
> > > **completion\_tokens** `number`
> > >
> > > Number of tokens in the completion.
> >
> > **hidden** `boolean`
> >
> > Whether the message is hidden from the user.
> >
> > **custom\_context** `AgentMessageCustomContext[]`
> >
> > Custom context provided with the message.
> >
> > > [accordion] Properties
> > >
> > > **message** `string` *required*
> > >
> > > Context message.
> > >
> > > **data** `Record\<string, any\>` *required*
> > >
> > > Associated data for the context.
> > >
> > > **type** `string` *required*
> > >
> > > Type of context.
> >
> > **model** `string`
> >
> > Model used to generate the message.
> >
> > **checkpoint\_id** `string`
> >
> > Checkpoint ID for the message.
> >
> > **metadata** `AgentMessageMetadata`
> >
> > Metadata about when and by whom the message was created.
> >
> > > [accordion] Properties
> > >
> > > **created\_date** `string` *required*
> > >
> > > When the message was created.
> > >
> > > **created\_by\_email** `string` *required*
> > >
> > > Email of the user who created the message.
> > >
> > > **created\_by\_full\_name** `string` *required*
> > >
> > > Full name of the user who created the message.
> >
> > **additional\_message\_params** `Record\<string, any\>`
> >
> > Additional custom parameters for the message.
>
> **metadata** `Record\<string, any\>`
>
> Optional metadata associated with the conversation.

#### Examples

```typescript List recent conversations with pagination theme={null}
const recentConversations = await base44.agents.listConversations({
  limit: 10,
  sort: '-created_date'
});
```

```typescript Filter by agent and metadata theme={null}
const supportConversations = await base44.agents.listConversations({
  q: {
    agent_name: 'support-agent',
    'metadata.priority': 'high'
  },
  sort: '-created_date',
  limit: 20
});
```

#### See

* [`getConversations()`](#getconversations) for retrieving all of the current user's conversations without filtering
* [`getConversation()`](#getconversation) for retrieving a specific conversation by ID

***

### createConversation()

> **createConversation**(`conversation`): `Promise`\<`AgentConversation`>

Creates a new conversation with an agent.

The conversation belongs to the current user. Only that user can read it or add messages to it.

#### Parameters

**conversation** `CreateConversationParams` *required*

Conversation details including agent name and optional metadata.

> [accordion] Properties
>
> **agent\_name** `string` *required*
>
> The name of the agent to create a conversation with.
>
> **metadata** `Record\<string, any\>`
>
> Optional metadata to attach to the conversation.

#### Returns

`AgentConversation`

An agent conversation containing messages exchanged with an AI agent.

Promise resolving to the created conversation.

> [accordion] Properties
>
> **id** `string` *required*
>
> Unique identifier for the conversation.
>
> **app\_id** `string` *required*
>
> App ID.
>
> **agent\_name** `string` *required*
>
> Name of the agent in this conversation.
>
> **created\_by\_id** `string` *required*
>
> ID of the user who created the conversation.
>
> **created\_date** `string` *required*
>
> When the conversation was created.
>
> **updated\_date** `string` *required*
>
> When the conversation was last updated.
>
> **messages** `AgentMessage[]` *required*
>
> Array of messages in the conversation.
>
> > [accordion] Properties
> >
> > **id** `string` *required*
> >
> > Unique identifier for the message.
> >
> > **role** `"user" | "assistant" | "system"` *required*
> >
> > Role of the message sender.
> >
> > **created\_date** `string` *required*
> >
> > When the message was created.
> >
> > **updated\_date** `string` *required*
> >
> > When the message was last updated.
> >
> > **reasoning** `AgentMessageReasoning | null`
> >
> > Optional reasoning information for the message.
> >
> > > [accordion] Properties
> > >
> > > **start\_date** `string` *required*
> > >
> > > When reasoning started.
> > >
> > > **end\_date** `string`
> > >
> > > When reasoning ended.
> > >
> > > **content** `string` *required*
> > >
> > > Reasoning content.
> >
> > **content** `string | Record\<string, any\>`
> >
> > Message content.
> >
> > **file\_urls** `string[]`
> >
> > URLs to files attached to the message.
> >
> > **tool\_calls** `AgentMessageToolCall[]`
> >
> > Tool calls made by the agent.
> >
> > > [accordion] Properties
> > >
> > > **id** `string` *required*
> > >
> > > Tool call ID.
> > >
> > > **name** `string` *required*
> > >
> > > Name of the tool called.
> > >
> > > **arguments\_string** `string` *required*
> > >
> > > Arguments passed to the tool as JSON string.
> > >
> > > **status** `"error" | "success" | "running" | "stopped" | "waiting_for_user_input"` *required*
> > >
> > > Status of the tool call.
> > >
> > > **results** `string`
> > >
> > > Results from the tool call.
> >
> > **usage** `AgentMessageUsage`
> >
> > Token usage statistics.
> >
> > > [accordion] Properties
> > >
> > > **prompt\_tokens** `number`
> > >
> > > Number of tokens in the prompt.
> > >
> > > **completion\_tokens** `number`
> > >
> > > Number of tokens in the completion.
> >
> > **hidden** `boolean`
> >
> > Whether the message is hidden from the user.
> >
> > **custom\_context** `AgentMessageCustomContext[]`
> >
> > Custom context provided with the message.
> >
> > > [accordion] Properties
> > >
> > > **message** `string` *required*
> > >
> > > Context message.
> > >
> > > **data** `Record\<string, any\>` *required*
> > >
> > > Associated data for the context.
> > >
> > > **type** `string` *required*
> > >
> > > Type of context.
> >
> > **model** `string`
> >
> > Model used to generate the message.
> >
> > **checkpoint\_id** `string`
> >
> > Checkpoint ID for the message.
> >
> > **metadata** `AgentMessageMetadata`
> >
> > Metadata about when and by whom the message was created.
> >
> > > [accordion] Properties
> > >
> > > **created\_date** `string` *required*
> > >
> > > When the message was created.
> > >
> > > **created\_by\_email** `string` *required*
> > >
> > > Email of the user who created the message.
> > >
> > > **created\_by\_full\_name** `string` *required*
> > >
> > > Full name of the user who created the message.
> >
> > **additional\_message\_params** `Record\<string, any\>`
> >
> > Additional custom parameters for the message.
>
> **metadata** `Record\<string, any\>`
>
> Optional metadata associated with the conversation.

#### Example

```typescript Create a new conversation with metadata theme={null}
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`>

Adds a message to a conversation.

Sends a message to the agent and updates the conversation. You can only add messages to conversations the current user created. This method
also updates the realtime socket to notify any subscribers.

#### Parameters

> [accordion] Properties
>
> **conversation** `AgentConversation` *required*
>
> The conversation to add the message to.
>
> > [accordion] Properties
> >
> > **id** `string` *required*
> >
> > Unique identifier for the conversation.
> >
> > **app\_id** `string` *required*
> >
> > App ID.
> >
> > **agent\_name** `string` *required*
> >
> > Name of the agent in this conversation.
> >
> > **created\_by\_id** `string` *required*
> >
> > ID of the user who created the conversation.
> >
> > **created\_date** `string` *required*
> >
> > When the conversation was created.
> >
> > **updated\_date** `string` *required*
> >
> > When the conversation was last updated.
> >
> > **messages** `AgentMessage[]` *required*
> >
> > Array of messages in the conversation.
> >
> > > [accordion] Properties
> > >
> > > **id** `string` *required*
> > >
> > > Unique identifier for the message.
> > >
> > > **role** `"user" | "assistant" | "system"` *required*
> > >
> > > Role of the message sender.
> > >
> > > **created\_date** `string` *required*
> > >
> > > When the message was created.
> > >
> > > **updated\_date** `string` *required*
> > >
> > > When the message was last updated.
> > >
> > > **reasoning** `AgentMessageReasoning | null`
> > >
> > > Optional reasoning information for the message.
> > >
> > > > [accordion] Properties
> > > >
> > > > **start\_date** `string` *required*
> > > >
> > > > When reasoning started.
> > > >
> > > > **end\_date** `string`
> > > >
> > > > When reasoning ended.
> > > >
> > > > **content** `string` *required*
> > > >
> > > > Reasoning content.
> > >
> > > **content** `string | Record\<string, any\>`
> > >
> > > Message content.
> > >
> > > **file\_urls** `string[]`
> > >
> > > URLs to files attached to the message.
> > >
> > > **tool\_calls** `AgentMessageToolCall[]`
> > >
> > > Tool calls made by the agent.
> > >
> > > > [accordion] Properties
> > > >
> > > > **id** `string` *required*
> > > >
> > > > Tool call ID.
> > > >
> > > > **name** `string` *required*
> > > >
> > > > Name of the tool called.
> > > >
> > > > **arguments\_string** `string` *required*
> > > >
> > > > Arguments passed to the tool as JSON string.
> > > >
> > > > **status** `"error" | "success" | "running" | "stopped" | "waiting_for_user_input"` *required*
> > > >
> > > > Status of the tool call.
> > > >
> > > > **results** `string`
> > > >
> > > > Results from the tool call.
> > >
> > > **usage** `AgentMessageUsage`
> > >
> > > Token usage statistics.
> > >
> > > > [accordion] Properties
> > > >
> > > > **prompt\_tokens** `number`
> > > >
> > > > Number of tokens in the prompt.
> > > >
> > > > **completion\_tokens** `number`
> > > >
> > > > Number of tokens in the completion.
> > >
> > > **hidden** `boolean`
> > >
> > > Whether the message is hidden from the user.
> > >
> > > **custom\_context** `AgentMessageCustomContext[]`
> > >
> > > Custom context provided with the message.
> > >
> > > > [accordion] Properties
> > > >
> > > > **message** `string` *required*
> > > >
> > > > Context message.
> > > >
> > > > **data** `Record\<string, any\>` *required*
> > > >
> > > > Associated data for the context.
> > > >
> > > > **type** `string` *required*
> > > >
> > > > Type of context.
> > >
> > > **model** `string`
> > >
> > > Model used to generate the message.
> > >
> > > **checkpoint\_id** `string`
> > >
> > > Checkpoint ID for the message.
> > >
> > > **metadata** `AgentMessageMetadata`
> > >
> > > Metadata about when and by whom the message was created.
> > >
> > > > [accordion] Properties
> > > >
> > > > **created\_date** `string` *required*
> > > >
> > > > When the message was created.
> > > >
> > > > **created\_by\_email** `string` *required*
> > > >
> > > > Email of the user who created the message.
> > > >
> > > > **created\_by\_full\_name** `string` *required*
> > > >
> > > > Full name of the user who created the message.
> > >
> > > **additional\_message\_params** `Record\<string, any\>`
> > >
> > > Additional custom parameters for the message.
> >
> > **metadata** `Record\<string, any\>`
> >
> > Optional metadata associated with the conversation.
>
> **message** `Partial\<AgentMessage\>` *required*
>
> The message to add.
>
> > [accordion] Properties
> >
> > **id** `string` *required*
> >
> > Unique identifier for the message.
> >
> > **role** `"user" | "assistant" | "system"` *required*
> >
> > Role of the message sender.
> >
> > **created\_date** `string` *required*
> >
> > When the message was created.
> >
> > **updated\_date** `string` *required*
> >
> > When the message was last updated.
> >
> > **reasoning** `AgentMessageReasoning | null`
> >
> > Optional reasoning information for the message.
> >
> > > [accordion] Properties
> > >
> > > **start\_date** `string` *required*
> > >
> > > When reasoning started.
> > >
> > > **end\_date** `string`
> > >
> > > When reasoning ended.
> > >
> > > **content** `string` *required*
> > >
> > > Reasoning content.
> >
> > **content** `string | Record\<string, any\>`
> >
> > Message content.
> >
> > **file\_urls** `string[]`
> >
> > URLs to files attached to the message.
> >
> > **tool\_calls** `AgentMessageToolCall[]`
> >
> > Tool calls made by the agent.
> >
> > > [accordion] Properties
> > >
> > > **id** `string` *required*
> > >
> > > Tool call ID.
> > >
> > > **name** `string` *required*
> > >
> > > Name of the tool called.
> > >
> > > **arguments\_string** `string` *required*
> > >
> > > Arguments passed to the tool as JSON string.
> > >
> > > **status** `"error" | "success" | "running" | "stopped" | "waiting_for_user_input"` *required*
> > >
> > > Status of the tool call.
> > >
> > > **results** `string`
> > >
> > > Results from the tool call.
> >
> > **usage** `AgentMessageUsage`
> >
> > Token usage statistics.
> >
> > > [accordion] Properties
> > >
> > > **prompt\_tokens** `number`
> > >
> > > Number of tokens in the prompt.
> > >
> > > **completion\_tokens** `number`
> > >
> > > Number of tokens in the completion.
> >
> > **hidden** `boolean`
> >
> > Whether the message is hidden from the user.
> >
> > **custom\_context** `AgentMessageCustomContext[]`
> >
> > Custom context provided with the message.
> >
> > > [accordion] Properties
> > >
> > > **message** `string` *required*
> > >
> > > Context message.
> > >
> > > **data** `Record\<string, any\>` *required*
> > >
> > > Associated data for the context.
> > >
> > > **type** `string` *required*
> > >
> > > Type of context.
> >
> > **model** `string`
> >
> > Model used to generate the message.
> >
> > **checkpoint\_id** `string`
> >
> > Checkpoint ID for the message.
> >
> > **metadata** `AgentMessageMetadata`
> >
> > Metadata about when and by whom the message was created.
> >
> > > [accordion] Properties
> > >
> > > **created\_date** `string` *required*
> > >
> > > When the message was created.
> > >
> > > **created\_by\_email** `string` *required*
> > >
> > > Email of the user who created the message.
> > >
> > > **created\_by\_full\_name** `string` *required*
> > >
> > > Full name of the user who created the message.
> >
> > **additional\_message\_params** `Record\<string, any\>`
> >
> > Additional custom parameters for the message.

#### Returns

`AgentMessage`

A message in an agent conversation.

Promise resolving to the created message.

> [accordion] Properties
>
> **id** `string` *required*
>
> Unique identifier for the message.
>
> **role** `"user" | "assistant" | "system"` *required*
>
> Role of the message sender.
>
> **created\_date** `string` *required*
>
> When the message was created.
>
> **updated\_date** `string` *required*
>
> When the message was last updated.
>
> **reasoning** `AgentMessageReasoning | null`
>
> Optional reasoning information for the message.
>
> > [accordion] Properties
> >
> > **start\_date** `string` *required*
> >
> > When reasoning started.
> >
> > **end\_date** `string`
> >
> > When reasoning ended.
> >
> > **content** `string` *required*
> >
> > Reasoning content.
>
> **content** `string | Record\<string, any\>`
>
> Message content.
>
> **file\_urls** `string[]`
>
> URLs to files attached to the message.
>
> **tool\_calls** `AgentMessageToolCall[]`
>
> Tool calls made by the agent.
>
> > [accordion] Properties
> >
> > **id** `string` *required*
> >
> > Tool call ID.
> >
> > **name** `string` *required*
> >
> > Name of the tool called.
> >
> > **arguments\_string** `string` *required*
> >
> > Arguments passed to the tool as JSON string.
> >
> > **status** `"error" | "success" | "running" | "stopped" | "waiting_for_user_input"` *required*
> >
> > Status of the tool call.
> >
> > **results** `string`
> >
> > Results from the tool call.
>
> **usage** `AgentMessageUsage`
>
> Token usage statistics.
>
> > [accordion] Properties
> >
> > **prompt\_tokens** `number`
> >
> > Number of tokens in the prompt.
> >
> > **completion\_tokens** `number`
> >
> > Number of tokens in the completion.
>
> **hidden** `boolean`
>
> Whether the message is hidden from the user.
>
> **custom\_context** `AgentMessageCustomContext[]`
>
> Custom context provided with the message.
>
> > [accordion] Properties
> >
> > **message** `string` *required*
> >
> > Context message.
> >
> > **data** `Record\<string, any\>` *required*
> >
> > Associated data for the context.
> >
> > **type** `string` *required*
> >
> > Type of context.
>
> **model** `string`
>
> Model used to generate the message.
>
> **checkpoint\_id** `string`
>
> Checkpoint ID for the message.
>
> **metadata** `AgentMessageMetadata`
>
> Metadata about when and by whom the message was created.
>
> > [accordion] Properties
> >
> > **created\_date** `string` *required*
> >
> > When the message was created.
> >
> > **created\_by\_email** `string` *required*
> >
> > Email of the user who created the message.
> >
> > **created\_by\_full\_name** `string` *required*
> >
> > Full name of the user who created the message.
>
> **additional\_message\_params** `Record\<string, any\>`
>
> Additional custom parameters for the message.

#### Example

```typescript Send a message to the agent theme={null}
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`

Subscribes to realtime updates for a conversation.

Establishes a WebSocket connection to receive instant updates when new
messages are added to the conversation. You can only subscribe to conversations the current user created. Returns an unsubscribe function
to clean up the connection.

> [!NOTE]
>
> When receiving messages through this function, tool call data is truncated for efficiency. The `arguments_string` is limited to 500 characters and `results` to 50 characters. The complete tool call data is always saved in storage and can be retrieved by calling [`getConversation()`](#getconversation) after the message completes.

#### Parameters

> [accordion] Properties
>
> **conversationId** `string` *required*
>
> The conversation ID to subscribe to.
>
> **onUpdate** `(conversation) =\> void`
>
> Callback function called when the conversation is updated. The callback receives a conversation object with the following properties:
>
> * `id`: Unique identifier for the conversation.
> * `agent_name`: Name of the agent in this conversation.
> * `created_date`: ISO 8601 timestamp of when the conversation was created.
> * `updated_date`: ISO 8601 timestamp of when the conversation was last updated.
> * `messages`: Array of messages in the conversation. Each message includes `id`, `role` (`'user'`, `'assistant'`, or `'system'`), `content`, `created_date`, and optionally `tool_calls`, `reasoning`, `file_urls`, and `usage`.
> * `metadata`: Optional metadata associated with the conversation.

#### Returns

Unsubscribe function to stop receiving updates.

#### Example

```typescript Subscribe to realtime updates theme={null}
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`

Gets WhatsApp connection URL for an agent.

Generates a URL that users can use to connect with the agent through WhatsApp.
The URL includes authentication if a token is available.

#### Parameters

**agentName** `string` *required*

The name of the agent.

#### Returns

`string`

WhatsApp connection URL.

#### Example

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

***

### getTelegramConnectURL()

> **getTelegramConnectURL**(`agentName`): `string`

Gets Telegram connection URL for an agent.

Generates a URL that users can use to connect with the agent through Telegram.
The URL includes authentication if a token is available. When the user opens
this URL, they are redirected to the agent's Telegram bot with an activation
code that securely links their account.

#### Parameters

**agentName** `string` *required*

The name of the agent.

#### Returns

`string`

Telegram connection URL.

#### Example

```typescript Get Telegram connection URL theme={null}
const telegramUrl = base44.agents.getTelegramConnectURL('support-agent');
console.log(`Connect through Telegram: ${telegramUrl}`);
// User can open this URL to start a Telegram conversation
```

## Type Definitions

### AgentName

> **AgentName** = keyof `AgentNameRegistry` *extends* `never` ? `string` : keyof `AgentNameRegistry`

Union of all agent names from the [`AgentNameRegistry`](#agentnameregistry). Defaults to `string` when no types have been generated.

#### Example

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

### AgentNameRegistry

Registry of agent names. The [`types generate`](https://docs.base44.com/developers/references/cli/commands/types-generate) command fills this registry, then [`AgentName`](#agentname) resolves to a union of the keys.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.