# Chatto Documentation

> AI chat platform with multi-provider LLM support, knowledge base management, and vector search.

## overview

# Welcome to Chatto

Chatto is an AI agent platform that lets you create, train, and deploy intelligent chat assistants for your business.

## What You Can Do

- **Create AI Agents** — Build custom chat assistants tailored to your needs
- **Train with Your Data** — Upload documents so agents know your business
- **Deploy Anywhere** — Share agents publicly or use them internally
- **Manage Teams** — Organize users with role-based access
- **Monitor Usage** — Track conversations and costs in real-time
- **Voice Conversations** — Talk to agents using voice input and output

## How It Works

1. **Create an agent** with a name, personality, and AI model
2. **Upload knowledge** — PDFs, websites, or text your agent should know
3. **Chat with it** — Test in the playground or deploy for others to use
4. **Monitor** — See usage, costs, and performance in the dashboard

---

## getting-started

## Getting Started

### Step 1: Log In

Visit the Chatto login page and sign in with your email or Google account.

### Step 2: Join an Organization

You'll be invited to an organization by an admin. Organizations group your agents, users, and credits together.

### Step 3: Create Your First Agent

1. Go to **Dashboard → Agents**
2. Click **Create New Agent**
3. Enter a name and description
4. Choose an AI model (e.g., GPT-4o)
5. Write a system prompt that defines how the agent should behave
6. Click **Save**

### Step 4: Chat with Your Agent

1. Click on your new agent
2. Click **Chat**
3. Type a message and press Enter
4. The agent responds based on its configuration

### Step 5: Add Knowledge (Optional)

Upload documents so your agent can reference specific information:

1. Go to **Dashboard → Knowledge Bases**
2. Create a new knowledge base
3. Upload PDFs, enter URLs, or paste text
4. Connect the knowledge base to your agent

### Step 6: Deploy (Optional)

Make your agent accessible to others:

1. Go to your agent's settings
2. Enable **Public Access**
3. Share the URL with your users

---

## agents

## Agents

Agents are AI assistants you create and configure to serve your users.

### Agent Settings

| Setting | What It Does |
|---------|--------------|
| **Name** | The agent's display name |
| **Description** | Explains what the agent does |
| **System Prompt** | Instructions that define the agent's behavior and knowledge |
| **Model** | The AI model powering the agent |
| **Temperature** | How creative responses are (0 = precise, 1 = creative) |
| **Max Tokens** | Maximum length of each response |

### System Prompts

The system prompt is your agent's core instruction set. Good prompts:

- Define the agent's role: "You are a customer support agent for Acme Corp"
- Set boundaries: "Only answer questions about our products"
- Specify tone: "Be friendly and professional"
- Include context: "We sell software for project management"

### Chatting with Agents

- **Playground**: Test agents privately in the dashboard
- **Public Chat**: Deploy agents for external users
- **Voice Calls**: Speak to agents using voice input/output

### Agent Types

Create different agents for different purposes:

| Agent Type | Use Case |
|------------|----------|
| **Customer Support** | Answer common questions, troubleshoot issues |
| **Sales Assistant** | Qualify leads, provide product info |
| **Internal Helper** | Help employees find information |
| **Knowledge Expert** | Answer questions about your documentation |

---

## knowledge-bases

## Knowledge Bases

Knowledge bases teach your agents about your specific content — products, documentation, policies, and more.

### Adding Knowledge

You can add content in several ways:

| Method | Best For |
|--------|----------|
| **PDF Upload** | Manuals, guides, documentation |
| **Web Crawl** | Websites, online docs, help centers |
| **Manual Text** | Policies, FAQs, specific information |

### How It Works

When you upload documents, Chatto:

1. Breaks the content into smaller chunks
2. Analyzes the meaning of each chunk
3. Stores them for fast retrieval
4. When someone chats with your agent, relevant chunks are found and used to answer

### Best Practices

- **Keep documents focused** — One topic per document works best
- **Use clear headings** — Helps the system understand structure
- **Update regularly** — Keep knowledge current
- **Test after uploading** — Chat with your agent to verify it learned correctly

### Supported Formats

- PDF documents
- Web pages (via URL)
- Plain text
- Excel spreadsheets

### Connecting to Agents

1. Go to your agent's settings
2. Select **Knowledge Bases**
3. Choose which knowledge bases to connect
4. Save changes

---

## personas

## Personas

Personas control how your agents communicate — their tone, style, and personality.

### Why Use Personas?

Different situations call for different communication styles:

- **Customer support** → Friendly, patient, helpful
- **Sales** → Enthusiastic, persuasive, knowledgeable
- **Technical support** → Clear, precise, detailed
- **Internal tools** → Concise, direct, efficient

### Creating a Persona

