---
canonical_url: "https://docs.composio.dev/toolkits/gptbots"
markdown_url: "https://docs.composio.dev/toolkits/gptbots.md"
product: "platform"
version: null
last_updated: null
---

# GPTBots

GPTBots is an enterprise AI agent platform for conversations, knowledge management, databases, user data, and usage analytics. This toolkit auth config supports Singapore Agent API Keys only; JP and TH keys are unsupported because requests use the fixed Singapore base URL.

- **Category:** ai agents
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 12
- **Triggers:** 0
- **Slug:** `GPTBOTS`
- **Version:** 00000000_00

## Tools

### Create Conversation

**Slug:** `GPTBOTS_CREATE_CONVERSATION`

Create a GPTBots conversation for a developer-defined user on the Agent connected by this API key. Returns the conversation ID needed for subsequent message and history operations. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | Yes | Developer-defined user ID used for conversation memory, user attributes, and analytics. Maximum 32 characters. |
| `anonymous_id` | string | No | Device or anonymous-user ID to bind to the conversation. Omit it to let GPTBots generate an anonymous ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Agent Information

**Slug:** `GPTBOTS_GET_AGENT_INFORMATION`

Return the GPTBots Agent bound to the connected Agent API Key, including its ID and runtime configuration. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Total Credit Consumption

**Slug:** `GPTBOTS_GET_TOTAL_CREDIT_CONSUMPTION`

Return aggregate Agent credit consumption by category for a reporting range of up to 365 days. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end_time` | integer | Yes | End of the reporting range as a Unix timestamp in milliseconds; must not precede start_time or be more than 365 days after it. |
| `start_time` | integer | Yes | Start of the reporting range as a Unix timestamp in milliseconds. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Conversation Credits

**Slug:** `GPTBOTS_LIST_CONVERSATION_CREDITS`

Return one page of per-conversation Agent credit consumption for a time range of up to 30 days, optionally filtered by conversation ID. GPTBots code 40001 means the time range is invalid and must be corrected, not retried. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end_time` | integer | Yes | End of the reporting range as a Unix timestamp in milliseconds; must not precede start_time or be more than 30 days later. |
| `page_size` | integer | No | Conversation usage records per page (1-100). |
| `start_time` | integer | Yes | Start of the reporting range as a Unix timestamp in milliseconds. |
| `next_cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |
| `conversation_id` | string | No | Conversation ID to filter by; omit to include all conversations. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Conversation Messages

**Slug:** `GPTBOTS_LIST_CONVERSATION_MESSAGES`

Return one page of current v2 message details for a GPTBots conversation. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_size` | integer | No | Messages to return in this page (1-100). |
| `next_cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |
| `conversation_id` | string | Yes | Conversation whose message history to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Conversations

**Slug:** `GPTBOTS_LIST_CONVERSATIONS`

Return one page of Agent conversations filtered by source, recent-chat time range, and optional user. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Developer user ID to filter by; omit to include all users. |
| `end_time` | integer | Yes | End of the recent-chat time range as a Unix timestamp in milliseconds; must not precede start_time. |
| `page_size` | integer | No | Conversations per page (10-100). |
| `start_time` | integer | Yes | Start of the recent-chat time range as a Unix timestamp in milliseconds. |
| `next_cursor` | string | No | Continuation cursor returned by a previous response. Omit for the first page and pass it back unchanged to fetch the next page. |
| `conversation_type` | string | No | Conversation source filter, such as ALL, API, or EMBED. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Database Tables

**Slug:** `GPTBOTS_LIST_DATABASE_TABLES`

Return database tables configured for the Agent ID supplied by the caller. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent ID (bot_id) returned by Get Agent Information. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Knowledge Bases

**Slug:** `GPTBOTS_LIST_KNOWLEDGE_BASES`

Return all knowledge bases attached to the GPTBots Agent connected by this API key. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Knowledge Documents

**Slug:** `GPTBOTS_LIST_KNOWLEDGE_DOCUMENTS`

Return one page of documents in a GPTBots knowledge base. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_size` | integer | No | Documents to return in this page (10-100). |
| `next_cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |
| `knowledge_base_id` | string | Yes | Knowledge base ID, obtainable from List Knowledge Bases. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Metadata Fields

**Slug:** `GPTBOTS_LIST_METADATA_FIELDS`

Return global and per-knowledge-base document metadata field definitions for the connected GPTBots Agent. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Query User Attributes

**Slug:** `GPTBOTS_QUERY_USER_ATTRIBUTES`

Return configured GPTBots Agent attributes for either developer user IDs or anonymous IDs. Exactly one non-empty selector is required. Missing identities are successful results with no property values. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_ids` | array | No | Developer user IDs to query, up to 100 per request. Pass one ID or a list of IDs. Provide exactly one of this field or anonymous_ids. |
| `anonymous_ids` | array | No | Anonymous or device IDs to query, up to 100 per request. Pass one ID or a list of IDs. Provide exactly one of this field or user_ids. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send Message

**Slug:** `GPTBOTS_SEND_MESSAGE`

Send the latest user text to a GPTBots conversation and wait for the Agent's complete blocking response. This tool does not use streaming, webhooks, multimodal files, or human handoff. It consumes credits and creates a permanent message. Do not blindly retry after a timeout, disconnect, or other ambiguous acceptance; reconcile through conversation messages first. GPTBots documents a shared default limit of 3 requests per minute for Free Plan accounts; higher or custom tiers may differ. On Free Plan, serialize calls and back off on HTTP 429 or provider code 40008.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message` | string | Yes | Latest user text to send. GPTBots uses stored conversation memory, so prior turns normally should not be repeated. |
| `conversation_id` | string | Yes | Conversation ID returned by Create Conversation. |
| `custom_variables` | object | No | Agent-defined custom variable names and JSON values for this call. Keys must match variables configured on the connected Agent. |
| `long_term_memory` | boolean | No | Optional per-call override for the Agent's long-term memory setting; omit to use the Agent default. |
| `short_term_memory` | boolean | No | Optional per-call override for the Agent's short-term memory setting; omit to use the Agent default. |
| `knowledge_base_ids` | array | No | Optional knowledge base IDs that constrain retrieval for this message. They are combined as a union with knowledge_document_ids. Omit both fields to use Agent defaults, or pass both as empty arrays to disable knowledge retrieval. |
| `knowledge_document_ids` | array | No | Optional knowledge document IDs that constrain retrieval for this message. They are combined as a union with knowledge_base_ids. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |