# ChatMaxima Studio: Agent Guide

ChatMaxima Studio is a conversational AI platform. Bots are built as visual flows
(blocks wired together), then deployed to a website widget, WhatsApp, Instagram,
Facebook Messenger, and other channels.

This page tells an AI agent how to build ChatMaxima bots on behalf of a human.

Everything here runs through the ChatMaxima MCP server. The human's own LLM is the
agent loop; ChatMaxima exposes the tools.

## Connect

ChatMaxima ships an MCP (Model Context Protocol) server over Streamable HTTP.

```
https://chatmaxima.com/mcp
```

Add that as a custom connector in Claude, ChatGPT, Gemini, or any MCP client. The
client will run OAuth 2.1 (dynamic client registration, PKCE, authorization code).
The human signs in to ChatMaxima, picks the workspace the agent should act on, and
approves. No API key handling, no copy-paste secrets.

An existing API key also works: send it in the `Authorization` header, raw or as
`Bearer <key>`. Keys are created in the ChatMaxima dashboard under Developer.

Access tokens are scoped to a single workspace, chosen by the human at consent time.
They can be revoked at any point from Settings, Connected Apps.

### Requirements

The human needs a ChatMaxima account with an active plan before an agent can build
anything. There is no anonymous or pre-signup flow. If the human does not have an
account yet, send them to https://chatmaxima.com/ first.

## Tools

Tools are grouped into three sections. `tools/list` only advertises the sections the
signed-in user's role grants, so the visible tool set varies by user.

### Bot builder

| Tool | Purpose |
| --- | --- |
| `list_block_types` | Catalog of every available block type |
| `get_block_schema` | Exact fields, enums, and required keys for one block type |
| `list_bots` | Bots in the workspace |
| `get_bot` | One bot's block graph |
| `create_bot` | New bot from the default template |
| `add_block` | Append a block, auto-connecting after a given node |
| `connect_blocks` | Wire a specific output to a specific target (branches) |
| `update_block` | Patch a block's data, including rename |
| `delete_block` | Remove a block |
| `organize_bot` | Tidy the canvas layout |
| `run_test` | Run a scripted conversation and return the transcript |

Role required: admin, member, or bot_manager.

### WhatsApp Flows

| Tool | Purpose |
| --- | --- |
| `list_whatsapp_flows` | Flows in the workspace |
| `get_whatsapp_flow` | One flow's definition |
| `list_whatsapp_accounts` | Connected WhatsApp accounts |
| `get_flow_schema` | Supported step types and field rules |
| `create_whatsapp_flow` | Build a draft flow from a declarative step config |
| `update_whatsapp_flow` | Update a draft flow |

Flows are created as local drafts. Publishing to Meta stays a dashboard action.

Role required: admin, member, or campaign_manager.

### WhatsApp message templates

| Tool | Purpose |
| --- | --- |
| `list_whatsapp_templates` | Templates in the workspace |
| `get_whatsapp_template` | One template |
| `browse_template_library` | Public template marketplace |
| `get_template_schema` | Composition rules and limits |
| `compose_whatsapp_template` | Validate and return Meta-ready components JSON |

These are read-only or advisory. `compose_whatsapp_template` does not submit to Meta:
template creation is permanent, needs WABA approval, and the name cannot be changed
afterward, so it stays a deliberate dashboard action.

Role required: admin, member, or campaign_manager.

## Build order

Follow this sequence. It matches how the visual builder itself works.

1. `list_block_types` to see what is available.
2. `get_block_schema` for every block type you intend to add. Do not guess field
   names; the schema is authoritative.
3. `create_bot` to get a bot alias. The new bot starts with a small default graph:
   a trigger, a start message, and a restart handler.
4. `add_block` repeatedly, threading `after_node` from the previous block. Each call
   auto-connects the new block after that node and re-organizes the canvas.
5. `connect_blocks` for anything non-linear: button choices, condition branches, and
   any output beyond the first.
6. `organize_bot` for a final tidy pass.
7. `run_test` with realistic visitor messages, and read the transcript before telling
   the human it is done.

Then send the human the builder URL returned by `create_bot` so they can review it.

## Rules

**Always call `get_block_schema` before `add_block`.** Block data keys are specific
per type and are validated. Guessing produces a block that saves but does not run.

**Never invent account aliases or template names.** Anything referring to a connected
channel, WhatsApp account, or approved template must come from a list tool. Made-up
identifiers fail at runtime, sometimes silently.

**Block titles are normalized.** The builder lowercases and snake_cases them, so
"Ask Name" becomes `ask_name`. Refer to blocks by the id returned from `add_block`.

**Test before declaring success.** `run_test` executes the real runtime with side
effects simulated. A bot that was never tested should not be described as working.

**Respect the human's workspace.** Tokens are scoped to one workspace. Do not attempt
to reach bots, flows, or accounts outside it; those calls will be rejected.

## Limits

- Write operations are rate limited per workspace.
- Bot writes drive the real visual builder, so they are not instant. Expect roughly a
  second or two per block. Build deliberately rather than firing large parallel batches.
- Bot saves require an active plan. An expired subscription blocks saving with an
  upgrade message, even though bot creation itself may succeed.
- WhatsApp Flow step types are limited to self-contained ones: forms, text input, and
  date pickers. List types backed by a runtime data source are rejected with guidance.

## Errors

Tool errors come back as a normal MCP tool result with `isError` set and a plain
message. Common cases:

| Condition | What to do |
| --- | --- |
| `Unauthorized` | Token missing, expired, or revoked. Ask the human to reconnect. |
| `You do not have access to the ... tools in this workspace` | The user's role does not grant that section. A workspace admin must grant it. |
| `Unknown block_type "..."` | Call `list_block_types` and use an exact name from it. |
| Subscription expired on save | The workspace plan lapsed. The human must renew before bots can be saved. |
| Rate limited | Too many calls. Slow down and retry. |

## Documentation

- Product: https://chatmaxima.com/
- Docs: https://docs.chatmaxima.com/
- Dashboard: https://chatmaxima.com/dashboard/
- Connected apps and revocation: https://chatmaxima.com/dashboard/settings/connected-apps/