1. Go to **Dashboard → Personas**
2. Click **Create New Persona**
3. Give it a name and description
4. Write detailed instructions for tone and behavior
5. Save and assign to agents

### Persona Examples

**Professional Support Agent**
> You are a professional customer support agent. Be courteous, acknowledge concerns, provide step-by-step solutions, and always confirm understanding.

**Casual Assistant**
> You are a friendly, casual assistant. Use everyday language, be enthusiastic, and keep responses conversational. Use emojis occasionally.

**Technical Expert**
> You are a technical documentation assistant. Be precise, use correct terminology, provide code examples when relevant, and always cite sources.

### Assigning Personas

1. Go to an agent's settings
2. Select a persona from the dropdown
3. Save changes
4. The agent will now communicate using that persona's style

---

## organizations

## Organizations

Organizations group your agents, users, and billing together.

### Organization Roles

| Role | Can Do |
|------|--------|
| **Admin** | Manage members, settings, billing, and all agents |
| **Member** | Create and use agents, view their own usage |
| **Viewer** | Read-only access to agents and knowledge bases |

### Managing Members

Organization admins can:

1. **Invite users** — Send email invitations
2. **Assign roles** — Set each member's access level
3. **Remove members** — Revoke access when needed
4. **Bulk import** — Add multiple users at once

### Organization Settings

Each organization has:

- **Shared balance** — Credits used by all members
- **Shared agents** — Agents all members can access
- **Usage tracking** — Monitor team activity
- **Spending controls** — Set per-member limits

### Creating an Organization

If you have permission:

1. Go to **Dashboard → Organizations**
2. Click **Create Organization**
3. Enter name and settings
4. Invite members

---

## roles-permissions

## Roles & Permissions

Control who can do what with role-based access.

### Default Roles

| Role | Description |
|------|-------------|
| **System Admin** | Full platform access across all organizations |
| **Organization Admin** | Manage members and settings within their org |
| **Member** | Create and use agents |
| **Viewer** | Read-only access |

### What Each Role Can Access

| Action | Viewer | Member | Org Admin | System Admin |
|--------|--------|--------|-----------|--------------|
| View agents | ✅ | ✅ | ✅ | ✅ |
| Create agents | ❌ | ✅ | ✅ | ✅ |
| Manage knowledge | ❌ | ✅ | ✅ | ✅ |
| Invite members | ❌ | ❌ | ✅ | ✅ |
| View billing | ❌ | ❌ | ✅ | ✅ |
| Manage models | ❌ | ❌ | ❌ | ✅ |
| System settings | ❌ | ❌ | ❌ | ✅ |

### Custom Roles

System admins can create custom roles with specific permissions:

1. Go to **Dashboard → Roles & Permissions**
2. Click **Create Role**
3. Select which permissions to include
4. Save and assign to users

---

## voice-calls

## Voice Calls

Talk to your agents using voice instead of typing.

### Starting a Voice Call

1. Open any agent's chat page
2. Click the **Voice** button
3. Allow microphone access when prompted
4. Just talk. The call listens for you to finish your sentence and answers on its own
5. The agent starts speaking as soon as its first sentence is ready, while the rest is still being written

### Features

