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

# Chatforma

Chatforma is a chatbot automation platform for managing bots, users, segments, broadcasts, dialogs, forms, notifications, and variables.

- **Category:** ai chatbots
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 10
- **Triggers:** 0
- **Slug:** `CHATFORMA`
- **Version:** 00000000_00

## Tools

### Get User Variable

**Slug:** `CHATFORMA_GET_USER_VARIABLE`

Get the current value of one bot variable for one bot user.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |
| `bot_user_id` | integer | Yes | Bot user ID returned by CHATFORMA_LIST_USERS. |
| `variable_id` | integer | Yes | Variable ID returned by CHATFORMA_LIST_VARIABLES. |

#### 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 Bots

**Slug:** `CHATFORMA_LIST_BOTS`

List bots belonging to the connected Chatforma account so their IDs can be used in bot-scoped tools.

#### 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 Dialog Messages

**Slug:** `CHATFORMA_LIST_DIALOG_MESSAGES`

Return one page of messages exchanged in a specific user's bot dialog, with a cursor for continuing the history.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |
| `user_id` | integer | Yes | Dialog user ID returned by CHATFORMA_LIST_USERS with view=open_dialogs. |
| `per_page` | integer | No | Requested messages per page. Chatforma documents a default of 30 but no maximum. |
| `next_cursor` | string | No | Continuation cursor returned by a prior call. Omit for the first page and pass it back unchanged to continue. |

#### 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 Predefined Messages

**Slug:** `CHATFORMA_LIST_PREDEFINED_MESSAGES`

List predefined messages configured in a bot so a message ID can be selected for sending.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |

#### 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 Segments

**Slug:** `CHATFORMA_LIST_SEGMENTS`

List the user segments configured for a bot, including segment IDs needed for targeted sends.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |

#### 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 Users

**Slug:** `CHATFORMA_LIST_USERS`

List a bot's users, members of one segment, or users with open dialogs; choose the view that matches the task.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `view` | string ("bot_users" | "segment_members" | "open_dialogs") | No | Which user collection to return: all bot users, members of one segment, or users with open dialogs. |
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |
| `deleted` | boolean | No | For bot_users only, return deleted users instead of active users. |
| `per_page` | integer | No | For bot_users or open_dialogs, requested records per page. Chatforma does not document a maximum, and defaults bot_users to 100. |
| `segment_id` | string | No | Segment ID returned by CHATFORMA_LIST_SEGMENTS. Required only when view is segment_members. |
| `next_cursor` | string | No | For bot_users or open_dialogs, continuation cursor returned by a prior call. Repeat the same view and omit it for the first page. |

#### 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 Variables

**Slug:** `CHATFORMA_LIST_VARIABLES`

List variables configured for a bot, including IDs and types needed to read user-specific values.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |

#### 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 Dialog Message

**Slug:** `CHATFORMA_SEND_DIALOG_MESSAGE`

Immediately send a user-visible text message into a specific user's bot dialog. This irreversible action may contact a real user.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |
| `message` | string | Yes | Text to send to the user. Sending is immediate and cannot be undone. |
| `user_id` | integer | Yes | Dialog user ID returned by CHATFORMA_LIST_USERS with view=open_dialogs. |
| `idempotency_key` | string | Yes | Unique client-generated ID for this message, used to recognize the sender's own message and avoid accidental duplicate identifiers. |

#### 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 Predefined Message

**Slug:** `CHATFORMA_SEND_PREDEFINED_MESSAGE`

Send a configured bot message to one user or dispatch it to a segment. This irreversible action may contact one or many real users.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |
| `run_at` | string | No | For a segment dispatch only, schedule delivery for this ISO 8601 date-time; omit to dispatch immediately. |
| `message_id` | string | Yes | Predefined message ID returned by CHATFORMA_LIST_PREDEFINED_MESSAGES. |
| `segment_id` | string | No | Segment ID returned by CHATFORMA_LIST_SEGMENTS. Required only when recipient_type is segment. |
| `bot_user_id` | integer | No | Bot user ID. Required only when recipient_type is user. |
| `recipient_type` | string ("user" | "segment") | Yes | Send to one bot user or dispatch to every user in a segment. |

#### 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 Text Dispatch

**Slug:** `CHATFORMA_SEND_TEXT_DISPATCH`

Create a user-visible text dispatch for one bot user or a segment. Delivery may be immediate or scheduled where supported and cannot be undone through this API.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bot_id` | integer | Yes | Bot ID returned by CHATFORMA_LIST_BOTS. |
| `run_at` | string | No | For a single-user dispatch only, schedule delivery for this ISO 8601 date-time; omit to dispatch immediately. |
| `content` | string | Yes | Text content delivered to the selected recipient or audience. Sending cannot be undone through this API. |
| `segment_id` | string | No | Segment ID returned by CHATFORMA_LIST_SEGMENTS. Required only when recipient_type is segment; use 0 to target all bot users. |
| `bot_user_id` | integer | No | Bot user ID. Required only when recipient_type is user. |
| `recipient_type` | string ("user" | "segment") | Yes | Dispatch to one bot user or every user in a segment. |

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