# Communa Documentation > Source: https://communa.io/docs > Generated: 2026-09-14 ## Table of Contents ### Getting Started - [Introduction](https://communa.io/docs/getting-started/introduction) - [Quickstart](https://communa.io/docs/getting-started/quickstart) - [Core Concepts](https://communa.io/docs/getting-started/core-concepts) ### Platform - [Platform Overview](https://communa.io/docs/platform/overview) - [People & Permissions](https://communa.io/docs/platform/people-permissions) ### Agents - [Agent Overview](https://communa.io/docs/agents/overview) - [Chat & Computer](https://communa.io/docs/agents/chat-sandbox) - [Actions & Sequences](https://communa.io/docs/agents/actions) - [Context & Configuration](https://communa.io/docs/agents/context) - [Runs & Scheduling](https://communa.io/docs/agents/runs) - [Change Log](https://communa.io/docs/agents/changes) - [Credentials](https://communa.io/docs/agents/credentials) - [Integrations](https://communa.io/docs/agents/integrations) - [Datasets](https://communa.io/docs/agents/datasets) - [Files](https://communa.io/docs/agents/files) - [Mail](https://communa.io/docs/agents/mail) - [Channels](https://communa.io/docs/agents/channels) - [↳ Telegram](https://communa.io/docs/agents/channels-telegram) - [↳ WhatsApp](https://communa.io/docs/agents/channels-whatsapp) - [↳ Voice (Phone)](https://communa.io/docs/agents/channels-voice) - [↳ Webhook / API](https://communa.io/docs/agents/channels-webhook) - [Queue](https://communa.io/docs/agents/queue) - [Schedule](https://communa.io/docs/agents/schedule) - [Agent Settings](https://communa.io/docs/agents/settings) ### API - [API Overview](https://communa.io/docs/api/overview) - [↳ Datasets API](https://communa.io/docs/api/datasets) ### Resources - [FAQ](https://communa.io/docs/resources/faq) --- # Introduction > Source: https://communa.io/docs/getting-started/introduction Learn what Communa is and how growing teams use collaborative AI agents to run recurring business operations. ## What is Communa? Communa is the collaborative AI agent platform for growing business operations. It helps operations teams create AI agents that handle recurring work across inboxes, spreadsheets, portals, files, and business tools. Each agent runs in its own isolated environment — complete with a real desktop, unrestricted terminal, file system, database, credential vault, and communication layer. Think of it as giving each AI agent their own computer — and the skills of a senior operations specialist, analyst, admin, and technical teammate combined. > **Tip:** Your agent already knows everything in this documentation by heart. Instead of reading through these pages, you can simply ask your agent — *"How do skills work?"*, *"Set up a schedule for me"*, *"What tools do you have?"* — and it will explain, guide you, or just do it for you. Your agent can also configure itself through conversation: schedules, email, instructions, and more. These docs exist as a reference, but your agent is always the fastest path to answers and action. ## Why Communa Exists Three problems exist in the AI agent space today: ### 1. Limited Capabilities Most platforms give you a chat interface with a handful of API integrations. That works for answering questions and simple tasks. But real work — the kind that involves logging into apps, filling forms, processing spreadsheets, editing videos, writing and deploying code — requires a real computer. ### 2. Overwhelming Complexity Platforms that *do* offer more capabilities force you into complicated drag-and-drop flowcharts, JSON configurations, code blocks, and integration setups. You shouldn't need a software engineering degree to build an AI agent. ### 3. Narrow, Predefined Actions Even platforms that call themselves "agent builders" limit agents to a fixed set of predefined actions — search the web, send an email, query a database. Real work is messy and unpredictable. It requires installing software, writing custom scripts, interacting with UIs that have no API, and adapting to unexpected situations on the fly. ### A Different Approach Communa takes a fundamentally different approach. Each agent is a **true AI conversation**. You tell it what to do in plain language. It configures itself, manages its own tools, and executes real work on a real computer. No flowcharts. No JSON. No code blocks. Just a conversation with an intelligent agent that has its own OS. When you create a new agent, it walks you through setup conversationally — asking about its purpose, tone, schedule, and email preferences — then configures itself. From that point on, you interact with it the same way you would with a human teammate: through natural conversation. ## What Your Agents Can Actually Do Agents on Communa aren't limited to a single task or domain. They operate a full computer with unrestricted terminal access — meaning they can do virtually anything a skilled human can do at a keyboard. ### Work Across Every Domain - **Personal Assistant & Productivity** — Manage your inbox, schedule meetings, research topics, process invoices, organize files, send follow-ups, and handle daily busywork. Like having a tireless executive assistant that works around the clock and never forgets a task. - **Coding & Engineering** — Write, debug, test, and deploy code in any language. Install frameworks, run test suites, commit to git, spin up servers, and ship to production. From frontend to backend, scripts to full-stack apps. - **Data & Analytics** — Scrape websites, process spreadsheets, build reports, analyze trends, run SQL queries, write data pipelines, and populate structured datasets. Turn raw data into actionable insights. - **Marketing & Content** — Draft blog posts, create SEO audits, analyze campaign performance, manage ad spend, design slides, generate reports, and build content calendars. - **Sales & CRM** — Research prospects, qualify leads, update pipelines, draft personalized outreach, manage follow-ups, and track deal stages across platforms. - **DevOps & Infrastructure** — Monitor services, investigate incidents, fix configurations, restart pods, apply patches, manage deployments, and post status updates. - **Communication & Coordination** — Send and receive emails, process inboxes, coordinate with other agents, route tasks, and report to team members automatically. - **File Processing & Media** — Convert file formats, process PDFs, manipulate images, edit videos with ffmpeg, merge documents, extract text from scans, and transform media files. - **Any Digital Task** — If it can be done on a computer, your agent can likely do it. Form filling, browser testing, API integration, document generation, web research, database management — the possibilities are bounded only by what software exists. ### The Power of Unrestricted Terminal Access Every agent has full terminal access — the same power a senior engineer has on their workstation. This is transformative: - **Install anything on the fly** — Need ffmpeg for video processing? Python for data analysis? Puppeteer for browser testing? The agent runs `apt-get install` or `pip install` and sets up whatever it needs. No pre-configured tool list. No waiting for integrations. - **Write and run code in any language** — Agents don't just use pre-built tools. When a task requires custom logic, they write scripts in Python, Node.js, Bash, Go, or any language — then execute them immediately. Need a custom data pipeline? The agent writes it, runs it, and delivers the results. - **Chain complex workflows** — Combine terminal commands, browser automation, file management, and web research in a single task. Download a CSV, process it with Python, upload results to a web app, and email a summary — all in one conversation. - **Create their own skills** — When agents develop effective workflows, they can save them as formal skills by writing `SKILL.md` files in the `Skills/` folder on their computer. These skills are automatically detected and can be published to your team's skill catalog for reuse across other agents. Agents also update their own instructions via `settings_manager` to improve over time — they literally self-evolve. This means you never hit a wall. If an agent encounters a task that requires a tool it doesn't have, it installs it. If a task requires custom logic, it writes it. If a workflow needs optimization, it refactors its own approach. ### Always On, Always Ready Agents don't need to be babysat. They operate in three modes: - **On-demand** — Chat with an agent in real time. Give it a task, watch it work on the live desktop preview, and interact as needed. - **Scheduled (24/7)** — Set a schedule (every 5 minutes to every 24 hours) and the agent wakes up automatically, starts its own computer, processes its queue, and goes back to sleep. No human intervention needed. - **Event-driven** — When an email arrives or another agent sends a task, items are automatically queued. The agent picks them up on its next scheduled run — or you can trigger processing manually. - **Channel-connected** — Connect Telegram (and more coming soon) so you can message your agent directly from external platforms. Messages wake the agent automatically and are handled the same way as dashboard chat. Scheduled agents automatically start their own computer, process all pending queue items, and shut down cleanly when done. They run 24/7 without you lifting a finger. Your digital workforce operates while you sleep. ## Who Is Communa For? Communa is built for growing businesses that want AI agents to actually *do the work* — without building complicated flowcharts or writing integration code: - **Growing businesses** turning recurring back-office work into reliable agent-run workflows - **Operations teams** automating customer requests, vendor follow-up, data entry, report generation, approvals, and cross-app workflows - **Finance and admin teams** processing invoices, matching purchase orders, reconciling payments, updating spreadsheets, and maintaining audit trails - **Agencies and client-service teams** deploying specialized agents for different clients, each with their own workspace and credentials - **Founders and operators** who need a digital teammate that works around the clock on research, outreach, data processing, and operations ## How This Documentation Is Organized This documentation covers everything you need to get started and go deep: - **Getting Started** — What you're reading now. Covers concepts, quickstart, and architecture. - **[Agents](/docs/agents/overview)** — Creating agents, the chat & computer workspace, skills, credentials, datasets, files, email, queue, runs, and scheduling. - **[Platform](/docs/platform/overview)** — Workspaces, teams, navigation, dashboards, billing, and member management. > **Tip:** If you're new to Communa, start with the [Quickstart](/docs/getting-started/quickstart) to deploy your first agent in under 5 minutes. ## Key Terminology | Term | Definition | |------|-----------| | **Agent** | An autonomous AI entity with its own isolated computer, skills, and tools. Each agent runs in its own desktop environment with full terminal access and its own email address. | | **Team** | A workspace that groups related agents, skills, and data together. (Sometimes referred to internally as a *project*.) | | **Skill** | A reusable set of instructions that teaches an agent how to perform a specific task. | | **Credential** | An encrypted secret (password, API key, token) that agents can use without seeing the raw value. | | **Dataset** | A structured table of data that agents extract, create, or transform during their work. | | **Sandbox** | The isolated desktop environment where an agent operates — including screen, file system, and full terminal access. | | **Queue** | A list of tasks waiting to be processed by an agent. Items can be added manually, from emails, or from other agents. | | **Run** | A single execution of an agent task — from start to completion. | | **Onboarding** | The conversational setup flow where a new agent introduces itself and configures its own settings through chat. | | **Training** | The iterative process of teaching an agent your specific workflows through task assignment, feedback, and skill refinement — like onboarding a new employee, but 100x faster. | | **Skill Catalog** | Your team's library of reusable skills. Browse, search, create, and share skills across all agents in a team. | | **Channel** | An external messaging platform connection (e.g., Telegram) that lets you chat with your agent outside the dashboard. Messages are handled the same way as dashboard chat. | | **Bash** | Full terminal access that lets agents install software, run scripts in any language, and execute any command — like having a senior engineer's terminal. | --- # Quickstart > Source: https://communa.io/docs/getting-started/quickstart Deploy your first AI agent in under 5 minutes. Create a team, set up an agent, and run your first task. ## Overview This guide walks you through creating your first team, setting up an agent, and running your first task. By the end, you'll have an AI agent that can browse the web, write code, install software, and complete real work on your behalf. > **Prerequisites:** You need a Communa account. If you don't have one yet, [request access](/) from our landing page. > **Tip:** Here's a secret — once you create your agent (Steps 1–3), you can skip the rest of this guide entirely. Just ask your agent what to do next. It knows this documentation inside out and can configure itself, set up skills, create schedules, and handle everything through conversation. These steps are here if you prefer a guided walkthrough, but your agent is always the fastest path. ## Step 1: Create a Team Teams are workspaces that group your agents, skills, and data together. Think of them as folders for related work. 1. Log in to your Communa dashboard 2. Click **New Team** in the sidebar 3. Give your team a name and optional description 4. Click **Create** Your team is now ready. You'll be taken to the team dashboard. ## Step 2: Create Your First Agent 1. Navigate to **Agents** in your team sidebar 2. Click **New Agent** 3. Give it a name (e.g., "Web Researcher") and an optional description 4. Click **Create** You'll land on the agent detail page with several tabs: | Tab | Purpose | |-----|---------| | **Agent** | The primary workspace — chat with your agent and watch it work on the live computer preview | | **Context** | Attach skills and define custom instructions that shape the agent's behavior | | **Mail** | View received and sent emails, configure email settings and whitelisted addresses | | **Files** | Upload and manage files the agent can access in its file system | | **Datasets** | View and manage structured data tables the agent has created or extracted | | **Credentials** | Store secrets the agent needs (logins, API keys, tokens) | | **Runs** | View execution history, logs, and replay past sessions | ## Step 3: Meet Your Agent (Onboarding) When you open a new agent for the first time, something unique happens: the agent **introduces itself** and walks you through setup conversationally. During onboarding, the agent will ask you about: - **Its name** — It suggests a creative name based on its purpose. Pick one you like. - **Its purpose** — Tell it what you need it to do. It uses this to shape its persona and behavior. - **Communication style** — Professional? Casual? Concise? It adapts to your preference. - **Schedule** — Should it run automatically on a timer? The agent can set this up for you. - **Email** — Should it process incoming emails automatically? - **Credentials** — Will it need to log into websites? It'll guide you to **Settings → Credentials**. The agent configures all of this itself using natural conversation — no forms, no settings pages, no JSON. When setup is done, it sends you a summary email and unlocks its full capabilities. > **Info:** You can skip onboarding at any time by saying "skip" or "let's go". The agent will immediately unlock all tools and start working. ## Step 4: Wake Up the Computer Before your agent can interact with applications, it needs a **computer** — its own isolated Linux desktop environment. (The underlying technology is sometimes called a *sandbox* — they refer to the same thing.) 1. Go to the **Agent** tab (the default tab) 2. Click **Wake Agent** (or the play button in the header) 3. Choose a screen resolution for the computer 4. Wait a few seconds while the computer starts Once awake, you'll see a **split-screen layout**: the chat panel on the left and a live preview of the agent's desktop on the right. This is a real Linux desktop running in the cloud — you can watch the agent work in real time. ## Step 5: Chat With Your Agent The chat panel is how you communicate with your agent. Try sending: ``` Go to google.com and search for "latest AI news". Summarize the top 3 results. ``` Watch the agent's desktop as it: 1. Opens the browser 2. Navigates to Google 3. Types the search query 4. Reads the results 5. Sends you a summary in chat > **Info:** The agent uses computer-use capabilities — it literally controls a mouse and keyboard on its desktop, just like a human would. It can also use the terminal, search the web, read URLs, manage files, and much more. ### Push the Boundaries That was just a warm-up. Try something more ambitious: ``` Install ffmpeg, then download this video from [URL]. Trim it to the first 30 seconds, convert to MP4, and save the result to my files. ``` Or: ``` Write a Python script that scrapes the top 10 results from Hacker News, extracts the title, URL, and score for each, and save the results as a dataset. ``` Or: ``` Log into our CRM, export the leads from last week, clean up the data, and email me a summary report. ``` Your agent will install the necessary tools, write and execute code, interact with applications, and deliver the result — all autonomously. If it needs a tool it doesn't have, it installs it. If it needs custom logic, it writes it on the fly. ## Step 6: Add a Skill (Optional) Skills make agents reliable and repeatable. Instead of explaining the same task every time, teach it once — or browse skills that already exist. ### Option A: Browse the Skill Catalog Every team has a **Skill Catalog** — a library of reusable skills accessible from the **Skills** page in your team sidebar. 1. Go to your agent → **Context** tab → click **Add Skill** 2. The Skill Selector opens with a **category sidebar** (Analytics, Communication, Creative, Engineering, etc.) and a search bar 3. Browse available skills or search for what you need 4. Click a skill to attach it — your agent immediately knows how to use it You can also click **Browse Full Library** to see all skills in your team's catalog. ### Option B: Create a New Skill 1. Navigate to the **Skills** page in your team sidebar (your skill catalog) 2. Click **New Skill** 3. Name it (e.g., "Summarize Search Results") 4. Write the instructions: ``` When asked to research a topic: 1. Open the browser and go to google.com 2. Search for the given topic 3. Open the top 3 results in new tabs 4. Read each article 5. Write a concise summary with key points from each 6. Present the results in a clean format with source links ``` 5. Save the skill 6. Go back to your agent → **Context** tab → **Add Skill** → select it Skills created here live in your **team's skill catalog** — available to attach to any agent in the team. ### Option C: Let the Agent Create Its Own Skills Agents can create skills themselves! Just tell your agent: ``` Create a skill for summarizing search results. Save it as a SKILL.md in the Skills folder. ``` The agent will write a properly structured skill file in its sandbox. Click **Sync from Files** in the Context tab to detect it, then **Publish to Catalog** to make it available to other agents. This is powerful: agents that discover effective workflows can formalize them into skills — effectively teaching themselves and other agents. ## Step 7: Run It Again Try a different prompt now: ``` Research "computer use AI agents 2026" and summarize the findings. ``` The agent will follow the skill's instructions automatically, producing consistent results every time. ## Step 8: Let It Run While You Sleep (Optional) Want your agent to work autonomously on a schedule? 1. In the chat, tell the agent: **"Set up a schedule to check my email every 15 minutes and process any new tasks"** 2. The agent will configure its own schedule and email settings using `settings_manager` — no forms to fill out 3. From now on, it wakes up every 15 minutes, starts its own computer, checks its queue, processes any items, and goes back to sleep You can also configure schedules manually in the agent's queue settings, but why bother when you can just ask? This is the magic of Communa: an agent that runs 24/7, picks up tasks from email and other agents, installs whatever tools it needs, writes code on the fly, and delivers results — all without human intervention. ## Step 9: Connect Telegram (Optional) Want to chat with your agent from Telegram instead of the dashboard? 1. Open [@BotFather](https://t.me/BotFather) on Telegram 2. Send `/newbot` and follow the prompts to create a bot 3. Copy the bot token BotFather gives you 4. Go to your agent → **Channels** tab → **Connect Channel** 5. Paste the token and click **Connect Bot** That's it — send a message to your bot on Telegram and your agent will respond. If the agent is sleeping, it wakes up automatically. Your bot works in private chats by default. To use it in **group chats**, disable Group Privacy in BotFather — see the [Channels docs](/docs/agents/channels) for details. ## What's Next? You've successfully created a team, deployed an agent, and run your first task. Here's where to go from here: - **[Core Concepts](/docs/getting-started/core-concepts)** — Understand the architecture and building blocks behind Communa - **[Agent Overview](/docs/agents/overview)** — Everything about creating and managing agents - **[Context & Configuration](/docs/agents/context)** — Set up skills, instructions, and tools - **[Credentials](/docs/agents/credentials)** — Securely store passwords and API keys for your agents - **[Queue](/docs/agents/queue)** — Manage task queues and automated processing - **[Runs & Scheduling](/docs/agents/runs)** — Set up automated runs and scheduling - **[Mail](/docs/agents/mail)** — Configure email communication between agents and the outside world - **[Channels](/docs/agents/channels)** — Connect Telegram for external messaging --- # Core Concepts > Source: https://communa.io/docs/getting-started/core-concepts Understand the architecture, mental model, and key building blocks of the Communa platform. > **Tip:** You don't need to memorize any of this. Your agent understands all these concepts natively — its computer, skills, queues, credentials, email, scheduling, and more. Just ask it: *"How does the queue work?"*, *"Create a skill for me"*, or *"Set up my email."* It will explain or act on your behalf. This page is a reference for when you want the full picture. > **Note on terminology:** Throughout the docs we use **computer** to mean the agent's isolated Linux desktop environment. The underlying technology is sometimes called a *sandbox* — they refer to the same thing. ## The Mental Model Communa's architecture is built on one core principle: **each AI agent gets their own computer**. This isn't a metaphor — each agent literally runs in an isolated Linux desktop environment with its own screen, file system, terminal, and runtime. This isolation means agents can't interfere with each other, and you get the same security and governance you'd expect from giving a human employee their own workstation. ## Agents Take Action, Not Just Answer This distinction matters. Traditional AI assistants answer questions and call APIs. Communa agents *do work*. The difference: | Traditional Chatbot | Communa Agent | |---------------------|---------------| | Explains how to convert a video | Installs ffmpeg and converts the video | | Suggests a Python script | Writes, runs, and debugs the script | | Lists steps to fill a form | Opens the browser and fills the form | | Recommends a data pipeline | Builds, runs, and delivers the pipeline output | | Drafts an email template | Researches the recipient, personalizes the message, and sends it | | Describes how to set up a server | Installs packages, writes configs, and starts the server | Agents have full terminal access (`bash`) and can install any software, write code in any language, and execute complex multi-step workflows — all without asking you for permission at every step. When an agent encounters a task that requires a tool it doesn't have, it installs it. When a task requires custom logic, it writes a script and runs it. When a workflow breaks, it diagnoses the issue and tries a different approach. This is what makes the platform fundamentally different: **agents are constrained only by what a computer can do — which is almost anything.** ## The Chat-First Paradigm Unlike platforms that require drag-and-drop flowcharts, JSON configurations, or code to build agents, Communa is **chat-first**. Every interaction with an agent happens through natural conversation: - **Setup** — New agents configure themselves through an onboarding conversation. They ask about their purpose, tone, schedule, and email — then set it all up. - **Execution** — You tell the agent what to do in plain language. It figures out how to do it using its tools. - **Configuration** — Agents can read and update their own settings (schedule, email, persona) through the `settings_manager` tool — no settings pages required. This means the barrier to creating a working agent is as low as having a conversation. No engineering required. ## Running Modes Agents support three operational modes — and you can combine all three: ### On-Demand (Interactive) Chat with your agent in real time. You send messages, the agent works, and you watch the live desktop preview side by side. Perfect for exploratory tasks, debugging, and hands-on work. ### Scheduled (24/7 Autonomous) Configure a schedule — every 5 minutes, hourly, daily — and the agent runs automatically. On each scheduled run, it: 1. **Starts a computer** automatically (or connects to an existing one) — no human needs to "wake" the agent 2. **Processes queue items** sequentially — up to a configurable max per run 3. **Shuts down cleanly** when the queue is empty Scheduled agents are truly autonomous. They wake up, do their job, and go back to sleep. No human oversight required. They run 24/7 — processing tasks, sending emails, generating reports — while you focus on other things. ### Event-Driven (Reactive) Agents can react to external events: - **Incoming emails** are automatically added to the queue for processing - **Other agents** can send tasks via email, which are auto-queued - Queue items from any source are processed on the next scheduled run ### Channel-Connected (External Messaging) Agents can receive messages from external platforms like Telegram, WhatsApp, or phone calls (Voice). When you send a message: 1. If the agent is sleeping, it **wakes up automatically** — no dashboard visit needed 2. Your message is processed the same way as a dashboard chat message 3. The response is sent back to the messaging platform in real time This means you can interact with your agent without ever opening the Communa dashboard. Connect a Telegram bot, WhatsApp number, or voice phone number in the **Channels** tab and your agent is reachable 24/7. **Combine all four modes:** Chat with an agent to set it up, connect a Telegram bot for messaging on the go, then let it run on a schedule processing emails and tasks from other agents — checking in only when you need to. ## Architecture Overview Here's how the pieces fit together: ``` ┌─────────────────────────────────────────────┐ │ TEAM │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Agent A │ │ Agent B │ │ │ │ │ │ │ │ │ │ ┌────────┐ │ │ ┌────────┐ │ │ │ │ │Sandbox │ │ │ │Sandbox │ │ │ │ │ │Desktop │ │ │ │Desktop │ │ │ │ │ │Files │ │ │ │Files │ │ │ │ │ │CLI │ │ │ │CLI │ │ │ │ │ └────────┘ │ │ └────────┘ │ │ │ │ │ │ │ │ │ │ Skills │ │ Skills │ │ │ │ Credentials │ │ Credentials │ │ │ │ Datasets │ │ Datasets │ │ │ │ Email ←──┼──┼──→ Email │ │ │ │ Queue │ │ Queue │ │ │ │ Channels │ │ Channels │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ Shared Skills Library │ └─────────────────────────────────────────────┘ ``` Notice the arrow between agents' email: agents can communicate with each other by sending emails to each other's addresses, enabling multi-agent collaboration workflows. ## Teams A **team** is a workspace that groups related agents together. Teams provide: - A shared space for organizing agents by domain, function, or workflow - A team-level dashboard with activity feeds, run analytics, and agent status - A **shared skills library** — skills are created at the team level and can be attached to any agent in the team - Centralized settings and member management Most users start with one team and expand as their needs grow. ## Agents An **agent** is the core building block of Communa. Each agent has: ### Identity & Configuration - **Name and description** — What the agent does and how to identify it - **AI model** — Which language model powers the agent's reasoning (Claude, GPT, and more) - **Custom instructions** — System-level instructions that shape the agent's behavior and persona - **Onboarding** — New agents walk users through setup conversationally, then mark onboarding complete ### Capabilities (Tools) Each agent has access to a powerful set of tools that can be individually enabled or disabled: | Tool | Purpose | |------|---------| | `computer` | Screen interaction — click, type, scroll, take screenshots. Interact with any web app, desktop tool, or GUI. | | `bash` | **Unrestricted terminal** — Run any command as a power user. Install software (`apt-get`, `pip`, `npm`, `cargo`), write and execute scripts in any language, process files, manage services, and build and deploy applications. Agents write code on the fly to solve problems — if a task requires custom logic, they create it. The agent has the same terminal power as a senior engineer. | | `web_search` | Search the internet for current information, research topics, find resources. | | `read_url` | Read and extract clean content from any web page as structured markdown. | | `data_capture` | Extract structured data from the computer (screen, clipboard, files) into datasets. | | `data_management` | Create datasets, insert/update/delete rows, query and transform stored data. | | `use_credential` | Fill login forms with stored credentials — values are never exposed to the AI model. | | `read_file` | Access files from the agent's file storage (uploads, skills, resources). | | `download_to_sandbox` | Transfer stored files onto the computer for processing. | | `list_emails` / `read_email` / `send_email` | Full email operations — read inbox, process messages, send emails to anyone. | | `settings_manager` | Read or update the agent's own configuration — schedule, email, persona, instructions. | ### Data - **Files** — Per-agent file storage for uploads, downloads, and working documents - **Datasets** — Structured tables for extracted and transformed data - **Email** — A dedicated email address (`agent-name@mailer.communa.io`) for sending and receiving messages. Built-in by default for internal and team workflows; switch to your own SMTP server for customer-facing email at scale ([details](/docs/agents/mail#custom-smtp--send-from-your-own-domain)) ## Onboarding When you create a new agent, it starts in **onboarding mode**. During onboarding, only the `settings_manager` and `send_email` tools are available — all other capabilities are locked. The agent will: 1. Read its current configuration 2. Walk you through naming, purpose, tone, schedule, and email settings — one topic at a time 3. Configure each setting as you discuss it (no waiting until the end) 4. Send you a summary email when done 5. Mark onboarding complete, unlocking all capabilities This is a core design principle: agents should be able to set themselves up through conversation. You never need to fill out configuration forms. > **Tip:** You can skip onboarding at any time by saying "skip" or "done". The agent will immediately unlock all tools. ## Training Your Agent Think of a new Communa agent like a new employee. It's smart and capable, but it doesn't know your specific workflows, preferences, tools, and expectations yet. **Training** is the process of getting it there. ### How Training Works Training an agent is iterative — just like training a human team member: 1. **Give it a task** — Start with something concrete: "Research this company and summarize the findings" or "Process these invoices and update the tracker" 2. **Observe the results** — Watch the agent work on the live desktop preview. Did it navigate to the right places? Did it extract the right data? Is the output quality acceptable? 3. **Give feedback** — Tell the agent what it did well and what needs improvement: "The summary was too long — keep it to 3 bullet points" or "You missed the invoice date column" 4. **Refine with skills and instructions** — As patterns emerge, formalize them into skills and custom instructions so the agent's behavior becomes consistent and repeatable 5. **Validate with iterations** — Run the task again and verify the improvement. Repeat until the agent performs reliably ### The Agent Helps You Train It Communa agents aren't passive during training. The agent will actively: - **Ask clarifying questions** when instructions are ambiguous - **Suggest improvements** to its own skills and workflows - **Create skills for itself** by writing `SKILL.md` files when it develops effective approaches - **Update its own instructions** via `settings_manager` to refine its behavior over time ### How Long Does Training Take? It depends on the agent's complexity: | Agent Complexity | Training Time | Examples | |------------------|---------------|----------| | **Simple** | 5–15 minutes | Web research, data entry, file conversion, email triage | | **Moderate** | 30–60 minutes | Multi-step workflows, CRM management, report generation, content creation | | **Complex** | 1–3 hours | Full business processes, multi-app orchestration, edge case handling, multi-agent coordination | Even at the high end, this is **orders of magnitude faster** than training a human employee for the same tasks — which typically takes days to weeks. And unlike humans, once an agent is trained, it executes perfectly every time, 24/7, without forgetting or getting tired. ### Training Tips - **Start small** — Begin with a single, well-defined task before expanding scope - **Use the live preview** — Watch the agent work to catch issues early - **Formalize early** — Turn successful patterns into skills as soon as you identify them, rather than relying on conversational memory - **Test with variations** — Run the same task with different inputs to verify the agent handles edge cases - **Iterate, don't restart** — Build on what works rather than starting over. Agents improve incrementally, just like people do — except faster ## The Sandbox The **sandbox** is the isolated desktop environment where an agent operates. When you "wake up" an agent, a sandbox is provisioned with: - **A full Linux desktop** — With a real display, window manager, and applications - **Mouse & keyboard control** — The agent sees the screen and controls input devices - **A file system** — Persistent storage for the agent's files and data - **Unrestricted terminal access** — Full command line for running scripts, installing packages, and executing any command - **Network access** — The agent can browse the web, call APIs, and interact with services - **Configurable resolution** — Choose the screen resolution when creating the sandbox The terminal access is what makes Communa agents fundamentally more capable than other platforms. Agents can install any software available on Linux, write and execute code in any programming language, build complex data pipelines, create skills for themselves, and adapt to any task — all from the command line. They never hit a wall: if they need a tool, they install it. If they need custom logic, they write it. If something breaks, they debug it. > **Warning:** Sandboxes are ephemeral by default — they're created when an agent wakes and destroyed when it sleeps. Files that should persist are synced to permanent storage automatically. You can enable **Persistent Sandbox** in the agent's Settings to preserve sandbox state across sessions — the sandbox pauses instead of being destroyed, and resumes instantly when the agent wakes — preserving browser sessions (including website logins), installed packages, and running processes. ## Skills **Skills** are the backbone of reliable agent behavior. A skill is a structured set of instructions — following the [Open Skills Standard](https://agentskills.io) — that teaches an agent how to perform a specific task. ### The Skill Catalog Every team has a **Skill Catalog** — a library of reusable skills that any agent in the team can use. Access it from the **Skills** page in your team sidebar. The catalog supports: - **Search and filter** — Find skills by name, description, or category (Analytics, Communication, Creative, Engineering, etc.) - **Create and edit** — Build skills with a name, description, category, icon, and detailed instructions - **Version tracking** — Skills have content hashes for change detection - **Usage tracking** — See how many agents use each skill ### Attaching Skills to Agents Skills are attached to agents via the **Context** tab: 1. Click **Add Skill** to open the Skill Selector 2. Browse by category or search 3. Click a skill to attach it — the agent receives its own **copy** 4. Drag to reorder — higher skills get priority Each agent gets an independent copy of the skill. If the catalog version is updated, agents see an "Update Available" badge and can pull changes when ready. ### Agent-Created Skills This is where it gets interesting. Agents can **create their own skills** by writing `SKILL.md` files in their sandbox: ``` Skills/ my-new-skill/ SKILL.md ← Instructions (required) scripts/ ← Executable scripts (optional) references/ ← Documentation, guides (optional) assets/ ← Templates, configs, data (optional) ``` When you click **Sync from Files** in the Context tab, the system detects these files and creates skill instances automatically. Agent-created skills are labeled **"Local"** and can be **Published to Catalog** to share with other agents. Just tell your agent: *"Create a skill for [task] and save it in the Skills folder."* It will write a properly structured `SKILL.md` file with the right frontmatter and instructions. ### The Skill Lifecycle ``` Create (Catalog or Agent) → Attach to Agent (Copy) → Agent Modifies Locally → Push Changes to Catalog → Other Agents Pull Updates ``` This git-like flow means skills improve over time as agents and users refine them. ### Writing Good Skills The best skills are: 1. **Specific** — Describe exact steps, not vague goals 2. **Sequential** — List actions in order: go here, click this, type that 3. **Defensive** — Include what to do when things go wrong 4. **Observable** — Tell the agent what success looks like Skills can also include: - **Scripts** — Python, Bash, or Node.js code the agent can execute - **References** — Documentation, API guides, or runbooks - **Assets** — Templates, config files, or sample data ## Credentials **Credentials** are encrypted secrets — passwords, API keys, access tokens — that agents can use without ever seeing the raw values. How they work: 1. You create a credential in **Settings → Credentials** with a name and value 2. The value is encrypted and stored securely 3. When an agent needs to log in or authenticate, it requests the credential by name using the `use_credential` tool 4. The system fills in the value directly into the UI field — the AI model never sees it in plaintext This is critical for security. Even if an AI model behaves unexpectedly, it literally cannot leak credentials it doesn't have access to. The agent can never echo, print, or transmit credential values — it can only trigger the system to fill them into form fields. ## Datasets **Datasets** are structured data tables that agents create, populate, and transform. Think of them as spreadsheets that fill themselves. - **Auto-created** — When an agent extracts structured data using `data_capture`, a dataset is created automatically - **Manageable** — Agents can also create datasets and insert/update/delete rows programmatically using `data_management` - **Editable** — Click any cell to edit inline in the UI - **Transformable** — Ask the agent to transform columns ("normalize all emails", "extract domain names") - **Filterable & sortable** — Use column filters and sort to find what you need - **Exportable** — Download as CSV - **Protected** — Datasets can be locked or have per-operation permissions (insert, update, delete, read) to prevent accidental modification ## The Queue The **queue** is a task list that agents process sequentially. Each agent has its own queue where items wait to be handled. ### How Items Enter the Queue - **Manually** — Add items through the UI - **From emails** — When "auto-queue incoming emails" is enabled, new emails are automatically added as queue items - **From other agents** — An agent can send an email to another agent, which gets auto-queued for processing - **From scheduled runs** — The cron system processes queue items on the agent's configured schedule ### How Processing Works When a scheduled run triggers: 1. The system provisions a new sandbox (or connects to an existing one) — **no human needs to "wake" the agent** 2. Queue items are processed sequentially with full AI context 3. Each item gets its own chat session for traceability 4. The agent has a time budget per item with graceful cutoff 5. After processing, the sandbox stays warm for the next run Items in the queue have a position (drag-and-drop to reorder). The agent processes them in order, and each completed item is marked done. ### Queue Processing Schedule Agents can have a **queue processing schedule** that automatically processes queue items at regular intervals (every 5 minutes to every 24 hours). The schedule can be configured through the UI or by the agent itself via `settings_manager`. Each scheduled run processes up to a configurable number of items. This is how agents run 24/7: the schedule triggers a run → the system provisions a sandbox → the agent processes its queue → the sandbox stays ready for the next run. Fully autonomous, fully observable. ### Scheduled Jobs In addition to the queue processing schedule, agents support **scheduled jobs** — time-based triggers that inject a specific prompt into the queue at configured times (daily, weekdays, custom days, or at intervals). Each scheduled job has its own prompt, timezone, and model selection. When a job fires, it creates a queue item that's processed through the normal pipeline. See **[Schedule](/docs/agents/schedule)** for details. ## Inter-Agent Communication Agents communicate with each other through **email**. Each agent has its own email address (e.g., `researcher@mailer.communa.io`), and agents can: - **Send emails** to other agents, external addresses, or team members - **Receive emails** from anyone (other agents, external senders, or team members) - **Auto-queue incoming emails** for processing — enabling asynchronous agent-to-agent workflows ### Example: Multi-Agent Workflow 1. **Agent A** (Researcher) scrapes a website, writes a Python script to process the data, and sends an email to Agent B with the results 2. **Agent B** (Analyst) has auto-queue enabled — the email appears as a queue item 3. Agent B's schedule triggers, it provisions its own sandbox, installs the analysis tools it needs, processes the queue item, and produces a report 4. Agent B emails the report to a team member or back to Agent A for further action Each agent in this workflow independently installs its own tools, writes its own scripts, and handles its own tasks — all communicating through simple email. This email-based communication model is simple, observable (every message is logged in the Mail tab), and doesn't require any special configuration — agents just send emails to each other's addresses. > **Info:** Outbound emails are restricted to a whitelist by default for security. Team members and the agent's own address are always allowed. Additional addresses must be added in the Mail tab settings. Advanced users can disable whitelist enforcement with acknowledgment — see **[Mail](/docs/agents/mail#disabling-the-whitelist)**. ## Runs A **run** is a single execution of an agent task — from when the agent starts working to when it finishes (or is stopped). Each run captures: - All chat messages between you and the agent - Every action the agent performed (clicks, keystrokes, commands) - Screenshots at key moments - Token usage and cost - Start time, end time, and final status Runs provide full auditability. You can review exactly what happened, debug issues, and understand the agent's decision-making process. Runs can be triggered manually through chat, from queue processing, or automatically on a schedule. ## What's Next? Now that you understand the building blocks, dive deeper into specific areas: - **[Agent Overview](/docs/agents/overview)** — Creating agents and navigating the agent detail page - **[Chat & Computer](/docs/agents/chat-sandbox)** — The primary workspace for interacting with your agent - **[Context & Configuration](/docs/agents/context)** — Skills, instructions, and tool management - **[Credentials](/docs/agents/credentials)** — Secure access to external services - **[Datasets](/docs/agents/datasets)** — Structured data capture and management - **[Files](/docs/agents/files)** — Session files and persistent storage - **[Mail](/docs/agents/mail)** — Agent email and inter-agent communication - **[Channels](/docs/agents/channels)** — Connect Telegram, WhatsApp, and Voice (Phone) channels - **[Queue](/docs/agents/queue)** — Task queues and processing - **[Runs & Scheduling](/docs/agents/runs)** — Execution history and automation - **[Workspace Management](/docs/platform/overview#inviting-members)** — Inviting members, managing roles, and workspace settings --- # Platform Overview > Source: https://communa.io/docs/platform/overview Understand how Communa is organized — workspaces, teams, members, invites, navigation, dashboards, and billing. > **Tip:** Your agent understands the platform structure natively. Ask it anything — *"How do I switch teams?"*, *"Where's my billing page?"*, *"Add a workspace member"* — and it will guide you or handle it for you. > **Note on terminology:** Throughout the docs we use **team** to mean the grouping that holds related agents, skills, and data. Internally (and in some URLs like `/p/...`) a team may be referred to as a *project* — they refer to the same thing. ## Platform Hierarchy Communa is organized in a clear hierarchy: ``` Workspace (top level) └── Team └── Agent ├── Skills ├── Credentials ├── Datasets ├── Files ├── Email └── Queue ``` Everything starts with a **Workspace**. Inside workspaces, you create **Teams**. Inside teams, you create **Agents**. This hierarchy keeps things organized as your AI workforce grows. ## Workspaces A **Workspace** is your top-level organizational unit — the container for everything. When you sign up, a default workspace is created automatically. ### What a Workspace Contains - **Teams** — Groups of related agents and skills - **Members** — People with role-based access - **Billing** — Subscription plan and credit balance (billing is per-workspace) ### Workspace Members & Roles You can invite team members to your workspace. Each member has a role that determines their permissions: | Role | Permissions | |------|------------| | **Owner** | Full access — manage members, roles, billing, teams, and agents. One per workspace (the creator). | | **Admin** | Create, update, delete teams and agents. Manage members. Cannot transfer ownership. | | **Member** | Create and update teams and agents. Cannot manage other members. | Roles are hierarchical — each role inherits the permissions of the roles below it. The Owner has complete control, Admins can manage most things, and Members can create and update teams and agents. > **Info:** To invite members or manage roles, go to **Workspace Settings**. See the sections below for details. ### Switching Workspaces If you belong to multiple workspaces (your own + ones you've been invited to): 1. Look at the **bottom of the sidebar** for the workspace switcher 2. Click it to see all your workspaces with a search bar 3. Each workspace shows your role — **Owner** (with a crown icon) or **Member** (with a people icon) 4. Click a workspace to switch — the app reloads with that workspace's data The workspace switcher only appears if you have access to more than one workspace. Your last-used workspace is remembered between sessions. > **Info:** Switching workspaces clears all cached data to ensure you always see fresh, accurate data from the selected workspace. ### Inviting Members Owners and Admins can invite new members to a workspace: 1. Open **Workspace Settings** — click the **Manage Workspace** button at the bottom of the sidebar (inside the workspace switcher) 2. Scroll to the **Members** section and click **Invite** 3. Enter the invitee's **email address** 4. Select a **role** from the dropdown: - **Owners** can invite as Admin or Member - **Admins** can invite as Member only 5. Click **Send Invite** — an email is sent with the workspace name, assigned role, inviter name, and an **Accept Invite** button Invites **expire after 72 hours**. If a pending invite already exists for that email, you must revoke it first before sending a new one. ### Managing Invites Pending invites are displayed in a **Pending Invites** section below the members table (visible to Owners and Admins): | Column | What It Shows | |--------|--------------| | **Email** | The invitee's email address | | **Role** | The role they'll receive when they accept | | **Invited** | When the invite was sent | | **Expires** | Countdown timer (e.g., "2d left", "18h left") or a red **Expired** label | **Actions on pending invites:** - **Resend** — Click the refresh icon to resend the invite email. This works for both active and expired invites, generating a fresh email and resetting the 72-hour timer. - **Revoke** — Click the ✕ icon to cancel the invite entirely. The invite link becomes invalid immediately. Expired invites remain visible until you revoke or resend them. ### Accepting an Invite When an invitee clicks the **Accept Invite** link in their email: - **If already logged in** — The invite is accepted automatically, and the user is redirected to the new workspace. - **If not logged in** — The invite token is preserved through the login flow. After the user logs in or signs up, the invite is accepted automatically. - **Already a member?** — Handled gracefully. The user is redirected to the workspace with a message that they're already a member. > **Info:** Accepting a workspace invite bypasses the waitlist — an invite from an Owner or Admin explicitly approves the invitee's access. ### Workspace Settings Access Workspace Settings by clicking the **Manage Workspace** button in the workspace switcher at the bottom of the sidebar. The settings page is organized into three sections: | Section | What You Can Do | |---------|----------------| | **General** | Rename the workspace (Owners and Admins only). | | **Members** | View all members with avatars, names, emails, roles, and join dates. Change roles via dropdown. Remove members. Invite new members. See and manage pending invites. | | **Danger Zone** | Delete the workspace permanently (Owner only). Requires typing the workspace name to confirm. This action is irreversible. | **Role management rules:** - **Owners** can change anyone's role to Admin or Member - **Admins** can change roles to Member only (cannot promote to Admin) - You cannot change the Owner's role or remove the Owner - You cannot change your own role or remove yourself ## Teams A **Team** groups related agents, skills, and data together. Think of teams as departments or workflows: - A "Marketing" team with content, SEO, and social media agents - A "Sales" team with prospecting, outreach, and CRM agents - A "DevOps" team with monitoring, deployment, and incident response agents - A "Personal" team with your daily assistant, research agent, and email triager ### Creating a Team 1. Click **New Team** on the home dashboard (or use the team switcher → **Create New**) 2. Enter a name and optional description 3. Click **Create** — you'll be taken to the team dashboard ### What a Team Contains - **Agents** — Your AI teammates, each with their own computer and capabilities - **Skill Catalog** — Reusable skills shared across all agents in the team - **Team Dashboard** — Analytics, activity feed, and agent status overview - **Settings** — Team-level configuration, notifications, API keys, and danger zone ### Switching Teams There are two fast ways to switch between teams: **From the breadcrumbs (fastest):** 1. Click the **team name** in the breadcrumb bar at the top of the page 2. A dropdown appears with search, your team list, and quick actions 3. Click a team to switch, or use **View All** to go to the home dashboard, or **Create New** to start a fresh team **From the home dashboard:** 1. Click the **Communa logo** in the top-left corner (always takes you home) 2. You'll see all your teams as cards with mini-dashboards showing agent count, recent runs, and status 3. Click any team card to enter it ## Navigation ### The Sidebar The sidebar is your primary navigation within a team: | Item | Description | |------|------------| | **Dashboard** | Team-level analytics, charts, activity feed, and top agents | | **Agents** | List of all agents in the team — create, manage, and access agent detail pages | | **Skills** | The team's skill catalog — browse, create, edit, and manage reusable skills | | **Billing** | Workspace-level billing (global — same page regardless of which team you're in) | Below the main navigation, you'll see a **live agent list** showing every agent in the current team. Each agent displays real-time status: - 🟢 **Green pulse** — Agent is currently running - 🟣 **Purple dot** — Agent has unread emails or pending queue items (needs attention) - 🔵 **Accent dot** — Agent's computer is awake (ready but not actively running) - **Schedule indicator** — Shows the interval (e.g., "15m") if a schedule is active - **Email counter** — Number of unread emails - **Queue counter** — Number of pending queue items Click any agent in the list to jump directly to its detail page. The sidebar can be **collapsed** using the chevron button at the bottom, showing only icons for a compact view. ### The Top Bar The top bar contains: - **Communa logo** — Click to go to the home dashboard (all teams view) - **Breadcrumbs** — Dynamic navigation path showing Team → Section → Detail, with a team switcher dropdown built into the team name - **Profile menu** — Your email, credit balance with color-coded status indicator, dark/light mode toggle, and sign out The credit balance in the profile menu changes color based on your remaining credits: - **Normal** — Healthy balance, no indicator - **Amber dot** — Low balance warning — time to top up - **Red pulsing dot** — Critical balance (near zero) — agent runs may be affected Clicking the credits item takes you directly to the billing page. ## Dashboards Communa has two dashboard levels that give you visibility at different scopes: ### Home Dashboard (All Teams) Accessed by clicking the **Communa logo** or navigating to `/dashboard`. Shows: - **All your teams** as cards, each displaying: - Team name and description - Number of agents - Recent run activity as a sparkline chart - Quick status indicators - **Overview stats** — Total agents and teams across your workspace - **New Team** button in the header If you have no teams yet, a prominent **"Launch Your First Agent"** empty state guides you through creating your first team and agent. ### Team Dashboard Accessed by clicking **Dashboard** in the sidebar (or clicking a team card from home). Shows: - **Stat cards** — Total agents, agents currently running, run statistics, and credit usage - **Charts** — Daily spend, run distribution, and model usage over the last 30 days - **Activity feed** — Recent runs and emails across all agents, with timestamps and status - **Top agents** — Most active agents ranked by usage, with quick-access links - **Agent filter** — Dropdown to filter the entire dashboard to a single agent's data (appears when you have multiple agents) The team dashboard gives you a command-center view of everything happening in your team at a glance. ## Settings The **Settings** page (accessible from the team sidebar or profile menu) is organized into sections: | Section | What You Can Configure | |---------|----------------------| | **Team Settings** | Team name, description, and general configuration | | **Notifications** | Email notifications for agent events, errors, and completions | | **Account** | Your account details and preferences | | **API Keys** | Generate and manage API keys for programmatic access | | **Preferences** | UI preferences like default views and behavior | | **Danger Zone** | Destructive actions — delete the team (requires confirmation) | ## Billing Billing is managed at the **workspace level** — meaning the subscription plan and credit balance apply to all teams and agents within a workspace. Access it from the **Billing** link in the sidebar (it's the same page regardless of which team you're in). ### Subscription Status At the top of the billing page, you'll see your current plan with: - **Plan name** and billing interval (monthly or annual) - **Status badge** — Active, Trial, Canceling, or Past Due - **Renewal date** — When your next billing cycle occurs - **Manage button** — Opens the Stripe billing portal for payment method updates, invoice history, and receipts Status-specific alerts appear automatically: - **Past Due** — "Payment failed — please update your payment method to avoid service interruption" - **Canceling** — Shows the exact date your plan will downgrade to Free, with option to resubscribe before then ### Plans Plans are displayed as a side-by-side comparison with a **monthly/annual toggle** at the top (annual plans typically offer savings). Each plan card shows: - Plan name and description - Price (monthly or annual per-month rate) - Feature list with checkmarks and informational tooltips - Action button: **Upgrade**, **Downgrade**, **Current Plan**, or **Switch Billing** **Upgrading:** Click a higher plan's button to see a **proration preview dialog** showing: - Credit for unused time on your current plan - Charge for the new plan (prorated to your billing cycle) - Net total charged today - New recurring rate going forward This ensures you never overpay — you always get credit for what you've already paid. **Downgrading:** Same proration preview flow. Any unused credit from your current plan is applied to the lower plan's cost. **Switching billing interval:** If you switch from monthly to annual (or vice versa) on the same plan tier, you'll see a proration breakdown showing the adjustment. **Canceling:** Clicking "Downgrade" to the Free plan opens the Stripe billing portal where you can cancel. Cancellation takes effect at the end of your current billing period — you keep full access until then. ### Credits Below the plans section, a **credit top-up card** lets you purchase additional credits: - **Current credit balance** displayed prominently - **Slider** to select a credit package — drag to choose your amount - **Package labels** showing available options with credit amounts and prices - **Purchase button** — Opens Stripe Checkout for a one-time credit purchase Credits are consumed by agent runs (AI model tokens, computer compute time, etc.). They supplement your plan's included allowance and never expire. > **Info:** Need more concurrent agents or custom pricing? A "Contact us" link below the plan cards connects you with our team for enterprise and custom arrangements. ### Billing Portal For paid plans, the **Manage Subscription** button opens the Stripe billing portal where you can: - Update your payment method (credit card, etc.) - View and download invoices - Review payment history and receipts - Cancel your subscription The portal is hosted by Stripe — fully secure and PCI-compliant. Your payment details are never stored on Communa's servers. --- # People & Permissions > Source: https://communa.io/docs/platform/people-permissions How Communa handles the people who interact with your agents — workspace teammates, external contacts, and the trust levels in between. > **Tip:** Your agent can answer questions about who has access. Ask it — *"Who's in this workspace?"*, *"What can a Member do?"*, *"Show me what this agent knows about Sarah"* — and it will walk you through it. ## Overview People interact with Communa in two different ways, and it helps to keep them separate in your mind: - **Workspace roles** — Who can do what in your Communa dashboard (Owner, Admin, Member). These are enforced rules. - **Per-agent people** — Who your agent talks to and how it treats them. The agent maintains memory about each person, and you can give it personalized instructions for each one. > **Info:** Workspace roles are strictly enforced by Communa. The way your agent treats different senders is shaped by instructions you can customize — think of it as steering the agent's judgment, not building a wall. We cover both below and where each one applies. ## Workspace Roles Every workspace has three roles. Each one has its own permissions: | Role | What They Can Do | |------|------------------| | **Owner** | Everything. Manages members, billing, and the workspace itself. Each workspace has exactly one Owner — the person who created it. | | **Admin** | Manages teams, agents, skills, and invites Members. Cannot manage billing or delete the workspace. | | **Member** | Creates and works with teams and agents. Cannot invite people or manage other members. | Roles are hierarchical — higher roles include everything the lower roles can do, plus more. ### Owner-Only Actions A few actions are reserved for the Owner alone: - **Billing** — Plans, payment methods, credit top-ups, subscription changes - **Workspace deletion** — Permanently removing the workspace - **Promoting Admins** — Only the Owner can grant the Admin role If you're an Admin or Member, you'll see the Billing page redirect with a friendly message, and Owner-only buttons will be hidden in your view. Ask your Owner to handle these actions. > **Info:** For the full list of what each role can do across the platform, see **[Platform Overview](/docs/platform/overview)**. ## Inviting Teammates Owners and Admins can invite people to a workspace: 1. Open **Workspace Settings** from the workspace switcher at the bottom of the sidebar 2. Scroll to **Members** and click **Invite** 3. Enter the person's email and pick a role 4. Click **Send Invite** Invites are sent by email and **expire after 72 hours**. You can resend or revoke pending invites from the Members table at any time. **A few rules to know:** - Admins can only invite Members — promoting to Admin is Owner-only - You can't have two pending invites for the same email — revoke the old one first - Accepting an invite is automatic if the person is already logged in; otherwise it completes after they sign in ## Two-Factor Authentication (2FA) Workspace Owners can require 2FA for everyone in the workspace. When enabled: - All existing members get a **grace period** (shown in days) to set up 2FA - New invites must set up 2FA before getting full dashboard access - The setting lives in **Workspace Settings → Security** > **Info:** 2FA secures access to your **Communa dashboard**. It's a strong protection for the people in your workspace logging in to Communa itself. It doesn't change how your agent behaves when it talks to people on Telegram, WhatsApp, or other channels — those interactions are shaped by the trust tiers covered below. ## Per-Agent People Separate from workspace roles, each agent keeps track of the people it talks to. You'll find this under the **People** tab on any agent's detail page. People are split into two groups: | Group | Who They Are | |-------|--------------| | **Internal** | Your workspace teammates — anyone with a workspace role (Owner, Admin, or Member) | | **External** | Anyone messaging your agent through Telegram, WhatsApp, Voice, or Email who is **not** a workspace member | For each person, the agent maintains two pieces of information: - **Memory** — What the agent has learned about them through conversations. The agent updates this on its own as it interacts with them. - **Instructions** — Personalized notes from you, the Owner, about how the agent should treat this specific person. Only you can see and edit these. ### Working with People A few useful actions on the People tab: - **Add manually** — Add someone before they first message your agent (e.g., give the agent context about a new customer before introducing them) - **Edit memory** — Correct or refine what the agent remembers about a person - **Add instructions** — Tell the agent how to handle this person specifically (*"Sarah prefers concise replies"*, *"This is a VIP — be extra accommodating"*) - **Merge** — Combine two records that turn out to be the same person across different channels (same human messaging on both WhatsApp and Telegram) > **Tip:** Per-person instructions are powerful for exceptions. Use them when one person needs different treatment than your general tier-level instructions would provide. ## Trust Tiers — How the Agent Treats Different Senders When someone messages your agent, the agent knows which tier they belong to and adjusts its behavior accordingly. There are four tiers: | Tier | Who They Are | |------|--------------| | **Owner** | You — the workspace creator with full authority | | **Admin** | Your trusted teammates with broad permissions | | **Member** | Your regular workspace teammates | | **External** | Anyone messaging via Telegram, WhatsApp, Voice, or Email who isn't part of your workspace | For each tier, the agent has a default style — cooperative and broad for Owners, helpful but careful for Members, careful and scoped for External senders. You can customize this in **Agent Settings → Roles & Permissions**. ### Customizing the Tier Prompts In Roles & Permissions, each tier shows two things: 1. **Can / Cannot** — The hard rules Communa enforces for this tier. You can't change these; they're the system's job. 2. **The prompt** — The text the agent reads about how to treat this sender. This is fully customizable. For example, the default External prompt tells your agent to be careful with private information and stay within the scope you've defined. You can rewrite it to be friendlier, stricter, more specific to your use case, or anything in between. > **Tip:** Start with the defaults — they cover most situations well. Customize a tier when you have a specific behavior you want, like *"For External senders, always offer to escalate to a human if they sound frustrated."* ## What Communa Enforces vs. What's Guided This is important to understand clearly: **Communa strictly enforces:** - Workspace role permissions (who can do what in the dashboard) - Owner-only actions (billing, workspace deletion, promoting Admins) - **Agent settings & skills changes** — when a **Member** or an **External/Email** sender asks the agent to change its settings or create/edit/delete skills, the tool call is **blocked server-side** and returns a permission error. The agent reads this as guidance too, so it declines politely instead of trying and failing. - Outbound email whitelist (your agent can only send to email addresses you've approved) - Credential isolation — your agent can only *use* a stored credential at runtime; it never sees the raw value and has **no tool to create, read, or edit** credentials. Credential management lives in the dashboard and is gated by workspace role. **The trust-tier prompts guide your agent's behavior**, but they're not a hard wall. They're instructions, and like any instructions given to an AI, the agent can occasionally interpret them loosely. They're a strong influence, not a perfect filter. ### What This Means in Practice A few habits that help you stay in good shape: - **Don't store secrets in instructions or per-person notes.** Use Credentials for anything sensitive — that's the system that's actually built to hide them. - **Be intentional about what you ask external senders to share.** If something is sensitive, don't rely on a prompt to stop the agent from acting on it. - **Use the Mail whitelist for hard limits on outbound email.** It's enforced strictly, unlike prompt text. - **Review the Change Log periodically.** It shows what your agent has done across all senders — a great way to spot anything unexpected early. ## Best Practices - **Keep the Owner tier loose** — You're the most trusted sender; let your agent be fully helpful with you - **Be more specific for External** — The External tier is where it pays to be explicit about scope (*"Help with order status and returns only; for anything else, ask them to contact support"*) - **Use per-person instructions for exceptions** — A single VIP customer or a difficult contact doesn't require rewriting your whole External tier - **Don't lean on prompts for safety-critical decisions** — Use Credentials, the email whitelist, and your own review for anything that really matters - **Revisit periodically** — As your agent's role evolves, the trust-tier prompts should evolve with it ## What's Next? - **[Platform Overview](/docs/platform/overview)** — Workspace, team, and billing structure - **[Credentials](/docs/agents/credentials)** — Where to store secrets so your agent can use them without seeing them - **[Mail](/docs/agents/mail)** — How the outbound email whitelist gives you hard control over who your agent emails - **[Change Log](/docs/agents/changes)** — Review what your agent has done and revert anything you didn't expect --- # Agent Overview > Source: https://communa.io/docs/agents/overview Understand what agents are, how to create them, and how the agent detail page is organized. > **Tip:** Your agent already knows all of this. Just ask it — *"What tabs do you have?"*, *"What's your status?"*, or *"Walk me through your capabilities."* ## What Is an Agent? An agent is an autonomous AI teammate that runs in its own isolated environment — a real Linux desktop with a browser, terminal, file system, and network access. Each agent has its own identity, skills, credentials, email address, and task queue. Agents aren't chatbots that answer questions. They *do things*: browse the web, fill forms, write and run code, process files, send emails, extract data — anything a skilled human can do at a computer. ## Creating an Agent 1. Navigate to **Agents** in your team sidebar 2. Click **New Agent** in the top-right corner 3. Enter a name and optional description 4. Click **Create** You'll be taken to the agent detail page — the command center for everything related to this agent. ## The Agent Detail Page The agent detail page is organized into tabs, each covering a different aspect of the agent's capabilities: | Tab | What It Does | |-----|-------------| | **Agent** | Primary workspace — chat with your agent and watch it work on the live computer preview | | **Context** | Attach skills, write custom instructions, and configure which tools the agent can use | | **Mail** | View received and sent emails, configure email settings and whitelisted addresses | | **Channels** | Connect external messaging platforms (Telegram) so you can chat with your agent outside the dashboard | | **Files** | Upload and manage files — both persistent storage and live files on the computer | | **Datasets** | View, edit, filter, and export structured data tables the agent has created | | **Credentials** | Store encrypted secrets (passwords, API keys, tokens) the agent can use without seeing | | **Integrations** | Connect Google Workspace and custom MCP servers (GitHub, Linear, …) so your agent can call external tools | | **Queue** | Manage the agent's task queue — add items, reorder, and configure processing | | **Schedule** | Create time-based triggers that run the agent with a specific prompt on a schedule | | **Runs** | View execution history, token usage, costs, and run details | | **Settings** | Centralized configuration — identity, computer persistence, working hours, chat, actions, queue, mail, and danger zone (accessed via the Settings button in the header) | ## Agent Lifecycle Agents move through distinct states: ``` Created → Onboarding → Sleeping ⇄ Awake → Running → Sleeping ``` ### Onboarding When you first create an agent, it starts in **onboarding mode**. The agent introduces itself and walks you through setup conversationally — asking about its purpose, communication style, schedule, and email preferences. During onboarding, only the `settings_manager` and `send_email` tools are available. You can skip onboarding at any time by saying *"skip"* or *"let's go"*. ### Sleeping The agent's computer is shut down. No compute resources are used. The agent can still receive emails (which are queued), **respond to Telegram messages (which auto-wake the computer)**, and you can configure its settings. Scheduled runs will automatically wake the agent when triggered. ### Paused (Persistent Mode) When **Persistent Computer** is enabled in Settings, sleeping the agent **pauses** the computer instead of destroying it. All files, processes, and memory are frozen in place. Resuming takes ~1 second — no fresh provisioning needed. A paused computer doesn't use compute resources. > **Tip:** Persistent computer is the default for all new agents. For stateless agents that prefer a clean environment each session, you can switch to on-demand mode in **Settings → Computer**. ### Awake The computer is running. You can see the live desktop preview and chat with the agent. The agent can interact with its desktop, browse the web, run terminal commands, and use all its tools. ### Running The agent is actively executing a task — either from a chat message, a queue item, or a scheduled run. You can watch it work in real time on the desktop preview. ## AI Model Selection Each agent is powered by a language model that you can choose and change at any time. Click the **model selector** in the chat input area to switch between available models: - **Claude** (Anthropic) — Excellent at computer use, reasoning, and following complex instructions - **GPT** (OpenAI) — Strong general-purpose capabilities - **Other models** — Additional models as they become available Different models have different strengths, token costs, and speed profiles. The model selector shows cost indicators to help you choose. ## What's Next? - **[Chat & Computer](/docs/agents/chat-sandbox)** — Learn how to interact with your agent and use the live desktop preview - **[Channels](/docs/agents/channels)** — Connect Telegram for external messaging - **[Context & Configuration](/docs/agents/context)** — Set up skills, instructions, and tools - **[Schedule](/docs/agents/schedule)** — Create time-based triggers for automated agent runs - **[Runs & Scheduling](/docs/agents/runs)** — Track execution history and configure queue processing --- # Chat & Computer > Source: https://communa.io/docs/agents/chat-sandbox Learn how to interact with your agent through the chat interface and monitor its work on the live computer preview. > **Tip:** Your agent knows how its own interface works. Ask it — *"How do I use the computer?"*, *"What keyboard shortcuts are there?"*, or *"Show me what you see on screen."* > **Note on terminology:** Throughout the docs we use **computer** to mean the agent's isolated Linux desktop environment. The underlying technology is sometimes called a *sandbox* — they refer to the same thing. ## Overview The **Agent** tab is the primary workspace — where you talk to your agent and watch it work. It features a split-panel layout with the chat on one side and a live desktop preview on the other. This is where the magic happens: you type a message, and the agent takes action on a real computer in real time. ## The Split-Panel Layout The Agent tab shows a **side-by-side layout** with the chat interface on the left and the live desktop preview on the right. You can **resize the panels** by dragging the divider between them to find the balance that works for you. ### Collapsing the Desktop Preview If you prefer a full-width chat experience, you can **hide the desktop preview entirely**: - **Drag the divider** all the way to the right to collapse the preview panel - **Keyboard shortcut** — Press **⌘ \\** (Mac) or **Ctrl \\** (Windows) to toggle the preview on/off - **Click the handle arrow** on the divider to expand/collapse Your preference is **remembered between sessions** — if you collapse the preview, it stays collapsed next time you visit the agent. This is useful when you want to focus on the conversation without the visual distraction of the live desktop, or when you're working on a smaller screen. ## The Chat Interface Type your message in the input area at the bottom and press **Enter** to send. You can ask the agent to do anything a human could do at a computer: - *"Go to Google and search for the latest AI news"* - *"Write a Python script that analyzes this CSV file"* - *"Log into our CRM and export last month's leads"* - *"Install ffmpeg and convert that video to MP4"* The chat displays your messages, agent responses, tool calls (actions the agent is performing), screenshots of the agent's screen, and web search citations. ### Keyboard Shortcuts | Shortcut | Action | |----------|--------| | **Enter** | Send message | | **Shift + Enter** | New line (without sending) | | **⌘ \\** (or **Ctrl \\**) | Toggle computer preview panel | ## Multiple Conversations (Tabs) You can have **several separate conversations** with the same agent at once — like tabs in a browser. Each tab keeps its own history, so you can juggle different topics without mixing them up. Tabs appear in a row above the chat input. The active tab is highlighted, and you can switch between them at any time. ### Starting a New Conversation Click the **+** button at the end of the tab row to open a fresh conversation. The agent starts with a clean slate — no memory of what you discussed in other tabs. This is perfect when you want to change topics without losing your previous thread, or when you're working on two unrelated tasks in parallel. ### Switching Between Conversations Just **click any tab** to switch to it. Your place in each conversation is preserved — scroll position, draft message, everything. The agent remembers the full context of whichever conversation you're in. ### Closing a Conversation Click the **×** on a tab to close it. The conversation isn't deleted — it's **archived**, so you can always bring it back later. ### Restoring an Archived Conversation Open the **archive drawer** (from the tab bar menu) to see all your past conversations. Click any one to restore it — the tab reappears instantly and becomes active, right where you left off. > **Tip:** Use separate tabs for separate topics. Your agent keeps the context of each conversation fully independent, so it won't get confused between a research task in one tab and a coding task in another. ### The Streaming Indicator When a conversation is generating a reply, you'll see a **subtle animated line** sweep across the bottom of its tab. This lets you know which conversation is working — even if you've switched to a different tab in the meantime. You can safely switch away while the agent is thinking; when you come back, the full response will be waiting for you. ## The Computer Preview The computer preview shows a **live stream** of the agent's desktop — a real Linux environment with a window manager, browser, terminal, and applications. You'll see the agent's mouse cursor moving, windows opening, browser tabs loading, and terminal commands executing in real time. When waking an agent, you choose the **screen resolution** for the computer. Higher resolutions provide more screen real estate for the agent to work with but use more bandwidth for the live preview. ## Waking and Sleeping ### Wake Agent Click the **Wake Agent** button to start the computer. The process takes a few seconds — the computer is provisioned in the cloud, the Linux desktop boots up, and the live preview connects. ### Sleep Agent Click **Sleep** to shut down the computer. A confirmation dialog appears because session files that haven't been synced to persistent storage will be lost, and any active processes will stop. > **Warning:** Always sync important files to persistent storage before sleeping an agent. The Files tab shows which files are synced and which are session-only. ### Computer Persistence (Persistent by Default) By default, sleeping **pauses** the computer — all state is frozen and preserved: - **Sleep becomes Pause** — The confirmation dialog reassures you that all state is preserved instead of warning about data loss - **Everything is frozen** — Files, processes, browser sessions (including website logins and cookies), installed packages, and memory are all preserved - **Resume in ~1 second** — Click "Resume Agent" to reconnect to the frozen computer instantly, instead of starting a fresh one - **No compute costs while paused** — The computer doesn't use resources in its paused state This means agents that maintain browser sessions (logged-in websites, open tabs), have heavy package installations, or run background services keep everything intact across pauses. Instead of spending the first few minutes of every session logging in and reinstalling tools, the agent picks up exactly where it left off. If you prefer a fresh environment each time, you can switch to **On-Demand mode** in **Settings → Computer**. In on-demand mode, sleeping destroys the computer entirely and a new one is started on the next wake. > **Info:** Computer persistence mode is configured per-agent in **Settings → Computer**. See [Agent Settings](/docs/agents/settings#sandbox) for details. ## Onboarding Flow New agents start with an **onboarding conversation**. The agent introduces itself and walks you through setup conversationally — asking about its purpose, communication style, schedule, and email preferences. It configures each setting as you discuss it using `settings_manager`, and sends a summary email when complete. During onboarding, only `settings_manager` and `send_email` are available. This ensures the agent focuses on setup before taking action. > **Info:** Skip onboarding any time by saying *"skip"* or *"done"*. All tools unlock immediately. ## The Action Queue While the agent is working, you'll see its actions in the chat as expandable tool-call blocks. These show exactly what the agent is doing — screen interactions, terminal commands, web searches, and data extraction. Each action block is collapsible so you can focus on the results without the noise. Actions can be **saved, recorded, and replayed** as deterministic sequences. For full details on building and managing action sequences, see **[Actions & Sequences](/docs/agents/actions)**. ## Beyond the Dashboard The dashboard chat isn't the only way to interact with your agent. You can connect external messaging platforms via the **[Channels](/docs/agents/channels)** tab — starting with Telegram. When connected, you send messages directly in Telegram and receive responses from your agent in real time. Your agent works the same way as in the dashboard — same tools, skills, and context. If the agent is sleeping, a Telegram message **automatically wakes it up** — no need to visit the dashboard first. This is useful for mobile-first workflows, quick interactions on the go, or any situation where opening the dashboard isn't practical. ## Tips & Best Practices - **Be specific** — Instead of *"research companies"*, say *"Go to Crunchbase, find the top 5 AI startups founded in 2025, and save them as a dataset"* - **Use the live preview** — Watch the agent work to catch issues early and give real-time corrections - **Collapse when chatting** — Hide the preview for a clean, focused chat experience; expand it when you need to see the agent's screen - **Let the agent install tools** — If it needs ffmpeg, Python packages, or browser extensions, it will install them automatically - **Don't micromanage** — Give the goal, not every step. The agent figures out the best approach ## What's Next? - **[Actions & Sequences](/docs/agents/actions)** — Record, build, and replay deterministic action sequences - **[Channels](/docs/agents/channels)** — Connect Telegram so you can chat with your agent from external platforms - **[Context & Configuration](/docs/agents/context)** — Configure skills, instructions, and tools to shape your agent's behavior - **[Files](/docs/agents/files)** — Understand session files vs. persistent storage - **[Credentials](/docs/agents/credentials)** — Securely store passwords and API keys --- # Actions & Sequences > Source: https://communa.io/docs/agents/actions Record, build, and replay deterministic action sequences — saved actions your agent can perform exactly as you defined them. > **Tip:** Actions are your automation building blocks. Record once, replay forever — perfect for deterministic workflows where you need the agent to follow exact steps. ## Overview The **Actions** tab lets you build, save, and replay sequences of actions — clicks, keystrokes, bash commands, AI messages, and more. Unlike chat-based interactions where the AI decides what to do, saved actions are **deterministic**: they execute exactly as you defined them, every time. This makes actions ideal for: - **Repeatable workflows** — Login sequences, form submissions, data entry routines - **Multi-step automations** — Navigate to a page, extract data, process results - **Consistency** — Ensure the same steps run the same way across multiple runs - **Data-driven processing** — Run the same sequence across many rows of captured data ## The Actions Tab The Actions tab sits alongside the Chat, Queue, and other tabs on your agent page. It shows: - **Toolbar** — Add New button, Record toggle, filter dropdown, Play All with delay controls - **Action List** — A drag-and-drop list of all saved actions - **Bulk Operations Bar** — Appears when you select multiple actions ## How Actions Get Saved Actions can be saved to your sequence in two ways, controlled by the **Auto-Save** setting in Action Settings: ### Auto-Save Disabled (Default) When auto-save is off, AI actions appear in the chat as tool-call blocks with an **"Add" button**. You manually choose which actions to save to your sequence. This gives you selective control — keep only the actions you need and skip the rest. New agents start here so you can curate a clean sequence intentionally. ### Auto-Save Enabled When auto-save is on, every action the AI performs during a chat session is **automatically saved** to your action history. As the agent clicks, types, runs commands, and navigates — each action appears in the Actions tab in real time. This is great for building sequences organically: tell the agent what to do via chat, and the actions are captured automatically. Turn this on in Action Settings when you're ready. ## Recording Actions Manually Beyond capturing AI actions, you can **record actions directly** by interacting with the live computer preview. ### How to Record 1. Open the Actions tab 2. Click the **Record** button (next to "Add New") — it requires a running computer 3. The button turns red and shows a pulsing **REC** indicator 4. Click, scroll, and type on the live computer preview — each interaction is captured as an action 5. Click **REC** again to stop recording ### What Gets Captured | Interaction | Captured As | |-------------|-------------| | Single click | `left_click` at coordinates | | Double click | `double_click` at coordinates | | Triple click | `triple_click` at coordinates | | Right click | `right_click` at coordinates | | Middle click | `middle_click` at coordinates | | Scroll up/down | `scroll` with direction and amount (rapid scrolls are batched) | | Typing | `type` with the text (characters are buffered into a single action) | | Enter key | `key` press or appended to typed text | > **Info:** The recorder automatically detects click types — you don't need to tell it you're double-clicking. It waits 300ms after a click to determine if it's a single, double, or triple click before recording. ## The Action Editor Click **Add New** to open the Action Editor, or click any existing action to edit it. The editor provides a full-featured interface for creating and configuring actions. ### Action Categories The editor organizes actions into four categories: #### Mouse Actions | Action | Description | |--------|-------------| | **Left Click** | Click at specific coordinates | | **Right Click** | Right-click at coordinates | | **Double Click** | Double-click at coordinates | | **Triple Click** | Triple-click (select entire line/paragraph) | | **Middle Click** | Middle mouse button click | | **Drag** | Click and drag from start to end coordinates | | **Move Mouse** | Move cursor to coordinates without clicking | #### Input Actions | Action | Description | |--------|-------------| | **Type Text** | Type a string of text (supports `{{field}}` placeholders) | | **Press Key** | Press a single key (Enter, Tab, Escape, etc.) | | **Hold Key** | Hold a key for a specified duration (Shift, Ctrl, Alt) | #### Navigation Actions | Action | Description | |--------|-------------| | **Scroll** | Scroll in any direction (up, down, left, right) with configurable amount | | **Wait** | Pause for a specified duration (useful between actions) | | **Screenshot** | Capture a screenshot of the current screen | #### Advanced Actions | Action | Description | |--------|-------------| | **AI Message** | Send a message to the AI agent (with optional "wait for completion") | | **Bash Command** | Execute a terminal command (or restart the bash session) | | **Data Capture** | Extract structured data from the screen, clipboard, or a file | | **Use Credential** | Securely enter a stored credential value (type or paste) | ### Custom Titles and Notes Every action supports: - **Custom Title** — A descriptive name (e.g., "Click Login Button", "Enter Search Query"). This replaces the auto-generated label in the action list. - **Note** — Additional context (e.g., "Use the test account credentials", "Wait for page to load first"). ### Placeholder Syntax For **Type Text** and **AI Message** actions, you can use placeholder syntax to inject data from captured datasets: - `{{field_name}}` — Replaced with the field value from the current data row - `{{field_name | default_value}}` — Uses the default if the field is empty This powers data-driven playback, where the same action sequence runs across many rows of data. ## Replaying Actions The Actions tab provides several ways to replay your saved actions: ### Play Single Action Click the **Play** button (▶) on any action card to execute just that one action immediately on the computer. ### Play All Actions Click **Play All Actions** at the top of the Actions tab to execute the entire sequence from start to finish. The agent runs each action in order with a configurable delay between them. ### Play From Here Open the play dropdown (▶ ▾) on any action card and select **Play from here**. This starts playback from that specific action and continues through the rest of the sequence. ### Play Selected When you have actions selected (via checkboxes), a **Play** button appears in the bulk operations bar. This runs only the selected actions in their original order. ### Auto-Play Delay Use the delay dropdown next to the Play All button to configure the wait time between actions: | Delay | Best For | |-------|---------| | **0s** | Fast execution, no visual feedback needed | | **1-2s** | Watching the agent work, light debugging | | **3-5s** | Step-by-step observation, demos | ### Playback Progress During playback, a progress indicator appears showing: - **Standard playback**: "Playing action 3 of 12" - **Data-driven playback**: "Row 2 of 10 • Action 3 of 5" Click **Stop** at any time to halt playback immediately. ## Data-Driven Playback When your agent has captured structured data (via the Data Capture action), you can run your action sequence **across every row** of that data. ### How It Works 1. Build an action sequence that uses `{{field}}` placeholders (e.g., type `{{company_name}}` into a search box) 2. Ensure you have captured data with matching field names 3. Click **Play All** — the system detects placeholders and offers data-driven mode 4. Each row in your dataset runs the full sequence independently 5. Placeholders are substituted with the actual values from each row This is powerful for tasks like: *"For each company in my list, search for it on LinkedIn, capture the company page, and save the results."* ## Organizing Actions ### Drag-and-Drop Reorder Grab the **grip handle** (⠿) on any action card and drag it to a new position. The sequence order updates immediately and persists to the database. ### Duplicate Actions Hover over an action and click the **duplicate** icon (⧉) to create a copy. Useful for repeating similar steps with slight modifications. ### Delete Actions Hover over an action and click the **trash** icon. Click again to confirm. Deletions are permanent. ### Filter by Type Use the filter dropdown in the toolbar to show only specific action types: - **All** — Show everything - **Bash** — Only bash commands - **Click types** — left_click, double_click, etc. - **Type** — Only text input actions - Any other action type present in your sequence ## Bulk Operations ### Selecting Actions - **Hover** over an action to reveal its checkbox - **Click the checkbox** to select/deselect - **Shift+Click** to select a range (from last selected to current) - **Select All** toggle in the bulk bar selects all visible (filtered) actions ### Bulk Actions When one or more actions are selected, a bulk operations bar appears at the bottom: | Action | Description | |--------|-------------| | **Play (N)** | Play only the selected actions in order | | **Delete** | Delete all selected actions (with confirmation dialog) | | **Clear** | Deselect all | ## Action Settings Open the **Settings** page (click the Settings button in the agent header) and navigate to the **Actions** section to configure: ### Auto-Save Actions Toggle whether AI actions are automatically saved to your action history. When disabled, actions appear in chat with an "Add" button for manual selection. ### Clear Action History Permanently delete all saved actions from this agent. This shows a confirmation dialog with warnings — cleared actions cannot be recovered. ## Tips & Best Practices - **Start with auto-save on** — Let the AI build your initial sequence, then refine by editing, reordering, and removing actions - **Use custom titles** — Name your actions descriptively so the sequence reads like a script: "Navigate to Login", "Enter Username", "Click Submit" - **Add Wait actions** — Insert waits between actions that trigger page loads or animations - **Test incrementally** — Use "Play from here" to test specific parts of your sequence without running everything - **Use AI Message actions** — For steps that need intelligence (like "find the right button" or "summarize this page"), use an AI Message action instead of hardcoded clicks - **Combine recording and editing** — Record a rough sequence by clicking through the computer, then refine coordinates and add advanced actions in the editor - **Keep sequences focused** — Build multiple short sequences rather than one massive one. You can run them separately or combine later ## What's Next? - **[Chat & Computer](/docs/agents/chat-sandbox)** — Learn about the chat interface and live desktop preview - **[Datasets](/docs/agents/datasets)** — Understand captured data that powers data-driven playback - **[Runs & Scheduling](/docs/agents/runs)** — Schedule your action sequences to run automatically - **[Credentials](/docs/agents/credentials)** — Store credentials securely for Use Credential actions --- # Context & Configuration > Source: https://communa.io/docs/agents/context Configure your agent's behavior with custom instructions, skills, and tool settings. > **Tip:** Your agent can configure itself. Just say *"Update your instructions to always respond in bullet points"* or *"Disable the web search tool"* and it will use `settings_manager` to make the change. ## Overview The **Context** tab is where you shape your agent's behavior. It has three main areas: 1. **Custom Instructions** — Free-form text that acts as the agent's system prompt 2. **Skills** — Reusable instruction sets that teach the agent specific workflows 3. **Tools Panel** — Toggle individual capabilities on or off Together, these define the agent's **context window** — the information and capabilities available to it during every interaction. ## Custom Instructions Custom instructions are free-form text that shapes the agent's persona, behavior, and approach. Think of them as a job description plus operating guidelines. ### Writing Instructions Click the **Custom Instructions** section in the Context tab to expand the editor. Write in plain language: ``` You are a senior data analyst. When given a research task: 1. Always start by searching for the most recent data 2. Cross-reference at least 3 sources 3. Present findings in a table format 4. Include source URLs for every claim 5. Flag any conflicting information Communication style: concise, professional, data-driven. Never make assumptions — ask clarifying questions when needed. ``` ### Tips for Good Instructions - **Be specific** — *"Respond in 3 bullet points"* is better than *"Be concise"* - **Include examples** — Show the agent what good output looks like - **Define boundaries** — Tell the agent what it should NOT do - **Set priorities** — If instructions conflict with a skill, which wins? Instructions are saved automatically when you leave the field. ## Skills Skills are structured instruction sets — following the [Open Skills Standard](https://agentskills.io) — that teach an agent how to perform specific tasks. They're the backbone of reliable, repeatable agent behavior. ### Attached Skills The Context tab shows all skills currently attached to the agent. Skills higher in the list get priority in the context window. If a catalog skill has been updated since it was attached, an "Update Available" indicator appears. ### Attaching a Skill 1. Click **Add Skill** at the top of the skills section 2. The **Skill Selector** opens with: - A **category sidebar** — Analytics, Communication, Creative, Engineering, and more - A **search bar** — Find skills by name or description - **Skill cards** showing name, description, and category 3. Click a skill to attach it to the agent Each agent gets an **independent copy** of the skill. Changes to the catalog version don't automatically propagate — the agent sees an "Update Available" badge and can pull changes when ready. ### Reordering Skills **Drag and drop** skills to change their priority order. Skills higher in the list are injected earlier in the context window, giving them higher priority when instructions overlap. ### Skill Actions Each attached skill has several actions: | Action | What It Does | |--------|-------------| | **Update** | Pull the latest version from the catalog (when an update is available) | | **Push to Catalog** | Publish local changes back to the team's skill catalog | | **Sync from Files** | Detect `SKILL.md` files the agent created on its computer and import them | | **Detach** | Remove the skill from the agent (the catalog version is unaffected) | ### The Skill Lifecycle Skills flow between agents and the catalog: ``` Catalog Skill → Attach to Agent (Copy) → Agent Modifies Locally → Push to Catalog → Other Agents Pull Update ``` Or the reverse — agents create skills from scratch: ``` Agent Creates SKILL.md on its Computer → Sync from Files → Local Skill Instance → Publish to Catalog → Available to All Agents ``` ## The Context Bar At the top of the Context tab, the **context bar** shows a visual breakdown of the agent's token usage: - **Total context** — How much of the model's context window is used - **Instructions** — Tokens consumed by custom instructions - **Skills** — Tokens consumed by attached skills (each skill shown separately) - **System** — Base system prompt tokens This helps you understand how much context budget remains. If skills and instructions together consume too many tokens, the agent has less room for conversation history and task context. ## Tools Panel The **Tools Panel** lets you toggle individual agent capabilities on or off. Click any tool to enable or disable it: | Tool | Default | Purpose | |------|---------|---------| | `computer` | ✅ On | Screen interaction — click, type, scroll, screenshot | | `bash` | ✅ On | Unrestricted terminal access | | `web_search` | ✅ On | Internet search | | `read_url` | ✅ On | Read web page content | | `data_capture` | ✅ On | Extract structured data into datasets | | `data_management` | ✅ On | Create/modify datasets and rows | | `use_credential` | ✅ On | Fill forms with stored credentials | | `read_file` | ✅ On | Access files from persistent storage | | `download_to_sandbox` | ✅ On | Transfer files onto the computer | | `list_emails` | ✅ On | View inbox | | `read_email` | ✅ On | Read email content | | `send_email` | ✅ On | Send emails | | `settings_manager` | ✅ On | Read/update own configuration | Disabling tools is useful when you want to restrict an agent's capabilities — for example, turning off `send_email` if an agent shouldn't communicate externally, or disabling `bash` if you want to limit it to browser-only tasks. ## How Context Flows to the Agent When the agent receives a message, the full context is assembled in this order: 1. **System prompt** — Base platform instructions 2. **Custom instructions** — Your free-form text 3. **Skills** — Injected in priority order (top skill first) 4. **Conversation history** — Recent messages and tool results 5. **Available tools** — Only enabled tools are presented to the model This means custom instructions and high-priority skills have the strongest influence on agent behavior. ## Tips & Best Practices - **Keep instructions focused** — Use skills for specific workflows and instructions for general behavior - **Watch the context bar** — If you're using too many tokens on skills, the agent has less room for conversation context - **Disable unused tools** — Fewer tools means the agent is less likely to choose an inappropriate approach - **Use skill priority** — Put the most important skill at the top - **Let agents create skills** — When an agent develops a good workflow, ask it to save it as a `SKILL.md` for reuse ## What's Next? - **[Credentials](/docs/agents/credentials)** — Store secrets your agent needs for authentication - **[Datasets](/docs/agents/datasets)** — Understand how agents capture and manage structured data - **[Runs & Scheduling](/docs/agents/runs)** — Automate agent execution with schedules --- # Runs & Scheduling > Source: https://communa.io/docs/agents/runs Track execution history, understand run types and statuses, and configure automated scheduling. > **Tip:** Your agent tracks its own runs. Ask it — *"How did your last run go?"*, *"Show me your run history"*, or *"Set up a schedule to run every 15 minutes."* ## Overview A **run** is a single execution of an agent task — from when the agent starts working to when it finishes. The **Runs** tab provides full visibility into every run: what happened, how long it took, what it cost, and whether it succeeded. Runs are the audit trail for your agent's work. Every action, message, and decision is captured and reviewable. ## The Runs Tab The Runs tab displays a sortable table of all past and active runs — showing status, trigger type, duration, token usage, and cost at a glance. ### Run Detail Drawer Click any run to open the **Run Detail Drawer**, which shows: - Full status timeline (queued → running → completed) - All chat messages from the run - Every tool call and action performed - Screenshots captured during execution - Token breakdown (input vs. output) - Duration and cost details - Error messages (if the run failed) ## Run Statuses | Status | Meaning | |--------|---------| | **Queued** | Run is scheduled but hasn't started yet | | **Running** | Agent is actively executing | | **Completed** | Run finished successfully | | **Failed** | Run encountered an error and stopped | | **Canceled** | Run was manually stopped by a user | | **Timed Out** | Run exceeded its time budget | ## Run Types Runs are triggered from different sources: ### Manual (Chat) When you chat with your agent and it takes action, that's a manual run. You're interacting in real time and can provide additional input as needed. ### Action Playback When you replay saved action sequences (Play All, Play Selected, or Play From Here), each playback session creates a run. This includes data-driven playback where the same sequence runs across multiple data rows. See **[Actions & Sequences](/docs/agents/actions)** for details. ### Queue Processing When the agent processes items from its queue — either manually triggered or on schedule. Each queue item gets its own run with a dedicated chat session, so you can review exactly how each task was handled. ### Scheduled When the cron system triggers an automatic run based on the agent's configured schedule. This includes both queue processing schedule runs and **scheduled job** runs (time-based triggers that inject prompts into the queue). The system: 1. Starts a computer automatically 2. Processes queue items up to the configured maximum 3. Each item creates a separate run for traceability 4. The computer stays warm for efficiency Scheduled jobs create their own queue items with a specific prompt — these items are then processed like any other queue item. See **[Schedule](/docs/agents/schedule)** for details on creating time-based triggers. ## Scheduling Scheduling turns your agent into a 24/7 autonomous teammate. Configure a schedule and the agent processes its queue at regular intervals without any human intervention. ### Setting Up a Schedule You can set up a schedule two ways: **Through the UI:** 1. Open the Queue tab 2. Access Queue Settings 3. Set the schedule interval (every 5 min to every 24 hours) 4. Configure max items per run **Through conversation:** Tell your agent: *"Set up a schedule to process your queue every 15 minutes, max 5 items per run."* The agent uses `settings_manager` to configure it. ### Schedule Intervals | Interval | Best For | |----------|---------| | **5 minutes** | Near real-time email processing, urgent monitoring | | **15 minutes** | Responsive task processing, email triage | | **30 minutes** | Balanced workload processing | | **1 hour** | Batch processing, periodic checks | | **6 hours** | Morning/afternoon batch runs | | **12 hours** | Twice-daily reports and digests | | **24 hours** | Daily summaries, end-of-day processing | ### How Scheduled Runs Work ``` Schedule triggers (e.g., every 15 min) → System starts the computer automatically → Agent processes queue items sequentially → Each item gets its own chat session → Agent completes or hits time/item limit → Computer stays warm for next trigger ``` The key insight: **no human needs to "wake" the agent**. The system handles computer provisioning, execution, and cleanup entirely on its own. ## Cost & Token Tracking Every run tracks resource consumption: - **Input tokens** — Tokens sent to the AI model (context, instructions, history) - **Output tokens** — Tokens generated by the AI model (responses, tool calls) - **Total tokens** — Combined input + output - **Estimated cost** — Dollar cost based on the model's pricing This data helps you: - Understand which tasks are expensive - Optimize instructions and skills to reduce token usage - Budget for scheduled runs over time - Identify runs that are using more resources than expected ## Active Run Banner When a run is currently in progress, an **active run banner** appears at the top of the agent page showing: - Run status (running) - Duration so far - A link to view the run details This provides at-a-glance visibility without navigating to the Runs tab. ## Tips & Best Practices - **Review failed runs** — Check the error details in the Run Detail Drawer to understand what went wrong - **Start with longer intervals** — Begin with hourly schedules and increase frequency as you gain confidence - **Monitor costs** — Check run costs regularly, especially for scheduled agents running frequently - **Use the detail drawer** — The full message and action history is invaluable for debugging and optimization - **Set item limits** — Configure max items per run to prevent unexpectedly long (and expensive) processing sessions - **Let the agent set its schedule** — Tell the agent your preferences and it will configure the schedule itself ## What's Next? - **[Change Log](/docs/agents/changes)** — The sibling sub-tab — a full audit trail of configuration changes - **[Queue](/docs/agents/queue)** — Understand how the queue feeds runs - **[Schedule](/docs/agents/schedule)** — Create time-based triggers that inject prompts into the queue - **[Mail](/docs/agents/mail)** — Set up email-driven task automation - **[Agent Settings](/docs/agents/settings)** — Configure sandbox and agent-level settings --- # Change Log > Source: https://communa.io/docs/agents/changes Review every configuration change made to your agent — by you or the agent itself — with full before/after values, actor attribution, and one-click revert. > **Tip:** The Change Log is your agent's built-in audit trail. Every settings edit, scheduled job tweak, or mail/voice configuration change is captured automatically — with the exact before and after values, and a one-click **Revert** on most entries. ## Overview The **Change Log** is a complete audit trail of every configuration change made to your agent. Unlike **[Runs](/docs/agents/runs)** — which tracks *execution* — the Change Log tracks *mutations*: what was changed, when, by whom, with the exact before and after values, and a one-click way to undo it. Every time your agent updates its own settings, edits one of its skills, or a team member changes configuration through the UI, a change entry is recorded. This gives you a transparent, reviewable history of how your agent has evolved over time — and a safe way to roll back when something doesn't pan out. ## Where to Find It The Change Log lives inside the **History** tab as a sub-tab next to **Runs**. Both views share a toolbar row so you can switch between execution history and configuration history without losing context. - **Runs** — What the agent *did* - **Changes** — What the agent *became* ## What Gets Tracked The Change Log captures mutations across six configuration surfaces. Both **agent-initiated** changes (chat, `settings_manager`, `manage_skills`, skill sync) and **user-initiated** changes (saves from any UI tab) are captured uniformly — same schema, same diff view, same revert flow. | Category | Examples | |----------|----------| | **Agent Settings** | Title, persona name, description, working hours, computer mode, default model, cache strategy, context memory, auto-save actions, queue interval, max items per run | | **Mail Settings** | Whitelist entries, whitelist enforcement, auto-queue incoming emails, email processing instructions | | **Voice Settings** | Greeting, transcription language, conversation model, context mode, processing instructions, pacing, progress messages, silence handling, call duration, and recording | | **Scheduled Jobs** | Creation, updates (name, prompt, cron expression, enabled state), and deletion | | **Skills** | Skill creation, deletion, and metadata edits (title, description, tags, attached/detached state) | | **Skill Files** | Per-file content edits to instructions, scripts, references, and other skill files inside a skill | Only fields that **actually changed** are recorded — no-op saves don't clutter the log. ## Anatomy of a Change Entry Each entry is rendered as a card on a vertical timeline (commit-rail style), containing: - **Operation icon** — Color-coded by entity type (settings, mail, voice, scheduled job, skill, skill file) - **Entity name** — What was changed (e.g., *"Agent Settings"*, *"Scheduled Job: Daily Digest"*, *"Skill: Lead Researcher"*) - **Operation badge** — **Created**, **Updated**, or **Deleted** - **Actor badge** — Who made the change (agent, user, or system) - **Inline preview** — For single-field updates, shows the before → after values directly on the card - **Relative timestamp** — e.g., *"3 minutes ago"*, with the exact time on hover - **Revert button** — On revertable entries, a one-click revert is exposed in the detail drawer Click any entry to open the full detail drawer. ## Operations | Operation | Meaning | Visual | |-----------|---------|--------| | **Create** | A new entity was added (e.g., new scheduled job) | Green accent, *"Created"* badge | | **Update** | An existing entity was modified | Neutral accent, field-level diff inline | | **Delete** | An entity was removed | Red accent, *"Deleted"* badge | ## Actors & Sources Every change is attributed to one of three **actor types**, so you can always tell *who* made a change: | Actor | Who It Is | When You'll See It | |-------|-----------|--------------------| | **Agent** | The AI itself, acting through tools like `settings_manager` or `manage_skills` | When your agent self-configures during onboarding, or when you tell it to change something in chat | | **User** | A team member editing via the UI | When someone opens Settings, Mail, Voice, or Schedule and saves a change | | **System** | An automated platform action | Rare — e.g., migrations, backfills, or scheduled cleanup | Agent-driven entries link to the chat session and run where the change originated, so you can trace a setting change back to the exact conversation that caused it. ### Source Beyond the actor, every entry also records a **source** — the specific code path that wrote the change. The detail drawer surfaces this so you can tell, for example, whether the agent changed a setting through chat (`settings_manager`) or as part of skill maintenance (`manage_skills`). | Source | Meaning | |--------|---------| | `settings_manager` | Agent edited automation/tab settings via the `settings_manager` tool | | `manage_skills` | Agent created/updated/deleted a skill via the `manage_skills` tool | | `skill_sync` | Skill files were reconciled from the computer (post-run, scheduled, or manual sync) | | `user_ui` | A team member saved a change from the UI (Settings / Mail / Voice / Schedule / Skills tabs) | | `api` | Direct API call (programmatic integration) | | `rollback` | Auto-written when an entry is reverted — links the rollback row back to the original | ## Filtering The toolbar in the top-right of the Changes sub-tab lets you narrow the timeline by category: - **All changes** (default) - **Agent settings** — Title, persona, computer, working hours, chat, actions, queue - **Mail & Voice** — Channel-specific configuration and processing instructions - **Scheduled jobs** — Create, update, delete on time-based triggers - **Skills** — Skill and skill-file changes Filters work alongside the grouping — filtered entries still cluster under their date headers. ## The Change Detail Drawer Clicking any entry opens a side drawer showing the **full field-by-field diff** for that change: - Every modified field listed with its **before** and **after** values - Multi-line strings (like `email_processing_instructions` or a scheduled job prompt) rendered in full — no truncation - JSON/object fields pretty-printed for readability - Actor details (name, email, session, run) plus the **source** badge, with links back to the originating chat and run - A **Revert** button on revertable entries (see next section) This is especially useful for verifying agent-made changes to long-form settings like processing instructions — you can see the exact text the agent wrote, character-for-character. ## Reverting a Change Most entries can be reverted with a single click from the detail drawer. The system handles the messy parts for you — drift detection, cascading restores for skill files, and pushing reverted content back to your running computer. ### What's Revertable | Entity | Revertable Operations | |--------|----------------------| | **Agent settings** | Updates to fields like title, persona, working hours, computer mode, models, cache strategy, etc. | | **Mail / Voice / Schedule tab settings** | Field-level updates | | **Scheduled jobs** | Create, update, delete (a deleted job is restored on revert) | | **Skills** | Create, update, delete (a deleted skill — and its files — are restored on revert) | | **Skill files** | Create, update, delete | Rollback rows themselves (`source: rollback`) are **not** revertable — to undo a revert, just revert the rollback row's predecessor instead, or make the change manually. ### Drift Detection If the entity has changed since the entry was written (e.g., someone edited the field again, or the agent overwrote it), reverting could clobber newer work. The API detects this and asks for confirmation: > *"The entity has changed since this entry — confirm to proceed."* Confirming forces the revert; the rollback row's reason field records exactly which fields were drifted and force-overwritten. ### Ancestry Auto-Restore Reverting a **skill file** edit on a skill that was later detached or deleted automatically restores the parent skill instance first, then applies the file revert. The drawer surfaces this clearly (*"auto-restored parent skill"*) so you're never surprised. ### Computer Push For skill and skill-file reverts, the reverted content is pushed best-effort to your running computer so the agent immediately sees the rolled-back version on its next action. This step is non-fatal — if the computer is asleep or unreachable, the DB revert still succeeds and the file syncs on the next wake-up. ### No-Op Reverts If the entity is *already* at the target value (e.g., a later edit already restored it, or two opposing edits cancelled out), the revert is treated as a no-op. You'll see a friendly *"already at target"* message instead of a fake-success toast, and no rollback row is written. ### Rollback Rows Every successful revert writes a new entry to the timeline with `source: rollback`. Its reason field links back to the original entry's ID and notes any drift or ancestry restoration that happened along the way — so the audit trail of *"someone reverted X because of Y"* is preserved alongside the original change. ## Grouping & Timeline Entries are grouped by date for easy scanning: - **Today** — Changes from today - **Yesterday** — Changes from yesterday - **This week** — Changes from the last 7 days (excluding today/yesterday) - **Older** — Grouped by calendar date (e.g., *"April 12"*) Within each group, entries appear chronologically (newest first) along a connected commit-rail — making it visually clear which changes happened close together. ## Retention How long your change history is kept depends on your **plan**. Higher tiers retain change-log entries for longer — so you can look back further when reviewing how your agent has evolved or tracking down when a setting changed. If your timeline only goes back so far, you've likely hit your plan's retention window. Upgrading extends it going forward, and may also bring back recent entries that are still around. See the [Billing page](/billing) for the retention window included with each plan. > **Heads up:** Retention applies to **change-log entries** only. Runs, skills, and other data follow their own rules. ## Use Cases ### Debug Unexpected Behavior When your agent starts behaving differently, the Change Log is the first place to look. *"It was working yesterday"* becomes *"it was working yesterday, and here's exactly what changed overnight — and here's the revert button."* ### Verify Agent-Made Changes When you tell your agent to update a setting in chat, open the Change Log afterward to confirm it did exactly what you asked — and nothing more. The inline before/after preview makes verification instant, and one click rolls anything back. ### Review Skill Edits When your agent improves one of its own skills — rewriting instructions, adding a script, or tweaking a reference file — the Change Log captures it. Open any skill or skill-file entry to see exactly what the agent changed, and revert to the previous version if the new one regresses. ### Audit & Accountability For team-managed agents, the Change Log provides a clear accountability trail: who changed what, when, from which surface (chat, UI, API, sync), and why (via linked chat sessions for agent-initiated changes). ### Safe Experimentation Try an experimental setting, watch how the agent behaves, then click **Revert** to roll back precisely. No guesswork, no copy-paste, no risk of forgetting the original value. ## Tips & Best Practices - **Check the Change Log after onboarding** — See exactly what your agent configured for itself during the first conversation - **Use the source badge to triage** — A surprising change with source `user_ui` points to a teammate; `settings_manager` points to a chat conversation - **Use the Mail & Voice filter** when debugging channel-specific behavior — narrows the timeline to communication settings only - **Open the detail drawer for long text fields** — The inline preview is compact; the drawer shows the full before/after for instructions, prompts, and other multi-line content - **Trace agent decisions** — Agent-initiated entries link back to the originating chat session, so you can see the conversation that led to a change - **Don't fear the Revert button** — Drift detection prevents accidental clobbering, and every revert itself becomes a new (revertable) timeline entry - **Pair with Runs** — A surprising run result often correlates with a recent configuration change. Sibling sub-tabs make side-by-side investigation easy ## What's Next? - **[Runs & Scheduling](/docs/agents/runs)** — The other half of History — execution tracking - **[Agent Settings](/docs/agents/settings)** — The main surface that feeds Change Log entries - **[Mail](/docs/agents/mail)** — Mail configuration changes tracked here - **[Schedule](/docs/agents/schedule)** — Scheduled job create/update/delete changes tracked here --- # Credentials > Source: https://communa.io/docs/agents/credentials Securely store passwords, API keys, and tokens that your agent can use without ever seeing the raw values. > **Tip:** Your agent understands the credential system. Ask it — *"What credentials do I have set up?"* or *"I need to log into Salesforce — help me set up a credential."* ## Overview Credentials are encrypted secrets — passwords, API keys, access tokens — that agents can use **without ever seeing the raw values**. This is a core security feature: even if an AI model behaves unexpectedly, it literally cannot leak credentials it doesn't have access to. ## How It Works The credential system uses a **placeholder injection model**: 1. You create a credential with a **name** and **value** (e.g., name: "Gmail Password", value: "my-secret-pass") 2. The value is encrypted and stored securely — it never appears in chat, logs, or the AI model's context 3. When the agent needs to authenticate, it calls the `use_credential` tool with the credential name and the target form field 4. The **system** (not the AI) fills the value directly into the form field on the agent's computer 5. The agent sees only a confirmation that the credential was applied — never the raw value ``` Agent sees: "Credential 'Gmail Password' applied to password field" Agent NEVER sees: "my-secret-pass" ``` This means the AI model cannot echo, print, log, or transmit your secrets. The credential value exists only in the encrypted store and in the form field on the computer — never in the AI's context window. ## Creating a Credential 1. Open **Settings → Credentials** on your agent's detail page 2. Click **Add Credential** 3. Fill in: - **Name** — A descriptive label (e.g., "GitHub Token", "CRM Login") - **Value** — The secret itself (password, API key, token) 4. Click **Save** The value is encrypted immediately and won't be shown again. Only the name is visible in the UI. ## Managing Credentials Each credential appears as a card in the Credentials section (**Settings → Credentials**) showing: - **Name** — The credential's label - **Created date** — When it was added - **Edit button** — Update the name or replace the value - **Delete button** — Remove the credential (with confirmation dialog) ### Editing a Credential Click **Edit** on a credential card to: - Change the **name** (for better organization) - Replace the **value** (the old value is overwritten) The current value is never displayed — you can only replace it with a new one. ### Deleting a Credential Click **Delete** to remove a credential. A confirmation dialog appears since this action cannot be undone. If the agent tries to use a deleted credential, it will receive an error. ## How the Agent Uses Credentials When your agent encounters a login form or authentication prompt, it uses the `use_credential` tool: 1. The agent identifies the form field that needs a password/key 2. It calls `use_credential` with the credential name and field location 3. The system injects the value directly into the field 4. The agent proceeds with the workflow You can tell your agent which credential to use: *"Log into GitHub using my 'GitHub Token' credential"* — or the agent can list available credentials and choose the right one. ## Security Model | Aspect | How It's Protected | |--------|-------------------| | **Storage** | Values are encrypted at rest | | **AI context** | Values are never included in the model's context window | | **Chat history** | Values never appear in messages or tool results | | **Logs** | Values are excluded from all logging | | **Transmission** | Values flow directly from encrypted storage to the form field on the computer | The AI sees only credential **names** — never values. Even if you asked the agent *"What's my GitHub password?"*, it would have no way to answer because the value doesn't exist in its context. ## Best Practices - **Use descriptive names** — "Salesforce Production Login" is better than "cred1" - **One credential per service** — Don't reuse the same credential across different services - **Rotate regularly** — Update credential values when you change passwords or rotate API keys - **Don't put secrets in instructions** — Use credentials instead of typing passwords into custom instructions or skill files - **Test after creating** — Ask the agent to use the credential on the target login form to verify it works ## What's Next? - **[Datasets](/docs/agents/datasets)** — Learn how agents capture and manage structured data - **[Files](/docs/agents/files)** — Understand session files and persistent storage - **[Mail](/docs/agents/mail)** — Configure your agent's email capabilities --- # Integrations > Source: https://communa.io/docs/agents/integrations Connect Google Workspace and custom MCP servers so your agent can call external tools. > **Tip:** Your agent can list its connected integrations. Ask it — *"What integrations am I connected to?"* or *"Connect me to Google Calendar."* ## Overview The **Integrations** tab is where you grant your agent access to third-party services. It hosts two kinds of integrations side-by-side: - **Native connectors** — first-party integrations we build and maintain (Google Workspace today; more on the way). Tools execute **server-side** on our platform using OAuth tokens, with per-service toggles (Calendar, Drive, Docs, …). - **Custom MCP servers** — any [Model Context Protocol](https://modelcontextprotocol.io) compatible URL you want to connect (GitHub, Linear, Notion, your own internal APIs). Tools execute **remotely** via the MCP protocol, with per-tool toggles. Both kinds appear together as cards on the Integrations tab and use the same status/management UX. ## Native Connectors vs Custom MCP | | Native Connector | Custom MCP Server | |--|------------------|-------------------| | **Examples** | Google Workspace | GitHub, Linear, Notion, internal APIs | | **Execution** | Server-side on our platform | Remote, via the MCP protocol | | **Auth** | OAuth (managed end-to-end) | Bearer token, OAuth, or none | | **Granularity** | Per-service (Calendar, Drive, …) | Per-tool | | **Setup** | Pick from catalog → OAuth → choose services | Paste URL + auth → discover tools → toggle | | **Best for** | Common SaaS we've pre-vetted | Anything we don't ship a native connector for | If we ship a native connector for a service you need, **use it** — it's faster, has tighter scope control, and is pre-vetted. Otherwise, custom MCP gives you full flexibility. ## How It Works ### Native connectors 1. You pick a connector (e.g., **Google**) from the catalog and select which services to enable (Calendar, Drive, Docs) 2. You complete the OAuth flow in a popup 3. We store the OAuth tokens encrypted in Supabase Vault and auto-refresh them 4. Each enabled service exposes a set of **tools** the agent can call (e.g., `google_calendar_create_event`, `google_drive_search`) 5. When the agent calls a tool, our backend executes the request against the provider API using the stored token — the token is never sent to the LLM ### Custom MCP servers 1. You add a remote MCP server URL on the Integrations tab 2. The platform connects to the server and **discovers** the tools it exposes 3. Discovered tools are added to your agent's available toolset 4. When the agent calls one of those tools, your auth token is attached as a request-level credential — never inserted into the conversation 5. The tool's response is returned to the agent ``` Native: Agent calls "google_calendar_create_event" → Our backend calls Google's API with your OAuth token → Result returned to the agent MCP: Agent calls "create_issue" (from your GitHub MCP server) → The model provider attaches your bearer token and dispatches → Result returned to the agent ``` ## Connecting an Integration 1. Go to the **Integrations** tab on your agent's detail page 2. Click **Add Integration** 3. Pick from the catalog: - A native connector card (e.g., **Google**) — opens a service-selection step - **Custom MCP** — opens the MCP setup form ### Connecting Google Workspace 1. Click the **Google** card in the catalog 2. Tick the services you want to enable: - **Calendar** — create, read, update, and search events - **Drive** — search and read files - **Docs** — read and edit documents - **Gmail Inbox** — list, search, read, label, archive, and trash messages (recoverable for 30 days) - **Gmail Send** — send emails and create drafts - **Gmail Labels** — create, update, delete, and apply labels 3. Click **Connect** and complete the OAuth popup 4. The connector card shows as **Active** with a chip per enabled service You can enable additional services later from the connector's **Settings** drawer. Adding a service that needs new scopes (for example, enabling Gmail on an existing Google connection) will prompt a re-authorization. > **Safety note:** Gmail Inbox does **not** include permanent deletion — the agent can only move messages to Trash (recoverable from Gmail for 30 days). This is deliberate: trashing is reversible, permanent deletion is not. If you need to permanently purge messages, do so manually in Gmail (Trash folder → **Delete forever**). The same principle applies to Drive — the agent can move files to Trash but not bypass it. > **Note:** Google Sheets and additional Google services are on the roadmap. They'll appear as new checkboxes in the same flow once shipped. ### Connecting a Custom MCP Server 1. Click **Custom MCP** in the catalog 2. Fill in: - **Display name** — A friendly label (e.g., "GitHub", "Internal CRM") - **Server URL** — The MCP server endpoint - **Authentication** — Choose Bearer token, OAuth, or None (see below) 3. Click **Connect** The platform validates the connection and discovers available tools. Once connected, the integration appears as a card alongside your native connectors. ## Authentication Methods | Method | Applies To | When to Use | |--------|------------|-------------| | **OAuth** | Native connectors (always); some MCP servers | Per-user authorization, multi-tenant services. Tokens auto-refresh server-side. | | **Bearer token** | Custom MCP only | Static API key or personal access token. Encrypted at rest, easy to rotate. | | **None** | Custom MCP only | Public servers that don't require credentials. | For native connectors, OAuth is the only option — we manage the entire flow including refresh. ## Choosing What to Expose You don't have to expose everything an integration offers. - **Native connectors** — toggle individual **services** on/off via the Settings drawer. Disabled services hide all their tools from the agent. The card shows a chip per enabled service. - **Custom MCP** — toggle individual **tools** on/off via Edit. Disabled tools don't appear in the agent's toolset. This is useful when an integration offers both safe read-only operations and destructive write operations — expose just what you trust the agent to use. ## Connection Status Each integration card shows a status badge. The same set of statuses applies to both native connectors and custom MCP: | Status | Meaning | |--------|---------| | **Active** | Connected and tools are exposed to the agent | | **Disabled** | Paused — no tools are exposed, but configuration is preserved | | **Error** | Connection failed. Click **Test** to revalidate or **Edit** to fix the configuration | | **Expired** | OAuth refresh failed. Click **Reconnect** to re-authorize | | **Pending** | Setup is in progress | ## Managing Integrations Each integration card has actions in its menu: | Action | Native Connector | Custom MCP | |--------|------------------|------------| | **Toggle** | Enable/disable without deleting | Enable/disable without deleting | | **Settings** | Rename, change enabled services, danger zone | — | | **Edit** | — | Rename, replace token, change exposed tools | | **Test** | Revalidate the connection | Revalidate and rediscover tools | | **Reconnect** | Re-run OAuth (e.g., after adding a new service) | Re-run OAuth (for OAuth MCP) | | **Disconnect** | Permanently remove the integration | Permanently remove the integration | ## Security | Aspect | How It's Protected | |--------|-------------------| | **Token storage** | OAuth tokens and bearer tokens are encrypted at rest in **Supabase Vault** | | **AI context** | Tokens are never inserted into prompts, messages, or tool results — the model can't read them | | **Logs** | Authentication headers are redacted in all logs and tool results | | **OAuth refresh** | Refresh flows happen server-side — tokens never reach the browser | | **Tool calls (native)** | Executed on our backend; the agent sees only the result | | **Tool calls (MCP)** | Credentials attached at dispatch time; the agent sees only the result | The model can't read or echo your integration tokens — they aren't part of any prompt or message it sees. ## Best Practices - **Prefer native connectors when available** — they're faster, scope-controlled, and pre-vetted - **Enable only the services or tools you need** — fewer tools = clearer agent decisions and tighter security - **Use descriptive display names** — "GitHub (Production)" is clearer than "github" - **Test after rotating tokens** — click **Test** to verify the new token works before the next agent run - **Disable instead of deleting** — if you're temporarily not using an integration, disable it to keep configuration around for later - **Reconnect when adding native services** — adding a service that needs new OAuth scopes will prompt re-authorization; the existing token won't have the new permission ## What's Next? - **[Credentials](/docs/agents/credentials)** — Store passwords and API keys for login forms - **[Context & Configuration](/docs/agents/context)** — Configure skills, instructions, and tools - **[Agent Settings](/docs/agents/settings)** — Centralized agent configuration --- # Datasets > Source: https://communa.io/docs/agents/datasets View, edit, filter, and export structured data tables that your agent creates and manages. > **Tip:** Your agent can manage datasets directly. Ask it — *"Create a dataset for tracking leads"*, *"Add a row to the contacts dataset"*, or *"Export the research data as CSV."* ## Overview Datasets are structured data tables — like spreadsheets — that agents create, populate, and transform during their work. They're the primary way agents store and organize extracted information. Unlike traditional databases that require schema design upfront, datasets in Communa are **dynamic**: agents create them on the fly when they extract structured data, and schemas evolve as new columns are discovered. ## How Datasets Are Created Datasets appear through two main paths: ### Auto-Capture When an agent extracts structured data from its computer (screen, clipboard, files) using the `data_capture` tool, a dataset is created automatically. The agent defines the schema based on what it finds: - Scraping a table from a website → dataset with matching columns - Reading a spreadsheet → dataset mirroring the sheet's structure - Extracting form data → dataset with field names as columns ### Manual Creation Agents can also create datasets explicitly using the `data_management` tool: - *"Create a dataset called 'Leads' with columns: name, email, company, status"* - The agent creates the schema and starts populating it ## The Datasets Tab The **Datasets** tab shows all datasets belonging to the agent. ### Sidebar Navigation A sidebar lists all datasets with their names. Click a dataset to view it in the main area. The currently selected dataset is highlighted. ### The Data Table The main area displays the selected dataset as an interactive table. You can **click any cell to edit it inline**, **sort by any column**, **filter rows** using the controls above the table, and **select rows** for bulk actions. Changes are saved when you click outside the cell or press Enter. ### Column Reordering You can rearrange columns by dragging their headers. Hover over a column header to reveal the drag handle, then drag it left or right to reorder. The new column order is saved automatically and persists across sessions. ## Data Transforms Ask your agent to transform data within a dataset: - *"Normalize all email addresses to lowercase"* - *"Extract the domain from each email"* - *"Calculate the total for the revenue column"* - *"Flag any rows where the status is 'overdue'"* The agent uses the `data_management` tool to apply transformations row by row or in bulk. You can also apply transforms through the UI's transform action. ## Exporting Data Click the **Export CSV** button to download the dataset as a CSV file. The export: - Includes all columns and rows (respecting current filters) - Uses UTF-8 encoding with BOM for Excel compatibility - Downloads immediately to your browser ## Dataset Permissions Datasets can be protected with per-operation permissions to prevent accidental modification: | Permission | What It Controls | |-----------|-----------------| | **Insert** | Whether new rows can be added | | **Update** | Whether existing rows can be modified | | **Delete** | Whether rows can be removed | | **Read** | Whether data can be queried | You can also **lock** a dataset entirely, making it read-only until unlocked. This is useful for finalized datasets that shouldn't be modified. > **Note:** Dataset permissions above control what the **AI agent** can do. Separately, **workspace roles** control what human team members can do — only Owners and Admins can delete datasets and rows. All workspace roles can view and edit data. ## Deleting Datasets & Records Deleting datasets and individual rows requires **Owner** or **Admin** role in the workspace. Members can view and edit data but cannot delete. - **Delete a dataset** — Use the delete action on the dataset item in the sidebar. A confirmation dialog appears since deletion is permanent and removes all rows - **Delete individual rows** — Select a row using the checkbox, then use the delete action in the toolbar that appears - **Bulk delete** — Select multiple rows using the checkboxes, then click the delete action in the toolbar to remove them all at once ## Tips & Best Practices - **Let the agent create schemas** — Don't pre-define columns. Tell the agent what data you need and let it design the schema based on what it finds - **Use filters liberally** — Filters help you find specific data without asking the agent to search - **Export regularly** — Download important datasets as CSV backups - **Lock finalized data** — Use permissions to prevent accidental changes to completed datasets - **Combine with skills** — Create skills that define exactly what data to capture and in what format for consistent results across runs ## What's Next? - **[Datasets API](/docs/api/datasets)** — Read and write these datasets from your own code via the REST API - **[Files](/docs/agents/files)** — Manage uploaded files and computer file synchronization - **[Mail](/docs/agents/mail)** — Configure email communication for your agent - **[Queue](/docs/agents/queue)** — Understand how tasks are queued and processed --- # Files > Source: https://communa.io/docs/agents/files Manage your agent's file storage — session files on the computer and persistent files that survive sleep cycles. > **Tip:** Your agent manages its own files. Ask it — *"Upload this PDF to my storage"*, *"What files do you have?"*, or *"Download the report from storage onto your computer."* > **Note on terminology:** Throughout the docs we use **computer** to mean the agent's isolated Linux desktop environment. The underlying technology is sometimes called a *sandbox* — they refer to the same thing. ## Overview The **Files** tab gives you visibility into two distinct file systems: 1. **Session Files** — Live files inside the agent's running computer (ephemeral) 2. **Stored Files** — Persistent files in the agent's permanent storage (survive sleep cycles) Understanding the difference is essential — session files disappear when the computer sleeps, while stored files are always available. ## Two-Panel Layout The Files tab is organized into two side-by-side panels: ### Session Files (Left Panel) These are the files inside the agent's **running computer** — the actual file system of the Linux desktop. They appear only when the computer is awake. - **Real-time view** — Reflects the current state of the sandbox file system - **Ephemeral** — Created during the session and lost when the sandbox sleeps (unless synced) - **Full access** — The agent can read, write, move, and delete these files using terminal commands Session files include everything the agent creates or downloads during its work: scripts, screenshots, downloaded files, temporary data, and output artifacts. ### Stored Files (Right Panel) These are files in the agent's **persistent storage** — a cloud-based file system that survives sandbox sleep/wake cycles. - **Always available** — Accessible whether the sandbox is awake or not - **Persistent** — Files remain until explicitly deleted - **Organized** — Supports folders for organizing files Stored files are where you upload resources the agent needs (documents, images, data files) and where important outputs are saved for long-term access. ## Uploading Files Click the **Upload** button in the Stored Files panel to add files: 1. Select one or more files from your computer 2. Choose a destination folder (or upload to root) 3. Files appear immediately in the stored files panel Uploaded files are available to the agent via the `read_file` tool. You can also transfer them into the sandbox for processing. ## File Transfer Move files between the two systems: ### Stored → Sandbox (Transfer to Sandbox) Select a file in stored files and click **Transfer to Sandbox** to copy it into the running sandbox. The agent can then access it from the Linux file system — useful for processing documents, running scripts on data files, or loading resources. The agent can also do this itself using the `download_to_sandbox` tool. ### Sandbox → Stored (Sync) Files in the sandbox can be synced to persistent storage to survive the sleep cycle: - **Manual sync** — Click the sync button to copy sandbox files to stored files - **Auto-sync** — Important files are synced automatically at key moments (before sleep, after runs) > **Warning:** If you don't sync session files before sleeping the agent, they'll be lost. The system warns you in the sleep confirmation dialog if there are unsynced files. ## Folder Management Stored files support a folder hierarchy: - **Create folder** — Click the new folder button to organize your files - **Move files** — Drag files into folders - **Delete folder** — Remove empty folders (or folders with contents, with confirmation) - **Nested folders** — Create subfolders for complex file organizations ## File Preview Click any file to preview it directly — images, text, code, and PDFs are all supported. For other file types, you'll see metadata and a download button. ## What Happens When the Agent Sleeps When the sandbox shuts down (default **on-demand** mode): - **Session files** → Lost (unless synced to stored files) - **Stored files** → Remain untouched - **Skill files** → Preserved (skills are stored separately) When the agent wakes up again, it starts with a fresh sandbox. Stored files can be transferred back in as needed. > **Tip:** If you enable **Persistent Sandbox** in Settings → Sandbox, the sandbox is **paused** instead of destroyed. All session files, installed packages, and running processes are preserved and resume in ~1 second. This eliminates the need to sync files before every sleep. See [Agent Settings](/docs/agents/settings#sandbox) for details. ## Tips & Best Practices - **Sync early and often** — Don't wait until the end of a session to sync important files - **Use stored files for inputs** — Upload documents, data files, and resources to stored files before the agent processes them - **Use session files for scratch work** — Let the agent create temporary files in the sandbox without worrying about storage - **Organize with folders** — Create folders by project, date, or file type to keep stored files manageable - **Check before sleeping** — Always verify that important outputs have been synced before putting the agent to sleep ## What's Next? - **[Mail](/docs/agents/mail)** — Set up email communication for your agent - **[Queue](/docs/agents/queue)** — Understand the task queue and processing - **[Agent Settings](/docs/agents/settings)** — Configure resolution, timeout, and sandbox settings --- # Mail > Source: https://communa.io/docs/agents/mail Configure your agent's dedicated email address, manage inbox and sent messages, set up auto-queue, and connect your own SMTP server for customer-facing email at scale. > **Tip:** Your agent can configure its own email settings. Ask it — *"Enable auto-queue for incoming emails"*, *"Whitelist support@company.com"*, or *"Check my inbox."* ## Overview Every agent has a **dedicated email address** in the format: ``` agent-name@mailer.communa.io ``` This isn't just for show — agents can send and receive real emails. This email system enables: - **External communication** — Agents send reports, updates, and notifications to real email addresses - **Inbound task intake** — Send an email to your agent and it processes the request - **Inter-agent workflows** — Agents communicate with each other via email for multi-agent collaboration **Two ways to send:** Out of the box, your agent sends through a built-in shared address — perfect for internal updates, team notifications, and inter-agent workflows. For customer-facing email at scale, you can plug in your own SMTP server and send from your own domain. Both modes share the same inbox, queue, and whitelist — only the **outbound** path changes. ## The Mail Tab The Mail tab is organized into two views: ### Inbox Shows all emails received by the agent. Click any email to open the full message. Unread emails are visually highlighted. ### Sent Shows all emails the agent has sent — useful for reviewing what the agent communicated on your behalf. ## Email Actions You can mark emails as read/unread, **add them to the queue** for processing, or delete them. These actions are available individually or in bulk when multiple emails are selected. ## Auto-Queue The **Auto-Queue** feature is one of the most powerful email capabilities. When enabled: 1. Every incoming email is automatically added to the agent's **queue** as a task item 2. On the next scheduled run, the agent processes each queued email 3. The agent reads the email content and acts on it according to its skills and instructions This enables a powerful workflow: send an email to your agent → it's queued → the agent wakes up on schedule → processes the email → sends results back. ### Enabling Auto-Queue Toggle **Auto-Queue Incoming Emails** in the mail settings. When enabled, all new incoming emails are immediately added to the queue. ## Built-in Email (Default) Every agent starts with the built-in email path enabled — no setup required. Mail is sent from a shared platform address (`agent-name@mailer.communa.io`) and a small *"Sent via Communa.io"* footer is appended to outbound messages on the free plan. **Best for:** - Internal updates to team members - Agent ↔ agent workflows (research → analysis → reporting pipelines) - Inbound task intake — let people email your agent to kick off work - Internal reports, alerts, and notifications **What to know:** - A **monthly outbound limit** applies, defined by your plan. The current usage is shown in the Mail tab and Mail settings — you can see at a glance how much headroom you have. - The branded footer is removed automatically on **any paid plan**. - Inbound mail to your agent's address always works the same way, regardless of plan or sending mode. > **Info:** The built-in path is great for internal and team-facing communication. For customer-facing email — newsletters, transactional messages, sales outreach, support replies — we recommend sending from your own domain. See the next section. ## Custom SMTP — Send from Your Own Domain For production workloads where deliverability, brand, and volume matter, connect your own SMTP server. Once enabled, all outbound mail routes through your provider, sent from an address on a domain you control. ### Why it matters in production - **Send from your own domain** — Recipients see `you@yourcompany.com`, not a shared platform address. Replies land in your own inbox. - **No monthly outbound cap** — Your provider's quota is the only limit. Send hundreds, thousands, or more — whatever your plan with them allows. - **No branded footer** — Messages go out clean, exactly as your agent composed them. - **Deliverability you control** — Your SPF, DKIM, and DMARC records, your sending reputation. Established providers and authenticated domains land in the inbox, not in spam. - **Provider of your choice** — Use the SMTP service you already trust: SendGrid, AWS SES, Postmark, Mailgun, Resend, Google Workspace, Microsoft 365, or any standards-compliant SMTP server. ### When to switch Move to custom SMTP when: - Your agent emails **customers, leads, or end-users** (anyone outside your team) - You're **approaching the monthly cap** on the built-in path - You need messages to come from your **own brand and domain** - Deliverability is critical to the workflow (transactional email, outreach, support) ### Setup at a glance Setup is the same shape no matter which provider you use: 1. Open the agent's **Settings → Mail** and switch to the **SMTP** tab 2. Pick your provider from the presets (host, port, and encryption are filled in for you), or choose **Custom** 3. Enter your **Username** and **Password** — these come from your provider's dashboard, not your login credentials 4. Set the **From address** — most providers require this to be on a domain (or an exact address) you've verified with them. See the per-provider notes below 5. Optional: set a **Reply-to** address (defaults to your From address if left blank) 6. Click **Test** — we send a real message to confirm everything works 7. Once the test succeeds, flip the master switch on and **Save** > **Info:** Each provider has its own rule about which **From address** is allowed. Picking the wrong one is the #1 reason a test fails. The cards below tell you exactly what's allowed for each provider. ### Provider setup Pick the card that matches your provider. Each one shows the connection settings, the From-address rule, where to find your credentials, and a heads-up on common pitfalls. #### SendGrid Great if you're already using SendGrid for marketing or transactional email. | Setting | Value | |---|---| | Host | `smtp.sendgrid.net` | | Port | `587` | | Encryption | Use TLS: **off** (STARTTLS is automatic) | | Username | `apikey` *(literally the word "apikey")* | | Password | Your SendGrid API key | **From address rule:** Any address on a domain you've verified in SendGrid via **Domain Authentication**, or a single address you've verified via **Single Sender Verification**. Without one of these, sends are blocked. **Where to get your credentials:** 1. Sign in to SendGrid → **Settings → API Keys** 2. Create a key with **Full Access** (or at minimum, Mail Send permission) 3. Copy the key — you'll only see it once **Heads-up:** The Username field is the literal string `apikey`, not your email or account name. This trips up most people on their first try. #### Mailgun A solid choice for transactional email, especially if you're already on Mailgun for inbound parsing or routing. | Setting | Value | |---|---| | Host | `smtp.mailgun.org` *(or `smtp.eu.mailgun.org` for EU region)* | | Port | `587` | | Encryption | Use TLS: **off** (STARTTLS is automatic) | | Username | The SMTP user from your domain settings (often `postmaster@your-domain.com`) | | Password | The SMTP password from your domain settings | **From address rule:** Must be on a domain you've added and verified in Mailgun. Free accounts can only send to **authorized recipients** until you add a payment method and verify a domain. **Where to get your credentials:** 1. Sign in to Mailgun → **Sending → Domains** 2. Click your domain → **SMTP credentials** 3. Copy the login (your Username) and reset the password to get a fresh one **Heads-up:** If your Mailgun account is in the EU region, change the host to `smtp.eu.mailgun.org` — using the US host with an EU account will fail authentication. #### AWS SES The cheapest option at scale, ideal if you're already on AWS. | Setting | Value | |---|---| | Host | `email-smtp.us-east-1.amazonaws.com` *(swap in your region)* | | Port | `587` | | Encryption | Use TLS: **off** (STARTTLS is automatic) | | Username | Your SES SMTP username | | Password | Your SES SMTP password | **From address rule:** Must be a verified email identity, or any address on a verified domain identity. **In sandbox mode, the recipient must also be verified** — until you request production access, you can only send to addresses you've explicitly verified. **Where to get your credentials:** 1. Sign in to AWS Console → **Amazon SES** → pick your region 2. **SMTP settings → Create SMTP credentials** — this generates a username and password specifically for SMTP (these are *not* your AWS access keys) 3. Verify your sending domain or email under **Verified identities** 4. To send to anyone (not just verified addresses), open a **Production access** request from the SES console **Heads-up:** The host must match the AWS region your SES identities live in (e.g. `email-smtp.eu-west-1.amazonaws.com`). If you're seeing "Email address is not verified" errors, you're still in sandbox mode — request production access. #### Postmark Excellent deliverability and the cleanest dashboard. Best for transactional email where every message must land. | Setting | Value | |---|---| | Host | `smtp.postmarkapp.com` | | Port | `587` | | Encryption | Use TLS: **off** (STARTTLS is automatic) | | Username | Your **Server API token** | | Password | Your **Server API token** *(yes, the same value)* | **From address rule:** Must match a verified **Sender Signature**, or be on a domain where DKIM has been verified in Postmark. **Where to get your credentials:** 1. Sign in to Postmark → pick (or create) a **Server** 2. Open the server → **API Tokens** tab 3. Copy the **Server API token** — paste it into both Username and Password **Heads-up:** Postmark uses the same token for both fields. Also, Postmark separates "Transactional" and "Broadcast" servers — make sure you're using the token from the right one for your use case. #### Gmail / Google Workspace Convenient for low-volume sending if you already have a Google account, but with strict limits. | Setting | Value | |---|---| | Host | `smtp.gmail.com` | | Port | `465` | | Encryption | Use TLS: **on** (implicit TLS) | | Username | Your full Gmail or Workspace email address | | Password | A **Google App Password** *(not your account password)* | **From address rule:** - **Personal Gmail (`@gmail.com`):** The From address **must be exactly the same as the Gmail account you authenticated with**. Aliases and "Send mail as" addresses are not honored over basic SMTP — Gmail silently rewrites the From header to your real account. - **Google Workspace:** Same default — From must match the authenticated user. To send from a different address on your workspace domain, first add it under **Gmail → Settings → Accounts → "Send mail as"** and complete the verification email. Only then will Workspace accept it as a valid From address over SMTP. **Where to get your credentials:** 1. Make sure **2-Step Verification** is enabled on your Google account (App Passwords aren't available without it) 2. Go to **Google Account → Security → App passwords** 3. Generate a new app password (label it "Communa") and copy the 16-character code — that's your Password **Heads-up:** Daily sending limits are tight: ~500 messages/day on free Gmail, ~2,000/day on Workspace. Going over gets your account temporarily suspended. For volume, use a real transactional provider. #### Resend A modern developer-friendly choice with simple onboarding. | Setting | Value | |---|---| | Host | `smtp.resend.com` | | Port | `465` | | Encryption | Use TLS: **on** (implicit TLS) | | Username | `resend` *(literally the word "resend")* | | Password | Your Resend API key | **From address rule:** Must be on a domain you've verified in your Resend dashboard. The shared `onboarding@resend.dev` address works for quick tests but isn't intended for production traffic. **Where to get your credentials:** 1. Sign in to Resend → **API Keys** → create a key with **Sending access** 2. Verify your domain under **Domains** (add the DNS records they provide) 3. Use `resend` as Username and the API key as Password **Heads-up:** Like SendGrid, the Username is a fixed literal (`resend`), not your email. #### Custom server Use this when your provider isn't in the list, or when you're running your own mail server (Postfix, Microsoft 365, Zoho Mail, FastMail, etc.). | Setting | Value | |---|---| | Host | Provided by your mail service or IT team | | Port | Usually `587` (STARTTLS) or `465` (implicit TLS) | | Encryption | Use TLS: **on** for port 465, **off** for port 587 | | Username | Provided by your mail service | | Password | Provided by your mail service | **From address rule:** Whatever your provider or server allows. Most hosted services (Microsoft 365, Zoho, FastMail) require From to match the authenticated mailbox; self-hosted servers can be more permissive. **Where to get your credentials:** Ask your mail provider or IT team for the SMTP host, port, encryption mode, and a username/password (sometimes called "SMTP submission credentials"). **Heads-up on ports:** Port 465 = "Use TLS" on (the connection is encrypted from the start). Port 587 = "Use TLS" off (the connection upgrades to TLS automatically via STARTTLS). Mixing these up is a common source of "connection failed" errors. > **Tip:** Authenticate your sending domain (SPF + DKIM, ideally DMARC) with your provider **before** going live. The Test button only verifies the connection works — it doesn't check whether your domain is properly authenticated for deliverability. ### What changes once active - **Outbound** mail routes through your SMTP server. The monthly cap and branded footer no longer apply. - **Inbound** mail to `agent-name@mailer.communa.io` keeps working unchanged. Your agent still has an inbox at its platform address. - **Replies** to mail your agent sent through SMTP go to your own inbox (or to the Reply-to address you configured), **not** to the agent. The agent only sees inbound mail addressed to its platform address. - You can **toggle SMTP off** at any time to fall back to the built-in path. The monthly cap and branded footer return only if SMTP is off or your plan doesn't include footer removal. ### Plan availability Custom SMTP is included on **every paid plan**. See the [Billing page](/billing) for plan comparison and to upgrade. ## Mail Settings Open the **Settings** page (click the Settings button in the agent header) and navigate to the **Mail** section to configure: ### Outbound Whitelist For security, agents can only **send** emails to whitelisted addresses by default. The whitelist controls outbound email: - **Team members** — Always allowed (automatically whitelisted) - **The agent's own address** — Always allowed - **Custom addresses** — Add specific email addresses the agent can send to To add an address: 1. Open Mail Settings 2. Enter the email address in the whitelist field 3. Click **Add** The whitelist prevents agents from sending emails to arbitrary addresses — an important safety guardrail. ### Disabling the Whitelist The whitelist is enforced by default and can be disabled for agents that genuinely need to send to arbitrary recipients — customer-facing agents, outreach agents, or lead-response agents, for example. To disable enforcement: 1. Open Mail Settings → **Outbound Email Whitelist** 2. Toggle the **Enforce whitelist** switch off 3. A confirmation dialog appears — review the risks and tick the acknowledgment checkbox 4. Click **Disable whitelist**, then **Save Settings** When disabled, a warning banner appears in the Mail settings and the agent is informed (via its tool description) that it can send to any address. You can re-enable the whitelist at any time — your saved addresses are preserved. > **Warning:** Disabling the whitelist removes a key safety guardrail. AI agents can make mistakes, be affected by prompt injection from inbound emails, or send sensitive data to the wrong recipient. Only disable this if your use case genuinely requires it, and you accept responsibility for every email the agent sends. > **Info:** The whitelist applies to **outbound** emails only. Anyone can send emails *to* the agent regardless of the whitelist setting. The whitelist applies to **both** the built-in path and custom SMTP — switching to your own SMTP server doesn't bypass it. ## Inter-Agent Communication Agents can email each other to create multi-agent workflows: 1. **Agent A** finishes a task and sends results to `agent-b@mailer.communa.io` 2. **Agent B** receives the email — it appears in its inbox 3. If auto-queue is enabled on Agent B, the email becomes a queue item 4. Agent B's schedule triggers, it processes the email, and acts on it This creates asynchronous, observable workflows where each step is logged in the Mail and Runs tabs. ### Example: Research → Analysis Pipeline ``` Researcher Agent → Scrapes data, sends email to Analyst Agent → Analyst receives email, auto-queued → Analyst wakes on schedule, processes data → Sends report email to team member ``` > **Tip:** Agent-to-agent email always uses the built-in path internally — even if both agents have custom SMTP configured. Inboxes live on the platform side, so messages between agents flow through there directly. ## Tips & Best Practices - **Use the built-in path for internal workflows** — Team updates, agent-to-agent messages, and internal reports are exactly what it's designed for - **Switch to custom SMTP for customer-facing email** — Anything going to customers, leads, or external users belongs on your own domain - **Watch the monthly outbound counter** — When you start hitting it, that's a clear sign you've outgrown the built-in path - **Authenticate your domain before going live with SMTP** — SPF + DKIM (and DMARC) are non-negotiable for production deliverability - **Enable auto-queue for task agents** — If the agent processes requests, auto-queue means incoming emails become tasks automatically - **Whitelist carefully** — Only add addresses the agent genuinely needs to send to - **Use descriptive subjects** — When sending tasks to agents via email, clear subject lines help the agent understand and prioritize - **Check sent mail** — Review what your agent is sending to ensure quality and accuracy - **Combine with scheduling** — Auto-queue + scheduled runs = a fully autonomous email-driven agent ## What's Next? - **[Queue](/docs/agents/queue)** — Understand how queued items (including emails) are processed - **[Runs & Scheduling](/docs/agents/runs)** — Set up automatic processing schedules - **[Agent Settings](/docs/agents/settings)** — Configure agent behavior and computer settings --- # Channels Overview > Source: https://communa.io/docs/agents/channels Connect your agent to messaging apps, webhooks, and phone calls so it can operate beyond the dashboard. > **Tip:** Every channel reaches the same agent — with the same tools, skills, credentials, and governed context — through an interface suited to that channel. ## Overview Channels connect your agent to external text conversations, API triggers, and phone calls. People can message it through Telegram or WhatsApp, services can trigger it through Webhook, and callers can speak with it through Voice without opening the Communa dashboard. The agent keeps the same capabilities across these surfaces, while delivery, history, and interaction patterns adapt to each channel. ## Supported Channels | Platform | Status | Notes | |----------|--------|-------| | **Telegram** | ✅ Available | Full support — text, attachments, commands, inline actions | | **WhatsApp** | ✅ Available | Full support — text, attachments, inline actions, read receipts, outbound template messages | | **Voice (Phone)** | ✅ Available | Phone calls via Vapi — real-time spoken conversation with full agent capabilities | | **Webhook** | ✅ Available | Authenticated API endpoint for external systems and automation tools | > See the dedicated **[Telegram](/docs/agents/channels-telegram)**, **[WhatsApp](/docs/agents/channels-whatsapp)**, **[Voice](/docs/agents/channels-voice)**, and **[Webhook](/docs/agents/channels-webhook)** pages for setup guides, features, and troubleshooting. ## The Channels Tab The **Channels** tab in the agent detail page shows a grid of your connected channels. Each connection displays: - **Connection name and identifier** — Such as a Telegram username, WhatsApp number, Voice phone number, or webhook endpoint - **Status badge** — Active, Disabled, Error, or Pending - **Toggle switch** — Enable or disable the connection without removing it - **Test button** — Verify the bot token is still valid and the connection is healthy - **Disconnect** — Remove the connection entirely (with confirmation) Click **Connect Channel** to add a new connection. ## How Channel Activity Flows The exact interaction depends on the channel: - **Telegram and WhatsApp** deliver incoming messages and attachments to the agent, then return its response to the same conversation. - **Voice** transcribes the caller, speaks replies through Vapi, and adds the completed call transcript to the dashboard history. - **Webhook** validates an incoming request, responds immediately, and lets the agent process the trigger in the background. When work requires the agent's computer, it wakes automatically and runs with the same tools, skills, credentials, and context available in the dashboard. Text-channel conversations appear in the dashboard as they happen; Voice transcripts appear after the call. ## Auto-Wake When channel activity needs the agent's computer, Communa starts it automatically: 1. Messaging channels can show a short waking-up status while the computer starts 2. Voice plays the configured greeting while the full agent backend becomes ready 3. The message, call action, or webhook trigger is processed without requiring a dashboard visit This means your agent remains reachable through its connected channels even when its computer is shut down to save resources. > **Info:** Auto-wake respects your plan's concurrent agent limits. If the limit is reached, you'll receive a message asking you to stop another agent or upgrade. ## Sending Attachments Both Telegram and WhatsApp support sending files to your agent: | Type | Telegram | WhatsApp | |------|----------|----------| | **Photos** | ✅ | ✅ | | **Documents** | ✅ PDFs, spreadsheets, any file | ✅ PDFs, spreadsheets, any file | | **Videos** | ✅ | ✅ | | **Voice messages** | ✅ | ✅ | | **Audio files** | ✅ | ✅ | | **Stickers** | ✅ WebP, animated | ✅ WebP | Attachments are automatically downloaded, included in the agent's context, and visible in the agent's **Files** tab. ## Voice Message Transcription Voice messages and audio files sent via Telegram or WhatsApp are **automatically transcribed to text** using AI. Your agent reads the transcript as a regular text message — it can understand and respond to voice naturally, without any extra setup. **Key details:** - **57+ languages supported** — Hebrew, English, Arabic, Spanish, French, and many more. Language is auto-detected from the audio. - **Supported formats** — OGG (Telegram/WhatsApp voice notes), Opus, MP3, M4A, WAV, WebM, FLAC - **Max file size** — 20 MB - **Cost** — ~$0.003 per minute of audio (billed from your credits). A typical 30-second voice message costs less than $0.002. - **Non-blocking** — If transcription fails for any reason, the voice file is still delivered as an attachment so nothing is lost. > **Info:** Voice transcription works identically on both Telegram and WhatsApp. Your agent simply sees the spoken text as the message content. ## Managing Connections ### Enable / Disable Use the toggle switch on a connection card to temporarily disable a channel without removing it. Disabled connections stop receiving messages. Re-enable anytime to resume. ### Test Connection Click **Test** to verify the bot token is still valid and the connection is working. Useful for debugging if messages stop flowing. ### Disconnect Click the **Disconnect** button (trash icon) to permanently remove a connection. This removes the connection and deletes the stored bot token. A confirmation dialog prevents accidental disconnects. ### Status Meanings | Status | Meaning | |--------|---------| | **Active** | Connection is live — messages are being received and processed | | **Disabled** | Connection is paused — messages are not processed | | **Error** | Something went wrong (invalid token, connection failure) — check and reconnect | | **Pending** | Connection is being set up | ## Security Channel connections are designed with security in mind: - **Tokens and credentials are encrypted** with AES-256 and stored in Supabase Vault — never exposed in logs, API responses, or to the AI agent - **Webhook signature verification** — Telegram uses secret-based verification; WhatsApp uses HMAC-SHA256 signature validation (when App Secret is provided) - **Deduplication** — Duplicate messages are automatically filtered to prevent double-processing ## Tips & Best Practices - **Give channel-aware instructions** — Add to your agent's custom instructions: *"When responding via messaging channels, keep messages concise and well-formatted for mobile reading"* - **Check the Files tab** — Attachments sent through Telegram or WhatsApp are stored in your agent's file storage and visible in the Files tab - **Use the dashboard for complex tasks** — Channels are great for quick interactions; for tasks that require watching the desktop preview, use the dashboard - **Monitor from the dashboard** — Text-channel messages appear as they happen, and completed Voice calls add their transcript to the dashboard history - **Combine with scheduling** — An agent can handle channel messages during the day and run scheduled queue processing at night ## What's Next? - **[Telegram Channel](/docs/agents/channels-telegram)** — Setup guide, group chats, bot commands, and Telegram tips - **[WhatsApp Channel](/docs/agents/channels-whatsapp)** — Setup guide, Meta configuration, features, and WhatsApp troubleshooting - **[Voice Channel](/docs/agents/channels-voice)** — Setup guide, Voice settings, model options, and phone call tips - **[Webhook Channel](/docs/agents/channels-webhook)** — API endpoint, authentication, payloads, and trigger handling - **[Chat & Computer](/docs/agents/chat-sandbox)** — The dashboard workspace for direct agent interaction - **[Mail](/docs/agents/mail)** — Agent email and inter-agent communication --- # Telegram Channel > Source: https://communa.io/docs/agents/channels-telegram Connect a Telegram bot to your agent — setup guide, group chats, bot commands, and tips. > **Tip:** Your agent handles Telegram messages exactly like dashboard chat — same tools, same skills, same context. ## Connecting Telegram ### Step 1: Create a Bot via BotFather 1. Open [@BotFather](https://t.me/BotFather) on Telegram 2. Send `/newbot` 3. Follow the prompts — choose a name and username for your bot 4. BotFather gives you a **bot token** (looks like `123456789:ABCdefGHI...`) ### Step 2: Connect in Communa 1. Go to your agent → **Channels** tab 2. Click **Connect Channel** 3. Paste your bot token in the setup drawer 4. Click **Connect Bot** The system validates the token and shows the connection as **Active**. That's it — your bot is live. ### Step 3: Enable Group Chat Access (Optional) If you want your bot to work in **group chats** (not just private 1:1 conversations): 1. Open [@BotFather](https://t.me/BotFather) on Telegram 2. Send `/mybots` → select your bot 3. Go to **Bot Settings** → **Group Privacy** 4. Click **Turn off** > **Why?** By default, Telegram bots run in **Privacy Mode** — they can only see `/commands` in groups, not regular messages. Disabling group privacy allows the bot to receive all group messages, including @mentions. Without this, your bot literally never sees group messages and won't respond. --- ## Telegram Features ### Group Chats Your agent works in Telegram group chats, not just private conversations. Add the bot to any group and interact with it naturally. **How the bot responds in groups** — The bot doesn't respond to every group message, only when **directly addressed**: | Trigger | Example | |---------|---------| | **@mention** | `@YourBot summarize today's updates` | | **Reply to bot** | Reply to any message the bot sent | When you @mention the bot, the `@YourBot` tag is automatically stripped from the message before the agent processes it — so the agent sees clean text. **Group context** — When responding in a group, your agent knows it's in a group chat, sees the group name and sender's name, and tailors its responses accordingly. **Commands in groups** — Telegram appends the bot username to disambiguate when multiple bots are present: | Command | What It Does | |---------|-------------| | `/start@YourBot` | Welcome message | | `/stop@YourBot` | Cancel the active task | | `/help@YourBot` | Show help | > **Important:** Make sure you've disabled Group Privacy in BotFather (Step 3 in setup). Without this, Telegram blocks all non-command messages in groups. ### Bot Commands Your Telegram bot automatically registers these commands (visible when typing `/` in the chat): | Command | What It Does | |---------|-------------| | `/start` | Sends a welcome message introducing the bot | | `/stop` | Cancels the currently active task | | `/help` | Shows a brief help message | ### Voice Messages Send a voice message to your bot and it's **automatically transcribed** — the agent reads it as regular text and responds naturally. - Works in both **private chats** and **group chats** - Language is **auto-detected** (Hebrew, English, Arabic, and 50+ more) - Audio files sent as documents (`.mp3`, `.m4a`, `.wav`, etc.) are also transcribed - Cost: ~$0.003 per minute of audio, billed from your credits > **Info:** If transcription fails for any reason, the audio file is still delivered as an attachment. ### Stopping from Telegram - **`/stop` command** — Type `/stop` to cancel the active task. You'll see "⏹ Task stopped." - **Inline Stop button** — The first message of each agent response includes a **⏹ Stop** button. Tap it to cancel. The button is removed when the task completes. --- ## Tips & Best Practices - **Test with /start first** — After connecting, send `/start` to your bot to verify everything is working - **Bot not responding in groups?** — Make sure Group Privacy is disabled in BotFather (`/mybots` → Bot Settings → Group Privacy → Turn off) - **Keep messages concise** — Add to your agent's custom instructions: *"When responding via Telegram, keep messages concise and well-formatted for mobile reading"* - **Use the dashboard for complex tasks** — Telegram is great for quick interactions; for tasks that require watching the desktop preview, use the dashboard ## What's Next? - **[Channels Overview](/docs/agents/channels)** — Shared channel features, attachments, auto-wake, and connection management - **[WhatsApp Channel](/docs/agents/channels-whatsapp)** — Connect your agent via WhatsApp - **[Voice Channel](/docs/agents/channels-voice)** — Connect your agent via phone calls - **[Chat & Computer](/docs/agents/chat-sandbox)** — The dashboard workspace for direct agent interaction --- # WhatsApp Channel > Source: https://communa.io/docs/agents/channels-whatsapp Connect WhatsApp Business to your agent — Meta setup guide, features, outbound template messaging, and troubleshooting. > **Tip:** Your agent handles WhatsApp messages exactly like dashboard chat — same tools, same skills, same context. ## Connecting WhatsApp WhatsApp integration uses the official **Meta WhatsApp Business Cloud API**. The setup requires creating a Meta App and configuring a few pieces — it takes about 10–15 minutes the first time, but you only need to do it once. ### Before You Start You'll need: - A **Facebook account** (your personal account is fine) - A **phone number** that can receive an SMS or voice call for verification - That phone number **must NOT be currently registered with WhatsApp** (personal or business). If you want to use your existing number, you must first delete your WhatsApp account on that number. Alternatively, use a new number or Meta's free test number for development. > **Info:** If you don't have a Meta Business Portfolio yet, one will be created for you automatically during the app creation process. ### Step 1: Create a Meta App 1. Go to [developers.facebook.com](https://developers.facebook.com/) and log in with your Facebook account 2. Click **My Apps** in the top navigation, then **Create App** 3. Under **"What do you want your app to do?"**, select **Other**, then click **Next** 4. Select app type: **Business** — then click **Next** 5. Enter an app name (e.g., "My Communa Agent") and your contact email 6. If prompted, select or create a **Business Portfolio** (this links your app to your business) 7. Click **Create App** You'll land on the **App Dashboard**. This is where you'll manage everything. ### Step 2: Set Up the WhatsApp Use Case 1. In the App Dashboard, click **Use cases** in the left sidebar 2. Find **Connect on WhatsApp** and click the **Customize** button 3. If prompted to select a Business Portfolio, choose the same one from Step 1 4. You'll land in the WhatsApp configuration panel — the left submenu shows **Quickstart**, **API Setup**, **Configuration**, and other sub-pages ### Step 3: Get Your Phone Number ID In the WhatsApp configuration panel, click **API Setup** in the left submenu. You'll see a section called **"Send and receive messages"**. 1. Under **"From"**, you'll see a dropdown with a test phone number provided by Meta 2. Below the dropdown, you'll see the **Phone Number ID** — a numeric string like `100234567890123` 3. **Copy this Phone Number ID** — you'll need it when connecting in Communa > **About test numbers:** Meta provides a free test phone number. It works for development, but has limitations: you can only send messages to up to 5 phone numbers that you pre-register in the **"To"** field on this same page. For production use, you'll add your own business phone number later. ### Step 4: Create a System User & Generate a Permanent Access Token This is the most important step. The **temporary token** shown on the Getting Started page expires after 24 hours. For a reliable connection, you need a **permanent token** from a System User. #### Create a System User 1. Open [business.facebook.com/settings](https://business.facebook.com/settings) (Meta Business Settings) 2. In the left sidebar, navigate to **Users → System users** 3. Click **Add** to create a new system user 4. Enter a name (e.g., `communa-agent`) and set the role to **Admin** 5. Click **Create system user** #### Assign the WhatsApp App to the System User 1. Click on the system user you just created 2. Click **Add assets** 3. Select **Apps** from the asset type 4. Find and select the app you created in Step 1 5. Enable **Full control** (Manage app) 6. Click **Save changes** #### Generate a Permanent Token 1. Still on the system user page, click **Generate new token** 2. Select the **app** you created in Step 1 3. Set token expiration to **Never** (this creates a permanent token) 4. Select these **permissions** (check both): - `whatsapp_business_messaging` — allows sending and receiving messages - `whatsapp_business_management` — allows subscribing to your WhatsApp Business Account for webhook delivery 5. Click **Generate token** 6. **Copy the token immediately** and save it somewhere safe > **⚠️ Important:** You will only see this token once. If you close the dialog without copying it, you'll need to generate a new one. The token will look like `EAABs...` and will be quite long. ### Step 5: Get Your WhatsApp Business Account (WABA) ID The WABA ID is needed so Communa can subscribe to your WhatsApp Business Account for message delivery. 1. In [business.facebook.com/settings](https://business.facebook.com/settings), go to **Accounts → WhatsApp Accounts** in the left sidebar 2. Click on your WhatsApp Business Account 3. The **WABA ID** is a numeric string shown on the page (e.g., `109876543210`) — you can also find it in the URL: `business.facebook.com/settings/whatsapp-business-accounts/WABA_ID` 4. **Copy this WABA ID** ### Step 6: Connect in Communa Now you have everything needed. Head to Communa: 1. Go to your agent → **Channels** tab 2. Click **Connect Channel** → select the **WhatsApp** tab 3. Fill in the fields: - **Access Token** — the permanent token from Step 4 - **Phone Number ID** — from Step 3 - **WABA ID** — from Step 5 - **App Secret** (recommended) — found in Meta App Dashboard → **App Settings** (gear icon at the bottom of the left sidebar) → **Basic** → **App Secret** (click "Show" to reveal it). This enables webhook signature verification for security. 4. Click **Connect WhatsApp** Communa will validate your credentials, verify the phone number, and subscribe your app to the WABA. If successful, you'll see the connection as **Active**. > **Webhook URL & Verify Token:** After clicking Connect, the setup drawer shows the full **Webhook URL** and a pre-generated **Verify Token** — both with copy buttons. You'll need both values in the next step. Copy them before closing the drawer. ### Step 7: Configure the Webhook in Meta This final step tells Meta where to send incoming messages. 1. Go back to [developers.facebook.com](https://developers.facebook.com/) → your app 2. In the left sidebar, click **Use cases** → find **Connect on WhatsApp** → click **Customize** 3. In the left submenu, click **Configuration** 4. Under the **Webhook** section, click **Edit** 5. Enter these values: - **Callback URL:** `https://communa.io/api/webhooks/whatsapp` — this is always our production URL. You can copy it directly from the setup drawer. - **Verify token:** The verify token shown after connecting in Step 6 6. Click **Verify and save** — Meta will send a verification request to your URL, and if the token matches, it will confirm 7. After verification, scroll down to the **Webhook fields** table. Find the **messages** row and click **Subscribe** in its Subscribe column > **⚠️ You must subscribe to the "messages" webhook field.** Without this subscription, Meta won't forward incoming messages to your webhook URL, and your agent won't receive any WhatsApp messages. You'll see a list of available fields (like `account_alerts`, `message_template_status_update`, `messages`, etc.) — make sure **messages** has a checkmark in the Subscribe column. That's it — your WhatsApp channel is now fully connected and live! ### Test Your Connection 1. Open WhatsApp on your phone 2. Send a message to the business phone number shown in your Communa connection card 3. Your agent should wake up and respond > **If using the test number:** Remember, Meta's test number can only receive messages from the phone numbers you've pre-registered in the Meta App Dashboard → WhatsApp → Getting Started → **"To"** field. Add your phone number there first. --- ## WhatsApp Features ### How WhatsApp Conversations Work WhatsApp conversations work slightly differently from Telegram: - **No bot commands** — WhatsApp doesn't have a `/command` system. Just send normal messages. - **Read receipts** — Your agent automatically marks messages as read (blue double-check marks) when they're received. - **Inline Stop button** — Like Telegram, the first response message includes a **⏹ Stop** button to cancel the active task. - **Group chats** — If the business number is added to a WhatsApp group, all messages in the group are processed by the agent. - **Outbound templates** — Your agent can proactively send pre-approved template messages to contacts, even after the 24-hour window. See [Template Messages](#template-messages-outbound) below. ### Voice Messages Send a voice note to your agent and it's **automatically transcribed** — the agent reads it as regular text and responds naturally. - WhatsApp voice notes (OGG/Opus format) are **fully supported** - Language is **auto-detected** (Hebrew, English, Arabic, and 50+ more) - Audio files sent as attachments (`.mp3`, `.m4a`, `.wav`, etc.) are also transcribed - Cost: ~$0.003 per minute of audio, billed from your credits > **Info:** If transcription fails for any reason, the audio file is still delivered as an attachment. ### WhatsApp Message Limits WhatsApp has a **4,096-character limit** per message (same as Telegram). Long responses are automatically split into multiple messages at natural paragraph boundaries. ### Test Number Limitations If you're using Meta's free test phone number: - You can only send messages **to up to 5 pre-registered phone numbers** - Register recipient numbers in Meta Dashboard → WhatsApp → Getting Started → "To" field - The test number has a lower rate limit than production numbers - For production use, add and verify your own business phone number in the Meta Dashboard --- ## Template Messages (Outbound) Your agent can **proactively send messages** to WhatsApp contacts using pre-approved **Message Templates**. This is how you reach out to customers — whether it's sending appointment confirmations, order updates, follow-up messages, or marketing campaigns. ### Why Templates? WhatsApp has a strict **24-hour messaging window**. After a contact messages your agent, you can reply freely for 24 hours. But once that window closes, the only way to reach out is through a **pre-approved template**. Templates are reviewed and approved by Meta before they can be used. This ensures quality and prevents spam — but it also means templates are the key to proactive outbound communication. ### Template Categories Meta organizes templates into categories, each with different pricing and approval criteria: | Category | Use Case | Examples | |----------|----------|---------| | **Utility** | Transaction updates, account notifications | Order confirmations, shipping updates, appointment reminders | | **Marketing** | Promotions, offers, re-engagement | Product launches, special offers, newsletters | | **Authentication** | Login verification, security codes | OTP codes, password resets | > **Info:** Utility templates are generally approved faster and cost less than Marketing templates. Choose the right category when creating templates in Meta. ### Setting Up Templates #### 1. Create Templates in Meta 1. Go to [Meta Business Suite → Message Templates](https://business.facebook.com/wa/manage/message-templates/) 2. Click **Create Template** 3. Choose a category, name, and language 4. Write your template body — use placeholders like `{{customer_name}}` or `{{order_id}}` for dynamic content 5. Submit for review — Meta typically approves templates within minutes to a few hours > **Tip:** Use descriptive placeholder names like `{{appointment_date}}` instead of generic `{{1}}`. This makes it easier for both you and the AI to understand what goes where. #### 2. Sync Templates into Communa Once your templates are approved in Meta: 1. Go to your agent → **Settings** tab → scroll to the **WhatsApp** section 2. Click **Sync from Meta** — this pulls all your approved templates 3. You'll see each template listed with its name, category, and body text #### 3. Configure Each Template Click on a template to expand its configuration: - **Enable/Disable toggle** — Only enabled templates are available to the AI - **"When should the AI use this template?"** — Write a clear description of when this template should be sent. The AI reads this to decide which template fits the situation. - Good: *"Use to confirm an appointment with a customer, including date and time"* - Bad: *"Appointment template"* (too vague) - **Parameter Labels** — The name the AI sees for each placeholder. Keep these descriptive (e.g., `customer_name`, `appointment_date`) - **AI Guidance** — Additional context for each parameter to help the AI fill in the right value (e.g., *"The customer's full name as it appears in the conversation"*) #### 4. Save Settings Click **Save Settings** at the bottom. Your templates are now live. > **⚠️ Important:** Only templates that are both **enabled** and have a **description** will be available to the AI. If you enable a template but leave the description empty, the AI won't know when to use it. ### How the AI Uses Templates Once configured, the AI automatically decides when to send a template based on the context of the conversation: 1. The AI evaluates the situation and matches it to a template's description 2. It fills in the parameters using information from the conversation 3. The template message is sent to the contact on WhatsApp 4. This works **even after the 24-hour window has expired** — that's the whole point You don't need to tell the AI "send a template" — it understands when a template is appropriate based on the descriptions you wrote. Of course, you can also instruct it to send specific templates in your agent's custom instructions. > **Info:** The contact must have messaged your agent at least once. Templates can only be sent to existing conversations. ### Template Tips - **Keep descriptions specific** — The better your template descriptions, the more accurately the AI will choose the right template at the right time - **Resync after changes** — If you edit or add templates in Meta, click "Sync from Meta" again to pull the latest versions - **Test with utility templates first** — They're cheaper and approved faster. Great for getting the flow right before adding marketing templates. - **Check parameter labels** — After syncing, review that the parameter labels make sense. The AI uses these labels to understand what data each placeholder expects. - **Template costs** — Meta charges per template message sent (rates vary by category and country). Check [Meta's pricing page](https://developers.facebook.com/docs/whatsapp/pricing) for current rates. --- ## Troubleshooting ### Messages Not Arriving | Symptom | Likely Cause | Fix | |---------|-------------|-----| | Agent never responds | Webhook not configured | Complete Step 7 — set the callback URL and subscribe to "messages" | | Agent never responds | App not subscribed to WABA | Make sure you provided the WABA ID when connecting in Communa | | Agent never responds | Verify token mismatch | Disconnect and reconnect in Communa, then update the verify token in Meta | | Agent never responds | Using test number without registering recipient | Add your phone number in Meta Dashboard → WhatsApp → Getting Started → "To" field | ### "Invalid Token" Error When Connecting | Symptom | Likely Cause | Fix | |---------|-------------|-----| | Invalid token error | Using the 24-hour temporary token | Generate a permanent token via System User (Step 4) | | Invalid token error | Token missing required permissions | Regenerate with both `whatsapp_business_messaging` and `whatsapp_business_management` | | Invalid token error | Phone Number ID doesn't match the token's app | Ensure the Phone Number ID belongs to the same WABA that the system user has access to | ### Template Messages Not Sending | Symptom | Likely Cause | Fix | |---------|-------------|-----| | AI never sends templates | No templates enabled | Go to Settings → WhatsApp and enable at least one template | | AI never sends templates | Template has no description | Add a "When should the AI use this?" description for the template | | AI never sends templates | Templates not synced | Click "Sync from Meta" in WhatsApp settings | | Template not appearing after sync | Template not yet approved in Meta | Check the template status in Meta Business Suite — only approved templates are synced | | Wrong data in template fields | Parameter labels are unclear | Update the parameter labels and AI guidance to be more specific | | Template fails to send | Contact has never messaged the agent | The contact must have initiated at least one conversation with your agent first | ### "WABA Subscription Failed" Error This means Communa couldn't subscribe your app to the WhatsApp Business Account: - **"Access token is invalid or expired"** — Your token has expired. Generate a new permanent token (Step 4). - **"whatsapp_business_management permission required"** — Your token is missing a permission. Regenerate it with both permissions checked (Step 4). - **Wrong WABA ID** — Double-check the WABA ID in Business Settings → WhatsApp Accounts. ### Webhook Verification Fails in Meta When you click "Verify and save" in Meta's webhook configuration: - The callback URL must be exactly `https://communa.io/api/webhooks/whatsapp` — do not use localhost or a custom domain - Ensure the **Verify Token** matches exactly — copy it from Communa, don't type it manually - Check that the callback URL path is exactly `/api/webhooks/whatsapp` (no trailing slash) --- ## Tips & Best Practices - **Always use a permanent token** — The temporary token from Meta's Getting Started page expires in 24 hours. Use a System User permanent token for production. - **Don't forget the webhook** — The most common issue is forgetting to configure the webhook URL and subscribe to the "messages" field in Meta's dashboard - **Keep your App Secret configured** — While optional, the App Secret enables webhook signature verification, which protects against spoofed messages - **Moving to production?** — When you're ready to use your own phone number instead of Meta's test number, go to WhatsApp → Getting Started → add a phone number and complete verification - **Keep messages concise** — Add to your agent's custom instructions: *"When responding via WhatsApp, keep messages concise and well-formatted for mobile reading"* ## What's Next? - **[Channels Overview](/docs/agents/channels)** — Shared channel features, attachments, auto-wake, and connection management - **[Telegram Channel](/docs/agents/channels-telegram)** — Connect your agent via Telegram - **[Voice Channel](/docs/agents/channels-voice)** — Connect your agent via phone calls - **[Chat & Computer](/docs/agents/chat-sandbox)** — The dashboard workspace for direct agent interaction --- # Voice Channel (Phone) > Source: https://communa.io/docs/agents/channels-voice Connect a Vapi phone number and configure your agent's greeting, behavior, context, call experience, and recording controls. > **Tip:** Your agent handles phone calls with the same tools, skills, credentials, and context it has in the dashboard. The only difference is the interface — voice instead of text. ## Connecting Voice The Voice channel uses **Vapi** to handle phone calls. Vapi manages the telephony layer (STT → LLM → TTS) while your agent provides the intelligence. ### Step 1: Create a Vapi Account 1. Go to [vapi.ai](https://vapi.ai) and create an account 2. In the Vapi dashboard, navigate to **Dashboard → API Keys** 3. Copy your **API key** — you'll need it when connecting in Communa ### Step 2: Add a Phone Number in Vapi You need a phone number for callers to reach your agent: 1. In the Vapi dashboard, go to **Phone Numbers** 2. Click **Add Phone Number** 3. Choose a provider — Vapi offers built-in numbers, or you can connect your own via **Twilio** or **Vonage** 4. Follow the prompts to provision a number > **Info:** Vapi's built-in numbers are the easiest way to get started. For production use with specific area codes or international numbers, connect a Twilio or Vonage account. ### Step 3: Connect in Communa 1. Go to your agent → **Channels** 2. Click **Connect Channel** → select **Voice** 3. Paste your **Vapi API key**, then click **Validate & Load Numbers** 4. Select one of the phone numbers loaded from your Vapi account 5. Click **Connect Voice** Communa automatically registers the webhook on the selected Vapi phone number — no manual webhook configuration is needed. After connecting, open **Settings → Voice** to configure the greeting, transcription language, conversation model, context, instructions, and call experience. ### Test Your Connection Call the phone number shown on your connection card. Your agent should pick up, speak the greeting message, and be ready to converse. --- ## How It Works The Voice channel combines a low-latency conversation model with your full Communa agent: 1. The caller speaks and Vapi transcribes the audio to text (STT) 2. The selected **conversation model** handles turn-taking and direct conversational replies 3. Vapi converts the reply to speech (TTS) and plays it to the caller 4. When the caller asks the agent to **do** something — such as check email, run a script, or look up data — the conversation model invokes the `agent_action` tool 5. Your full Communa agent runs the action with its configured Chat model, tools, skills, credentials, and context, then returns the result to the call The Voice conversation model is therefore not a replacement for the agent's Chat model. It keeps the call responsive and routes operational work to the full agent backend. --- ## Model Options Choose which LLM powers the voice conversation. Communa exposes a curated set of Vapi models verified for the managed STT → LLM → TTS flow and tool calling. Realtime, experimental, regional, and duplicate alias IDs are intentionally hidden. ### OpenAI | Model family | Available options | |--------------|-------------------| | **GPT-5.6** | Sol (high intelligence), Terra (balanced), Luna (fast and affordable) | | **GPT-5** | GPT-5.4, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.2, GPT-5.1, GPT-5, GPT-5 Mini, GPT-5 Nano | | **Reasoning** | o3, o4 Mini | | **GPT-4** | GPT-4o, GPT-4o Mini, GPT-4.1, GPT-4.1 Mini, GPT-4.1 Nano, GPT-4 Turbo | | **Legacy compatibility** | GPT-3.5 Turbo | ### Anthropic | Model | Notes | |-------|-------| | **Claude Sonnet 4.6** | Default Anthropic option | | **Claude Sonnet 4.5** | Balanced performance | | **Claude Opus 4.6** | Advanced reasoning | | **Claude Haiku 4.5** | Fast, cost-effective | | **Claude 3.5 Sonnet / Haiku** | Legacy compatibility | ### Google | Model | Notes | |-------|-------| | **Gemini 3 Flash** | New-generation fast model | | **Gemini 2.5 Flash** | Default Google option | | **Gemini 2.5 Flash Lite** | Lightweight, low-latency option | | **Gemini 2.5 Pro** | Advanced reasoning | | **Gemini 2.0 Flash** | Previous generation | | **Gemini 1.5 Flash / Pro** | Legacy compatibility | > **Info:** The conversation model handles turn-taking and general responses. When tools are invoked, the agent uses its configured model from the Chat settings. GPT-4o remains Communa's stable default and fallback; GPT-5.6 variants are optional choices for higher intelligence, balance, or lower latency and cost. Newly announced Vapi models are added only after their exact API IDs are verified against Vapi's public API documentation and transient-assistant flow. --- ## Voice Settings After connecting the channel, open **Settings → Voice**. The settings are organized into three focused tabs, and one Save action persists the complete Voice configuration. ### General - **Greeting message** — The first thing callers hear. Leave it empty to use a dynamic greeting that includes the caller's name when available. - **Transcription language** — Optimizes speech recognition for the primary language callers use. - **Maximum call duration** — Sets a limit from 1 minute to 2 hours; the default is 30 minutes. ### Behavior - **Conversation model** — Selects the low-latency model that handles turn-taking and conversational replies. Tool-backed work still runs through the full agent and its configured Chat model. - **Conversation context** — Controls which history the agent can use during a call. - **Voice processing instructions** — Defines call-specific tone, interaction style, confirmation rules, scripts, and language preferences. Communa automatically adds spoken-output guardrails for TTS, including concise speech-friendly formatting. You do not need to duplicate those rules in your Voice processing instructions. #### Conversation Context Modes | Mode | What the agent can see | Best for | |------|-------------------------|----------| | **Session Isolated** | Only the current call, plus relevant scheduled-job follow-up context | Secure default for agents used by multiple callers | | **User History** | The same linked person's history across Voice, Telegram, WhatsApp, and the dashboard Main tab | Personalized service across channels | | **Shared History** | Messages from all channels, users, and conversations | Single-user agents only | > **Important:** User History only joins identities that are linked or merged into one Person. Unlinked callers remain separate. Purpose-built dashboard side tabs and group conversations also stay isolated. ### Experience - **Conversation pace** — Choose Responsive, Balanced, or Patient. Balanced is recommended for most agents. - **While the agent works** — Customize the immediate acknowledgment, up to five progressively timed updates, and the failure message spoken during an agent action. - **Caller silence** — Optionally ask whether an inactive caller is still there, then end abandoned calls after a separate silence limit. - **Call recording** — Enable or disable Vapi recording for this agent. Waiting messages and caller-silence messages solve different problems. Waiting messages play while an agent action is running; silence messages re-engage a caller who has stopped speaking. Waiting-message delays are elapsed milestones rather than repeating intervals. ### Reset to Defaults Use **Reset** in Behavior to restore the recommended Voice processing instructions. In Experience, use **Reset recommended defaults** to restore pacing, progress messages, silence handling, and recording defaults. --- ## Features ### Auto-Wake When your agent is sleeping and a call comes in: 1. The computer is **automatically started** — no dashboard visit needed 2. The greeting message plays while the computer warms up 3. The agent is ready to handle the call with full capabilities This means your agent is effectively **always reachable by phone**, even when its computer is shut down to save resources. ### Greeting Message The first thing callers hear when the call connects. Configure it in the agent's Voice settings. If left empty, Communa uses a dynamic greeting that includes the caller's name when available. ### Speech-to-Text (STT) Powered by **Deepgram Nova-3**. Configure the primary language under **Settings → Voice → General**: - **English** (default), Hebrew, Spanish, French, German, Arabic, and many more - Language selection optimizes recognition accuracy for the primary spoken language - The agent itself can respond in any language based on its instructions ### Text-to-Speech (TTS) The current Communa integration uses **OpenAI Alloy** — a natural, conversational voice. A dedicated provider-backed voice selector and audio preview are planned separately; voice identity is not yet configurable from the agent settings UI. ### Call Duration Default maximum: **30 minutes** per call. Configure it in the agent's Voice settings. After the maximum duration, the call ends gracefully. ### Call Recording Enabled by default and configurable under **Settings → Voice → Experience**. Call recordings are captured by Vapi and can support quality assurance and training. You are responsible for consent, disclosure, retention, and access requirements in every jurisdiction where the agent operates. ### End-Call Function The agent can hang up the call when appropriate — for example, after saying goodbye or when the caller's needs are fully addressed. This is handled automatically by Vapi's end-call function. ### Silence Handling By default, sustained caller silence ends the call after **30 seconds**. You can change this limit and optionally add a caller check-in such as “Are you still there?” Keep enough time between the final check-in and the hard cutoff so the caller can respond. --- ## How Voice Differs from Text Channels | Feature | Telegram / WhatsApp | Voice | |---------|-------------------|-------| | **Message format** | Text + attachments | Spoken audio (STT/TTS) | | **File attachments** | ✅ Photos, docs, videos | ❌ Audio only | | **`send_channel_message`** | ✅ Used for outbound messages | ❌ Vapi handles audio delivery | | **Bot commands** | ✅ Telegram: /start, /stop, /help | ❌ Not applicable | | **Group chats** | ✅ Telegram groups | ❌ 1:1 calls only | | **Conversation history** | Messages appear in dashboard chat | Call transcript appears after call ends | | **Latency** | Near-instant text delivery | Low latency with smart turn-taking | --- ## Tips & Best Practices - **Choose the right model** — GPT-4o is a great default. For simpler use cases, GPT-4o Mini offers faster responses at lower cost. - **Test your greeting message** — Call your agent and listen to the first impression. A good greeting sets the tone for the entire call. - **Keep voice instructions focused** — Unlike text chat, callers can't scroll back. Instruct your agent to be concise and confirm understanding. - **Acknowledge long actions** — Keep a short initial acknowledgment and progressively spaced waiting updates so callers know the agent is still working. - **Start with Balanced pacing** — Move to Responsive only when speed matters more than accommodating natural pauses; use Patient for callers who pause while recalling details. - **Set the right STT language** — If your callers primarily speak a non-English language, set the STT language accordingly for better recognition accuracy. - **Combine with other channels** — An agent can handle phone calls during business hours and process Telegram/WhatsApp messages anytime. Use the voice channel for high-touch interactions and text channels for async communication. - **Monitor from the dashboard** — While a call is in progress, you can observe the agent's actions in the dashboard chat in real time. ## What's Next? - **[Channels Overview](/docs/agents/channels)** — Shared channel features, auto-wake, and connection management - **[Telegram Channel](/docs/agents/channels-telegram)** — Connect your agent via Telegram - **[WhatsApp Channel](/docs/agents/channels-whatsapp)** — Connect your agent via WhatsApp - **[Chat & Computer](/docs/agents/chat-sandbox)** — The dashboard workspace for direct agent interaction --- # Webhook / API Channel > Source: https://communa.io/docs/agents/channels-webhook Trigger your agent from any external service with an inbound webhook — auth modes, payload shapes, custom handling instructions, and curl examples. > **Tip:** The Webhook channel gives your agent a unique inbound URL. Any external service (Zapier, n8n, Stripe, your own backend) can POST JSON to it to invoke the agent. The endpoint responds immediately — the agent processes in the background. ## How It Works 1. You connect a **Webhook / API** channel and get a unique endpoint URL scoped to this agent. 2. An external service POSTs a JSON body to that URL. 3. Communa verifies the request (based on your chosen auth mode and the credential **you entered**), then returns **202 Accepted** right away. 4. The agent processes the payload in the background — using the same tools, skills, and context as dashboard chat. Because the response is immediate and async, this works cleanly for long-running agent jobs. There is no synchronous reply body; the agent acts on the payload (sends emails, updates datasets, calls integrations, etc.). --- ## Connecting a Webhook 1. Go to your agent → **Channels** tab 2. Click **Connect Channel** → select **Webhook** 3. Choose an **Authentication** mode and **enter the credential** your calling service will send (see below) 4. Click **Create Webhook** 5. Copy the **Endpoint URL** — then start POSTing with the credential you entered > **You own the credential:** For **Bearer**, **Header** and **Basic** auth you type the exact secret your caller will send — Communa stores it securely and compares each incoming request against it. Nothing is generated for you, so there's no one-time reveal to miss. Only the advanced **Signed (HMAC)** mode generates a signing secret (shown once on creation). --- ## Authentication Modes | Mode | You enter | How the caller authenticates | Best for | |------|-----------|------------------------------|----------| | **Bearer token** *(recommended)* | A token | `Authorization: Bearer ` | Zapier, most custom APIs and scripts | | **Header auth** | Header name + value | `: ` (e.g. `X-API-Key`) | n8n Header Auth, Make, tools that only allow custom headers | | **Basic auth** | Username + password | `Authorization: Basic base64(user:pass)` | Tools with built-in HTTP Basic auth | | **Signature (HMAC)** *(advanced)* | — (generated for you) | `X-Communa-Signature: t=,v1=` over the raw body | Custom backends that verify a signature | | **Provider signature** | Provider secret + header + scheme | The provider's own signature header (e.g. `Stripe-Signature`) | Stripe, GitHub, Meta webhooks | | **None** | — | URL secret only (unguessable path) | Prototyping only — not for production | For **Bearer**, **Header** and **Basic** modes, always serve your endpoint over HTTPS — the credential travels on the wire. For **Signature (HMAC)** mode the signature is computed as `HMAC-SHA256(secret, ".")` and the timestamp must be within a few minutes of server time (replay protection). The secret is generated by Communa and shown once. For **Provider signature** mode you supply the provider's signing secret, the header name they use, and the scheme (hex, base64, or Stripe-style timestamped). --- ## Payload Shapes The webhook accepts **either** of these: ### 1. A natural-language message ```json { "message": "Summarize today's new signups and email me the report" } ``` Auto-detected fields: `message`, `text`, or `prompt`. You can also set a custom **Message Field** dot-path (e.g. `input.message`) in the setup drawer. ### 2. Structured fields ```json { "event": "order.created", "order_id": "ord_123", "amount": 4999, "customer_email": "jane@acme.com" } ``` When there is no message field, the entire payload is passed to the agent as a structured trigger block. You tell the agent how to interpret it via **handling instructions** (below). The full raw payload is always preserved and available to the agent, regardless of which shape you send. --- ## Handling Instructions Just like the Mail channel, you can give the agent **custom webhook handling instructions** so it knows what to do with each incoming trigger. 1. Go to your agent → **Settings** → **Webhook / API** 2. Write instructions in plain language, for example: > *"Each webhook is a new e-commerce order. Look up the customer in the People dataset, then send them a personalized thank-you email. If the order amount is over $500, also notify the sales team on Slack."* 3. Save. These instructions are injected into the agent's context on every webhook trigger. The agent can also update its own webhook handling instructions when you ask it to during a chat. --- ## Examples ### Bearer token Use the token you entered when connecting. ```bash curl -X POST https://app.communa.io/api/webhooks/agent/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "message": "Draft a weekly summary and email it to me" }' ``` ### Header auth + structured payload You choose both the header name (e.g. `X-API-Key`) and its value when connecting. ```bash curl -X POST https://app.communa.io/api/webhooks/agent/ \ -H "X-API-Key: " \ -H "Content-Type: application/json" \ -d '{ "event": "lead.created", "name": "Jane Doe", "email": "jane@acme.com", "company": "Acme Inc" }' ``` ### Basic auth Use the username and password you entered when connecting. ```bash curl -X POST https://app.communa.io/api/webhooks/agent/ \ -u ":" \ -H "Content-Type: application/json" \ -d '{ "message": "Process the new order" }' ``` ### Signature (HMAC) — advanced ```bash # Compute the signature over "." TS=$(date +%s) BODY='{"message":"Process the new lead"}' SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "" | awk '{print $2}') curl -X POST https://app.communa.io/api/webhooks/agent/ \ -H "X-Communa-Signature: t=$TS,v1=$SIG" \ -H "Content-Type: application/json" \ -d "$BODY" ``` ### Expected response ```json { "accepted": true } ``` The endpoint returns **202 Accepted** immediately. The agent runs asynchronously — track progress in the agent's **Runs** tab. --- ## Tips & Best Practices - **Always use HTTPS** — Bearer, Header and Basic modes send the credential on the wire. Signed (HMAC) never sends the secret, so it's the strongest option for backends you control. - **Avoid "None" in production** — it relies only on the secret URL and offers no request integrity. - **Keep payloads reasonable** — very large bodies are rejected. Send only the fields the agent needs. - **Write clear handling instructions** — the more specific your Settings → Webhook / API instructions, the more reliable the agent's behavior. - **Watch the Runs tab** — since responses are async, use Runs to confirm the agent received and processed each trigger. - **Rotate a leaked credential** — disconnect and reconnect the channel with a new credential. ## What's Next? - **[Channels Overview](/docs/agents/channels)** — Shared channel features, attachments, auto-wake, and connection management - **[Telegram Channel](/docs/agents/channels-telegram)** — Connect your agent via a Telegram bot - **[Mail](/docs/agents/mail)** — Give your agent its own email address with handling instructions - **[API Overview](/docs/api/overview)** — The full HTTP API for datasets and more --- # Queue > Source: https://communa.io/docs/agents/queue Manage your agent's task queue — add items manually, from emails, or from other agents, and process them on schedule. > **Tip:** The queue is managed through the UI and automated via schedules. Your agent processes queue items automatically when a schedule is enabled — you can also click **Process** on any item to start it manually. ## Overview The **Queue** is a prioritized task list that agents process sequentially. Each agent has its own queue where items wait to be handled. The queue is the foundation of autonomous agent operation — it's how agents know what to work on next. ## How Items Enter the Queue Items can be added to the queue from several sources: | Source | How It Works | |--------|-------------| | **Manual** | Add items directly through the Queue tab UI | | **Email** | When auto-queue is enabled, incoming emails become queue items automatically | | **Scheduled Jobs** | Time-based triggers inject prompts into the queue at configured times — see **[Schedule](/docs/agents/schedule)** | | **Other agents** | An agent sends an email to this agent → auto-queued for processing | ### Adding Items Manually 1. Open the **Queue** tab (accessible from the agent page or sidebar) 2. Click **Add Item** 3. Enter a description of the task 4. The item appears at the bottom of the queue ### From Email When **Auto-Queue Incoming Emails** is enabled in the Mail settings: 1. An email arrives at the agent's address 2. The email is automatically added as a queue item 3. The item includes the email subject, sender, and content 4. On the next processing run, the agent reads the email and acts on it ## The Queue Interface The Queue tab shows all pending and completed items: ### Drag-and-Drop Ordering **Drag items** to reorder them. The agent processes items from top to bottom, so reordering lets you prioritize what gets handled first. ### Bulk Actions Select multiple items for bulk operations: - **Delete selected** — Remove items from the queue - **Show/Hide completed** — Toggle visibility of processed items ## How Processing Works Queue processing can be triggered two ways: ### Manual Processing Click the **Process** button on a queue item to start processing it immediately. The agent: 1. Takes the top item from the queue 2. Creates a dedicated chat session for the task 3. Reads the item content and acts on it using all available tools 4. Marks the item as completed 5. Moves to the next item ### Auto Processing When auto processing is configured, the system automatically processes the queue at regular intervals: 1. The cron system triggers at the scheduled time 2. A computer is started automatically (no human needed) 3. The agent processes items sequentially — up to the configured maximum per run 4. Each item gets its own chat session for full traceability 5. After processing, the computer stays warm for the next run ### Processing Limits You can configure the **maximum number of items per run** in the queue settings. This prevents a single run from consuming too many resources if the queue has hundreds of items. Each item also has a **time budget** — if processing takes too long, the agent gracefully wraps up the current item and moves on. ## Queue Settings Access queue settings to configure processing behavior: | Setting | What It Controls | |---------|-----------------| | **Schedule interval** | How often the agent automatically processes (5 min to 24 hours) | | **Max items per run** | Maximum queue items to process in a single scheduled run | | **Auto-queue emails** | Whether incoming emails are added to the queue automatically | | **Processing order** | Items are processed top-to-bottom (drag to reorder) | ### Auto Processing Interval The interval determines how often the agent automatically wakes up and processes its queue: - **Every 5 minutes** — Near real-time processing - **Every 15 minutes** — Good balance of responsiveness and efficiency - **Every hour** — For batch-style processing - **Every 24 hours** — Daily digest/report agents - **Custom intervals** — Set any interval that fits your workflow When auto processing is disabled, items accumulate in the queue until you manually trigger processing. ## Queue Item Lifecycle ``` Added (manual / email / agent) → Pending (waiting in queue) → Processing (agent is working on it) → Completed ✓ ``` Completed items remain visible (toggle with Show/Hide) so you can review what was processed and when. ## Tips & Best Practices - **Use the queue for repeatable work** — Anything the agent does regularly (process emails, generate reports, check data) should flow through the queue - **Prioritize with drag-and-drop** — Put urgent items at the top - **Combine with auto-queue** — Email + auto-queue + schedule = fully autonomous task processing - **Set reasonable limits** — Configure max items per run to prevent resource exhaustion on large queues - **Review completed items** — Check the processed items periodically to ensure quality - **Clean up regularly** — Delete completed items you've reviewed to keep the queue manageable ## What's Next? - **[Schedule](/docs/agents/schedule)** — Create time-based triggers that inject prompts into the queue - **[Runs & Scheduling](/docs/agents/runs)** — Understand run types, status tracking, and scheduling details - **[Mail](/docs/agents/mail)** — Configure the email integration that feeds the queue - **[Agent Settings](/docs/agents/settings)** — Configure computer resolution, timeout, and other settings --- # Scheduler > Source: https://communa.io/docs/agents/schedule Create time-based triggers that automatically run your agent with a specific prompt on a schedule. > **Tip:** Your agent can create and manage its own scheduled jobs. Ask it — *"Send me a daily news summary at 9am"*, *"Run a weekly report every Monday"*, or *"Show me my active schedules."* ## Overview **Scheduled jobs** are time-based triggers that automatically inject a prompt into the agent's queue at specific times. When a job fires, it creates a queue item with the job's prompt — which is then processed through the normal queue pipeline. This is different from **queue auto processing** (configured in the Queue tab), which controls *how often* the agent processes its queue. Scheduled jobs control *what* gets added to the queue and *when*. | Concept | What It Does | |---------|-------------| | **Scheduled Job** | Creates a queue item with a specific prompt at a configured time | | **Queue Auto Processing** | Processes existing queue items at regular intervals | Both work together: scheduled jobs add work to the queue, and queue auto processing ensures that work gets picked up. ## The Scheduler Tab The Schedule tab shows all scheduled jobs as a card grid. Each card displays: - **Name** — A descriptive label for the job - **Schedule** — When it runs (e.g., "Daily at 09:00 Eastern Time") - **Prompt preview** — The first two lines of the prompt - **Toggle** — Enable or disable the job - **Last run** — When the job last fired - **Next run** — When it will fire next Click the **⋮ menu** on any card to edit or delete the job. ## Creating a Scheduled Job Click **Add Job** to open the form drawer: ### Name A descriptive label — e.g., "Morning News Briefing", "Weekly Analytics Report", "Daily Inbox Triage". ### Prompt The message sent to the agent each time the job fires. This is the most important field — see [Writing Good Prompts](#writing-good-prompts) below. ### Schedule Type | Type | Behavior | Example | |------|----------|---------| | **Daily** | Runs at a specific time every day | "09:00 every day" | | **Weekdays** | Runs at a specific time Monday through Friday | "08:30 Mon–Fri" | | **Custom Days** | Runs on specific days you pick | "Tue, Thu, Sat at 10:00" | | **Interval** | Runs every N minutes continuously | "Every 15 minutes" | ### Time & Timezone For daily, weekdays, and custom schedules, pick the time you want the job to run. The timezone defaults to the agent's timezone (set in **General** settings), so a job set for "9am daily" lines up with the agent's working hours automatically. You can override the timezone for a specific job if needed — open the dropdown and pick any city, organized by region with the current local time next to each option. ### Day Picker For custom schedules, click the day buttons to select which days the job should run. At least one day is required. ### Model Choose which AI model the agent uses when processing this job's prompt. Defaults to the latest Claude model. ## Writing Good Prompts When a scheduled job fires, its prompt is injected as a queue item. The agent processes it in a **fresh session with no memory** of any previous conversation. The prompt must be entirely self-contained. **Good prompt:** > Check the weather forecast for Tel Aviv, Israel for today. Then check the top 3 headlines from Hacker News. Compile everything into a brief morning briefing and send it to me at dan@company.com. **Bad prompt:** > Do the usual morning thing. The agent won't know what "the usual" means in a fresh session. Include: - **What to do** — Specific actions and data sources - **Where to deliver** — Email address, dataset name, or other output destination - **Format** — How results should be structured (bullets, table, summary, etc.) - **Context** — Any details the agent needs (locations, preferences, account names) ## How Scheduled Jobs Work ``` Scheduled job fires (e.g., daily at 9am) → Prompt injected as a queue item → Queue processing picks it up → Agent executes in a fresh session → Task completed, item marked done ``` The key insight: scheduled jobs **don't run the agent directly**. They add items to the queue, which are then processed by the existing queue pipeline. This means: - **Queue auto processing must be enabled** for scheduled job items to be picked up - Multiple scheduled jobs firing close together are processed sequentially - Each job's queue item gets its own chat session for full traceability ## Managing Jobs ### Enable / Disable Use the toggle on each card to pause or resume a job. Disabled jobs don't fire — their schedule is preserved for when you re-enable them. ### Edit Click **⋮ → Edit** to modify any aspect of the job — name, prompt, schedule, timezone, or model. If you change the schedule, the next run time is automatically recalculated. ### Delete Click **⋮ → Delete** to permanently remove a job. ### Via Conversation Your agent can manage scheduled jobs through the `settings_manager` tool. Ask it to create, update, list, toggle, or delete jobs conversationally. ## Circuit Breaker If a scheduled job fails **5 consecutive times**, the system automatically disables it to prevent wasted resources. When this happens: - The card shows a yellow warning banner with the failure count and last error - The toggle shows as disabled - No further queue items are injected until you re-enable the job To recover: fix the underlying issue (usually the prompt or a missing credential), then toggle the job back on. Re-enabling resets the failure counter. ## Tips & Best Practices - **Test before scheduling** — Run the prompt manually first (paste it in chat) to verify the agent produces the expected result. Adjust the prompt based on feedback, then create the scheduled job - **Write self-contained prompts** — The agent has no memory between scheduled runs. Include everything it needs in the prompt - **Combine with auto processing** — Scheduled jobs add items to the queue; make sure queue auto processing is enabled to pick them up - **Use descriptive names** — Good names make the Schedule tab scannable at a glance - **Start with daily** — Begin with a daily schedule and adjust frequency once you've validated the output - **Monitor via Runs** — Each scheduled job creates a run you can review in the Runs tab - **Check the circuit breaker** — If a job stops running, check if it was auto-disabled after failures ## What's Next? - **[Queue](/docs/agents/queue)** — Understand the queue pipeline that processes scheduled job items - **[Runs & Scheduling](/docs/agents/runs)** — View execution history and configure queue processing intervals - **[Agent Settings](/docs/agents/settings)** — Configure the computer, model, and other agent-level settings --- # Agent Settings > Source: https://communa.io/docs/agents/settings Configure agent identity, computer persistence, working hours, model, caching, context memory, actions, queue, mail, and more — all from a single Settings page. > **Tip:** Your agent can update its own settings. Ask it — *"Change your name to DataBot"*, *"Set your timeout to 30 minutes"*, or *"What are your current settings?"* ## Overview The **Settings** page is the centralized hub for all agent configuration. Click the **Settings** button in the agent header to open it. Settings is organized into sections via a sidebar navigation. On desktop, the sidebar appears on the left; on mobile, it's a horizontal scrollable bar at the top. | Section | What It Configures | |---------|-------------------| | **General** | Agent title, persona name, description, and timezone | | **Computer** | Computer persistence mode — persistent (default) vs. on-demand | | **Working Hours** | Days and hours the agent is allowed to operate | | **Chat** | Default AI model, prompt caching, and context memory | | **Roles & Permissions** | How the agent treats each sender tier — and the rules Communa enforces | | **Actions** | Auto-save toggle and action history management | | **Queue** | Processing interval, max items per run, and auto-queue | | **Mail** | Email handling, outbound whitelist, and SMTP delivery | | **Voice** | Greeting, transcription, conversation behavior, context, call experience, and recording | | **Danger Zone** | Delete the agent permanently | ## General ### Title The agent's display name — shown in the sidebar, headers, agent list, and everywhere the agent is referenced. ### Agent Name (Persona) An optional persona name the agent uses for itself. During onboarding, the agent often picks its own name (e.g., "ResearchBot" or "DataBot"). This is how the agent refers to itself in conversations. ### Description An optional description of what the agent does. Helps team members understand the agent's purpose at a glance. ### Timezone Set the timezone your agent operates in. It defaults to your current location, so most people don't need to change it. If you're setting up the agent for someone in another country, open the dropdown and pick their city — it's organized by region (Africa, America, Asia, Europe, Pacific) with the current local time shown next to each option, so you can see at a glance whether you've got the right one. The agent uses this timezone everywhere it matters — when reasoning about "today" or "this morning" in chat, when checking working hours, and as the default for scheduled jobs — so everything stays aligned. ## Computer > **Note on terminology:** Throughout the docs we use **computer** to mean the agent's isolated Linux desktop environment. The underlying technology is sometimes called a *sandbox* — they refer to the same thing. ### Computer Persistence Choose how the agent's computer behaves when idle or put to sleep. Select a mode by clicking the corresponding card — the change takes effect the next time the computer starts. #### Comparing the Two Modes | | **On-Demand** | **Persistent** (default) | |--|-------------------------|----------------| | **When agent sleeps** | Computer is **destroyed** — clean slate next time | Computer is **paused** — frozen in place | | **When agent wakes** | Fresh computer started (~10-15s) | Resumes from frozen state (~1s) | | **Browser sessions** | Lost — websites logged out, tabs closed | **Preserved** — stays logged in, tabs still open | | **Installed packages** | Gone — must reinstall on next wake | **Preserved** — pip, npm, apt packages remain | | **Running processes** | Terminated | **Frozen and resumed** automatically | | **Files on the computer** | Deleted (unless synced to stored files) | **Preserved** in place | | **Compute cost while idle** | None | None (paused computers use no compute) | #### When to Use Each Mode **Persistent** (default, recommended) is ideal for agents that **build up state over time** or need to pick up exactly where they left off: - Agents that **log into websites** (CRMs, dashboards, admin panels) — sessions and cookies survive across pauses, so the agent doesn't re-authenticate every time - Agents with **heavy environment setup** — Python/Node packages, databases, compiled tools that take minutes to install - Agents running **background services** — local servers, watchers, or daemons that should keep running - Long-running workflows where **context continuity** matters — open browser tabs, partially completed forms, in-progress downloads **On-Demand** is an alternative for agents that do **stateless, self-contained tasks** — each run is independent and doesn't rely on anything from the previous session: - Email triage and summarization - Web research and data scraping - Quick file conversions or one-off scripts - Tasks where a clean environment is actually preferred > **Tip:** Persistent mode is the default because most agents benefit from state continuity. Only switch to on-demand if your agent truly doesn't need anything from previous sessions. #### What Changes in the UI When Persistent mode is active: - The **Sleep button becomes Pause** — the confirmation dialog reassures you that all state is preserved instead of warning about data loss - **Timeout pauses instead of killing** — if the computer times out, it pauses automatically rather than being destroyed - **Resume replaces Wake** — clicking "Resume Agent" reconnects in ~1 second instead of starting a fresh computer - **Scheduled runs and channel messages** auto-resume a paused computer seamlessly ## Working Hours Configure the days and hours during which the agent is allowed to operate. Outside working hours, scheduled runs and queue processing are paused. Working hours are displayed in the agent header as a visual indicator showing whether the agent is currently within its operating window. The timezone shown here is the agent's overall timezone, set in **General** settings — change it there and working hours will follow. ## Chat ### Default Model Override the system default AI model for this specific agent. Useful when different agents have different cost/performance needs — a quick-task agent can use a lighter model while a research agent uses the most capable one. Select **System Default** to follow the platform-wide model setting. ### Cache Strategy Control prompt caching behavior to reduce costs on repeated interactions: | Strategy | Description | |----------|-------------| | **No Cache** | Every request is processed fresh — highest cost, best for volatile prompts | | **5 Minutes** | Recommended — caches the system prompt for 5 minutes, good balance of freshness and savings | | **1 Hour** | Maximum savings — caches for 1 hour, best for agents with stable system prompts | ### Context Memory Controls how much conversation history the AI sees when generating responses. Choose from three presets: | Preset | Text Messages | Tool Calls | Best For | |--------|:---:|:---:|---------| | **Minimal** | 20 | 10 | Short tasks, quick automations, lowest cost | | **Balanced** | 50 | 30 | Most agents — recommended default | | **Extended** | 150 | 80 | Complex multi-step workflows, long conversations | - **Text Messages** — User, assistant, and system messages loaded from conversation history - **Tool Calls** — Tool call/result pairs (computer actions, web searches, file reads, etc.) ### Advanced Context Settings For fine-grained control, expand **Advanced Context Settings** inside the Context Memory section to customize each value individually: | Setting | Range | Default | Description | |---------|:---:|:---:|-------------| | Text Messages | 10 – 200 | 50 | Max user turns loaded from history | History is measured in **turns**, not individual messages. One turn is a user message plus every assistant reply and tool call/result it triggered — so tool interactions are always loaded together with the turn that produced them, and are never split apart. Changing the slider automatically switches the preset to **Custom**. Pick a preset button to reset all values. > **Tip:** Start with **Balanced**. Only increase if your agent loses track of earlier context in long sessions. Reduce to **Minimal** for simple, repetitive tasks to save on token costs. ## Roles & Permissions The **Roles & Permissions** section controls how your agent treats each person who messages it, based on their **trust tier**. When someone sends a message, the agent knows which tier they belong to and reads tier-specific guidance before responding. There are four tiers: | Tier | Who They Are | |------|--------------| | **Owner** | You — the workspace creator, with full authority | | **Admin** | Trusted teammates with broad permissions | | **Member** | Regular workspace teammates | | **External** | Anyone messaging via Telegram, WhatsApp, Voice, or Email who isn't a workspace member | ### What Each Tier Shows Selecting a tier reveals two things: 1. **Can / Cannot** — The hard rules. The **Cannot** rules are **enforced by Communa server-side**, not just suggested to the agent. If a Member or External sender asks the agent to do something on this list, the underlying tool call is blocked and returns a permission error — so the agent declines instead of trying. 2. **The prompt** — The customizable text the agent reads about how to treat this sender. Edit it to make the agent friendlier, stricter, or more specific to your use case. #### What's enforced per tier | Action | Owner | Admin | Member | External | |--------|:---:|:---:|:---:|:---:| | Change agent settings (`settings_manager`) | ✅ | ✅ | ❌ | ❌ | | Create / edit / delete skills | ✅ | ✅ | ❌ | ❌ | | Run tasks, search, read files, use tools | ✅ | ✅ | ✅ | ✅ (scoped) | > **Note:** Credentials are never agent-mutable for *any* tier. The agent can only *use* a stored credential at runtime (its value stays hidden); it has no tool to create, read, or edit raw credential values. Credential management happens in the dashboard UI and is gated by **workspace role**, not sender tier. ### Customizing a Tier's Prompt Each tier ships with a sensible default — cooperative and broad for Owners, helpful but careful for Members, careful and scoped for External senders. Edit the prompt text and save to override it. The **External** tier prompt supports placeholders that are filled in at runtime so the same prompt works across every channel: | Placeholder | Resolves To | |-------------|-------------| | `{{channelLabel}}` | The channel the person is using (e.g. "Telegram", "WhatsApp") | | `{{participant}}` | The sender's name or identifier | | `{{idLine}}` | A short line identifying the sender's contact details | Click **Reset to default** on any tier to restore the original prompt. Every change is recorded in the **[Change Log](/docs/agents/changes)** and can be reverted. > **Tip:** Start with the defaults — they cover most situations. Customize a tier when you want specific behavior, e.g. *"For External senders, always offer to escalate to a human if they sound frustrated."* For deeper background on roles, people, and what's enforced vs. guided, see **[People & Permissions](/docs/platform/people-permissions)**. ## Actions ### Auto-Save Actions Toggle whether AI actions are automatically saved to the action history. When enabled, every action the agent performs during a chat session is captured in the Actions tab in real time. When disabled (default), actions appear in chat with an "Add" button so you can pick exactly which actions to keep in your sequence. ### Clear Action History Permanently delete all saved actions from this agent. This shows a confirmation dialog — cleared actions cannot be recovered. ## Queue ### Processing Interval How often the system checks for and processes pending queue items. Options range from every 5 minutes to every 24 hours. ### Max Items Per Run The maximum number of queue items processed in a single scheduled run. Prevents runaway processing on large queues. ### Auto-Queue Incoming Emails When enabled, every incoming email is automatically added to the agent's queue as a task item. Combined with a processing schedule, this creates a fully autonomous email-processing agent. ## Mail ### Whitelist For security, agents can only **send** emails to whitelisted addresses: - **Team members** — Always allowed (automatically whitelisted) - **The agent's own address** — Always allowed - **Custom addresses** — Add specific email addresses the agent is permitted to send to **Enforce whitelist** — A switch at the top of the Mail settings. On by default. Turning it off requires acknowledging the risks in a confirmation dialog, after which the agent can send to any recipient. See **[Mail → Disabling the Whitelist](/docs/agents/mail#disabling-the-whitelist)** for details. The whitelist applies to outbound emails only. Anyone can send emails *to* the agent regardless of the whitelist. ## Voice Configure phone-call behavior under **Settings → Voice**, including the greeting, transcription language, conversation model, context isolation, Voice processing instructions, pacing, progress messages, silence handling, maximum duration, and recording. See **[Voice Channel (Phone)](/docs/agents/channels-voice)** for connection steps and a complete explanation of Voice capabilities and settings. ## Danger Zone ### Delete Agent Permanently delete the agent and all associated data — chat history, files, datasets, credentials, skills, email, queue items, scheduled jobs, and runs. This action cannot be undone. ## Editing Settings Settings can be changed two ways: ### Through the UI Click the **Settings** button in the agent header to open the Settings page. Navigate between sections using the sidebar and make changes directly. ### Through Conversation The agent can update its own settings using the `settings_manager` tool. Just tell it: - *"Change your name to ResearchBot"* - *"Update your description to 'Handles daily email triage and reporting'"* This chat-first approach means you rarely need to visit the Settings page — your agent is its own settings panel. > **Audit trail:** Every change made here — whether by you in the UI or by the agent via chat — is automatically recorded in the **[Change Log](/docs/agents/changes)** with full before/after values, actor attribution, and timestamps. ## Tips & Best Practices - **Use descriptions** — A clear description helps team members understand what each agent is for - **Let the agent self-configure** — During onboarding, the agent sets its own name, persona, and settings through conversation - **Match context to the task** — Simple agents (e.g., email triage) work well with Minimal context; research or multi-step agents benefit from Extended - **Monitor token costs** — If an agent's per-message cost is higher than expected, try reducing context memory - **Persistent computer is the default** — Your agent preserves browser sessions, installed packages, and all state across pauses. Switch to on-demand only if you prefer a clean environment each time ## What's Next? - **[Agent Overview](/docs/agents/overview)** — Return to the agent overview for a high-level perspective - **[Chat & Computer](/docs/agents/chat-sandbox)** — Learn about the primary workspace - **[Context & Configuration](/docs/agents/context)** — Configure skills, instructions, and tools --- # API Overview > Source: https://communa.io/docs/api/overview Authenticate with scoped API keys and call the Communa REST API from your own dashboards, scripts, and integrations. > **Tip:** Use the API when you want code you control — a custom dashboard, a script, or another service — to read or write data your agent manages. Generate a key in the agent's **Settings → API Keys** section. ## Overview The Communa API exposes your agent's resources over a small, REST-standard HTTP interface. It's authenticated with **scoped API keys** and follows the **PostgREST/Supabase query style**, so any developer — or AI model — already knows how to call it. Under the hood the API reuses the exact same permission checks, plan limits, and validation as the agent itself, so an external integration can never do something the agent couldn't. This page covers everything that applies to **every** endpoint: the base URL, authentication, scopes, response shape, errors, and key management. Each resource then has its own reference page: - **[Datasets API](/docs/api/datasets)** — read and write an agent's dataset rows. _More resources (runs, files, and more) will be added here over time._ ## Base URL All endpoint paths are relative to the production base URL: ``` https://communa.io/api/v1 ``` ## Quickstart Make your first request in under a minute. 1. **Create an API key** — In the agent's **Settings → API Keys**, create a key with the `datasets:read` scope. Copy the raw key (shown once). 2. **List your datasets** to confirm it works: ```codetabs { "curl": "curl https://communa.io/api/v1/datasets \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\"", "js": "const res = await fetch('https://communa.io/api/v1/datasets', {\n headers: { Authorization: `Bearer ${process.env.COMMUNA_API_KEY}` },\n});\nconst { data } = await res.json();\nconsole.log(data);", "python": "import os, requests\n\nres = requests.get(\n 'https://communa.io/api/v1/datasets',\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n)\nprint(res.json()['data'])" } ``` You should get back a list of datasets: ```json { "data": [ { "id": "abc123", "name": "Leads", "row_count": 42 } ] } ``` That's it — every other endpoint follows the same auth header and base URL. ## Authentication Every request sends the key as a Bearer token: ``` Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxx ``` Keys are created in the agent's **Settings → API Keys** section (admin/owner only). The raw key is shown **once** at creation — store it safely. Each key carries one or more **scopes**: | Scope | Grants | |-------|--------| | `datasets:read` | List datasets, query/read rows (GET) | | `datasets:write` | Insert, update, delete rows (POST / PATCH / DELETE) | ## ⚠️ Never put the key in browser code A key in front-end JavaScript (including `VITE_`-prefixed env vars) is fully visible to anyone. **Always call the API from a server-side proxy** that holds the key in a server environment variable: ``` [Browser] → [Your dashboard's server proxy] → [Communa API] (holds the key in env) ``` - **Locally (Vite):** use `server.proxy` in `vite.config.ts`, or a tiny Node route. - **On Vercel:** a serverless function (e.g. `/api/proxy`) that forwards requests and injects the `Authorization` header. The Communa-side code is identical in both cases. ## Response shape Success responses wrap the payload in `data` (with optional `meta`). Row queries return a consistent `{ rows, total, columns }` shape, where `total` is the number of rows matching your query (filter/search aware): ```json { "data": { "rows": [ ... ], "total": 42, "columns": ["name","status"] } } ``` A `distinct` query instead returns `{ values, total_unique, ... }`. ## Errors Errors use a consistent envelope with a machine-readable `code`: ```json { "error": { "message": "This API key lacks the required scope \"datasets:write\".", "code": "insufficient_scope" } } ``` | Code | Status | Cause | Fix | |------|--------|-------|-----| | _(auth)_ | `401` | Missing, invalid, revoked, or expired key | Send a valid `Authorization: Bearer` header with an active key | | `insufficient_scope` | `403` | Key lacks the required scope, or the resource is locked for that operation | Use a key with the scope the endpoint requires | | `not_found` | `404` | The resource doesn't exist or isn't owned by this key's agent | Check the resource ID and that the key belongs to the right agent | | `row_not_found` | `404` | The `rowId` doesn't exist in this dataset | Re-fetch row IDs from a GET query | | `invalid_query` | `400` | Bad operator, out-of-range `limit`, negative `offset`, or non-integer pagination | Use valid query params (`limit` 1–1000, `offset` ≥ 0) | | `invalid_row_id` | `400` | The `rowId` in the path is not a valid UUID | Pass a UUID from a row's `id` field | ## Managing & revoking keys In **Settings → API Keys** you can see each key's prefix, scopes, last-used time, and request count, and **revoke** a key instantly. A revoked key is rejected on the very next request. ## What's Next? - **[Datasets API](/docs/api/datasets)** — The full endpoint reference for reading and writing dataset rows - **[Credentials](/docs/agents/credentials)** — Secrets your agent uses to log into services --- # Datasets API > Source: https://communa.io/docs/api/datasets Read and write an agent's dataset rows from external code using scoped API keys and a PostgREST-style REST API. > **New to the API?** Read the **[API Overview](/docs/api/overview)** first — it covers the base URL, authentication, scopes, the response envelope, error codes, and key management that apply to every endpoint below. ## Overview The Datasets API exposes your agent's datasets over a small, REST-standard HTTP interface. It uses the same **scoped API keys** and **PostgREST-style query syntax** described in the [API Overview](/docs/api/overview), and reuses the exact same permission checks, plan limits, and validation as the agent itself. All paths are relative to the base URL `https://communa.io/api/v1`, and every request sends a `Authorization: Bearer` header. Remember to call the API from a **server-side proxy** — never directly from the browser ([why](/docs/api/overview#never-put-the-key-in-browser-code)). ## API reference | Method | Path | Scope | Description | |--------|------|-------|-------------| | `GET` | [`/datasets`](#list-datasets) | `datasets:read` | List datasets the key's agent owns | | `GET` | [`/datasets/{captureId}/rows`](#query-rows) | `datasets:read` | Query rows (filter, sort, paginate) | | `POST` | [`/datasets/{captureId}/rows`](#insert-rows) | `datasets:write` | Insert one or more rows | | `PATCH` | [`/datasets/{captureId}/rows`](#update-rows-bulk) | `datasets:write` | Bulk-update rows matching a condition | | `DELETE` | [`/datasets/{captureId}/rows`](#delete-rows-bulk) | `datasets:write` | Bulk-delete rows by ID | | `GET` | [`/datasets/{captureId}/rows/{rowId}`](#fetch-one-row) | `datasets:read` | Fetch a single row | | `PATCH` | [`/datasets/{captureId}/rows/{rowId}`](#update-one-row) | `datasets:write` | Update a single row | | `DELETE` | [`/datasets/{captureId}/rows/{rowId}`](#delete-one-row) | `datasets:write` | Delete a single row | ## Endpoints ### List datasets ``` GET /datasets ``` Returns the datasets the key's agent owns. Requires `datasets:read`. ```codetabs { "curl": "curl https://communa.io/api/v1/datasets \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\"", "js": "const res = await fetch('https://communa.io/api/v1/datasets', {\n headers: { Authorization: `Bearer ${process.env.COMMUNA_API_KEY}` },\n});\nconst { data } = await res.json();", "python": "import os, requests\n\nres = requests.get(\n 'https://communa.io/api/v1/datasets',\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n)\ndata = res.json()['data']" } ``` **Response** ```json { "data": [ { "id": "abc123", "name": "Leads", "row_count": 42 } ] } ``` ### Query rows ``` GET /datasets/{captureId}/rows ``` Requires `datasets:read`. Supports a PostgREST-style query string: | Param | Example | Meaning | |-------|---------|---------| | `select` | `?select=name,status` | Return only these columns | | filter | `?amount=gte.100&status=eq.active` | `{field}={op}.{value}` | | `search` | `?search=acme` | Free-text across all columns | | `order` | `?order=created_at.desc` | Sort (`field.asc` / `field.desc`) | | `limit` / `offset` | `?limit=50&offset=100` | Pagination — `limit` 1–1000, `offset` ≥ 0 | | `distinct` | `?distinct=status` | Distinct values + counts (filter dropdowns) | **Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with` (`like`/`ilike` are accepted as aliases for `contains`). **Sorting is type-aware:** `?order=amount.asc` sorts numeric columns numerically (`75, 150, 1200`) and text columns alphabetically — you don't need a numeric filter present for numeric ordering. Sorting by `created_at`/`updated_at`/`row_index` uses the row's metadata. **Pagination is strict:** a `limit` outside 1–1000, a negative `offset`, or a non-integer value returns `400 invalid_query` rather than being silently clamped. ```codetabs { "curl": "curl \"https://communa.io/api/v1/datasets/abc123/rows?status=eq.active&amount=gte.100&select=name,amount&order=amount.desc&limit=20\" \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\"", "js": "const params = new URLSearchParams({\n status: 'eq.active',\n amount: 'gte.100',\n select: 'name,amount',\n order: 'amount.desc',\n limit: '20',\n});\nconst res = await fetch(\n `https://communa.io/api/v1/datasets/abc123/rows?${params}`,\n { headers: { Authorization: `Bearer ${process.env.COMMUNA_API_KEY}` } },\n);\nconst { data } = await res.json();", "python": "import os, requests\n\nres = requests.get(\n 'https://communa.io/api/v1/datasets/abc123/rows',\n params={\n 'status': 'eq.active',\n 'amount': 'gte.100',\n 'select': 'name,amount',\n 'order': 'amount.desc',\n 'limit': '20',\n },\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n)\ndata = res.json()['data']" } ``` **Response** ```json { "data": { "rows": [ { "id": "r1", "name": "Acme", "amount": 1200 } ], "total": 1, "columns": ["name","amount"] } } ``` ### Insert rows ``` POST /datasets/{captureId}/rows ``` Requires `datasets:write`. Respects the agent's dataset row plan limit. ```codetabs { "curl": "curl -X POST https://communa.io/api/v1/datasets/abc123/rows \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"rows\": [ { \"name\": \"Acme\", \"status\": \"active\" } ] }'", "js": "const res = await fetch('https://communa.io/api/v1/datasets/abc123/rows', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.COMMUNA_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ rows: [{ name: 'Acme', status: 'active' }] }),\n});\nconst { data } = await res.json();", "python": "import os, requests\n\nres = requests.post(\n 'https://communa.io/api/v1/datasets/abc123/rows',\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n json={'rows': [{'name': 'Acme', 'status': 'active'}]},\n)\ndata = res.json()['data']" } ``` **Response** ```json { "data": { "inserted": 1, "rows": [ { "id": "r9", "name": "Acme", "status": "active" } ] } } ``` ### Update rows (bulk) ``` PATCH /datasets/{captureId}/rows ``` Requires `datasets:write`. Updates **all** rows matching every `where` condition. Omit `where` to update all rows. The API builds and validates the SQL server-side — raw SQL is never accepted from the caller. ```codetabs { "curl": "curl -X PATCH https://communa.io/api/v1/datasets/abc123/rows \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"where\": { \"status\": \"pending\" }, \"set\": { \"status\": \"active\" } }'", "js": "const res = await fetch('https://communa.io/api/v1/datasets/abc123/rows', {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.COMMUNA_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ where: { status: 'pending' }, set: { status: 'active' } }),\n});\nconst { data } = await res.json();", "python": "import os, requests\n\nres = requests.patch(\n 'https://communa.io/api/v1/datasets/abc123/rows',\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n json={'where': {'status': 'pending'}, 'set': {'status': 'active'}},\n)\ndata = res.json()['data']" } ``` **Response** ```json { "data": { "updated": 7 } } ``` ### Delete rows (bulk) ``` DELETE /datasets/{captureId}/rows ``` Requires `datasets:write`. Get row IDs from a GET query (each row includes its `id`). ```codetabs { "curl": "curl -X DELETE https://communa.io/api/v1/datasets/abc123/rows \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"row_ids\": [\"r1\", \"r2\"] }'", "js": "const res = await fetch('https://communa.io/api/v1/datasets/abc123/rows', {\n method: 'DELETE',\n headers: {\n Authorization: `Bearer ${process.env.COMMUNA_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ row_ids: ['r1', 'r2'] }),\n});\nconst { data } = await res.json();", "python": "import os, requests\n\nres = requests.delete(\n 'https://communa.io/api/v1/datasets/abc123/rows',\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n json={'row_ids': ['r1', 'r2']},\n)\ndata = res.json()['data']" } ``` **Response** ```json { "data": { "deleted": 2 } } ``` ## Single row operations Rows are a sub-resource of a dataset, so a single row has its own REST URL with **both** IDs — the dataset `captureId` (which scopes authorization) and the `rowId` (which identifies the row): ``` GET /datasets/{captureId}/rows/{rowId} PATCH /datasets/{captureId}/rows/{rowId} DELETE /datasets/{captureId}/rows/{rowId} ``` This is the right choice when your dashboard already knows the row's `id` (e.g. a user clicks **Edit** or **Delete** on one row). For changing many rows at once by a condition, use the bulk collection endpoints above. ### Fetch one row ``` GET /datasets/{captureId}/rows/{rowId} ``` Requires `datasets:read`. Returns the single row `{ id, row_index, ...fields }`, or `404` if it doesn't exist in this dataset. ```codetabs { "curl": "curl https://communa.io/api/v1/datasets/abc123/rows/r1 \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\"", "js": "const res = await fetch('https://communa.io/api/v1/datasets/abc123/rows/r1', {\n headers: { Authorization: `Bearer ${process.env.COMMUNA_API_KEY}` },\n});\nconst { data } = await res.json();", "python": "import os, requests\n\nres = requests.get(\n 'https://communa.io/api/v1/datasets/abc123/rows/r1',\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n)\ndata = res.json()['data']" } ``` **Response** ```json { "data": { "id": "r1", "row_index": 0, "name": "Acme", "status": "active" } } ``` ### Update one row ``` PATCH /datasets/{captureId}/rows/{rowId} ``` Requires `datasets:write`. The `rowId` in the path **is** the scope — no `where` body. Returns `404 row_not_found` if the row doesn't exist in this dataset. ```codetabs { "curl": "curl -X PATCH https://communa.io/api/v1/datasets/abc123/rows/r1 \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"set\": { \"status\": \"active\", \"notes\": \"Reviewed\" } }'", "js": "const res = await fetch('https://communa.io/api/v1/datasets/abc123/rows/r1', {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.COMMUNA_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ set: { status: 'active', notes: 'Reviewed' } }),\n});\nconst { data } = await res.json();", "python": "import os, requests\n\nres = requests.patch(\n 'https://communa.io/api/v1/datasets/abc123/rows/r1',\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n json={'set': {'status': 'active', 'notes': 'Reviewed'}},\n)\ndata = res.json()['data']" } ``` **Response** ```json { "data": { "id": "r1", "status": "active", "notes": "Reviewed" } } ``` ### Delete one row ``` DELETE /datasets/{captureId}/rows/{rowId} ``` Requires `datasets:write`. Returns `{ "data": { "deleted": true, "id": "" } }`, or `404 row_not_found` if the row didn't exist. ```codetabs { "curl": "curl -X DELETE https://communa.io/api/v1/datasets/abc123/rows/r1 \\\n -H \"Authorization: Bearer $COMMUNA_API_KEY\"", "js": "const res = await fetch('https://communa.io/api/v1/datasets/abc123/rows/r1', {\n method: 'DELETE',\n headers: { Authorization: `Bearer ${process.env.COMMUNA_API_KEY}` },\n});\nconst { data } = await res.json();", "python": "import os, requests\n\nres = requests.delete(\n 'https://communa.io/api/v1/datasets/abc123/rows/r1',\n headers={'Authorization': f\"Bearer {os.environ['COMMUNA_API_KEY']}\"},\n)\ndata = res.json()['data']" } ``` **Response** ```json { "data": { "deleted": true, "id": "r1" } } ``` > An invalid (non-UUID) `rowId` returns `400 invalid_row_id`. ## Response shape Row queries return a consistent `{ rows, total, columns }` shape, where `total` is the number of rows matching your query (filter/search aware): ```json { "data": { "rows": [ ... ], "total": 42, "columns": ["name","status"] } } ``` A `distinct` query instead returns `{ values, total_unique, ... }`. For the full success/error envelope and error codes, see the **[API Overview](/docs/api/overview#errors)**. ## What's Next? - **[API Overview](/docs/api/overview)** — Auth, scopes, errors, and key management - **[Datasets](/docs/agents/datasets)** — How datasets are created and managed in the UI --- # FAQ > Source: https://communa.io/docs/resources/faq Answers to the most common questions about Communa — agents, computers, security, scheduling, billing, and more. Find answers to the most common questions below. Click any question to expand the answer.