- **Hands-free** — No tapping: the call notices when you start and stop speaking. Switch it off to tap the mic to talk and tap again to send
- **Starts speaking quickly** — The agent's reply is spoken sentence by sentence as it is written, instead of after the whole answer is ready
- **It remembers the call** — Follow-up questions work ("and the second one?"), because the agent sees what was said earlier in the call
- **Cutting in** — Tap the mic while the agent is talking to interrupt it. Turn on **Let me interrupt by speaking** to do the same just by talking (best with headphones: on laptop speakers the agent's own voice can be picked up). The agent remembers only the part of its answer you actually heard
- **Your words, as heard** — Each of your turns shows what the call understood
- **Multiple languages** — Support for various languages

### When to Use Voice

Voice calls are ideal for:

- Hands-free operation
- Mobile users on the go
- Accessibility needs
- Quick questions when typing is inconvenient

### Cost

Voice calls use credits based on:

- Duration of your audio input
- Length of the agent's spoken response
- The AI model used for generating the response

---

## chat-playground

## Chat Playground

The playground is where you test and interact with your agents privately.

### Using the Playground

1. Go to **Dashboard → Agents**
2. Click on an agent
3. Click **Chat**
4. Type your message and press Enter

### Features

- **Real-time responses** — See responses as they're generated
- **Chat history** — Review past conversations
- **Markdown support** — Responses include formatting, lists, and tables
- **Code highlighting** — Code blocks are syntax-highlighted

### Testing Tips

- **Try edge cases** — See how the agent handles unusual questions
- **Test knowledge** — Verify the agent knows your uploaded content
- **Adjust settings** — Change temperature or model to find the right balance
- **Compare prompts** — Try different system prompts to optimize behavior

### Exporting Conversations

You can download chat history for:

- Training new agents
- Analyzing common questions
- Sharing examples with your team
- Documentation purposes

---

## api-keys

## API Keys

Use API keys to integrate Chatto agents into your own applications.

### Creating an API Key

1. Go to **Dashboard → Resources → API**
2. Click **Create API Key**
3. Give it a name (e.g., "Production App")
4. Choose an expiration date (optional)
5. Save the key securely

### Important

- **Save your key immediately** — You won't be able to see it again
- **Keep it secret** — Never share API keys publicly
- **Use environment variables** — Store keys in your app's config, not in code
- **Rotate regularly** — Create new keys and delete old ones periodically

### Using API Keys

Include your key in API requests to authenticate:

```
Authorization: Bearer chatto_sk_your_key_here
```

### What You Can Do via API

| Action | Description |
|--------|-------------|
| List agents | Get all your agents |
| Chat | Send messages and get responses |
| Stream | Get responses as they're generated |
| Voice | Initiate voice calls |

### Seeing What Each Key Does

On **Dashboard → Resources → API**, the **Usage by key** card shows, for the last 7, 30 or 90 days, each key's calls, failed calls, tokens, cost and when it was last used, with the agent it calls most.

- Click **Export CSV** to download the same period as a spreadsheet: one row per day, key and agent (calls, failed calls, tokens and cost in USD).
- Calls are attributed to a key from the day this feature was released. Earlier calls cannot be tied to a key and are not shown.
- Cost is what your requests with that key were charged, including searching your knowledge and any teammates the agent asked for, so a key can show a cost even for a day with few calls.
- Only your own keys appear, and only you can download them.

### Rate Limits

Your API key has usage limits based on your plan. Monitor usage in the dashboard.

---

## monitoring

## Monitoring

Track usage, costs, and performance across your organization.

### Dashboard Overview

Access **Dashboard → Monitoring** to see:

- **Total conversations** — How many chats happened
- **Token usage** — How much AI processing was used
- **Costs** — Credits spent
- **Active agents** — Which agents are being used
- **Error rate** — Failed requests

### For Organization Admins

View team-level metrics:

- **Per-member usage** — Who's using the most credits
- **Per-agent usage** — Which agents are most popular
- **Cost breakdown** — Where credits are being spent
- **Trends** — Usage patterns over time

### Alerts

Set up notifications for:

- Low balance warnings
- High usage spikes
- Unusual activity
- Error rate increases

### Exporting Data

Download reports for:

- Billing reconciliation
- Usage analysis
- Capacity planning
- Compliance documentation

---

## balance

## Balance & Billing

Chatto uses a credit system to manage costs.

### How Credits Work

1. Your organization has a shared credit balance
2. Each conversation uses credits based on AI model and response length
3. Credits are deducted in real-time
4. Admins can add more credits when needed

### Checking Your Balance

- **Dashboard header** — See your current balance
- **Organization page** — Detailed balance breakdown
- **Monitoring page** — Usage history and trends

### Cost Factors

| Factor | Impact |
|--------|--------|
| **AI Model** | More powerful models cost more per token |
| **Response Length** | Longer responses use more tokens |
| **Knowledge Base** | Using knowledge adds a small overhead |
| **Voice Calls** | Additional cost for speech processing |

### Spending Limits

Organization admins can set limits:

- **Per-member limits** — Cap how much each user can spend
- **Reset periods** — Limits reset daily, weekly, or monthly
- **Automatic enforcement** — Users are blocked when limits are reached

### Adding Credits

1. Go to **Organization → Balance**
2. Follow the top-up instructions
3. Credits are added after payment confirmation

### Low Balance Warnings

When your balance gets low:

- You'll see warnings in the dashboard
- Admins receive email notifications
- Agents continue working until credits run out

---

## public-deployment

## Public Deployment

Share your agents with the world — no login required.

### Making an Agent Public

1. Go to your agent's settings
2. Enable **Public Access**
3. Set a URL slug (e.g., `support-bot`)
4. Customize the welcome message
5. Save and share the URL

### Sharing Options

| Method | Best For |
|--------|----------|
| **Direct Link** | Share in emails, documents, social media |
| **Website Widget** | Embed on your website |
| **API Access** | Integrate into your own applications |

### Public Chat Features

- **No login needed** — Users chat immediately
- **Customizable appearance** — Match your brand
- **Conversation tracking** — See all public interactions
- **Rate limiting** — Prevent abuse

### Monitoring Public Agents

Track performance:

- Total conversations
- Common questions
- User satisfaction
- Response times

### Best Practices

- **Write clear welcome messages** — Tell users what the agent can help with
- **Test before sharing** — Ensure responses are accurate
- **Monitor regularly** — Review conversations for quality
- **Update knowledge** — Keep information current

---