# Help Center

<h2 align="center">What can we help you find?</h2>

<p align="center">Browse the topics below or use Zaia Support AI for instant help.</p>

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-file-lines">:file-lines:</i></h4></td><td>Documentation</td><td>Complete technical and user documentation</td><td><a href="/spaces/Rlf9g0rt9pGUyAOZdMUi">/spaces/Rlf9g0rt9pGUyAOZdMUi</a></td></tr><tr><td><h4><i class="fa-messages">:messages:</i></h4></td><td>Endless Community</td><td>Join discussions and share experiences</td><td><a href="https://community.zaia.app/">https://community.zaia.app/</a></td></tr></tbody></table>


# Welcome

Welcome to the **Zaia Endless Documentation** — your technical guide to building, training, and scaling AI Agents in one unified platform.\
Here, you’ll find everything you need to understand Endless, from its key concepts to step-by-step setup instructions and advanced integrations.

### Jump right in

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-bolt">:bolt:</i></h4></td><td><strong>Quickstart</strong></td><td>Follow a guided process to build your first AI Agent with Alfred, the Zaia assistant</td><td></td><td></td><td><a href="/pages/rdT0pl4UjvpTGb0HM6uG">/pages/rdT0pl4UjvpTGb0HM6uG</a></td></tr><tr><td><h4><i class="fa-brain-circuit">:brain-circuit:</i></h4></td><td>Understand the Platform</td><td>Get an overview of Endless modules — Builder, CRM, and Settings — and how to navigate between them.</td><td></td><td></td><td><a href="/pages/lWdZgI2P4YIODQ7uazsl">/pages/lWdZgI2P4YIODQ7uazsl</a></td></tr><tr><td><h4><i class="fa-globe-pointer">:globe-pointer:</i></h4></td><td>Connect Your Agent</td><td>Deploy your Agent through WhatsApp, Instagram, or Website Widget and start interacting with users.</td><td></td><td></td><td><a href="/pages/DkKbt72hnJ7eoOLLb38O">/pages/DkKbt72hnJ7eoOLLb38O</a></td></tr></tbody></table>


# What is Zaia Endless?

Zaia Endless is the **all-in-one AI Agent Builder** that empowers you to create, configure, and deploy intelligent Agents with flexibility and control.

With Endless, you can build Agents that:

* Automate repetitive or complex business tasks
* Provide 24/7 support for customers and teams
* Integrate with your company’s data, knowledge, and tools
* Scale across multiple channels (Widget, WhatsApp, Instagram)
* Escalate conversations to humans when needed, using native CRM Teams

***

### Why Zaia Endless?

Endless was designed to solve common limitations of traditional chatbot platforms:

* Most chatbots are **rigid** and only follow pre-set scripts.
* Endless Agents are **prompt-driven**, meaning they understand instructions and can adapt to context.
* While many solutions only connect to one or two apps, Endless provides **native data handling** (Tables, Knowledge Bases) and **deep integrations** (MCPs such as Google Calendar, Notion, Airtable, Supabase, etc.).

This combination allows companies to go beyond “FAQ bots” and create **specialized Agents** that act as:

* **Support assistants** → answering questions, escalating when needed.
* **Sales reps** → qualifying leads, capturing data, sending information to CRM.
* **Operational Agents** → running workflows, managing internal processes.

***

### Key Differentiators

Zaia Endless stands out because it:

1. **Balances Simplicity and Power**
   * Start with just a Role + Prompt.
   * Add Tools, Knowledge, and Workflows only if the Agent needs them.
2. **Works with Multiple LLMs**
   * Choose the model that best fits your Agent (speed, creativity, cost).
3. **Provides Native Data Handling**
   * Create **Tables** inside Endless to store and query structured data.
   * Build **Knowledge Bases** to centralize documents, FAQs, and policies.
4. **Supports Human Collaboration**
   * Use **CRM Teams + Ticket Tools** for seamless human handoff.
   * Never rely on external or improvised methods.
5. **Scales Across Channels**
   * Test internally in Endless.
   * Then publish on Widget, WhatsApp, or Instagram with a single click.

***

👉 With Zaia Endless, you’re not just building chatbots — you’re creating **scalable, intelligent Agents** that grow with your business needs.


# Roadmap

Em tempo real

{% embed url="<https://linear-kanban.fly.dev/?embed=true>" %}


# Key Concepts

Zaia Endless is built around a set of **core concepts**.\
Understanding these will help you design Agents more effectively and avoid unnecessary complexity.

***

### Console, White Label, and workspace

**Console** is the administrative surface for managing workspaces.

Use it for workspace administration, billing, plans, checkout, slots, and global access.

**White Label** is the branded platform offering.

Use it for custom domains, visual identity, branding, and related permissions.

**Workspace** is the operational environment for a customer or use case.

Each workspace keeps its own configuration, members, and subscription.

***

### Agent

The central unit of Endless.\
Defined by **Role + Prompt + Settings**.

**Example:** “Assistant specialized in financial client data.”

**Best practice:** Start with the simplest configuration (Role + Prompt), then add Tools, Knowledge, or advanced capabilities only if needed.

***

### Role

A short sentence that summarizes what the Agent does.\
It helps position the Agent’s purpose.

**Example:** “Customer support agent for SaaS products.”

***

### Prompt

The main instruction set that defines how the Agent behaves.\
Supports up to **5000 characters**.

**Example:**\
“You are a sales assistant. Always ask the customer their name and product of interest. Be polite and concise.”

***

### Temperature

Controls the **creativity** of the Agent’s responses:

* `0%` → Fully methodical (ideal for factual Agents like finance or legal).
* `100%` → Highly creative (ideal for brainstorming or marketing).

***

### Effort

Defines how many **steps** the Agent can take to reach an answer.\
Range: **10–100**.

* **Low effort (10–20):** Simple tasks, FAQ-style Agents.
* **High effort (80–100):** Complex Agents orchestrating multiple Tools and Workflows.

***

### Planning

When enabled, the Agent creates a **plan** at the start of execution, considering available Tools and resources.

**Recommended for:**\
Agents operating in complex environments or executing multi-step logic.

***

### Reasoning

Controls the **depth of reasoning** applied by the Agent when generating responses.

Available modes:

* **Low:** Faster responses, suitable for simple conversations and FAQs.
* **Medium:** Balanced reasoning for most business use cases.
* **High:** Deeper analysis and structured thinking, ideal for complex decision-making or problem-solving.

> ⚠️ Higher reasoning levels may increase response time.

***

### Tools

Extensions that allow the Agent to go beyond the Prompt.\
Each Tool must be explicitly created and linked.

**Examples:**

* **Memory Tool** → Save variables like name, deadline, or budget.
* **Table Tools** → Insert, update, or search Table data.
* **Workflow Tool** → Execute a Workflow.
* **Ticket Tool** → Transfer the conversation to a CRM Team.
* **HTTP Tool** → Connect to external APIs.

**Best practice:** Only add Tools your Agent will actually use.

***

### Knowledge Base (KB)

A structured repository of documents, FAQs, or policies.\
Agents can search KBs using the **Knowledge Base Search Tool**.

***

### Tables

Native databases in Zaia Endless.\
Used to store and query structured data such as leads, CRM records, or inventory.

**Available operations via Tools:**

* Insert
* Update
* Search
* Semantic / similarity search

***

### Workflows

Sequences of steps that automate business logic.\
Workflows must be created first, then linked using a **Workflow Execution Tool**.

**Example:**\
“Check product availability → calculate delivery time → return result to the user.”

***

### MCP (Managed Connector Provider)

Native integrations with external applications.\
Require a **Connection** (OAuth or API Key) to activate.

**Examples:**

* Google Calendar → Create or list events
* Gmail → Fetch emails
* Supabase → Query external databases
* Notion / Airtable → Manage content

***

### Connection

Authentication that enables MCPs or Channels.\
Without a Connection, the Agent cannot access the external service.

***

### CRM Team

Groups of human operators that can receive conversations from Agents.\
Must be created before adding a **Ticket Tool**.

***

### Ticket Tool

The **only supported way** for Agents to transfer conversations to humans.\
Always linked to a CRM Team.

***

### Channels

Where the Agent interacts with users.

**Available options:**

* **Widget** (Web)
* **WhatsApp**
* **Instagram**
* **API**

**Best practice:**\
Test the Agent first using the internal chat (no channel required), then publish to external channels.

***

### Conditional Prompts (Advanced)

Conditional Prompts allow you to define **instructions that are executed only when specific conditions are met**.

They replace the previous concept of Tasks and enable more flexible, context-aware behavior.

**Examples:**

* If the user says *“finalize”* → Execute a closing prompt.
* If the user asks for a human → Trigger the Ticket Tool.
* If the conversation reaches a certain context → Change Agent behavior dynamically.

**Best practices:**

* Keep conditions specific and non-overlapping.
* Use Conditional Prompts for logic, not for core Agent identity.
* Avoid excessive chaining to maintain clarity and performance.


# Platform Tour

Zaia Endless is organized into clear and modular sections that guide how you navigate, build, and manage your AI ecosystem.

***

### Workspaces

Each **workspace** represents an independent environment where you manage Agents, Teams, Channels, and Settings.\
You can switch between workspaces from the top-left corner of the interface or create new ones as needed.

***

### Main Structure

The platform is divided into three main areas:

#### Builder

The **Builder** is where creation happens.

Opening the Builder home takes you to the full-screen **Vibe** experience. On other Builder pages, **Alfred** remains available as a floating assistant that can be minimized, resized, or expanded back to Vibe.

> ℹ️ **Vibe Agent access:** Vibe is available to users who belong to the workspace, including users who are not workspace owners. The actions available elsewhere in the platform still follow each user's assigned role.

The Advanced Builder organizes the workspace into:

* **Workforce** — Agents and Squads.
* **Capabilities** — Tools, MCPs, and Components.
* **Resources** — Tables, Knowledge, Workflows, and supported Triggers.

Publish and version actions remain in the contextual Builder header, keeping release controls visible without adding them to the navigation submenu.

***

### Search in lists

List search is contextual to each screen.\
The search input lists the fields it searches in its placeholder.

Hover over the input to read the complete field list.\
This helps when the placeholder text does not fit.

Search behavior remains the same.\
The interface only makes searchable fields visible.

The available fields are:

* **Agents** — name, internal name, role, and prompt.
* **Channels** — name, description, and prompt.
* **Components** — key.
* **Connections** — name and description.
* **Tables** and **Knowledge Bases** — name and description.
* **Voices** — name and instructions.
* **Table items** — value.
* **Knowledge items** and documents — name and description.

***

#### CRM

The **CRM** area centralizes conversations, support flows, and human handoff.

When the unified inbox is enabled, **Conversations** combines automated chat history and human-assisted tickets in one list. Teams can filter by queue, ticket status, tags, attendants, Agents, Squads, or search terms without leaving the page.

The CRM submenu acts as inbox navigation:

* **All conversations**
* **Assigned to me**
* **Human queue**
* **Unassigned**
* Dynamic views for **Tags** and **Team members**

Management pages contain Channels, Kanban, attendants, tags, tiers, external users, and external groups.

On mobile, the conversation list opens first. Select a conversation to open its details, and use Back to return to the list.

***

#### Analytics

The **Analytics** section provides visibility into how your workspace and Agents are performing.

Analytics opens with the **last 30 days** selected by default. You can change the period when you need a broader or narrower view.

From here, you can monitor metrics such as:

* Usage by channel
* Credits consumption per Agent
* Message volume over time
* Tickets created in a given period
* Average messages per user

Analytics helps you understand adoption, optimize Agent behavior, and track operational efficiency.

***

#### Settings

The **Settings** area contains all workspace-level configuration, billing, and integrations.

Available sections include:

* **Overview** — workspace information and identification.
* **Members** — manage users and permissions.
* **Billing** — plan details, payment method, invoices, and subscription management.
* **Usage** — detailed credit and consumption tracking.
* **Providers** — available integration providers.
* **Connections** — authentication for MCPs and Channels.
* **API Keys** — create and manage keys for API access and external integrations.

> ℹ️ Subscription management is fully integrated into the **Billing** section.

***

### Navigation

* **Sidebar** — provides structured access to all modules in a clear hierarchy.
* **Profile and usage card** — shows the current workspace, usage, workspace settings, and workspace switcher.
* **Top Bar** — shows contextual actions for the current area.
* **Main Area** — updates dynamically based on the selected section.

You can freely move between Builder, CRM, Analytics, and Settings using the sidebar.

***

### Command Palette

Press **Ctrl + K** (Windows/Linux) or **Cmd + K** (macOS) to open the **Command Palette**.

With it, you can:

* Jump directly to any page or module.
* Switch workspaces.
* Search for Agents, Workflows, or Channels.

This is the fastest way to navigate Zaia Endless without leaving the keyboard.

***

### Summary

| Section       | Purpose                                                                 |
| ------------- | ----------------------------------------------------------------------- |
| **Builder**   | Create and configure Agents, Squads, and core AI resources.             |
| **CRM**       | Manage conversations, tickets, teams, and communication channels.       |
| **Analytics** | Monitor usage, performance, and operational metrics.                    |
| **Settings**  | Configure workspace details, billing, usage, integrations, and API keys |

***

> 💡 **Tip:** Use the **Command Palette** to move quickly between sections — it’s the most efficient way to explore the platform.


# Plans, Princing and Usage Limits

> ⚠️ **Disclaimer:** This page explains the logic behind Zaia's pricing model. For current plan details, limits, and pricing, always refer to the **Plans page inside the platform** — that's where you'll find the most up-to-date information.

Zaia's plans are designed to scale with your usage. Instead of charging per feature, the platform measures **how much work your agents are doing** — and your plan defines the boundaries of that work.

***

#### 📐 How Plans Work

Plans are structured as a progression: as your usage grows, you move to a higher tier. Each tier unlocks higher limits across the three main usage pillars and adjusts the secondary limits accordingly.

There is also a **Custom** plan for teams with enterprise-level needs or specific requirements that don't fit standard tiers.

***

#### 🔑 The Three Main Pillars

Your plan is primarily determined by three types of usage:

**1. External Executions**

The core metric. This counts every interaction your agents have with real users across active channels — WhatsApp, Instagram, Widget, and any other connected channel.

Each conversation turn with a real user counts as an execution. The higher your plan, the more external executions your workspace can handle per month.

> **Important:** External executions measure platform usage only — they do not include LLM costs. AI model costs (OpenAI, Anthropic, Google Gemini, etc.) are billed directly by your LLM provider and depend on the model you configure. To deploy agents on external channels, you must have a valid LLM provider connected to your workspace. [Learn how to set up your provider →](https://docs.zaia.app/settings/providers)
>
> This is full cost transparency: you pay Zaia for what Zaia provides, and you pay your LLM provider directly for what the model consumes — no markup, no intermediary.

> **Note on legacy plans:** Zaia previously offered built-in AI credits as part of the platform. This model no longer exists in current plans. If you are on a legacy plan, you may still see credit-based usage — but all current plans require you to connect your own LLM provider to enable agents on external channels.

**2. Internal Test Usage**

Interactions made through the **Internal Chat** — the private testing environment inside the platform — are counted separately from external executions.

This allows you to test, iterate, and debug your agents without consuming your production quota.

> Internal usage has its own limit, independent of external executions.

**3. Vibe Agent Usage**

Every time you use **Vibe Agent** (the AI agent builder) to create, configure, or diagnose agents through natural language, that also counts toward a usage limit.

The more you use Vibe Agent to build, the more this meter moves.

> This pillar scales with how actively you're building — not just deploying.

***

#### ⚙️ Secondary Limits

Beyond the three main pillars, each plan also defines limits on platform resources. These are less likely to drive an upgrade decision, but they still define the boundaries of your workspace:

* **Members** — how many team members can access the workspace
* **Connections** — integrations with external services (used by MCPs and Channels)
* **Tables** — number of structured data tables available
* **Table rows** — total rows across all tables
* **Knowledge Bases** — number of KBs available
* **Knowledge Base characters** — total content volume across all KBs
* **Workflow concurrent executions** — how many workflows can run simultaneously
* **Rollback versions** — how many previous Agent versions can be restored

***

#### 🔄 Billing Cycles

Plans are available on **monthly** or **annual** billing. Annual billing typically offers a discount compared to the monthly equivalent.

***

#### 📊 Choosing the Right Plan

Start by estimating your **external executions per month** — that's the clearest indicator of which plan fits your operation.

From there, consider:

* How actively your team will be **building and testing** agents (internal usage + Vibe Agent)
* How many **integrations, knowledge bases, and tables** your workspace needs
* How many **team members** need access

If your needs exceed the top standard tier, reach out to discuss a **Custom** plan.

***

#### ✅ Key Takeaway

Zaia's pricing reflects usage, not features. Every plan gives you access to the full platform — what changes is **how much** your agents can do, how actively you can build, and how large your workspace can grow.


# Versioning Overview

The **Versioning system** in Zaia Endless allows you to safely update your Agents and related components using a **Draft environment**, without affecting what is currently running in production.

This ensures safe iteration, proper testing, and controlled releases.

***

### 🔄 What is Versioned

Versioning applies to **configuration entities** — everything that defines how your Agent behaves:

* Agents
* Squads
* Tools
* MCPs
* Voices
* Components
* Tasks

These elements can be edited safely in Draft and only affect production after a **Deploy**.

***

### 🚫 What is NOT Versioned

Some parts of the platform are always live and are **not affected by versioning**:

#### Operational Data

* Channels
* Conversations / Chats
* Tickets
* Tags
* Executions

#### Data & Storage

* Knowledge Bases
* Tables / Datagrid

#### System Configuration

* Users and Workspaces
* Connections
* Providers
* API Keys
* Billing / Subscription

***

#### 📌 Key Implication

> Versioning changes **behavior**, not **data**.

Deploying or rolling back will NOT modify:

* Conversation history
* CRM records
* Stored data

***

### 🔎 Core Concepts

#### Draft

A private environment where you can:

* Edit Agents and all versioned components
* Test changes safely using the **Internal Chat**
* Iterate without impacting real users

***

#### Production

The version currently active in the platform.

It is used in:

* Channels (WhatsApp, Instagram, Widget, API)
* CRM conversations
* All live user interactions

Only changes that are **deployed** affect Production.

***

#### History

All deployed versions are stored as history:

* Identified as versions (v1, v2, v3…)
* Used for comparison and rollback

***

### 🧭 How to Use Versioning

The recommended workflow is simple and safe:

***

#### ✏️ Editing your Agent

Whenever you want to make changes:

1. Work in the **Draft** version
2. Make all necessary updates (Agent, Tools, etc.)
3. Test using the **Internal Chat**

> These changes do not affect production until you publish.

***

#### 🚀 Publishing changes

When you are satisfied:

1. Click **Publish**
2. Review the changes (Diff)
3. Confirm the Deploy

After publishing:

* The new version goes live
* All channels use the updated behavior

***

#### 🔄 Rolling back to a previous version

If needed:

1. Go to **Version History**
2. Select a previous version
3. Click **Edit this version** (Rollback)
4. Confirm

What happens:

* The current Draft is replaced
* You can review the version
* Then publish again to apply it to production

***

### 🧪 Testing in Draft

Before publishing, you can test using the **Internal Chat**:

* Validate responses
* Test tools and flows
* Simulate real interactions

***

### ✅ Key Takeaway

Versioning allows you to:

* Build safely in Draft
* Test before going live
* Deploy with confidence
* Revert changes when needed

All without impacting your live users or data.


# Deploy & Rollback

This section covers how changes move to production and how to safely revert them.

### 🚀 Deploy (Publishing Changes)

A **Deploy** is the action of promoting your Draft version to Production.

***

#### What happens during a Deploy

* Your Draft becomes the new **live version**
* A version is saved in history (e.g., v23)
* A new Draft is automatically created

***

### ⚠️ Impact of Deploy

### When you can publish

The **Deploy** button is available only when the current Draft has pending changes.

If the Draft matches Production, the button is disabled. A tooltip explains that the Draft has no changes to publish.

Pending changes include:

* Creating, editing, or removing Agents, Components, MCPs, Squads, Tasks, Tools, or Voices
* Adding or removing Agent Tool, Agent MCP, or Squad Agent links
* Selecting a previous version through rollback before publishing it

The Builder detects removals and unlinked entities. These changes count as pending even when no entity remains in the current Draft.

After an edit, the Builder marks the Draft as changed immediately. You do not need to reload before publishing.

***

### 🔎 Review changes before deploying

Before confirming a Deploy, review the version preview.

The preview compares your Draft with the current Production version. It groups each change as:

* **Added** — an entity or relationship will be created
* **Removed** — an entity or relationship will be removed
* **Changed** — an existing entity has updated configuration

The preview includes Agents, Components, MCPs, Squads, Tasks, Tools, and Voices.

It also shows changes to Agent Tool, Agent MCP, and Squad Agent links.

For changed items, the preview shows the previous and new values. It highlights key fields, such as an Agent role or prompt, a Component value, a Task prompt, or Voice instructions.

> The preview summarizes deployment impact. It is not a complete field-by-field history. Long values may be shortened.

***

#### Conversations

* Ongoing conversations continue normally
* New messages follow the updated behavior

***

#### Channels

If an Agent or Squad is removed:

* The channel is automatically **deactivated**
* The responder is unassigned

***

#### Responders

* Removed Agents/Squads are no longer available
* Channels depending on them stop working

***

### 📡 Channel Behavior

* If the assigned Agent/Squad exists → works normally
* If removed → channel becomes inactive

***

### 🔄 Rollback (Reverting Versions)

A **Rollback** restores your configuration to a previous version.

> ⚠️ Rollback is global and affects all versioned entities.

***

### 🔎 Review rollback changes

Before editing a previous version, review its preview.

The preview compares the selected version with your current Draft. It uses the same **Added**, **Removed**, and **Changed** groups as Deploy.

This lets you confirm the configuration impact before replacing the Draft.

***

#### How to Rollback

1. Open **Version History**
2. Select a version
3. Click **Edit this version**
4. Confirm

***

#### What Happens

* The current Draft is permanently discarded
* A new Draft is created from the selected version
* You can review and deploy again

***

#### 📌 Plan Limitations

* Freemium → No rollback
* Starter → 1 version back
* Pro / Agency / Enterprise → Unlimited

***

#### ⚠️ Restrictions

* No partial rollback
* Cannot rollback only one component
* Cannot rollback to current Draft

***

### 🧾 Impact on CRM

CRM data is not versioned.

#### Preserved:

* Tickets
* History
* Tags
* Assignments

#### What changes:

* Only Agent behavior

***

### Workflow publishing and rollback

Workflow publishing follows its own save and publish states:

| Workflow state                          | Save      | Publish   |
| --------------------------------------- | --------- | --------- |
| Editing with unsaved changes            | Available | Disabled  |
| Saved and matching Production           | Disabled  | Disabled  |
| Saved as Draft with unpublished changes | Disabled  | Available |

When **Publish** is available, selecting it publishes the saved Workflow directly without opening an additional confirmation page.

Use the history icon beside Publish to review earlier versions. In version history, the Publish action appears only when the selected version is different from the version currently in Production.

***

### ✅ Key Takeaway

* Deploy makes your changes live
* Rollback safely restores previous versions
* Neither affects stored data or conversation history


# Safe Usage & Best Practices

This section explains how to safely work with Versioning and avoid common mistakes when deploying changes to production.

### 🧪 Testing in Draft

Before publishing, you should always test your changes using the **Internal Chat**.

***

#### What to Test

* Agent responses
* Tool execution
* Conversation flows
* Edge cases

***

#### Why Testing Matters

Even small changes can impact behavior.

Testing ensures:

* Stability
* Predictability
* Better user experience

***

### ⚠️ Important Behaviors to Understand

#### Deploy is immediate

Once you deploy:

* All new messages follow the updated behavior instantly
* There is no gradual rollout

***

#### Draft is completely isolated

* Changes in Draft do NOT affect production
* You can test freely without risk

***

#### Rollback replaces Draft

When performing a rollback:

* Your current Draft is lost
* It is replaced by the selected version

***

### 🚨 Common Mistakes to Avoid

#### Publishing without validation

May cause:

* Broken flows
* Missing tools
* Unexpected behavior

***

#### Skipping testing

Leads to:

* Bugs in production
* Poor user experience

***

#### Large unvalidated changes

Avoid:

* Editing too many things at once
* Deploying without iteration

***

### 📌 Best Practices

#### Work in small iterations

* Make small changes
* Test frequently
* Deploy with confidence

***

#### Always follow this workflow

1. Edit in Draft
2. Test using Internal Chat
3. Review changes before publishing *(use Diff when needed)*
4. Deploy
5. Monitor behavior

***

#### Use Diff as a safety tool

Diff helps you:

* Understand what changed
* Identify removals or additions
* Validate critical updates before deploy

> Use Diff when you want extra confidence before publishing.

***

#### Use Rollback as a safety net

* Not as a primary workflow
* Only when necessary

***

### ✅ Key Takeaway

To use Versioning effectively:

* Always work in Draft
* Always test before publishing
* Validate your changes
* Deploy carefully
* Rollback only when necessary

This ensures safe, predictable, and reliable updates to your Agents.


# What is an Agent?

In Zaia Endless, an **Agent** is more than a chatbot.\
It is a **configurable AI entity** capable of reasoning, using tools, interacting with data, and collaborating with humans — all inside a single platform.

Agents are designed to start **simple** (just a Role and a Prompt) and evolve progressively with Memory, Knowledge, Tools, Workflows, and external integrations.

***

### Core Identity

Every Agent starts with two essential elements:

#### Role

A short description that defines the Agent’s purpose.

**Example:**\
“Assistant specialized in customer onboarding.”

#### Prompt

A detailed instruction set (up to **5000 characters**) that defines:

* Behavior and tone
* Objectives and boundaries
* How the Agent should respond in different situations

> 💡 **Tip:** Whenever possible, keep essential knowledge directly in the Prompt to avoid unnecessary complexity.

***

### Settings That Shape Behavior

Agents are dynamic and configurable. These settings define *how* an Agent thinks and responds:

#### Temperature

Controls creativity:

* `0%` → Fully methodical (finance, legal, compliance).
* `100%` → Highly creative (brainstorming, marketing).

#### Effort

Defines how many **reasoning steps** the Agent can take.\
Range: **10–100**.

* Low (10–20): FAQs and simple flows
* High (80–100): Complex logic, tool orchestration, workflows

#### Planning

When enabled, the Agent creates a **structured execution plan** before acting, considering available Tools and resources.

Recommended for Agents that operate in multi-step or decision-heavy environments.

#### Reasoning

Controls the **depth of reasoning** applied when generating responses.

Available modes:

* **Low** — Faster responses for simple interactions
* **Medium** — Balanced reasoning for most business use cases
* **High** — Deeper analysis and structured thinking for complex problems

> ⚠️ Higher reasoning levels may increase response time and credit usage.

***

### Extending Agent Capabilities

Agents can be extended using native Endless resources:

#### Memory

Works like persistent variables.\
You decide what information should be stored and reused later.

**Examples:** name, email, budget, deadline.

#### Knowledge Bases

Structured repositories for large or frequently updated content such as:

* FAQs
* Product manuals
* Internal policies

Agents access them via **Knowledge Search Tools**.

#### Tables

Native Endless databases used for structured data like:

* Leads
* Customers
* Orders
* Tickets

Tables can be queried and modified through dedicated Tools.

#### Workflows

Predefined multi-step processes that automate business logic.

**Example:**\
“Validate input → call external API → update table → respond to user.”

#### MCPs (Managed Connector Providers)

Native integrations with external platforms.\
Once connected, MCPs unlock new Tools for the Agent.

**Examples:** Google Calendar, Notion, Airtable, Supabase.

***

### Acting Through Tools

Agents are **passive by design** — they only act when triggered by user interaction or internal logic.

Tools allow Agents to perform actions such as:

* Execute code (**Code Execution**)
* Store and retrieve memory (**Contextual Memory**)
* Send follow-up messages after inactivity (**Follow Up**)
* Search Knowledge Bases (**Knowledge Search**)
* Read and extract data from PDFs (**PDF Reader**)
* Insert, update, or search table rows (**Table Row Insertion / Update / Search**)
* Perform semantic or similarity searches on tables
* Execute workflows (**Workflow Executor**)
* Send messages programmatically (**Message Sending**)
* Create tickets for human assistance (**Ticket Creation**)
* Make external API calls (**HTTP Request**)
* Perform web searches (**Web Search**)

> 💡 **Best practice:** Only enable Tools your Agent is expected to use. Fewer tools lead to more predictable behavior.

***

### Conditional Prompts (Advanced)

Conditional Prompts replace the previous concept of Tasks.

They allow you to define **instructions that execute only when specific conditions are met**, enabling dynamic and context-aware behavior.

**Examples:**

* If the user asks for a human → trigger **Ticket Creation**
* If the conversation reaches a certain context → adjust tone or flow
* If the user confirms an action → execute a Workflow

**Best practices:**

* Keep conditions explicit and non-overlapping
* Use Conditional Prompts for logic, not for core identity
* Avoid excessive chaining to preserve clarity and performance

***

### Where Agents Operate

After testing internally, Agents can be deployed to Channels:

* **Website Widget**
* **WhatsApp**
* **Instagram**
* **API**

The **API channel** allows Agents to be consumed programmatically by external systems, applications, or custom frontends.

Each channel requires a valid **Connection** when applicable.

***

### Why Endless Agents Are Different

1. **Simplicity first** — Launch with just a Role and Prompt
2. **Native data handling** — Knowledge Bases and Tables live inside Endless
3. **Structured orchestration** — Tools and Workflows enable complex automation
4. **Seamless human handoff** — Built-in CRM with Tickets and Teams
5. **Multi-LLM flexibility** — Optimize cost, speed, and accuracy

***

👉 In Zaia Endless, an Agent is not just answering questions — it’s a **scalable digital teammate** that evolves with your business.


# Creating an Agent


# Creating from Scratch


# Creating from Template


# Creating with Alfred

The **Agent Builder Assistant** is itself an Agent inside Endless.\
It was designed to guide you through the creation process **step by step**, always prioritizing simplicity.

#### How it works:

* It asks **one question at a time** (goal, audience, tone, memory, etc.).
* Based on your answers, it generates:
  * **Role** (1 sentence).
  * **Main Prompt** (up to 5000 chars, with your knowledge embedded).
  * **Suggested Settings** (temperature, effort, planning, supervision).
  * **Minimal Tools and Resources** only if needed.
* At the end, it delivers a **Launch Checklist** in the correct order:
  1. Role & Prompt
  2. Settings
  3. Memory → Knowledge → Tables → Workflows → CRM Teams
  4. Tools
  5. MCPs
  6. Internal Test
  7. Channels
  8. Tasks (optional rules)
  9. Final Test

#### Why use it?

* Ensures you don’t miss essential steps.
* Prevents unnecessary complexity.
* Provides ready-to-use prompts and variables.
* Perfect for first-time users or complex use cases.

***


# Duplicating an Agent

Create a configurable copy of an existing Agent in the current Draft.

Duplicate an Agent to reuse its configuration in the current Draft. The original Agent remains unchanged.

### Before you start

You can duplicate Agents only in the current Draft. Draft changes do not affect Production until you deploy them.

### Duplicate an Agent

1. Open **Builder** and go to the Agent list.
2. Open the Agent's actions menu.
3. Select **Duplicate**.
4. Review the preview showing the new Agent, copied Tasks, and shared Tools and MCPs that will be linked.
5. Select **Cancel** to leave the Draft unchanged, or confirm to create the duplicate.

The preview shows only items that will be added or linked. It does not show **Removed** or **Changed** groups because duplication does not modify the source Agent or remove existing resources.

The new Agent appears in the list when duplication completes. The Draft is marked as changed.

{% hint style="info" %}
Wait for the confirmation before making other Draft changes. Builder locks Draft mutations while duplication runs.
{% endhint %}

### What gets copied

The duplicate receives its own Agent configuration. It includes:

* Name, role, prompt, model, provider, reasoning, temperature, timezone, planning, iterations, and code runtime.
* A duplicated Agent image and the same Voice.
* New Task records with the same Task configuration.

The duplicate receives the next available name. For example, `Support Agent` becomes `Support Agent (1)`. Names remain within the 50-character limit.

### Shared resources

Tools and MCPs are not duplicated as new entities. The new Agent links to the same active Tools and MCPs in the current Draft.

Changes to those shared Tools or MCPs can affect both Agents. Create separate resources before editing them independently.

### What is not copied

Squad membership is not copied. The duplicated Agent starts without a Squad.

Add the Agent to a Squad manually when needed.

### If duplication fails

Builder shows an error and unlocks the Draft. No Agent is added to the list.

Duplication is atomic. A failed operation does not leave a partially created Agent visible.


# Agent Settings

Agent Settings define the complete behavioral, cognitive, and operational configuration of an Agent.\
Each parameter directly affects how the Agent interprets inputs, reasons about context, and executes actions using connected MCPs, Tools, and Workflows.

This section details every configurable field available in the **Agent Builder** interface.

***

### Saving changes

Agent settings save automatically. There is no **Save** button.

When you edit a setting, Zaia saves the complete valid configuration in the background. This includes the Agent’s identity, instructions, model, and behavioral settings.

Text fields, such as **Role** and **Prompt**, save after 1.25 seconds without typing. Selectors, sliders, and switches save after 300 milliseconds.

The interface shows **Saving...** while a change is pending, saving, or retrying. You can keep editing during this time.

Zaia preserves newer edits when an earlier save finishes. If a save temporarily fails, it keeps your local changes and retries automatically.

You cannot leave the configuration screen while changes remain pending. This prevents unsaved settings from being lost.

#### Provider and model

**Provider** and **Model** are saved together. When you select another provider, Zaia refreshes the available models and selects the first compatible model when possible.

Zaia only saves the configuration after it has a valid provider and model selection.

Changing only the **Model** triggers the same automatic save flow. The new selection is persisted without changing the Agent's Prompt or other settings.

***

### Summary

| Section             | Description                                            |
| ------------------- | ------------------------------------------------------ |
| **Model Selection** | Defines the LLM provider and model used for reasoning. |
| **Role**            | Establishes the Agent’s identity and purpose.          |
| **Prompt**          | Configures tone, logic, and communication rules.       |
| **Temperature**     | Controls creativity vs. consistency.                   |
| **Effort**          | Determines reasoning depth and iteration count.        |
| **Planning**        | Enables task decomposition and multi-step execution.   |
| **Supervision**     | Allows iterative validation and self-correction.       |
| **Tasks**           | Adds conditional automated behaviors.                  |
| **Internal Chat**   | Interactive space for testing and fine-tuning.         |

Together, these settings define how each Agent **thinks, decides, and acts** inside the Endless ecosystem.


# Model Selection

In Zaia Endless, each Agent can be powered by a specific **Provider** and **Model**.\
This configuration defines:

* Which **LLM** is used for reasoning
* How **billing and credit consumption** are handled

The model selection is part of the Agent configuration flow and is defined **after the Prompt**, ensuring that the Agent’s instructions are clear before choosing how it will reason.

***

### Where to Select the Model

The **Provider** and **Model** selector is located **below the main Prompt field** in the Agent configuration screen.

This positioning reflects the recommended workflow:

1. Define the Agent’s **Role**
2. Write the **Prompt**
3. Select the **Provider and Model**
4. Adjust behavioral settings (Temperature, Effort, Planning, Reasoning)

***

### How Providers Work

There are two ways to connect LLMs to your Agents.

#### Option 1 — Using Zaia Provider

When you select **Zaia** as the provider, your Agent uses models natively available on the platform (such as *Claude Sonnet 4.5*, *GPT-4o mini*, or *Grok 4.5*).

In this mode:

* You consume **Zaia platform credits** per execution
* Authentication and billing are fully managed by Zaia
* No API key configuration is required

This is the recommended option for most users who want a fully managed experience with instant access to multiple LLMs.

***

#### Option 2 — Adding a Custom Provider

You can also connect your **own LLM provider**, bypassing Zaia’s managed credits.

To configure a custom provider, go to:

```
Platform → Settings → Providers → Configure Provider
```

In this panel, you can:

* Set a **provider name** (e.g., “OpenAI Personal”, “Anthropic Enterprise”)
* Select the **provider type** (Anthropic, OpenAI, or Google AI)
* Paste your **API key**
* Optionally add an internal description for identification

Once saved, the provider becomes available in the **Provider** dropdown inside the Agent configuration.

When an Agent uses a custom provider:

* It consumes **your own API credits**
* Billing happens directly with the external provider
* Zaia does not charge credits for model execution

> 🔒 **Security note:** API tokens are stored in encrypted form and are only used when invoking the selected model for your Agent.

***

### Switching Models Per Agent

Model selection is **Agent-specific**.\
This allows you to:

* Use lightweight models for FAQs or simple Agents
* Assign more powerful models to complex, reasoning-heavy Agents
* Optimize cost, latency, and accuracy across your workspace

You can change the model at any time without modifying the Agent’s Prompt or logic.

***

### Best Practices

* Always define the **Prompt first**, then select the model
* Use **Zaia Provider** for faster setup and predictable billing
* Use **custom providers** when you need:
  * Cost optimization at scale
  * Enterprise contracts
  * Provider-specific features

***

👉 Choosing the right model ensures your Agent balances **performance, cost, and reasoning quality** according to its purpose.


# Internal Name

The **Internal Name** is used for internal control and reference purposes.\
It does not affect the public name, role, or identity of the Agent visible to users.\
Useful for distinguishing similar Agents operating under different contexts (e.g., “Sales Assistant v2” vs. “Sales Assistant Sandbox”).


# Role

The **Role** defines what the Agent is designed to do and establishes the foundation for its decision-making.\
It should summarize the Agent’s responsibilities and general behavior without procedural details.

**Best practices:**

* Keep it under 250 characters.
* Focus on *purpose* rather than *process*.
* Avoid overly broad descriptions.

**Example:**

> “Dental care and scheduling assistant — specialized in Endodontics and Aesthetic Dentistry for premium clients.”

This field serves as the Agent’s mission statement, guiding its reasoning and responses.


# Prompt

The **Prompt** field defines the operational and communication logic of the Agent.\
It determines *how* the Agent should behave, speak, and execute its tasks.

Prompts can contain:

* Behavioral instructions (tone, vocabulary, persona).
* Operational logic (how to respond to certain topics).
* Context about the target audience or environment.
* Examples of expected responses or outputs.

**Example:**

> “You are the virtual assistant of a premium dental clinic. Maintain a professional and empathetic tone. Always confirm client data before scheduling and avoid providing medical advice.”

Markdown formatting is supported, allowing structured sections like:

```
## Voice & Tone
## Procedures
## Escalation Rules
## Example Replies
```


# Temperature

**Temperature** defines the Agent’s level of creativity and variability.\
It influences how deterministic or imaginative the responses will be.

| Range     | Behavior                        | Recommended Use                   |
| --------- | ------------------------------- | --------------------------------- |
| 0.0 – 0.3 | Consistent, factual, analytical | Customer support, data analysis   |
| 0.4 – 0.7 | Balanced, adaptive              | General-purpose assistants        |
| 0.8 – 1.0 | Creative, expressive            | Marketing, storytelling, ideation |

Higher temperatures make the Agent explore alternative reasoning paths, while lower ones make it precise and predictable.


# Effort

**Effort** defines how much computational reasoning an Agent invests before producing an answer.\
It can be interpreted as the number of internal reasoning “steps” performed per message.

* **Low Effort:** fast, lightweight responses.
* **Medium Effort:** moderate contextual analysis.
* **High Effort:** deeper reasoning, multi-step orchestration, and better handling of complex logic.

> 💡 The higher the Effort, the more credit or API cost may be consumed, since additional iterations are executed internally.


# Capacities

Extra Capabilities allow you to enable **advanced execution features** that change how an Agent reasons, plans, and contextualizes its responses.

These capabilities are optional and should be enabled **only when required**, as they may impact response time and credit consumption.

***

### Planning

When **Planning** is enabled, the Agent automatically generates an **execution plan** at the start of each task.

This plan evaluates:

* The user’s request
* Available Tools
* Connected MCPs
* Required steps to reach the objective

Planning helps the Agent act in a more structured and predictable way before executing any action.

#### Ideal for

* Agents that interact with **multiple Tools or Workflows**
* Scenarios involving **API orchestration**
* Problem-solving tasks that require structured execution
* Complex flows where the Agent must decide *how* to act before acting

> 💡 **Tip:** Enable Planning for operational or automation-heavy Agents. For simple conversational Agents, it’s usually unnecessary.

***

### Reasoning

Reasoning controls the **depth of analysis** applied by the Agent when generating responses.

When enabled, you can choose a **Reasoning Mode**:

* **Low** — Fast responses for simple interactions and FAQs
* **Medium** — Balanced reasoning for most business use cases
* **High** — Deeper analysis and structured thinking for complex decisions

Higher reasoning levels improve accuracy and coherence but may increase response time and credit usage.

#### Ideal for

* Analytical or decision-oriented Agents
* Agents that evaluate conditions before acting
* Use cases involving logic, comparison, or multi-step thinking

> ⚠️ **Note:** Use higher reasoning levels only when necessary to avoid unnecessary cost and latency.

***

### Date and Time

When **Date and Time** is enabled, the Agent gains awareness of the **current date and time**.

You can optionally define a **Timezone**, or keep it set to **Auto**, allowing the platform to infer the correct timezone automatically.

This capability allows the Agent to:

* Answer questions involving dates or schedules
* Reference the current day, week, or time
* Perform time-based reasoning (e.g., deadlines, reminders, availability)

#### Ideal for

* Scheduling and calendar-related Agents
* Task management and reminders
* Context-aware conversations involving time

***

### Best Practices

* Start with **all Extra Capabilities disabled**
* Enable **Planning** only for complex or multi-step flows
* Adjust **Reasoning Mode** based on the Agent’s responsibility
* Enable **Date and Time** only if the Agent needs temporal awareness

Keeping Extra Capabilities minimal results in **faster, more predictable, and more cost-efficient Agents**.


# Conditional Prompts

**Conditional Prompts** allow you to define **instructions that are executed only when specific conditions are met** during a conversation.

***

### What Is a Conditional Prompt?

A Conditional Prompt is composed of three elements:

* **Name** — an internal identifier to help you organize your logic
* **Prompt** — the instruction that will be injected into the Agent when the condition is met
* **Condition** — the rule that determines *when* the prompt should be executed

When multiple Conditional Prompts exist, the **condition** is what determines which one applies in each situation.

***

### How Conditional Prompts Work

During a conversation, the Agent continuously evaluates the defined conditions.

When a condition matches the current context:

1. The corresponding **Conditional Prompt** is activated
2. Its instructions are applied to the Agent’s reasoning
3. The Agent responds or acts according to that injected prompt

This allows Agents to adapt behavior dynamically without changing their core Prompt.

***

### Examples of Use

* If the user asks to speak with a human → trigger a prompt that uses the **Ticket Creation Tool**
* If the user confirms an action → inject a prompt that executes a **Workflow**
* If a specific keyword appears → change tone, flow, or next steps
* If the conversation reaches a certain state → guide the Agent to finalize or escalate

***

### Best Practices

* Keep **conditions explicit and non-overlapping**
* Use Conditional Prompts for **logic and flow control**, not for core identity
* Avoid duplicating logic already defined in the main Prompt
* Disable unused Conditional Prompts to keep behavior predictable

> 💡 **Tip:** Think of Conditional Prompts as *contextual instructions* that activate only when needed.


# Internal Chat

The **Internal Chat** is a live execution, testing, and inspection environment built directly into the Agent Builder.\
It allows you to interact with your Agent using the **exact same configuration, reasoning engine, tools, and provider** that will be used in production.

More than a chat interface, the Internal Chat is designed for **debugging, validation, and deep inspection** of Agent behavior before deployment.

***

### What You Can Do With the Internal Chat

#### Test Real Agent Behavior

The Internal Chat runs your Agent exactly as it would run in production.\
You can use it to:

* Validate how the **Prompt** behaves in real conversations
* Test how **Temperature, Effort, Planning, and Reasoning** affect responses
* Verify how **Conditional Prompts** are triggered
* Adjust tone, flow, and instructions safely before publishing

***

#### Send Rich Inputs

The Internal Chat supports full interaction testing, including:

* Text messages
* **Images**
* **Audio files**
* **Documents and attachments**

This allows you to simulate real-world user behavior and test how your Agent handles different input types.

***

#### Inspect Every Message and Execution Step

Each Agent response can be fully **inspected**.

Using the inspection view, you can:

* See the **execution timeline** of the response
* Inspect every **iteration** performed by the Agent
* View tool calls, inputs, and outputs
* Understand how the Agent reasoned and which resources were used
* Analyze the complete **execution pipeline** that generated the response

This level of visibility makes it easy to debug unexpected behavior and optimize complex flows.

***

#### View Credit Consumption

The Internal Chat displays **credit usage per execution**, allowing you to:

* See how many credits each response consumes
* Compare different models, reasoning modes, or settings
* Optimize cost before deploying to production

> ⚠️ **Important:** Using the Internal Chat **does consume credits**, exactly like production conversations.

***

#### Manage Conversation History

The Internal Chat includes full conversation management tools:

* **Clear the current conversation** to start fresh tests
* Access a **complete history** of past interactions
* Restore previous conversations by date and time

This allows you to revisit older tests, compare behaviors over time, and reproduce specific scenarios.

***

### Why the Internal Chat Matters

The Internal Chat allows you to:

* Iterate safely without affecting users
* Debug complex Agent logic with full transparency
* Validate production behavior before publishing
* Optimize performance, cost, and reliability

It is the **primary tool for building high-quality, predictable Agents** in Zaia Endless.


# What Are Squads

Squads are a way to **group multiple Agents** under a shared goal. Instead of having isolated Agents, you can organize them to collaborate, specialize, and delegate interactions.

#### 🔹 Key Concepts

* **Container of Agents** → A Squad groups Agents into a single unit.
* **Collaboration Modes** → Decide how Agents coordinate:
  * **Hierarchical** → one Manager orchestrates and delegates.
  * **Horizontal** → all Agents can pass conversations among themselves, with a Principal as fallback.
* **Shared Resources** → Squads can access **Tables, Knowledge Bases, and Workflows** directly.
* **Native Routing** → Handovers between Agents are seamless to the user, based on Roles and Prompts.

#### 🔹 Management Modes

* **Hierarchical Mode**:
  * One **Manager Agent** acts as the orchestrator.
  * Delegates user requests to the right specialist Agent.
  * Recommended for **structured triage** (e.g., first-line support routing to Sales, Billing, or Technical).
* **Horizontal Mode**:
  * All Agents collaborate equally.
  * A **Principal Agent** is chosen as the safety fallback.
  * Recommended for **peer-based expertise** (e.g., product, pricing, logistics).

#### 🔹 Why Use Squads?

* Organize Agents by **domain** (Support, Sales, R\&D).
* Handle **complex conversations** where multiple specialties may be needed.
* Scale gradually — start with a Manager + 2 Specialists, then expand.


# Creating Squads

This guide focuses on the **practical steps and management actions** involved in creating and maintaining Squads inside Zaia Endless.

If you’re looking for conceptual explanations about what Squads are and when to use each mode, refer to the previous article.

***

### Step 1: Create a Squad

1. Go to **Builder → Squads**
2. Click **New Squad**
3. Choose a **Management Mode**:
   * **Hierarchical**
   * **Horizontal**
4. Define a **Name**
5. Optionally add a **Description** (internal use, up to 1000 characters)
6. Assign:
   * a **Manager** (Hierarchical mode), or
   * a **Principal Agent** (Horizontal mode)
7. Save the Squad

***

### Step 2: Add Agents to the Squad

Once the Squad is created, you can add Agents in two ways:

* **Link an existing Agent**\
  Use the *link* icon to attach an Agent to the Squad.
* **Create a new Agent**\
  Use the **+** button to create a new Agent that is automatically linked to the Squad.

Each Squad can contain multiple Agents, but only **one Manager or Principal** at a time.

***

### Promoting an Agent to Manager / Principal

You can change leadership at any time.

* In the Squad’s **Agents list**, open the Agent’s options menu
* Select **Promote to Manager** (or Principal)
* The previous Manager/Principal is replaced automatically

This is useful when:

* Reorganizing responsibilities
* Testing different orchestration strategies
* Iterating on Squad behavior without recreating it

***

### Copying the Squad ID

Each Squad has a unique identifier.

* Open the Squad’s options menu
* Click **Copy ID**

The **Squad ID** is useful for:

* Advanced inspection and debugging
* API-based interactions
* Referencing Squads in external systems or logs

> 💡 Tip: Keep the Squad ID handy when working with APIs or internal diagnostics.

***

### Managing Squads Over Time

Best practices for ongoing management:

* Keep Squad descriptions updated to reflect their real purpose
* Avoid adding Agents without a clear role
* Regularly review who acts as Manager/Principal
* Prefer **small Squads** with clear responsibilities


# Tools: Overview

## Understanding Tools and When to Use Them

In Zaia Endless, **Tools** are what extend an Agent’s capabilities beyond its core **Role + Prompt**.

By default, an Agent can only respond using the instructions defined in its Prompt.\
Whenever you want an Agent to **interact with data, trigger actions, integrate with systems, or escalate to humans**, you must create and configure the appropriate Tools.

***

### How the Agent Uses Tools

Agents decide to use a Tool based on the **Tool description**.

* If the Agent determines a Tool is needed but required inputs are missing, it will **ask the user for the missing information first**
* Once all required properties are available, the Agent executes the Tool
* If all logic and information fit inside the Prompt, **no Tool is required**

> 💡 **Best practice:** Tools should only be created when they are truly necessary. Fewer Tools lead to more predictable behavior.

***

### Types of Tools in Zaia Endless

Below are the Tools currently available in the platform and when to use each one.

***

#### 📡 HTTP Request

Allows the Agent to perform API calls to external services.

**Supported methods:**\
GET, POST, PUT, DELETE, PATCH

**Use when:**

* Integrating with third-party systems
* Fetching or sending data to external APIs

***

#### ⚙️ Code Execution

Allows the Agent to execute custom code snippets.

**Use when:**

* Performing calculations
* Transforming data
* Applying custom logic not covered by other Tools

***

#### 🌐 Web Search

Allows the Agent to search the web for up-to-date information.

**Use when:**

* Information is not available in Knowledge Bases
* Real-time or external context is required

***

#### 🎫 Ticket Creation

Creates a ticket and transfers the conversation to a human in the Endless CRM.

**Important:**

* Requires a **CRM Team** to exist
* This is the **only native way** to escalate a conversation to humans

***

#### 🏷️ Chat Tagging

Allows the Agent to classify chats with a **preapproved set of tags** after it replies.

**Use when:**

* Categorizing conversations without creating a ticket
* Keeping **Chat History** and **Tickets** filterable by topic or intent
* Preserving manual tags outside the Tool scope

***

#### 🚫 External User Blocking

Allows the main chat Agent to block an external user after confirming a bot-to-bot conversation.

**Use when:**

* The Agent has absolute certainty that the external user is another bot
* You must stop future messages from that external user

The tool is available only in supported external chat channels.

***

#### ✉️ Message Sending

Allows the Agent to send messages to **specific phone numbers** based on a defined condition.

**Use when:**

* Sending notifications
* Triggering outbound messages
* Automating alerts or confirmations

***

#### ⏰ Follow Up

Allows the Agent to send **follow-up messages after conversation inactivity**.

**Use when:**

* Re-engaging users
* Reminding users to complete an action
* Continuing conversations automatically

***

#### 📚 Knowledge Base Search

Allows the Agent to search within a Knowledge Base created in Zaia Endless.

**Use when:**

* Information is too large or dynamic for the Prompt
* You need structured, searchable documentation or FAQs

***

#### 📄 PDF Reader

Allows the Agent to read and extract information from PDF files.

Allows the Agent to read and reason over the **entire content of a PDF as a single contextual document**, without chunking or semantic fragmentation.

***

#### 📊 Table Tools

Tables are native databases inside Zaia Endless.\
Each type of interaction requires its own Tool.

Available Table Tools:

* **Table Row Insertion** — insert new records
* **Table Row Update** — update existing records
* **Table Row Semantic Search** — search by meaning using natural language
* **Table Row Similarity Search** — search by vector similarity (closest matches)

**Use when:**

* Managing leads, customers, tickets, or structured data
* Persisting information across conversations

> ⚠️ Tables must be created before configuring their Tools.

***

#### 🔄 Workflow Execution

Executes a pre-built Workflow.

**Use when:**

* Orchestrating multi-step processes
* Automating business logic (e.g., payments, onboarding, approvals)

***

#### 🧠 Contextual Memory

Allows the Agent to store and retrieve information across conversations.

**Examples:**

* Name
* Company
* Budget
* Preferences

Memory works like **dynamic variables**, and the Agent relies on the Tool description to understand what should be extracted and stored.

***

### Best Practices

* **Keep it simple** — If information fits in the Prompt, don’t create a Tool
* **Respect dependencies** — Create the resource first (Table, Workflow, CRM Team)
* **Write clear descriptions** — Always explain Tools in natural language
* **Test internally** — Use the Internal Chat to validate Tool behavior before publishing

***

### Key Takeaway

Tools are what make Agents **active** inside Zaia Endless.

They connect your Agent to:

* Knowledge Bases
* Tables
* Workflows
* External APIs
* Humans

But remember:\
**More Tools = more complexity.**\
Start simple and only add what your Agent truly needs.


# Available Tools


# HTTP Request Tool

The **HTTP Request Tool** allows your Agent to interact with external APIs and services, extending its capabilities beyond the native Zaia Endless ecosystem.

With it, your Agent can retrieve data, create or update records, trigger third-party actions, or synchronize information with external systems in real time.

***

### 🔹 How the HTTP Request Tool Works

1. You define the Tool with a **clear natural-language description** explaining when it should be used.
2. The Agent reads this description to decide **if and when** the Tool applies during a conversation.
3. You define **Properties (variables)** that the Agent must collect (e.g., ID, email, date).
4. If required properties are missing, the Agent will **ask the user for them first**.
5. Once all required data is available, the Agent executes the HTTP request using your configuration.

This ensures that every request is **complete, contextual, and accurate** before execution.

***

### 🔹 Supported HTTP Methods

The HTTP Request Tool supports all standard REST methods:

* **GET** → Retrieve information
* **POST** → Create new resources
* **PUT** → Update existing resources
* **PATCH** → Perform partial updates
* **DELETE** → Remove resources

***

### ⚙️ Configuration Fields

When creating an HTTP Request Tool, you configure:

* **Name**
* **Description** (what the Tool does and when to use it)
* **URL**
* **Method**
* **Headers**
* **Query parameters**
* **Body**
* **Properties (variables)**

Each property includes:

* Type (string, number, etc.)
* Description (used by the Agent to ask the user correctly)
* Required / optional flag

***

### 🧩 Property Picker (Variable Insertion)

When editing **Headers**, **Query**, or **Body**, Zaia Endless provides a **Property Picker**.

Instead of typing variables manually (`{{variableName}}`), you can:

1. Click inside any field (Headers, Query, or Body).
2. A floating list appears showing all defined properties.
3. Click a property to automatically insert it in the correct format.

💡 **Example**\
If a property is called `userId`, selecting it automatically inserts:

```
{{userId}}
```

This eliminates syntax errors and significantly speeds up configuration.

***

### 🤖 cURL Import Assistant

Zaia Endless includes a **Creation Assistant** that allows you to **import a full HTTP configuration directly from a cURL command**.

#### How it works:

1. Click the **magic wand / assistant icon** when creating an HTTP Request Tool.
2. Paste a full `curl` command (or describe the request).
3. The Assistant automatically:
   * Detects the **HTTP method**
   * Extracts the **URL**
   * Parses **headers**
   * Converts request body fields into **Properties**
   * Pre-fills the Tool configuration

This is especially useful when:

* You already have API examples from documentation
* You are migrating existing integrations
* You want to avoid manual configuration errors

💡 **Example cURL**

```bash
curl -X POST "https://api.example.com/users" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@email.com"}'
```

The Assistant will automatically generate:

* URL
* Method: POST
* Headers
* Body
* Properties (`name`, `email`)

You can then refine descriptions and required fields before saving.

***

### 🔹 Example Setup

**Name:** Customer API Lookup\
**Description:**\
“Allows the Agent to retrieve customer information from the external CRM using a customer ID.”

**Property:**

* `id` (number) → “Customer ID provided by the user. Must be numeric.”

**Configuration:**

* URL: `https://api.crm.com/customers/{{id}}`
* Method: GET
* Headers:

```json
{
  "Authorization": "Bearer {{api_key}}"
}
```

**Example POST Body:**

```json
{
  "name": "{{name}}",
  "email": "{{email}}",
  "project_type": "{{project_type}}"
}
```

If `project_type` is missing, the Agent will ask the user for it before executing the request.

***

### 🧠 Best Practices

* Be explicit in property descriptions\
  *Example:* “Date of birth in format YYYY-MM-DD.”
* Keep Tools focused — one Tool per clear API action.
* Always test requests using the **Internal Chat** before publishing.
* Avoid hardcoding secrets directly in requests.
* For complex APIs, split actions into multiple Tools.
* Use the **Property Picker** and **cURL Assistant** to reduce errors.

***

### ✅ Key Takeaway

The HTTP Request Tool is the **bridge between your Agent and the external world**.

By combining:

* Clear descriptions
* Well-defined properties
* The Property Picker
* The cURL Import Assistant

You enable your Agents to safely, dynamically, and intelligently interact with any external API — asking for missing data when needed and executing only when everything is ready.


# Code Execution Tool

The **Code Execution Tool** allows your Agent to run predefined code during a conversation.\
It is useful for scenarios where the Agent needs to perform calculations, transform data, validate inputs, or execute custom business logic that goes beyond standard Tools.

***

### 🔹 How It Works

* You configure the Tool with a **description** that explains in plain language what the code does.

  > The Agent decides to call this Tool based on that description.
* You can define **properties (variables)** that the Agent will collect from the user before running the code.
  * Each property has a name, type, and description.
  * The description tells the Agent how to extract and format the data from the conversation.
* The Tool contains a **code block**, where you implement the function `main()`.
  * The Agent will pass the collected properties as inputs.
  * The function should return the processed output.
* **Important:** If the Agent decides to use the Tool but some properties are missing, it will **first ask the user for those values**, then execute the code.

***

### 🔹 Configuration Fields

When creating a Code Execution Tool:

1. **Name** → A clear label, e.g. `Discount Calculator`
2. **Description** → Natural language explanation, e.g.\
   *“Executes a calculation to determine the final price after discount.”*
3. **Properties** → Variables collected from the user, e.g.:
   * `price` (number) → *“The original product price in USD.”*
   * `discount` (number) → *“The discount percentage to apply.”*
4. **Code** → A JavaScript function inside `main()` that processes the input and returns the result.

***

### 🔹 Example Setup

**Name:** Discount Calculator\
**Description:** *“Executes a calculation to return the final product price after applying a discount.”*

**Properties:**

* `price` (number) → *“The original price in USD.”*
* `discount` (number) → *“Discount percentage (0–100).”*

**Code Example:**

```javascript
function main({{price}}, {{discount}}) {
  const finalPrice = price - (price * (discount / 100));
  return { finalPrice };
}
```

### 🔹 Example Use Case

User: *“The product costs 200 dollars, and I have a 15% discount. What’s the final price?”*

1. Agent decides to use the **Discount Calculator Tool**.
2. Properties collected: `price = 200`, `discount = 15`.
3. Code executes: `200 - (200 * 0.15) = 170`.
4. Agent responds: *“The final price after discount is **170 USD**.”*

***

### 🔹 Best Practices

* **Keep the description simple** → this ensures the Agent knows when to use the Tool.
* **Validate inputs** inside your code (e.g., check if numbers are positive).
* **Return structured outputs** in JSON, so the Agent can use the result consistently.
* **Test internally** before exposing the Tool to users.

***

### ✅ Key Takeaway

The Code Execution Tool gives your Agent flexibility to handle **custom logic**.\
With clear property descriptions and well-written code, your Agent can dynamically collect inputs, process them, and deliver accurate results in real time.


# Web Search Tool

The **Agentic Web Search Tool** allows your Agent to search the public web when it needs information that is not available in its existing context or knowledge sources. This is useful for retrieving up-to-date external information, validating facts, or gathering references from specific websites.

***

### 🔎 Overview

This tool gives your Agent an agentic way to search the web.

The Agent sends a textual description of what it needs to find. The search runs using OpenAI web search.

The tool returns:

* A consolidated text with the most relevant findings
* A list of source URLs found during the search

***

### ⚙️ Configuration Fields

1. **Name** — A clear name that identifies the purpose of the tool.\
   Example: `Product Documentation Search`
2. **Description** — Tells the Agent when and why it should use the tool.\
   Keep it specific so the Agent can choose the tool at the right time.
3. **Allowed Domains** — Optionally restricts search results to specific websites.\
   Use this when you want answers from trusted or official sources only.\
   Enter domains without `https://`.\
   Example: `openai.com`, not `https://openai.com/`.\
   A root domain also covers its subdomains.\
   Example: `openai.com` also covers subdomains.\
   OpenAI supports up to `100` allowed domains for `web_search`.
4. **Effort** — Defines the reasoning effort used during the search.\
   Available options: `low`, `medium`, `high`
5. **Execution** — Defines whether the tool is optional or mandatory.\
   Available options:
   * `eligible` — The Agent decides when to use the tool
   * `compulsory` — The tool must be executed
6. **Prompt** — Optional extra instruction that guides how the search should be conducted.\
   Use it for short guidance that improves search quality.
7. **LLM Provider** — Optional provider override for this tool.\
   Only **OpenAI providers** are supported.

***

### 🧠 How it works

1. The Agent decides to use the tool based on its configuration.
2. The Agent sends a textual description of the search it needs.
3. The tool performs the search using OpenAI web search.
4. If **Allowed Domains** is configured, results are limited to those domains.
5. **Effort** controls how much reasoning the search applies.
6. **Execution** controls whether use of the tool is optional or mandatory.

This makes the tool useful for external lookups that require fresh information or verifiable references.

{% hint style="info" %}
Domain filtering follows OpenAI `web_search` behavior in the Responses API. OpenAI supports up to `100` entries in `allowed_domains` or `blocked_domains`, but this tool currently exposes **Allowed Domains** only. These filters are not supported by the legacy `web_search_preview` tool or by Chat Completions search models. See [OpenAI Web Search domain filtering](https://platform.openai.com/docs/guides/tools-web-search).
{% endhint %}

***

### 📘 Example Setup

* **Name**: `Product Documentation Search`
* **Description**: `Use this tool when you need to find reliable information on official product documentation websites.`
* **Allowed Domains**: `docs.example.com`, `help.example.com`
* **Effort**: `medium`
* **Execution**: `eligible`
* **Prompt**: `Prefer official documentation and summarize the most relevant findings.`
* **LLM Provider**: `default OpenAI provider`

This setup helps the Agent search trusted documentation sources and return concise, grounded answers.

***

### 💡 Best Practices

* Keep the **Description** specific so the Agent knows when to use the tool.
* Use **Allowed Domains** when you want to restrict searches to trusted sources.
* List domains in plain form, without protocol prefixes.
* Choose higher **Effort** only when the task needs deeper reasoning.
* Use **compulsory** execution only when every relevant interaction must include a web lookup.
* Use the **Prompt** field for concise guidance, not long procedural instructions.


# Ticket Creation Tool

The **Ticket Creation Tool** allows an Agent to hand off a conversation to a human team natively inside **Zaia Endless CRM**.\
Instead of relying on external CRMs or manual escalation, this tool creates a ticket directly in the internal support area, ensuring a seamless human takeover with full context.

***

### 🔎 What It Does

* Creates a ticket in a specific **CRM Team**
* Transfers the full conversation context and collected data
* Allows human operators to continue exactly where the Agent stopped
* Enables structured filtering and prioritization using **tags**

This is the **official and recommended way** to escalate conversations from Agents to humans inside Endless.

***

### ⚙️ Configuration

When creating a Ticket Creation Tool, you configure:

* **Name**\
  A clear label for the tool\
  *Example:* `Escalate to Support`
* **Description**\
  Defines *when* the Agent should trigger the ticket\
  *Example:*\
  “Create a ticket when the user asks to talk to a human or when the request cannot be solved automatically.”
* **CRM Team**\
  The team responsible for receiving the ticket
  * Must be created beforehand in **CRM → Teams**
  * Can include one or multiple human operators

***

### 🆕 Automatic Tags on Ticket Creation

The Ticket Creation Tool now supports **automatic tag assignment** when a ticket is created.

#### 🏷️ How Tags Work

* Tags are created and managed in **CRM → Tags**
* Each tag has:
  * **Name**
  * **Description**
  * **Color** (for visual identification)
* Tags are **not created by the Agent** — they must exist beforehand

When the ticket is created:

* The Agent analyzes the **conversation context**
* It selects the most appropriate tag(s) based on the **tag descriptions**
* The selected tags are automatically applied to the ticket

***

#### 💡 Example

If the user is asking about billing or payments and the conversation is escalated:

* Existing tag: **Finance**
  * Description: “Questions related to billing, payments, invoices, or pricing.”
* Result:
  * The Agent creates the ticket
  * Automatically applies the **Finance** tag

Human operators can then easily **filter tickets by tag**, improving triage and response time.

***

### 🔄 Runtime Behavior

1. The Agent detects the need for human escalation
2. The Ticket Creation Tool is triggered
3. A ticket is created in the selected CRM Team
4. Relevant tags are applied automatically
5. A human operator takes over the conversation

All tickets are visible in **CRM → Attendants / Conversations**, fully searchable and filterable by tags.

***

### 📌 Example Use Cases

* **Support escalation**\
  User: “I want to talk to a real person.”\
  → Ticket created and routed to *Support Team*
* **Sales follow-up**\
  Agent collects lead data and user requests a proposal\
  → Ticket created and assigned to *Sales Team*
* **Specialized routing with tags**\
  Conversation about refunds\
  → Ticket created with *Finance* tag

***

### ✅ Best Practices

* Always associate the tool with a valid CRM Team
* Write very explicit tool descriptions so the Agent knows exactly when to escalate
* Create clear, well-described tags in advance
* Use tags to simplify filtering and prioritization for human teams
* Combine with **Tasks** to trigger escalation under specific conditions

***

### 🎯 Key Takeaway

The Ticket Creation Tool ensures **reliable, native human handoff** inside Zaia Endless.\
With automatic tag assignment, escalated conversations arrive **contextualized, categorized, and ready for action**, allowing human teams to work faster and more efficiently.


# Chat Tagging Tool

Use the **Chat Tagging Tool** to enable automatic chat tagging.

After each Agent response, the Agent can classify the conversation using approved tags. Tags are applied at the chat level. This works without creating a ticket.

***

### 🔎 What It Does

The Chat Tagging Tool lets an Agent keep chat tags aligned with the conversation context.

The Agent can:

* Add or remove existing tags on the current chat
* Use only tags selected in the tool's **Allowed Tags**
* Evaluate the full conversation context, not only the latest message

The Agent cannot create new CRM tags. It can only assign or remove existing tags preselected in the tool configuration.

### ⚙️ How to enable automatic chat tagging

{% stepper %}
{% step %}

#### Create the tags

Go to **CRM → Tags**. Create the tags that the Agent may manage.

Give each tag a clear name and description. For example, use `Billing`, `Refund`, or `Priority`.
{% endstep %}

{% step %}

#### Create a Chat Tagging Tool

Create a tool with the **Chat Tagging** type.

Add a clear name and description. The description should define the categories the Agent should identify.
{% endstep %}

{% step %}

#### Select the allowed tags

In **Allowed Tags**, select the existing CRM tags this tool may manage.

Only these tags can be added or removed by this tool.
{% endstep %}

{% step %}

#### Activate and attach the tool

Keep the tool active. Then link it to the Agent that should tag chats automatically.

There is no separate tagging toggle. The tool must be active and have valid allowed tags.

After replies, the Agent can automatically update the chat's allowed tags when the conversation context changes.
{% endstep %}
{% endstepper %}

### 🧠 How it works

The Agent receives the allowed tags, their descriptions, and the managed tags currently on the chat.

It uses this information and the conversation context to determine the desired classification. It cannot manage any tag outside the selected **Allowed Tags**.

### ⏱️ Execution behavior

The Chat Tagging Tool works in **post-response mode**. It is evaluated after the Agent sends a response.

The tool is called only when the desired managed tag state differs from the current state. If nothing should change, no tool call is made.

This avoids unnecessary updates during interactions that do not change the chat classification.

### 🔄 Synchronization rules

When a change is needed, the Agent returns the final desired state for the tool's allowed tags. The system then synchronizes only that managed set.

The system:

* Adds allowed tags included in the desired state
* Removes allowed tags that should no longer remain
* Prevents duplicate tags

Tags outside the tool's allowed set remain unchanged. This includes manual and operational tags that the tool does not manage.

### 👀 Visibility in Inbox

Chat tags are stored at the **chat level**.

They are:

* Visible in **Inbox → Chat History**
* Visible in **Inbox → Human Support → Tickets**
* Available as filters in both areas

This helps teams find and prioritize conversations by category.

### 📌 Best practices

* Select only stable categories the Agent should manage.
* Write distinct descriptions for tags with similar meanings.
* Keep manual or operational tags outside **Allowed Tags** when they must persist.

***

### ✅ Key Takeaway

The Chat Tagging Tool enables automatic chat tagging after an Agent response.

Create tags in **CRM → Tags**, select them as **Allowed Tags**, activate the tool, and link it to an Agent. The Agent can then update only those existing tags when the conversation classification changes.


# Follow Up Tool

The **Follow Up Tool** allows an Agent to schedule proactive messages based on the **current conversation context**, enabling timely re-engagement when the user stops responding — without breaking the conversational flow.

This tool is especially useful for sales, lead qualification, onboarding, reminders, and pending decision scenarios.

***

### 🔎 What the Follow Up Tool Does

* Schedules one or more follow-up messages during a conversation.
* Uses **conversation context and conditions** to decide *if* a follow-up should be scheduled.
* Defines **when** the message should be sent and **what** it should say.
* Automatically cancels follow-ups if the user re-engages before the scheduled time.
* Allows operators to **view, edit, or delete** scheduled follow-ups directly from the conversation history.

***

### ⏱️ Channel Limitation (Important)

When the Agent is connected to **WhatsApp Official** or **Instagram**, follow-ups must respect the **24-hour messaging window**:

* The follow-up must be scheduled **within 24 hours of the user’s last message**.
* If the window expires, the follow-up will not be delivered.

This behavior follows Meta’s official messaging policies.

***

### 🧠 How Follow Ups Are Evaluated

The key concept to understand:

> **The Agent evaluates follow-up conditions at the moment it sends a message — not in the future.**

#### What this means in practice:

* The Agent **does not know** whether the user will reply or not.
* It **predicts the need for a follow-up** based on:
  * The current conversation state
  * The user’s intent
  * What information is still missing
  * Whether the conversation feels “open” or “pending”

If the condition matches, the Agent:

1. Decides that a follow-up *may be needed*
2. Reads the scheduling prompt
3. Schedules the message for a future time

***

### ⚙️ Tool Configuration

Each Follow Up entry contains:

#### 1️⃣ Name

A short identifier for the follow-up scenario.

Example:\
`Waiting for car preference`

***

#### 2️⃣ Conversation Stage

Describes **when this follow-up should be scheduled**, based on the current state of the conversation.

This is **not** about future behavior.\
It’s about **what is true right now**.

**✅ Good examples of conversation stages:**

* “The user asked about cars but hasn’t specified a model or brand yet.”
* “The user showed interest in pricing but didn’t confirm the plan.”
* “The user requested information but stopped responding before choosing an option.”
* “The user asked for a proposal but hasn’t shared required details.”

❌ Avoid future assumptions like:

* “If the user doesn’t reply…”\
  (The Agent cannot know this yet.)

***

#### 3️⃣ Scheduling Prompt

Defines **when** the follow-up should be sent and **what message** should be scheduled.

This prompt tells the Agent:

* How long to wait
* What tone to use
* What question or reminder to send

**✅ Good scheduling prompt examples:**

* “After 10 minutes, ask if I can send the complete list of available cars.”
* “In 30 minutes, politely check if the user needs help choosing a plan.”
* “After 1 hour, remind the user that support is available if they have questions.”
* “Later today, follow up asking if the proposal should be adjusted.”

***

### 🔄 Runtime Behavior

#### Scheduling

* Follow-ups are scheduled immediately after the Agent sends a message.
* The scheduled message appears in the conversation history.

#### Automatic Cancellation

* If the user sends **any message before the follow-up time**:
  * All pending follow-ups are automatically canceled.
  * The Agent may schedule **new follow-ups**, based on the updated context.

#### Manual Control

Operators can:

* See scheduled follow-ups inside the conversation timeline
* Edit:
  * Send date and time
  * Message content
* Delete follow-ups if needed

This gives full operational visibility and control.

***

### 🔁 Fallback Follow Up (Optional)

You can define a **Fallback Follow Up**, used when:

* None of the configured follow-up conditions match
* The Agent still considers a re-engagement useful

This ensures the Agent always has a safe default behavior.

***

### 📌 Practical Example

**Conversation**\
User: “I want to know more about cars.”

Agent asks follow-up questions (brand, model, type).

**Conversation Stage**\
“The user showed interest in cars but hasn’t specified which one yet.”

**Scheduling Prompt**\
“After 10 minutes, ask if I can send the complete list of available cars.”

**Result**

* Follow-up is scheduled
* If the user replies before 10 minutes → follow-up is canceled
* If not → message is sent automatically

***

### 🧠 Best Practices

* Write conversation stages based on **present context**, not future outcomes.
* Keep scheduling prompts clear and time-specific.
* Use follow-ups to unblock decisions, not to spam users.
* Always respect the 24-hour window on WhatsApp and Instagram.
* Monitor and adjust follow-ups from conversation history when needed.


# Knowledge Base Search Tool

The **Knowledge Base (KB) Search Tool** allows your Agent to query structured repositories of documents, FAQs, guides, or policies created inside Zaia Endless.\
It is the most efficient way to ensure your Agent always has access to updated and reliable information without overloading the main Prompt.

***

### 🔎 What Is a Knowledge Base?

A Knowledge Base in Endless is a structured container where you store information such as:

* Company policies and procedures
* Product documentation
* Pricing and plan descriptions
* Frequently Asked Questions (FAQs)
* Training and onboarding materials

Unlike the Agent Prompt, Knowledge Bases are optimized for **search and retrieval**, allowing the Agent to access only what is relevant to each question.

***

### ⚙️ How the Tool Works

* The **Description** field defines *when* the Agent should use this tool.
* You must link the tool to an existing Knowledge Base using its **ID**.
* When triggered, the Agent searches the Knowledge Base and integrates the most relevant results into its response.

***

### 🆕 Execution Options

The Knowledge Base Search Tool includes two execution toggles that control how the search behaves:

#### 🔁 Execute Always

When enabled, the Knowledge Base search is executed on **every Agent response**, regardless of the user’s question.

* Use when the Knowledge Base contains **critical context** that should always influence responses.
* When disabled, the Agent decides dynamically whether the KB is relevant.

***

#### 📄 Preselect Documents

When enabled, the Agent first selects the **most relevant document** before searching its content.

* The selection is based on the **Description field of each document** in the Knowledge Base.
* After choosing the best-matching document, the Agent searches only within the blocks generated from that document.

This improves precision and performance, especially in Knowledge Bases with many documents.

***

### 📐 When to Use a Knowledge Base

Use a Knowledge Base when:

* Information changes frequently (pricing, policies, documentation)
* Content is too long for the Agent Prompt
* Structured retrieval is required

**Tip:**\
Keep stable behavioral rules in the Prompt, and store long or evolving information in Knowledge Bases.

***

### 🛠️ Setup Example

**Scenario:** Your Agent needs to answer questions about pricing.

1. Create a Knowledge Base
   * Name: Pricing and Plans
   * Upload pricing documentation or FAQs
2. Configure the Tool
   * Description:\
     “Use this tool when the user asks about prices, plans, billing, or upgrades.”
   * Knowledge Base ID: Pricing and Plans
   * Execute Always: Disabled
   * Preselect Documents: Enabled

If a user asks *“What’s included in the Pro Plan?”*, the Agent retrieves the correct pricing information directly from the Knowledge Base.

***

### ✅ Best Practices

* Write clear, action-oriented tool descriptions
* Use meaningful descriptions for each document in the Knowledge Base
* Enable **Preselect Documents** for large or diverse KBs
* Keep Knowledge Bases updated to avoid outdated answers
* Avoid duplicating the same content in both the Prompt and the KB

***

### 🎯 Key Takeaway

The Knowledge Base Search Tool gives your Agent structured, up-to-date knowledge on demand.\
With **Preselect Documents**, retrieval becomes faster and more precise by narrowing the search to the most relevant document before reading its content.

Used correctly, it keeps Agents accurate, scalable, and easy to maintain.


# Table Tools

Table Tools allow Agents to interact with structured data in Endless. They provide the ability to **insert, update, search, and compare data directly inside tables**, making Agents more autonomous in managing business information.

These tools are essential when the Agent needs to **store new information**, **update existing records**, or **search across large datasets** for relevant answers.

***

### 📝 Insert Row in Table

* **What it does**: Inserts a new row into a specific table with information collected during the conversation.
* **When to use**:
  * Collecting user feedback.
  * Storing contact details from leads.
  * Recording structured inputs that Agents gather step by step.
* **Important**: The Agent will only call this tool after ensuring it has collected all required fields for the table.

***

### ✏️ Update Row in Table

* **What it does**: Updates existing records in a table with new or corrected information.
* **When to use**:
  * A customer updates their contact details.
  * Correcting errors in a record.
  * Tracking process stages (e.g., status change from *Pending* → *Completed*).

***

### 🔎 Semantic Search in Table

* **What it does**: Allows Agents to run **semantic searches** inside table rows. Instead of relying only on exact matches, the Agent can interpret **meaning and context** of the query.
* **When to use**:
  * Finding relevant user feedback (even if the exact keywords differ).
  * Searching for contextual information in descriptive fields.
  * Recalling similar cases from historical datasets.
* ⚠️ **Key Requirement**:\
  Semantic search only works if the **column is explicitly enabled for semantic indexing**.
  * While configuring the table, toggle **Enable Semantic Search** for the columns where you want the Agent to run contextual queries (e.g., free text, notes, messages).
  * Columns without this option enabled will be ignored in semantic queries.

***

### 🔍 Similarity Search in Table

* **What it does**: Finds records that are **most similar** to the input provided by the user.
* **When to use**:
  * Searching for users with similar names or IDs.
  * Matching product descriptions.
  * Detecting duplicates or related records.
* **Difference from Semantic Search**:
  * **Similarity Search** → looks for closest matches based on embeddings (vectors).
  * **Semantic Search** → interprets meaning and context, broader and more flexible.

***

### ✅ Best Practices

* Always design tables with **clear column names and descriptions**.
* Use **semantic search only for text-heavy columns** where meaning matters (e.g., feedback, notes, support tickets).
* For structured fields (e.g., CPF, Email, Phone), prefer **Similarity Search** for better precision.
* Agents will automatically gather all required variables (like column values) before executing insert or update actions.

***

👉 With these tools, your Agents can **not only answer queries**, but also **write, update, and search structured datasets**, becoming a powerful interface between conversations and your company’s internal data.


# Message Sending Tool

The **Message Sending** Tool lets an Agent send outbound WhatsApp messages to specific phone numbers.

Use it for alerts, summaries, handoffs, reminders, and operational notifications. Messages are sent immediately when the Agent decides to use the tool.

***

### 🔎 What It Does

With Message Sending, an Agent can:

* Send regular text messages
* Send approved WhatsApp templates on official connections
* Try text first, then fall back to a template when the 24-hour window is closed
* Choose the destination dynamically or use predefined numbers

***

### ⚙️ How the Tool Works

The Agent decides to use the tool based on its description and instructions.

At runtime:

1. The Agent decides whether a message should be sent.
2. It determines the destination phone number.
3. It uses the configured send mode.
4. Zaia sends the message through the selected connection.

***

### 📞 WhatsApp Connection Rules

#### WhatsApp (Official)

Official WhatsApp connections support three send modes:

* **Text**
* **Template**
* **Text with template fallback**

**Text**

Zaia sends a regular message.

This works when the recipient is inside an active 24-hour WhatsApp window.

**Template**

Zaia sends an approved WhatsApp template directly.

Use this mode when you need a pre-approved outbound message.

**Text with template fallback**

Zaia tries to send a regular message first.

If WhatsApp rejects the message because the 24-hour window expired, Zaia sends the configured template instead.

> ⚠️ Template fallback is not generic. It only runs for the specific WhatsApp window-expired error.

#### WhatsApp (Waha)

Waha connections support **text only**.

Templates and template fallback are not available on Waha.

***

### 📲 Predefined Phone Numbers vs Dynamic Discovery

#### Predefined phone numbers

When enabled:

* You define one or more phone numbers
* The tool sends only to those numbers
* This works well for internal alerts and fixed recipients

#### Dynamic phone number discovery

When disabled:

* The Agent determines the destination number at runtime
* The number can come from the conversation context
* This works well for context-aware notifications

***

### 🧩 Template Behavior in the Tool

When the selected connection is **WhatsApp (Official)**, Zaia only lists templates that are:

* Approved in Meta
* Available for that connection
* Valid for the linked WhatsApp account

Zaia builds the template inputs dynamically from Meta's schema. This includes:

* **Body** variables
* **Header** variables
* **Button** variables
* **Header image** input, when required

In the tool, template fields can be filled partially. Missing values can be completed during execution from context, execution data, or the LLM output.

If a value already exists in the tool configuration, Zaia keeps it. If a value is missing, Zaia can merge extra variables into the template payload.

***

### 🖼️ Image headers

Templates with an image header accept:

* A public URL
* A stored file
* A data URL

Before sending, Zaia converts the image into the format accepted by the WhatsApp API.

***

### ✍️ Defining the Message Content

For **text** mode, content is controlled by prompt instructions.

You can:

* Define a fixed message
* Instruct the Agent to generate the message dynamically

For **template** modes, content comes from the selected WhatsApp template and its variables.

#### Example instruction

> “When you create a support ticket, send a WhatsApp message to **11 984444444** containing:
>
> * A summary of the conversation so far
> * The user’s phone number as a clickable link in the format\
>   `https://wa.me/55{{user_phone}}`”

In this case, the Agent writes the text, injects context, and sends the message to the selected number.

***

### ✅ Validations and Restrictions

Zaia validates template data before sending.

This includes limits for fields such as:

* Body text
* Header text
* OTP values
* Button URL suffixes

Templates only work when the official WhatsApp connection is active and correctly configured. If the template cannot be resolved or validated by Meta, the send is blocked.

For Workflow-based outbound messaging, see [Message Sending Node](/workflows/workflow-nodes/message-sending-node). For official connection requirements, see [WhatsApp (Official)](/channels/channel-types/whatsapp-official).

***

### 📌 Recommended Usage Pattern

Use a dedicated phone number for outbound notifications whenever possible.

This helps:

* Protect your main number reputation
* Control outbound volume
* Isolate operational traffic from live conversations

***

### 🧠 Best Practices

* Be explicit in the tool description so the Agent knows when to send
* Use **text** for active conversations
* Use **template** when you need an approved outbound message
* Use **text with template fallback** only when a valid fallback template exists
* Avoid excessive outbound traffic

***

### ✅ Key Takeaway

The **Message Sending** Tool supports both text and approved WhatsApp templates.

With an official WhatsApp connection, you can send text, send templates directly, or recover from an expired 24-hour window with controlled template fallback.


# Workflow Execution Tool

The **Workflow Execution Tool** allows Agents to trigger specific workflows that you have configured in Endless. Instead of linking directly to a single workflow, this tool is connected to a **workflow trigger** — a node inside a workflow known as **Agent Tool Request**.

This flexibility means that:

* You can have **multiple triggers** inside the same workflow.
* Each trigger can be linked to a different Execution Tool.
* Depending on the context, the Agent will decide which Execution Tool (and therefore which trigger) to call.
* The workflow will then execute only the scenario linked to that trigger.

***

### 🔑 Key Concepts

#### **Workflow Trigger**

* A trigger is a defined entry point inside a workflow.
* It is created using the **Agent Tool Request** node.
* Each trigger has its own name and logic, allowing multiple workflows or paths to exist inside the same workflow.

#### **Execution vs. Trigger**

* **Execution Tool:** What the Agent can call.
* **Trigger inside Workflow:** The specific entry point that will be executed.
* In practice, you configure the tool to point to one of the workflow’s triggers.

***

### 🛠️ Configuration

When creating the Workflow Execution Tool, you must define:

1. **Trigger** – select which workflow trigger (Agent Tool Request) this tool should call.
2. **Name** – how the tool will be referenced internally by the Agent.
3. **Description** – clearly explain what the tool does. The Agent will rely on this description to decide when to use it.

***

### 📌 Example Use Cases

* **Order Processing Workflow:**
  * One trigger could handle order creation.
  * Another trigger in the same workflow could handle cancellations.
  * Each trigger is linked to a different Execution Tool.
* **Support Automation Workflow:**
  * One trigger could escalate to Level 2 Support.
  * Another trigger could send a satisfaction survey.
* **Multi-Path Workflow:**
  * All scenarios exist in a single workflow.
  * The triggers define which path to follow depending on the tool used.

***

### 🧠 How the Agent Uses It

* If the Agent identifies that the user’s request matches a scenario handled by a workflow, it will check the available Execution Tools.
* The Agent decides **which Execution Tool** (and therefore which trigger) is relevant.
* The workflow is executed, running the nodes you designed under that trigger.

***

✅ This design gives you **scalability and modularity**: you don’t need to create a new workflow for every scenario — you can create one large workflow with multiple entry points, each activated by a different Execution Tool.


# Contextual Memory Tool

The **Contextual Memory Tool** allows your Agent to **store and retrieve structured information across conversations**, enabling it to "remember" past interactions, user preferences, and relevant data. This transforms your Agent from a simple assistant into a **truly contextual and personalized companion**.

***

### Contextual Memory in Squads

Memory access depends on the Squad management mode:

* **Hierarchical mode**: only the Squad Manager uses Contextual Memory.
* **Horizontal mode**: every Agent in the Squad can use Contextual Memory.

This behavior is defined by the selected management mode. Configuring the tool does not change access, routing, or memory persistence.

***

### 🔑 Key Capabilities

* **Custom Properties**: You decide what kind of information should be stored (e.g., names, preferences, conversation summaries, tool usage).
* **Typed Data**: Each property can have a type (`string`, `number`, `boolean`), making the memory precise and structured.
* **Natural Language Descriptions**: Define, in plain language, what the Agent should store, when to store it, and in which format.
* **Sensitive Flag**: Mark certain data as **sensitive** so it won’t be visible to human support agents if a chat is escalated.
* **Retrieval Across Sessions**: Data stored can be retrieved in future interactions, creating continuity across multiple conversations.

***

### 🛠️ How to Configure

When creating a **Contextual Memory Tool**, you can:

1. **Add Properties**
   * New tools include `interacoes` and `chamadasDeTool` by default.
   * `chamadasDeTool` is marked as sensitive by default.
   * Example:
     * `interactions (string)` → A list with the main points of the conversation.
     * `toolCallHistory (string)` → A bullet list of all tools called and their results.
     * `people (string, sensitive)` → Names, roles, or preferences mentioned by the user.
2. **Describe Each Property Clearly**
   * Example:
     * *"A list of people, their names and/or nicknames, professional roles, contact details, and preferences."*
     * *"A summary of the last tool calls and what was learned from them."*
3. **Choose the Data Type**
   * `string` for free text (e.g., notes, names, feedback).
   * `number` for numerical values (e.g., age, budget, score).
   * `boolean` for true/false data (e.g., subscription active: true/false).
4. **Mark Sensitive Data** (optional)
   * Toggle this if the information is private and should **not be shared** when the chat is escalated to a human.

***

### 🌍 Example Use Cases

* **Customer Support**: Remember user account details, previous issues, and preferences to avoid asking the same questions again.
* **Sales Assistant**: Store budget ranges, product interests, and negotiation history to personalize follow-ups.
* **Learning Agent**: Track what topics the user studied, their skill level, and which tools they’ve used successfully.
* **Internal Tools**: Store agent’s own usage history, making it smarter in how it calls tools over time.

***

### 📌 Best Practices

* Be **specific** in property descriptions so the Agent knows exactly when and how to save information.
* Use **concise names** for properties (`people`, `preferences`, `history`) to make them easy to reuse.
* Mark **sensitive data** whenever it involves personal or confidential information.
* Use memory in combination with **Tickets** and **Knowledge Base** to ensure smooth human handover and reliable long-term records.

***

👉 With **Contextual Memory**, your Agents evolve beyond scripted bots, becoming adaptive, continuous, and deeply personalized in every interaction.


# PDF Reader Tool

The **PDF Reader** Tool allows an Agent to read, interpret, and reason over the **entire content of a PDF document that is uploaded during the Agent configuration**.

Unlike Knowledge Bases, which split content into chunks for retrieval, PDF Reader preserves the **full structure and continuity of a single document**, enabling deeper and more contextual reasoning.

***

### 🔎 What It Does

With PDF Reader, an Agent can:

* Read a **pre-configured PDF document**
* Read **encrypted or protected PDFs** when text is still extractable
* Understand the document **as a whole**, without fragmentation
* Extract insights, summaries, rules, or structured information
* Reason across sections, pages, and references consistently

This tool is ideal when a document must be treated as **authoritative context**, not as searchable snippets.

***

### 🧠 How PDF Reader Works

PDF Reader acts as a **static cognitive extension** of the Agent.

At configuration time:

1. The Agent creator uploads a PDF file.
2. The full document is ingested as a **single contextual source**.
3. During conversations, the Agent can reason over the entire document whenever needed.
4. The document remains available to the Agent as long as the tool exists.

The Agent decides to use the PDF Reader based on the **tool description**, not by user action.

### Model compatibility

Supported models, including **Grok 4.5**, receive the configured PDF Reader information correctly when the Agent prepares a tool call.

The tool definition must remain complete in the Agent context. If the configuration is invalid or unavailable, the execution must report a clear failure instead of passing an undefined tool property.

***

### 🔐 Encrypted PDFs and readability

Zaia does not reject a PDF only because it is encrypted or protected.

If the file still allows text selection or extraction, Zaia processes it normally.

When the primary extraction path returns no usable content, Zaia retries with a plain-text fallback.

Zaia only treats the file as unreadable when no text can be extracted after all supported attempts.

This reduces false negatives for protected files that still contain readable content.

#### PDFs that still fail

Zaia cannot extract content from:

* Image-only or scanned PDFs with no selectable text
* Invalid or corrupted PDF files
* PDFs that truly contain no extractable text

When extraction fails, Zaia reports that the content could not be extracted instead of assuming password protection.

***

### 📚 PDF Reader vs Knowledge Base

#### Use **PDF Reader** when:

* The document must be interpreted as a whole
* Cross-section understanding is required
* The content represents a single source of truth (e.g., contract, policy, manual)
* The document does not need semantic retrieval by fragments

#### Use **Knowledge Base** when:

* Content must be searchable and modular
* Information changes frequently
* Multiple documents need to be queried
* You want long-term, scalable retrieval

💡 **Rule of thumb:**\
PDF Reader is for **deep reasoning over one document**.\
Knowledge Base is for **searching across many documents**.

***

### 📄 Common Use Cases

* Company policies or internal rulebooks
* Legal contracts or compliance documents
* Technical manuals or specifications
* Institutional PDFs that must be followed strictly

***

### ⚙️ Tool Configuration

When creating a PDF Reader Tool, you configure:

* **Name**\
  A clear identifier for the tool\
  Example: `Company Policy PDF`
* **Description**\
  Guides the Agent on when to use the document\
  Example:

  > “Use this tool whenever the user asks about company rules, policies, or internal procedures.”
* **PDF File**\
  The document uploaded during Agent configuration

The description is essential — it determines **when the Agent will rely on the PDF**.

***

### 🧠 Best Practices

* Use PDF Reader for documents that must be interpreted in full
* Avoid duplicating large documents into the main prompt
* Keep the description explicit and scoped
* If the document needs frequent updates or search, prefer a Knowledge Base
* Combine with Tasks or Follow Ups to act on document-based conclusions

***

### ✅ Key Takeaway

The **PDF Reader** Tool allows an Agent to reason over a **single, complete PDF document configured by the Agent creator**, without chunking or fragmentation.

It is the best choice when structural integrity, coherence, and full-context understanding are critical — including protected PDFs that still expose readable text.


# External User Blocking Tool

Block an external chat user when an Agent confirms the conversation is automated.

Use the **External User Blocking Tool** to stop confirmed bot-to-bot conversations.

The tool is native to the main chat Agent. It has no configuration or input fields.

***

### 🔎 When the tool is available

The tool is available only during a main chat flow. It requires a chat owned by an external user.

It supports these channels:

* Instagram
* Telegram
* WhatsApp, including Waha
* Widget

The tool is unavailable for API and Zaia channels. It is also unavailable outside chat context.

### 🛡️ When to use it

Use this tool only when the Agent has absolute certainty that it is talking to another bot.

Do not use it for suspected automation or ambiguous behavior. Blocking stops future messages from that external user.

{% hint style="warning" %}
The certainty requirement is guided by the tool instruction. It is not enforced by a separate blocking rule.
{% endhint %}

### ⚙️ What happens when the Agent blocks a user

The system resolves the target from the current chat owner. The Agent cannot choose or provide another user.

Before blocking, the system confirms that:

* The external user exists in the workspace.
* The external user owns the current chat.

If the user is already blocked, the tool succeeds without changes. Otherwise, it marks the external user as blocked.

The chat updates immediately in the interface. The workspace owner also receives an email notification.

### 📬 Owner notification

The notification identifies the blocked external user by ID. It directs the owner to locate that user in **Inbox → Chat History**.

The email does not include a direct link to the chat.

### ✅ Result

After the user is blocked, existing platform rules reject new messages from that user. This prevents the automated exchange from continuing.

The workspace owner can review the event in Chat History.


# Scheduled Execution Tool

The **Scheduled Execution Tool** lets an Agent schedule a Workflow execution for a future time during a conversation.

Use it when the future action should be decided by a Workflow instead of being limited to sending a follow-up message.

### Scheduling rules

* The Agent can schedule a single future execution using an absolute date and time or a relative delay, such as “in one hour.”
* Each schedule points to one existing Workflow trigger.
* When the scheduled time arrives, Zaia runs that trigger automatically.
* No separate CRM rule is required to create a one-time schedule.
* Scheduled executions are separate from the legacy Follow Up Tool. Existing follow-up messages continue to work independently.

### Context sent to the Workflow

The scheduled Workflow receives the conversation context needed to choose the next action, including the chat, channel, recent messages, current tags, and the active ticket when one exists.

The Workflow can then send a reminder, update an external system, start another automation, or perform any action supported by its configured nodes.

### Status and management

A scheduled execution has a visible status:

* **Pending** — waiting for its scheduled time.
* **Executed** — the Workflow trigger completed.
* **Canceled** — the execution will no longer run.
* **Failed** — the trigger could not complete.

Failed executions keep a consultable reason. Existing schedules can be reviewed and updated through scheduled-execution management.

### Validation and restrictions

* The Workflow trigger must exist when the schedule is created.
* The schedule must include the minimum conversation context required by the execution.
* Invalid schedules are rejected instead of being saved partially.
* Recurring schedules and automatic schedules created from workspace events are not part of the initial release.


# What are MCPs?

MCPs (**Managed Connection Providers**) are **integrations** that connect your Agents and Workflows to external services and APIs.

Think of MCPs as **packages of configurable HTTP requests** that:

* Share the same **authentication credentials** (OAuth, API Key, etc.).
* Can expose multiple **tools** (e.g., “create event in Google Calendar”, “list emails from Gmail”, “send message in Slack”).
* Are described in **natural language**, so your Agent knows when and how to use them.

***

### 🚀 Why MCPs Matter

Without MCPs, every integration would need to be created and authenticated separately. MCPs solve this by:

* Centralizing **authentication** → set credentials once, reuse across all tools inside that MCP.
* Simplifying **configuration** → no need to craft raw HTTP requests every time.
* Making Agents more **autonomous** → they can discover and call tools inside MCPs whenever relevant.
* Unlocking **enterprise-grade integrations** → securely connect CRMs, calendars, databases, ticketing systems, and more.

In practice, MCPs are the **bridge between Endless and the external world**, extending your Agents with almost limitless capabilities.

***

### 🛠️ MCPs in Action

For example, you can create an MCP for **Google Calendar**:

* Authentication: Google OAuth.
* Tools exposed:
  * `listEvents` (list calendar events).
  * `createEvent` (schedule a meeting).
  * `deleteEvent` (cancel a meeting).

Your Agent can then **choose the right tool** when a user asks:

> “Book a meeting with John tomorrow at 10am.”

***

### 📌 Key Characteristics

* **Authentication layer**: One connection, many tools.
* **Multiple tools per MCP**: Each tool maps to an API endpoint or function.
* **Natural language descriptions**: Agents pick the tool based on your description.
* **Scalable**: You can create MCPs for any external system your business needs.


# How to Connect a New MCP

This guide shows, step-by-step, how to add a Managed Connection Provider (MCP) and make its tools available to your Agents and Workflows.

***

### Step-by-step

#### 1) Open the MCPs area

Go to **MCPs** in the left navigation and click **New MCP**.

#### 2) Choose the integration

Select the MCP you want (e.g., **Google Calendar**, **Notion**, **Airtable**, **Slack**, etc.).

#### 3) Name and describe

Fill in:

* **MCP Name** – a clear internal name (e.g., “Google Calendar – Sales”).
* **Description** (optional) – what this integration is for (helps future you and teammates).

#### 4) Create a Connection (authentication)

Connections are the authentication layer shared by all tools inside the MCP.

1. Click **+ Add Connection**.
2. Give the connection a **Name** and (optionally) a **Description**.
3. Complete the authentication (OAuth sign-in, API key, etc.).
4. Once successful, the connection will appear in the list.

> Pro tip: use different connections for different teams or accounts, so permissions remain separated.

#### 5) Enable the tools you need

All tools start **disabled**. Click to **activate** only the ones your Agent should use.\
Hovering over a tool shows what it does (e.g., in Google Calendar: *create event*, *find free slots*, *update event*).

#### 6) Create the MCP

Click **Create MCP**. Your integration is now available in Endless.

***

### Make MCP tools available to an Agent

Unlike custom tools or tables, you don’t have to add each tool individually.\
Instead:

1. Open **Agents → Your Agent → MCPs**.
2. Activate the MCP you just created.
3. Done ✅ — all selected tools inside that MCP are now automatically available for the Agent.

***

### Test internally (recommended)

Use the **internal chat** on the Agent’s page:

* Example for Google Calendar MCP:
  * “Find me 3 free 30-minute slots this week.”
  * “Book a meeting with John tomorrow at 10am.”

The Agent will gather missing details (date, participants, duration) and then trigger the right tool.

***

### Troubleshooting

* **MCP created but no tools available?**\
  Make sure you enabled at least one tool before saving.
* **Auth completed but calls fail?**\
  Verify the connection’s&#x20;

***

👉 With this, you now know how to create an MCP, connect it, activate its tools, and make them instantly available for your Agent.


# Workflows: Overview

Workflows allow you to create automated processes inside Endless.\
They are made of **nodes**, each one representing an action (like receiving a webhook, calling an API, or returning a response).

With Workflows you can:

* Connect external services via webhooks or HTTP requests.
* Allow Agents to trigger multi-step processes.
* Organize logic visually, step by step.

***

### 🛠️ How Workflows Work

* A Workflow is a **blank canvas** where you drag and drop nodes.
* Each Workflow has a **trigger** (for example, a webhook call or an Agent request).
* You can then chain actions like making an HTTP request, saving variables, or sending back a response.

***

### 🔑 Available Nodes

Currently, you can use:

* **Webhook Request** → receives data from an external service.
* **Webhook Response** → sends back a reply to that service.
* **Agent Request** → lets an Agent call this workflow.
* **Agent Response** → sends information back to the Agent.
* **External Event Trigger** → starts a workflow when a supported external event arrives.
* **HTTP Request** → call an external API (GET, POST, PUT, DELETE, PATCH).
* **Define Variables** → store values for later use in the workflow.
* **LLM** → call a language model to process or generate text.
* **Message Sending** → send outbound WhatsApp or Instagram messages. WhatsApp supports text and templates. Instagram supports text sent to a comment or scoped user ID.

***

### 📌 Why Use Workflows

* No need for custom code — build automations visually.
* Reuse them across different Agents.
* Control the logic of how and when actions happen.

Workflows are the **orchestration layer** of Endless.\
They allow you to go beyond simple tool calls, creating structured flows that respond exactly the way you need.

***

👉 Next: we’ll explore each **node** in detail, starting with **Webhook Request**.


# Workflow Nodes


# Webhook Request Node

The **Webhook Request Node** is used to **start a Workflow** from an external HTTP call.\
It allows Zaia Endless to **receive data** sent by any external system, such as CRMs, websites, or automation platforms.

This node effectively acts as an **entry point** for external integrations, enabling other systems to trigger a Workflow execution inside Endless.

***

### 🛠️ How It Works

When a **Webhook Request Node** is added to a Workflow, Endless automatically generates a **Test URL** — a unique endpoint that listens for incoming HTTP requests.

External services (such as form handlers, backend systems, or third-party apps) can send data to this URL using one of the supported methods.\
Each request can include headers, query parameters, or body payloads that are captured and made available for downstream nodes in the Workflow.

**Supported HTTP Methods:**\
`GET`, `POST`, `PUT`, `DELETE`, `PATCH`

***

### ⚙️ Configuration Options

| Setting                 | Description                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| **Test URL**            | A unique endpoint automatically generated for the node. Use it to send requests from external systems. |
| **Method**              | Select the HTTP method the webhook will accept (e.g., `POST` for JSON payloads).                       |
| **Allowed Origins**     | Restricts which domains or sources can call this endpoint. If empty, any origin is allowed.            |
| **Authentication Type** | Defines how requests are authorized before execution (see below).                                      |
| **Response**            | Controls how and when Endless returns a response (`Immediate` or `Webhook Response Node`).             |
| **Response Code**       | Lets you define the HTTP status code to return (e.g., 200, 201, 400).                                  |

***

### 🔒 Authentication Options

The Webhook Request Node supports **two authentication modes**:

#### 1. **None**

No authentication is required. Any system can trigger the webhook.

Use this mode for testing or public integrations where security is not critical.

***

#### 2. **Bearer Authentication**

Secures the webhook using a **Bearer Token** from a **Credential Pool**.

When selected:

1. Choose or create a **Credential Pool** (type: `API Key`).
2. Generate a **token** inside that pool.
3. Copy the generated token — it will be required in external HTTP requests.

Example request:

```http
POST https://z-sovereign-service-staging.fly.dev/platform/v1/workflows/capture
Authorization: Bearer 6c8c5187-2f0c-47de-bae0-de22a4855340
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}
```

If the request does not include a valid token from the selected pool, Endless will reject it with a **401 Unauthorized** response.

> ⚙️ **Credential Pools** can contain multiple tokens and can be managed or revoked at any time.\
> This enables secure, centralized credential management for different integrations.

***

### 🧪 Node Test Mode

The **Node Test** feature lets you simulate and validate incoming webhook requests directly inside Endless before deploying the Workflow.

When you click **“Execute Test”**, the node enters **listening mode**, waiting for an incoming HTTP request to the generated Test URL.\
Once a request is received, the panel displays a structured preview of the received data.

#### Example test output:

```json
{
  "snapshot": {
    "body": {
      "name": "New name",
      "test": "data01"
    },
    "headers": {
      "authorization": "Bearer 6c8c5187-2f0c-47de-bae0-de22a4855340",
      "content-type": "application/json"
    },
    "method": "POST",
    "query": {}
  }
}
```

After the test completes, you can **use this received data as input** for subsequent nodes in the same Workflow — ideal for end-to-end testing and schema validation.

> 🧠 **Tip:**\
> Use Node Test mode to verify payload structures before integrating production systems.\
> It ensures field mapping and authentication are configured correctly.

***

### 🔁 Response Behavior

The **Response** setting determines when the webhook returns a response:

| Mode                      | Behavior                                                                                                                                                         |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Immediate**             | Endless responds immediately after receiving the request, without waiting for the rest of the Workflow to complete.                                              |
| **Webhook Response Node** | Endless waits until a dedicated **Webhook Response Node** executes later in the Workflow — allowing you to return dynamic, processed data back to the requester. |

Example use case:

* Use **Immediate** for asynchronous triggers (e.g., logging an event).
* Use **Webhook Response Node** for synchronous integrations where the external system expects a processed response.

***

### 📌 Example Use Cases

| Scenario                    | Description                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| **Lead Capture**            | Receive a lead from a website form and trigger a workflow to store it in a Table or CRM.            |
| **CRM Sync**                | Capture updates from another system and propagate them across Agents or integrations.               |
| **External Event Triggers** | Start a workflow when an external event occurs — e.g., a new payment, ticket creation, or API call. |
| **Internal Integrations**   | Connect Zaia Endless Workflows with internal apps through secure Bearer-authenticated webhooks.     |

***

### ✅ Best Practices

1. **Always use Bearer authentication** for production webhooks.
2. **Restrict origins** whenever possible to reduce exposure.
3. **Test payloads** with the Node Test tool before connecting external systems.
4. **Document response codes** expected by the calling system.
5. **Regenerate tokens periodically** in Credential Pools for added security.

***

#### 🧠 Summary

| Feature               | Description                                                      |
| --------------------- | ---------------------------------------------------------------- |
| **Purpose**           | Starts a Workflow via external HTTP call.                        |
| **Authentication**    | Supports `None` or `Bearer` (via Credential Pools).              |
| **Test Mode**         | Allows real request capture and data inspection inside the node. |
| **Response Handling** | `Immediate` or via `Webhook Response Node`.                      |
| **Security**          | Configurable origins, token management, and credential rotation. |

***

#### 🚀 Final Note

The **Webhook Request Node** transforms Zaia Endless into an integration hub — capable of receiving data from any system in a secure, controlled, and testable way.\
With built-in authentication, real-time testing, and flexible response handling, it provides a powerful foundation for building seamless, event-driven automations.


# Webhook Response Node

The **Webhook Response** node is used to send a reply back to the service or application that triggered your Workflow through a Webhook Request.

***

### 🛠️ How It Works

* A **Webhook Request Node** starts the Workflow when it receives an external call.
* The **Webhook Response Node** closes the loop, sending a response back to the caller.
* Without this node, the external service might not receive any confirmation.

***

### ⚙️ Configuration Options

* **Status Code** → define the HTTP status code (e.g., `200 OK`, `201 Created`, `400 Bad Request`).
* **Response Body** → optional data to return in the response (JSON, text, etc.).
* **Headers** → add custom headers if required by the external system.

***

### 📌 Example Use Cases

* Confirm to a form that the lead was received successfully (`200 OK`).
* Return generated data, like an ID or token, to the external system.
* Send error messages (`400`, `404`, etc.) if the request was invalid.


# Agent Request Node

The **Agent Request** node allows your Workflow to be triggered by an **Agent tool call** inside Endless.\
When an Agent decides it needs to use a Workflow, this node is the entry point.

***

### 🛠️ How It Works

* Agents can call Workflows just like they call MCP tools.
* When this happens, the Workflow starts from the **Agent Request Node**.
* The request can include inputs (parameters) that your Workflow can use in the next steps.

***

### ⚙️ Configuration Options

* **Parameters** → define the input fields your Agent will send when triggering this Workflow.
* **Validation** → optional rules to ensure required parameters are provided.

***

### 📌 Example Use Cases

* An Agent needs to **generate a custom report** → it calls a Workflow that collects data and formats it.
* An Agent needs to **start an approval process** → it triggers a Workflow that sends a notification.
* An Agent needs to **query an external API** indirectly → it passes the request to a Workflow that handles it.

***

⚡ **Tip:** Combine the **Agent Request Node** with an **Agent Response Node** so your Workflow can return results directly back to the Agent.


# Agent Response Node

The **Agent Response** node is used to send information back to the **Agent** that triggered the Workflow with an **Agent Request Node**.

It closes the communication loop between your Workflow and the Agent.

***

### 🛠️ How It Works

* A Workflow starts with an **Agent Request Node** (called by the Agent).
* The Workflow executes its steps (variables, API calls, logic).
* The **Agent Response Node** returns the final result to the Agent.
* The Agent can then use this data to answer the user or take the next action.

***

### ⚙️ Configuration Options

* **Response Body** → the content returned to the Agent (can include variables created in the Workflow).
* **Format** → JSON or text, depending on the type of output expected.
* **Error Handling** → optionally define error messages if the Workflow fails.

***

### 📌 Example Use Cases

* Agent asks: *“What’s the status of order #123?”*\
  → Workflow queries a database and **returns the order status** via Agent Response.
* Agent asks: *“Create a new lead with this info.”*\
  → Workflow inserts the data into a CRM and **returns the new lead ID**.
* Agent asks: *“Run analysis on these numbers.”*\
  → Workflow uses an LLM node to analyze data and **returns a summary**.

***

⚡ **Tip:** Always make sure the response is **clear and structured**, so the Agent can use it naturally in a conversation.


# HTTP Request Node

The **HTTP Request** node allows your Workflow to connect directly to external APIs and services via standard HTTP requests.\
It’s one of the most powerful nodes, because it enables Endless to interact with **any system that exposes an API**.

***

### 🛠️ How It Works

* You configure the node with the **endpoint URL**.
* Choose the **method** (GET, POST, PUT, DELETE, PATCH).
* Optionally add **headers** (e.g., authentication tokens, content type).
* Add **query parameters** or body parameters depending on the method.
* The Workflow sends the request and captures the **response** for use in later steps.

***

### ⚙️ Configuration Options

* **URL** → the API endpoint you want to call.
* **Method** → HTTP verb (GET, POST, PUT, DELETE, PATCH).
* **Headers** → e.g., `Authorization: Bearer <token>`, `Content-Type: application/json`.
* **Parameters** → query parameters (GET) or body fields (POST/PUT).
* **Timeout** → how long the Workflow should wait before failing.

You can also **test the request** inside the node to validate the configuration before deploying.

***

### 📌 Example Use Cases

* **Weather API**\
  Call `GET https://api.weather.com?city=São Paulo` and return the forecast to the Agent.
* **CRM Integration**\
  `POST https://crm.com/leads` with JSON body `{ "name": "Alice", "email": "alice@mail.com" }` to create a new lead.
* **Database Access**\
  Call a custom API endpoint to read or write information stored in your systems.

***

⚡ **Tip:** Combine the HTTP Request node with **Variables** to dynamically pass user input (like city, product ID, or email) into your API calls.


# Variables Node

The **Variables** node allows you to define, store, and reuse values throughout your Workflow.\
It works like a **temporary memory** where you can save data from one step and use it later in another.

***

### 🛠️ How It Works

* You **map a variable name** (e.g., `productSKU`, `userEmail`, `city`).
* You **assign a value** to that variable. The value can come from:
  * Static text (you write it directly).
  * A **reference** to data produced by another node in the Workflow.
  * AI-generated content (if you enable **Use AI**).
* Once saved, the variable can be used in any following node.

***

### ⚙️ Configuration Options

* **Mapping name** → the variable’s key (e.g., `customerName`).
* **Value** →
  * Literal value (e.g., `"São Paulo"`).
  * Workflow reference (e.g., `@workflow.request.userInput`).
  * AI-generated (if you select **Use AI**).
* **Multiple variables** → you can add as many mappings as needed.

***

### 📌 Example Use Cases

* **Dynamic API Calls**\
  Save the user’s city into a variable `city` and use it in an HTTP Request node to fetch the weather:\
  `GET /weather?city=@workflow.variables.city`
* **Storing User Input**\
  Capture `name` and `email` once, then reuse them across different steps (e.g., CRM API, confirmation message).
* **AI Processing**\
  Enable **Use AI** to automatically transform or enrich the data before saving it (e.g., normalizing product names).

***

⚡ **Tip:** Variables make your Workflow **modular and reusable**, avoiding repeated inputs and allowing complex logic.


# LLM Node

The **LLM (Large Language Model) node** allows you to run prompts directly inside your Workflow using one of the available AI models.\
This makes it possible to **generate text, transform data, analyze inputs, or create structured outputs** automatically.

***

### 🛠️ How It Works

1. You **select a provider** (e.g., Zaia).
2. You **choose a model** (e.g., Claude, GPT, etc.).
3. You define the **output type** → text or JSON.
4. You set the **temperature** → controls balance between **precision** (deterministic answers) and **creativity** (diverse answers).
5. You write a **prompt** that the LLM will execute.

The result can then be passed to other nodes in the Workflow.

***

### ⚙️ Configuration Options

* **Provider** → The service powering the LLM (e.g., Zaia).
* **Model** → Which model to use (e.g., `claude-sonnet-4.5`).
* **Output type** →
  * **Text**: free-form answer.
  * **JSON**: structured response (ideal for automation).
* **Temperature** →
  * Low = deterministic (e.g., 0.1 → precise answers).
  * High = creative (e.g., 0.8 → more variation).
* **Prompt** → The instruction/query you want the LLM to process.

***

### 📌 Example Use Cases

* **Summarization**: Input long text, output a short summary.
* **Data transformation**: Convert unstructured text into JSON for APIs.
* **Creative generation**: Ask for product descriptions, social media posts, or marketing copies.
* **Decision support**: Evaluate conditions and suggest next steps.

***

### 🚀 Example

Prompt:

```
Extract the email and phone number from the following text and return in JSON:  

"Hi, my name is John. You can reach me at john@example.com or call me at +1 555 123 4567."  
```

Output (JSON):

```json
{
  "email": "john@example.com",
  "phone": "+1 555 123 4567"
}
```

***

⚡ **Tip:** Always be explicit in your prompts about the **format you expect** (e.g., JSON, bullet points, step-by-step instructions).


# Message Sending Node

Send outbound WhatsApp or Instagram messages from a Workflow.

The **Message Sending** node sends outbound WhatsApp or Instagram messages from a Workflow.

Use it to notify a user, reply privately to an Instagram comment, or send an Instagram direct message.

***

### 🛠️ How It Works

When the Workflow reaches this node, Zaia sends a message through the selected connection.

You choose a **connection**. The connection type determines the available fields and send modes.

***

### 📲 Supported Connection Types

#### WhatsApp (Official)

Official WhatsApp connections support:

* **Text**
* **Template**
* **Text with template fallback**

#### WhatsApp (Waha)

Waha connections support **text only**.

Templates and template fallback are not available on Waha.

#### Instagram

Instagram connections support **text only**.

The destination is an Instagram ID, not a phone number. Choose one destination type:

* **Comment** — sends a private reply using an Instagram comment ID.
* **User** — sends a direct message using an Instagram scoped user ID.

***

### ⚙️ Send Modes

#### Text

Zaia sends a regular message.

Use this mode when the recipient is already inside an active 24-hour WhatsApp window.

#### Template

Zaia sends an approved WhatsApp template directly.

Use this mode when you need to start a conversation or send a pre-approved message outside the 24-hour window.

#### Text with template fallback

Zaia tries to send a regular message first.

If WhatsApp rejects the message because the 24-hour window expired, Zaia sends the configured template instead.

> ⚠️ The fallback only runs for the specific WhatsApp window-expired error. Other delivery errors do not trigger template fallback.

***

### 📍 Instagram destination

When you select an Instagram connection, Zaia hides the phone number field and sets the send mode to **Text**.

Select the destination type and provide its matching ID:

* For **Comment**, provide the comment ID.
* For **User**, provide the Instagram scoped user ID.

The destination ID can include Workflow variables. Zaia resolves them when the Workflow runs.

Instagram does not support templates or template fallback in this node.

***

### 🧩 Template Configuration

When the selected connection is **WhatsApp (Official)**, Zaia loads only templates that are:

* Approved in Meta
* Available for that connection
* Valid for the linked WhatsApp account

Zaia builds the template fields dynamically from Meta's template schema. This includes:

* **Body** variables
* **Header** variables

#### Required fields in Workflows

In the Workflow node, all required template fields must be filled before you save the configuration.

This ensures the node is ready to execute without missing data.

***

### 🖼️ Image headers

Templates with an image header accept:

* A public URL
* A stored file
* A data URL

Before sending, Zaia converts the image into the format accepted by the WhatsApp API.

***

### ✅ Validations

Zaia validates the selected connection before sending.

The connection must exist, belong to the current workspace, and be active.

For Instagram, Zaia also requires:

* A configured Instagram account and token.
* A destination type.
* A destination ID.
* **Text** send mode.

If a required value is missing, Zaia stops the Workflow before sending.

Zaia also validates WhatsApp template data before sending.

This includes size and format limits for fields such as:

* Body text
* Header text
* OTP values
* Button URL suffixes

If the data exceeds Meta's limits, the node blocks the send until the values are fixed.

***

### 🔒 Restrictions

* Templates only work with active and correctly configured **WhatsApp (Official)** connections.
* The selected template must exist and be approved in Meta.
* If the template cannot be resolved or validated, the message is blocked.
* Waha connections cannot send templates.
* Instagram messages require an active Instagram connection.
* Instagram messages do not use phone numbers, templates, or template fallback.

***

### 📌 Example Use Cases

* Send a reminder after a payment event.
* Trigger an approved reactivation template after the 24-hour window closes.
* Send a private Instagram reply after receiving a comment.

***

### ✅ Key Takeaway

Use the **Message Sending** node when your Workflow must deliver a message directly.

WhatsApp uses phone numbers. Instagram uses a comment ID or scoped user ID. Instagram sends text only.


# External Event Trigger

The **External Event Trigger** node starts a workflow from an external event.

It defines the workflow entry point. The **Triggers** screen creates the operational link to the event source.

{% hint style="info" %}
Configuration is split across two areas. The workflow defines its entry point. The **Triggers** screen selects the source, filters, and destination.
{% endhint %}

### How it works

Deploy a workflow containing an **External Event Trigger** node. Deployment creates a workflow trigger for that entry point.

Create an external trigger in the **Triggers** screen. Select the connection, event, optional filters, and the workflow trigger as its destination.

When the external event arrives, Endless finds a compatible active trigger. It then sends the event payload into the deployed workflow.

### Configure a workflow trigger

{% stepper %}
{% step %}

### Add the entry point

Add an **External Event Trigger** node to the workflow.

Use one entry point for each external event path.
{% endstep %}

{% step %}

### Deploy the workflow

Deploy the workflow to create its workflow trigger.

The workflow trigger identifies the deployed entry point.
{% endstep %}

{% step %}

### Create the external trigger

Open **Triggers** and create a trigger.

Select the external connection, event, and destination. Choose the workflow trigger from the deployed workflow.
{% endstep %}
{% endstepper %}

### Supported event

Currently, Endless supports this external event:

* **Source:** Instagram
* **Event:** New comment

You can apply a post filter using its `mediaId`. Leave the filter empty to match comments from every post on the selected connection.

### Trigger destinations

An external trigger can run an **Agent**, **Squad**, or **Workflow**.

For a workflow destination, select the workflow trigger created by the deployed entry point. Endless injects the incoming event as an external event into that node.

For Agent and Squad destinations, you can provide an optional prompt.

### Execution flow

1. Instagram sends a new-comment webhook.
2. Endless normalizes the event and identifies its connection and event ID.
3. Endless finds active triggers that match the connection, event, and filter.
4. Endless runs the configured destination.

Each run creates an execution with an external-trigger origin. This provides traceability for the event and destination.

### Rules and limitations

* The selected connection must be active and support Instagram.
* Duplicate triggers cannot share the same connection, event, and filters.
* Endless processes each trigger and external event only once.
* Redeploy the workflow after changing its entry points.

When you redeploy, Endless recreates the workflow triggers. Existing workflow destinations update when their entry point still exists. If an entry point is removed, linked triggers become inactive.

### Test the entry point

The node shows triggers linked to its entry point. When several triggers exist, select one before testing.

The test action generates a sample Instagram comment payload. Use it to validate the workflow logic before receiving live events.


# Switch Node

The **Switch Node** evaluates conditions and chooses the Workflow branch that should continue.

### Branch selection

* Zaia evaluates the configured branches and follows the branch whose condition is satisfied.
* When no condition is satisfied and a fallback exists, Zaia follows the fallback branch.
* When no condition is satisfied and no fallback exists, the node has no valid output.

### Test a Switch Node

When you test the node, the result preview identifies the branch that was actually selected.

This includes:

* A matched condition branch.
* The fallback branch.
* A clear no-output result when there is no match and no fallback.

The branch shown in the preview is the same branch used by Workflow execution. Use this result to continue testing the next node on the selected path without guessing which route was taken.


# Components

**Components** are reusable values that you define once and can reference across different parts of the platform — including Agent prompts, Tasks, MCPs, and Tools.

Instead of repeating the same information in multiple places, you create a Component and insert it wherever needed. When the value changes, you update it in one place and it reflects everywhere automatically.

***

#### 🧩 What is a Component

A Component is a named variable with a fixed value.

It has three properties:

* **Name** — how you reference it (e.g. `especialidade`)
* **Type** — the kind of value it holds (String, Number, or Boolean)
* **Value** — the actual content that will be injected when the Component is used

> Components are **global** — once created, they are available to all Agents in your workspace.

***

#### 💡 When to Use Components

Components are useful whenever you have information that:

* Repeats across multiple Agents or configurations
* Might change over time and needs to stay consistent
* Should be managed centrally rather than edited in every prompt

Common examples:

* Clinic name, specialty, or doctor's name used across Agent prompts
* A numeric threshold (e.g. max retries, score limit) shared across Tools
* A feature flag (Boolean) that controls behavior in multiple Agents

***

#### ➕ How to Create a Component

1. Inside your Agent, go to **Components** in the left menu
2. Click **New Component**
3. Fill in the **Name**, **Type**, and **Value**
4. Click **Add Component**

The Component is immediately available across your workspace.

***

#### 🔢 Component Types

| Type    | Value field                 | Use when                                  |
| ------- | --------------------------- | ----------------------------------------- |
| String  | Free text (up to 250 chars) | Names, descriptions, instructions, labels |
| Number  | Numeric spinner             | Counts, limits, IDs, scores               |
| Boolean | Toggle (on/off)             | Feature flags, conditions, enable/disable |

#### 💬 How to Use a Component

Wherever the platform accepts variables (prompts, Tasks, MCPs, Tools, etc.), you can insert a Component in two ways:

* Type `@` in the text field and select the Component from the list
* Click inside the field and pick the Component from the panel that appears

The Component will appear as a **tag** in the editor (e.g. `[[especialidade]]`) and will be replaced by its value at runtime.

**Example:**

> Prompt: *"You are an AI Agent for the clinic of Dr. `[[especialidade]]`"*
>
> At runtime: *"You are an AI Agent for the clinic of Dr. Estética Dental"*

***

#### 🔄 Updating a Component

To change the value of a Component:

1. Go to **Components** in the left menu
2. Find the Component and click the **⋯** menu
3. Edit the value and save

The updated value will be applied everywhere the Component is used — no need to touch individual prompts or configurations.

***

#### 📌 Best Practices

* Use **clear, descriptive names** — the name is how you and your team will find and reference the Component
* Prefer Components over hardcoding values directly in prompts when the same information appears in more than one place
* Use **Boolean** Components as feature flags to toggle behaviors without editing prompts
* Use **Number** Components for thresholds or limits you might need to adjust over time

***

#### ✅ Key Takeaway

Components let you:

* Define values once and reuse them across Agents, prompts, Tasks, MCPs, and Tools
* Keep your workspace consistent and easy to maintain
* Update information globally without editing each Agent individually

It's a small change that makes a big difference when managing multiple Agents at scale.

<br>


# Inbox: Overview

The Inbox is the operational center for Agent conversations and human support.

### Conversations

When the unified inbox is enabled, **Conversations** combines automated chat history and human-assisted tickets in one view.

The list is ordered by the most recent activity, whether that activity is a message or a ticket update. New messages update the list in real time, move the conversation to its current position, and refresh its unread state.

Select a conversation to review the complete message history and, when a ticket exists, manage the human-support flow from the same screen.

### Inbox views and filters

Use the CRM submenu to open common views immediately:

* **All conversations** — shows the complete unified list.
* **Assigned to me** — shows conversations assigned to the signed-in attendant.
* **Human queue** — shows conversations that require human support.
* **Unassigned** — shows conversations without an attendant.
* **Tags** — opens a conversation view filtered by the selected tag.
* **Team** — opens a conversation view filtered by the selected workspace member.

Advanced filters remain available in the contextual header, including channel, ticket status, attendant, responder, tag, and search filters. Search and filters are stored in the page URL so the selected view can be revisited or shared.

Human-queue views can be separated into **Unanswered**, **In progress**, and **Finished** states.

### Legacy History and Tickets

During migration, **History**, **Tickets**, and **Conversations** can coexist.

When migration is enabled:

* Conversations becomes the default CRM destination.
* History and Tickets are removed from the main navigation.
* Legacy links redirect to the corresponding Conversations view.

### Mobile behavior

On mobile, the conversation list opens first. Conversation details open only after the user selects an item.

While details are open, the Back action returns to the list. If the selected conversation is deleted or filtered out, the interface returns to the list instead of selecting another conversation automatically.


# Chat History

All messages generated by AI Agents are logged and available for review under **Chat History**.\
This feature provides complete visibility into user conversations, execution traces, and decision-making logic used by the Agent.\
It is designed for **debugging**, **training optimization**, and **behavior auditing**.

Each conversation entry displays:

* User and Agent messages
* Message timestamps
* Channel source (e.g., WhatsApp, Widget, API)
* Credit usage (if applicable)
* Chat tags

### External user details panel

When a conversation has a linked external user, the right-side details panel makes that user the primary reference for the interaction.

Zaia shows:

* The external user's name
* The phone number
* The finish date, when the conversation is already finished
* The channel name with the channel-type icon

Zaia does not show a separate channel type field.

From this panel, you can:

* Open **User Data** to view or edit the existing external user record
* Block the external user
* Unblock the external user

Block and unblock stay available whenever an external user is loaded.

This applies to active conversations and historical conversations.

The panel stays closed by default.

You can open it on hover or pin it open.

On smaller screens, the panel has its own scroll area so action buttons stay accessible.

Copy actions and assignee editing stay aligned with the related text for a consistent layout.

### **Delivery status and resend**

For outbound messages sent to external channels, you can inspect delivery status in detail and retry failed deliveries when resend is supported.

Use [Resending Failed Deliveries](/inbox/chat-history/resending-failed-deliveries) for the full resend flow, supported providers, payload rules, and restrictions.

### **Chat Tags**

Chats can include tags applied directly at the conversation level.

These tags:

* Appear in the list and detail views
* Can be used as filters in **Chat History**
* Update in real time when changed by the [Chat Tagging Tool](/tools/available-tools/chat-tagging-tool)

### **Message Inspection**

Selecting any Agent message opens the **Inspection Panel**, a technical trace viewer that exposes the full reasoning path of the AI model.\
This panel displays:

| Parameter              | Description                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------- |
| **Model Used**         | The LLM responsible for generating the response (e.g., Claude Sonnet 4.5, GPT-4o). |
| **Execution Time**     | Duration in seconds for message completion.                                        |
| **Reasoning Steps**    | Internal thinking layers, including Planning, Task Selection, and Tool Calls.      |
| **Inputs and Outputs** | Structured JSON view of the input data, LLM prompts, and resulting output.         |
| **Credits Used**       | Platform credit consumption for the operation.                                     |

The Inspection view helps technical teams trace *why* the Agent responded a certain way — mapping each reasoning phase from **prompt parsing → tool usage → final output**.

> **Note:** This feature is critical for understanding hallucinations, context loss, or suboptimal responses and allows for precise prompt refinement.

***

### **Agent Optimization**

By studying conversation logs and inspections, developers and operations teams can identify:

* Frequent escalation patterns (topics leading to human handoffs).
* Long reasoning loops or high credit usage per task.
* Prompt sections that cause redundant or low-quality outputs.

Data from Chat History can be used to:

* Rewrite system prompts.
* Adjust model temperature and effort parameters.
* Improve Task logic and condition definitions.
* Train Agents on realistic interaction data.


# Resending Failed Deliveries

Retry failed outbound message deliveries from Chat History when the channel and payload support it.

You can manually resend failed outbound deliveries for chat messages sent to external channels.

Use this when a message has at least one delivery in **failed** status and you need to retry that delivery without editing the original message.

***

### **Where to resend**

Open **Inbox** → **Chat History**.

Select a conversation and open the message delivery details in the **send status** modal.

Zaia shows delivery blocks grouped as:

* **Sent**
* **Pending**
* **Errors**

The **Resend** button only appears when the message has at least one failed delivery.

***

### **How resend works**

When you click **Resend**, Zaia retries each failed delivery for that message.

Zaia resends delivery entries. It does not edit the original message.

If the message has more than one failed delivery, Zaia retries each failed delivery individually.

Before retrying, each failed delivery changes to **pending**.

The interface updates in real time.

If the provider accepts the retry, the delivery changes to **sent**.

If the retry fails again, the delivery returns to **failed** and Zaia shows the updated error.

***

### **Status flow**

A manual retry follows this flow:

* **Failed** → user can retry the delivery
* **Pending** → Zaia started the new send attempt
* **Sent** → the provider accepted the delivery
* **Failed** → the new attempt failed and the error is refreshed

***

### **Permissions and restrictions**

Manual resend only works when all conditions are true:

* The user has the **customer support** permission
* The delivery status is **failed**
* The chat is linked to a channel with an **active** connection
* The connection is not in **failed** status
* The provider is supported for resend

Zaia blocks resend when any of these conditions is not met.

***

### **Supported providers**

Manual resend is currently available for:

* **WhatsApp (Waha)**
* **WhatsApp (Official)**
* **Instagram**
* **Telegram**

***

### **Supported payloads**

Zaia only retries deliveries that represent one supported payload.

Supported payload types are:

* **Text**
* **PNG image**
* **PDF**
* **WAV audio**

If the delivery contains an unsupported structure or more than one payload, Zaia blocks the resend.

***

### **Channel-specific behavior**

For **Instagram**, manual resend reuses the existing messaging-window rules.

If the provider rejects the delivery because the send window is not valid anymore, the delivery returns to **failed**.

***

### **Common scenarios**

#### **One failed delivery**

If a message has one failed delivery, Zaia shows **Resend** and retries that delivery.

#### **Multiple failed deliveries**

If a message has multiple failed deliveries, Zaia retries each failed delivery from that message.

#### **Invalid or failed connection**

If the channel connection is invalid or already failed, Zaia does not allow resend.

#### **Non-failed delivery**

If the delivery is not in **failed** status, Zaia does not allow resend.

***

### **Key point**

This feature resends a specific delivery entry.

It does not change the message content and it does not create a message-editing flow.


# Recovering Queued Responses

Recover unanswered WhatsApp and Instagram conversations after a temporary interruption.

Zaia automatically retries failed Agent response generation on **WhatsApp** and **Instagram**.

This protects conversations from transient processing failures and service interruptions.

The mechanism combines fast queue processing with durable recovery tracking.

***

### When automatic recovery applies

Recovery applies when the chat owner sends a message through WhatsApp or Instagram.

It does not apply when the chat has an active human-support ticket.

Zaia creates or updates a durable recovery record when it receives the message.

It then queues the chat for Agent response generation.

{% hint style="info" %}
Recovery is automatic. No workspace configuration is required.
{% endhint %}

***

### Retry behavior

When generation starts, Zaia acknowledges the queued item and records the attempt.

If a retryable error occurs, Zaia waits 30 seconds before retrying.

Zaia performs one automatic retry. A response therefore has at most two attempts.

After the limit, Zaia preserves the final error and marks recovery as failed.

***

### Errors eligible for retry

Most transient generation errors trigger the automatic retry.

Zaia does not retry these errors:

* `NotFound`
* `PreconditionFailed`
* `BadImplementation`
* LLM provider errors that do not require an alert

### Cleanup before retry

Before retrying, Zaia removes artifacts from the failed attempt.

* It deletes the response placeholder from the chat.
* It marks the previous execution as a failed attempt.
* It ends stale running executions as failed.

This prevents orphaned placeholders, duplicate primary executions, and incorrect usage counts.

### Durable recovery

Zaia uses an in-memory queue for immediate coordination.

It also stores recovery state in the database. This lets retries survive restarts and deployments.

A recovery uses these states:

* **Pending** — waiting to run or retry.
* **Processing** — response generation is in progress.
* **Completed** — the Agent generated the response.
* **Failed** — the retry budget was exhausted.

Zaia locks recovery by chat and thread. Only one recovery can process that conversation window.

If a recovery remains processing for 30 minutes, a scheduler attempts to recover it.

{% hint style="warning" %}
Recovery cannot restore messages that fail before initial persistence.
{% endhint %}


# Estimated LLM Costs

Understand estimated token usage and costs in execution inspections.

## Estimated LLM Costs

The **Inspection Panel** estimates LLM usage and costs for executions that use a custom provider.

Open an Agent message in **Chat History**, then select an execution to view its details.

### What the inspection shows

The cost section includes:

* Total input tokens.
* Total output tokens.
* Estimated total cost in USD.
* A per-iteration breakdown of model, provider, tokens, and estimated cost.

Expand an iteration to review each LLM use recorded for that event. An event can include multiple LLM calls.

{% hint style="info" %}
Costs are estimates. Actual provider charges can vary by model, provider, and pricing changes.
{% endhint %}

### What is included

The estimate covers LLM calls across the complete execution tree. This includes:

* The selected execution and its child executions.
* Retry attempts before and after the selected execution.
* Agent iterations, workflow LLM nodes, JSON conversions, and supporting tools.

This gives a consolidated view of primary, supporting, and retried LLM calls.

### When costs are available

Cost estimates appear only for executions using a configured custom provider. Zaia internal provider usage is not included.

Each recorded LLM call includes its model, provider, input tokens, and output tokens. Zaia calculates the estimate using the configured per-million-token price for that model.

### Understanding N/A

The inspection shows `N/A` when it cannot produce a reliable estimate. This happens when:

* The model has no configured price.
* Input or output token data is unavailable for any recorded use.
* A custom-provider event has no recorded LLM usage.

In the last case, the complete aggregate shows `N/A`. Input and output token totals are also unavailable. This prevents incomplete tracking from producing a misleading total.

### Related configuration

Add your API token in [Providers](/settings/providers) before selecting a custom provider for an Agent.


# Human Support


# Tickets

When an AI Agent transfers a conversation to a human, a **support ticket** is automatically created within the Inbox.\
Tickets follow a well-defined lifecycle:

| Stage           | Description                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------- |
| **Unanswered**  | Ticket created but not yet assigned or responded to.                                         |
| **In Progress** | A human attendant has taken ownership and is actively chatting with the user.                |
| **Finished**    | The human has finished and marked the ticket as resolved, returning control to the AI Agent. |

#### Automatic Handoff Behavior

When the Agent triggers a handoff:

1. The platform creates a new ticket.
2. The ticket is automatically routed to a **Team** linked to the tool or channel that triggered the handoff.
3. The Agent pauses and stops sending replies.
4. Human attendants can view the full conversation context.
5. When marked as “Closed,” the Agent regains control of the user session.

***

### **Manual Takeover Outside the Platform**

You can also let a human take over a conversation outside Zaia.

When **Enable manual takeover and interrupt Agent responses** is enabled:

* Zaia treats proactive messages sent from another platform as human messages.
* The Agent stops replying to that conversation.
* The conversation remains under human control until the return condition is met.

This is useful when the team needs to continue the conversation directly in the native channel.

#### Instagram Return Rule

Instagram requires an extra step before the Agent can take over again.

To end human handling on Instagram:

1. React to the user’s latest message with the preconfigured emoji.
2. Send a new message.

This sequence signals that manual handling has ended and the Agent can resume replies.

***

### **Attendant Interface**

The human support interface is designed for clarity and continuity.\
Each attendant can:

* View the full chat history between the user and the Agent.
* See the **Agent-generated summary** at the top of the conversation.
* Continue the discussion directly within the same thread.
* Mark the ticket as *Closed* when complete.
* Reassign responsibility to another member if needed.

#### Status Management

Attendants can toggle their availability at any time:

* 🟢 **Available** — Ready to receive new tickets.
* 🔴 **Unavailable** — Temporarily excluded from Round Robin distribution.

### External user details panel

When a conversation has a linked external user, the right-side details panel makes that user the primary reference for the interaction.

Zaia shows:

* The external user's name
* The phone number
* The finish date, when the conversation is already finished
* The channel name with the channel-type icon

Zaia does not show a separate channel type field.

From this panel, you can:

* Open **User Data** to view or edit the existing external user record
* Block the external user
* Unblock the external user

Block and unblock stay available whenever an external user is loaded.

This applies to active conversations and historical conversations.

The panel stays closed by default.

You can open it on hover or pin it open.

On smaller screens, the panel has its own scroll area so action buttons stay accessible.

Copy actions and assignee editing stay aligned with the related text for a consistent layout.

***

### **Tags in Tickets**

Tickets can display both ticket-level tags and chat-level tags.

In the Tickets interface, Zaia shows the combined set of:

* Tags applied directly to the chat
* Tags applied directly to the ticket

This keeps classification consistent between AI handling and human support.

Tags are:

* Visible in the list and detail views
* Available as filters
* Updated in real time when changed by the [Chat Tagging Tool](/tools/available-tools/chat-tagging-tool)

***

### **Kanban Views**

You can also organize human support chats in configurable Kanban boards.

Use [Kanban Views](/inbox/human-support/kanban-views) to create board-specific columns from chat tags, reorder columns, and move chats between stages in real time.

***

### **Agent Summary**

Before human takeover, the Agent generates an automatic **conversation summary**, displayed at the top of the ticket.\
This summary includes:

* User’s intent and key topics discussed.
* Context of prior messages.
* Outstanding actions or follow-up needs.

This ensures the human attendant immediately understands the situation — reducing handling time and improving accuracy.


# Kanban Views

Organize human support chats in configurable Kanban boards based on ordered chat tags.

Kanban Views organize human support chats into configurable boards.

Each view limits which channels appear on the board and uses selected tags as ordered columns.

### What you can configure

When you create or edit a view, you define:

* **Name**
* **Description**
* **Channels**
* **Tags used as columns**

Zaia always shows a **No tag** column.

This column contains chats that do not match any configured column tag.

### How column assignment works

Each chat appears in one column only.

Zaia resolves the main column using the first chat tag that matches the view's column order.

If a chat has no matching tag, it goes to **No tag**.

When you reorder columns, you also change the priority used to classify chats.

### Working with the board

From the board, you can:

* Reorder tag columns
* Drag cards within a column
* Move cards between columns
* Open the chat in [Chat History](/inbox/chat-history) in a new tab

Each card shows:

* Channel
* Chat title or name
* Additional tags
* Created date
* Updated date

### What happens when you move a card

Moving a card updates the board position and the chat tags.

Zaia removes the previous column tag and applies the destination column tag.

If you move the card to **No tag**, Zaia removes the current column tag and keeps the chat outside all configured tag columns.

Card order is persisted per view and per resolved column.

### Updating columns

You can change the order of the tag columns at any time.

A view must keep at least one configured tag column.

If you remove a tag used as a column, Zaia updates the view and reclassifies affected chats.

Stored positions for affected cards are also cleared when needed.

### Real-time updates

Kanban boards update in real time.

Open boards refresh when card data changes, column order changes, or a specific card is updated.

### Permissions

Kanban Views require the `workspace.permissions.customerSupport` permission.

### Current limitations

* Card fields are fixed in the current UI
* Additional tag filtering is not fully implemented end to end
* Side column behavior is not available in the current release


# Teams & Distribution

### **Teams**

Teams define how tickets are grouped and routed.\
Each workspace can contain multiple teams (e.g., *Support*, *Billing*, *Sales*), each linked to different communication channels or Agents.

Administrators can:

* Create new teams.
* Assign members from the workspace.
* Define permissions (viewer, responder, admin).
* Manage team capacity and metrics.

***

### **Round Robin**

Tickets are distributed automatically through the **Round Robin** system, which uses weighted percentages to balance workload between attendants.

| Member | Weight | Expected Distribution            |
| ------ | ------ | -------------------------------- |
| Alice  | 50%    | Receives half of all new tickets |
| Bob    | 25%    | Receives one quarter             |
| Carol  | 25%    | Receives one quarter             |

> This method guarantees fairness, continuity, and optimized team utilization.\
> Distribution pauses automatically if a member is marked as *Unavailable*.

***

### **Status & Responsibility**

Every ticket must have one **Responsible Attendant**.\
Responsibility can be manually reassigned through the right-hand ticket panel.

When reassigned:

* Ownership is updated instantly.
* The user’s experience remains uninterrupted.
* All previous messages remain visible in history.

This feature supports escalation workflows, shift transitions, and tiered support models.


# Roles & Permissions

When adding a new member to your workspace, you must assign a **role** that determines what the user can see and manage within the platform.\
These permissions directly affect how each person interacts with the **Inbox**, **Teams**, and **Agent-related operations**.

***

### **Available Roles**

| Role       | Access Level          | Description                                                                                                                                                                 |
| ---------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin**  | 🔧 Full Access        | Has unrestricted control over the entire workspace. Can manage billing, Agents, human support settings, teams, roles, and all conversations.                                |
| **Member** | ⚙️ Standard Access    | Can manage Agents, conversations, and team settings, but **does not** have access to billing configurations. Functionally identical to Admin within the Inbox scope.        |
| **Ops**    | 💬 Operational Access | Designed for support agents or operational staff. Can only interact with **human handoff conversations** assigned to them. Cannot modify Agents, Teams, or global settings. |

***

### **Role Behavior in Inbox**

| Action                                   | Admin | Member | Ops                                 |
| ---------------------------------------- | ----- | ------ | ----------------------------------- |
| View **Chat History**                    | ✅     | ✅      | ❌                                   |
| Inspect AI message traces                | ✅     | ✅      | ❌                                   |
| View **Human Support tickets**           | ✅     | ✅      | ✅ (only tickets assigned to them)   |
| Change own availability status           | ✅     | ✅      | ✅                                   |
| Transfer or reassign active tickets      | ✅     | ✅      | ✅ (only within their assigned team) |
| Manage teams & attendants                | ✅     | ✅      | ❌                                   |
| Adjust ticket distribution (Round Robin) | ✅     | ✅      | ❌                                   |
| Edit Agents or tools                     | ✅     | ✅      | ❌                                   |
| Access workspace billing                 | ✅     | ❌      | ❌                                   |

***

### **Ops Role: Focused View**

Users with the **Ops** role are restricted to the **Inbox (Human Support)** section.\
They can:

* See and reply to conversations that have been transferred to them.
* Change their **status** (Available / Unavailable).
* Transfer conversations to other team members.

They **cannot**:

* Edit or configure Agents.
* Manage Teams or distribution rules.
* Access analytics or Chat History.

This makes the Ops role ideal for front-line attendants and support agents who handle live user interactions but should not modify the automation layer.

***

### **Admin & Member Roles in Inbox**

Admins and Members both have full control over:

* Chat History and message inspection tools.
* Ticket routing and manual reassignments.
* Team creation, editing, and Round Robin setup.
* AI-human handoff monitoring and analytics.

The **only difference** between them is **billing access**:

> Members cannot access or edit billing and subscription details.

***

### **Example Use Case**

| Scenario                                                              | Ideal Role         |
| --------------------------------------------------------------------- | ------------------ |
| Reviewing how an Agent responded to a client and inspecting reasoning | **Admin / Member** |
| Managing workload between attendants and configuring teams            | **Admin / Member** |
| Handling a client transferred from an AI Agent                        | **Ops**            |
| Viewing cost and credit usage reports                                 | **Admin only**     |

***

### **Summary**

| Category                  | Admin                   | Member                 | Ops             |
| ------------------------- | ----------------------- | ---------------------- | --------------- |
| System Control            | ✅ Full                  | ✅ Partial (no billing) | ❌ None          |
| Agent Management          | ✅                       | ✅                      | ❌               |
| Conversation Access       | ✅ All                   | ✅ All                  | ✅ Assigned only |
| Configuration Permissions | ✅                       | ✅ (limited)            | ❌               |
| Ideal For                 | Platform Owners / Leads | Project Managers       | Support Agents  |


# Workers

**Workers** is a workspace that allows you to interact directly with your Agents in **production**, inside the Zaia Endless platform.

It provides a centralized chat interface where you can use your Agents for **real tasks, daily workflows, or testing**, without relying on external channels.

***

### 🧠 What is Workers

Workers is a chat-based interface to interact with your Agents in a way that feels similar to tools like ChatGPT or Claude.

However, instead of a single AI, you can:

> Choose exactly which Agent (or Squad) you want to interact with.

***

### 💡 When to Use Workers

Workers is designed for both **real usage** and **validation**.

You can use it to:

* Interact with Agents for daily productivity
* Use internal tools and workflows powered by Agents
* Share Agents across teams and collaborate
* Test how Agents behave in production
* Simulate real user conversations

***

### 💬 How It Works

The experience is divided into two main areas:

***

#### Left Panel (Conversation History)

* Displays all your conversations
* Organized by date
* Allows you to:
  * Resume previous chats
  * Search conversations
  * Start new chats

Each conversation is saved automatically and can be accessed anytime.

***

#### Main Chat Area

* Displays the active conversation
* Allows real-time interaction with the selected Agent
* Works like a messaging interface

***

### ➕ Starting a New Conversation

To start a new chat:

1. Click the **"+" button**
2. Select an Agent or Squad
3. A new conversation is created

***

#### Important

* Each conversation is tied to a specific Agent
* The conversation follows that Agent’s production behavior

***

### 🔄 Continuing Conversations

You can continue any previous conversation:

* Click a chat from the left panel
* The full history will be loaded
* Continue from where you left off

***

### ✏️ Renaming Conversations

You can rename chats to keep your workspace organized:

1. Click the edit icon
2. Enter a new name
3. Save

***

#### Why this is useful

* Organize different use cases
* Separate workflows by topic
* Improve navigation across conversations

***

### 🔍 Search

Workers allows you to search across conversations.

You can search by:

* Conversation title
* Message content
* Agent name

This helps you quickly find specific interactions or tasks.

***

### ⚠️ Production Behavior

Workers interacts with your Agents exactly as they are in **production**.

This means:

* All responses follow the live configuration
* Tools, flows, and logic are executed in real conditions
* Changes in Draft are NOT reflected until deployed

***

### 🔁 Workers vs Internal Chat

| Feature     | Workers                 | Internal Chat (Draft) |
| ----------- | ----------------------- | --------------------- |
| Environment | Production              | Draft                 |
| Behavior    | Live                    | In development        |
| Use case    | Real usage + validation | Development & testing |
| Risk        | Real behavior           | Safe experimentation  |

***

### 📌 Best Practices

* Use **Internal Chat** to test changes before deploying
* Use **Workers** for real usage and production validation
* Rename conversations to stay organized
* Use search to quickly retrieve past interactions

***

### ✅ Key Takeaway

Workers allows you to:

* Use your Agents in a real chat interface
* Support daily workflows and team productivity
* Interact with Agents in production
* Manage conversations in a centralized workspace

It’s not just for testing — it’s a **practical interface to work with your Agents every day**.


# Channels: Overview

Channels are the communication interfaces where your **Agents** or **Squads** interact with end users.\
Each channel connects the Endless platform to an external messaging platform (WhatsApp, Instagram, Telegram, or Web Widget) and manages how conversations are routed to the corresponding responder.

***

### **Overview**

Inside the **CRM → Channels** section, you can view, create, and manage all available channels in your workspace.\
Each channel must be linked to one or more Agents or Squads, depending on who will handle incoming messages.\
Channels can be individually activated or deactivated using the toggle on the right-hand side of the channel list.

#### Main Features

* Support for multiple communication platforms.
* Per-channel responder assignment (Agent or Squad).
* Optional custom prompts per channel.
* Authentication-based connection flows.
* Full widget customization for embedded chat.


# Creating a Channel

Click **“New Channel”** to begin the configuration process.\
Each channel type requires a slightly different setup flow, depending on the external platform.

***

### **General Configuration Parameters**

| Field                            | Description                                                                                               |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Type**                         | Selects the communication channel (Widget, WhatsApp (Waha), WhatsApp (Official), Instagram, or Telegram). |
| **Name**                         | Internal name used to identify the channel in the CRM list.                                               |
| **Description**                  | Optional internal note for context or control.                                                            |
| **Channel Responder**            | Defines which Agent or Squad will handle the conversations from this channel.                             |
| **Customized Prompt (optional)** | Overrides the Agent’s main prompt, applying a custom instruction only for this channel.                   |
| **Delay to Answer**              | Sets a delay (in seconds) before the Agent responds to a user message.                                    |

## **Channel Management**

Once created, channels are displayed in the **Channels Dashboard**.

| Action                     | Description                                                      |
| -------------------------- | ---------------------------------------------------------------- |
| **Toggle Active/Inactive** | Enables or disables message routing for the selected channel.    |
| **Edit Settings**          | Opens the configuration modal to modify responder or prompt.     |
| **View Configuration**     | For Widget channels, shows embed code and customization options. |
| **Delete Channel**         | Permanently removes the channel and its routing link.            |

Each active channel is monitored automatically, ensuring continuous connectivity and message delivery.\
If authentication expires (e.g., expired WhatsApp token), the channel status will display as inactive until reconnected.

***

## **Troubleshooting**

| Issue                                  | Possible Cause                            | Solution                                                              |
| -------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
| QR Code expires before scanning        | Delay during setup                        | Reload and rescan within 40 seconds.                                  |
| No pop-up window for WhatsApp Official | Browser blocked pop-ups                   | Enable pop-ups in browser settings.                                   |
| Instagram connection fails             | Wrong account permissions                 | Use an account with messaging access enabled.                         |
| Telegram connection fails              | Invalid bot token or webhook setup failed | Confirm the token belongs to a Telegram bot and retry the connection. |
| Widget not loading on site             | Script not embedded correctly             | Re-copy the embed code and ensure it’s inside the `<body>`.           |


# Channel Types

Each channel type follows a unique **authentication and connection flow**.

## **Summary**

| Channel Type            | Authentication      | Connection Flow            | Customization               | Typical Use                             |
| ----------------------- | ------------------- | -------------------------- | --------------------------- | --------------------------------------- |
| **Widget**              | None                | Instant setup              | Full color + code embedding | Websites and apps                       |
| **WhatsApp (Waha)**     | QR Code             | Mobile scan pairing        | None                        | Personal or small business accounts     |
| **WhatsApp (Official)** | OAuth via Facebook  | Login + Meta authorization | None                        | Official Business API integration       |
| **Instagram**           | OAuth via Instagram | Login and authorization    | None                        | DMs through connected Instagram account |
| **Telegram**            | Bot token           | Token validation + webhook | Split long messages         | Private 1:1 bot conversations           |


# Widget

The **Widget** channel is used to embed an interactive chat directly on your website or system.

#### Steps to Create

1. Select **Type: Widget**.
2. Name the channel (e.g., *Official Widget*).
3. Assign a responder (Agent or Squad).
4. Optionally, add a custom prompt.
5. Set the response delay.
6. Click **Create Channel**.

Once created, the channel exposes a **Widget Configuration Page** containing:

| Section                   | Description                                                                  |
| ------------------------- | ---------------------------------------------------------------------------- |
| **Configuration Code**    | JavaScript snippet that must be copied and pasted into your site or web app. |
| **Theme Controls**        | Switch between **Light Mode** and **Dark Mode** versions.                    |
| **Customization Options** | Modify colors for background, text, and buttons.                             |
| **Open on Load**          | Option to auto-open the widget when the page loads.                          |

```html
<body>
  <script>
    window.ZV2Widget = {
      ChannelURL: "https://widget.endless.zaia.app/widget/channel/..."
    };
  </script>
  <script src="https://widget.endless.zaia.app/script/widget-loader.js" async></script>
</body>
```

> ⚙️ Use the “Copy” button to copy the full script into your HTML `<body>` section.\
> Once deployed, your website visitors will be able to chat directly with your Agent.

## **Customization Notes**

For **Widget Channels**, Zaia provides a live customization environment:

* Modify message bubble colors and text colors.
* Adjust button color to match your branding.
* Switch between Light and Dark previews.
* Instantly preview all UI changes before saving.

Each customization option is applied independently per channel, allowing multiple widget styles for different sites or environments.

### Send documents in the Widget

Website visitors can attach documents to Widget messages. The Widget accepts:

* `.pdf`
* `.md`
* `.txt`

Each document can be up to **10 MB**. Zaia sends the file's original extension with the message.

{% hint style="info" %}
PDF files have an additional content limit. Zaia rejects PDFs whose converted text exceeds 50,000 characters.
{% endhint %}

Markdown and text files do not use this PDF content check.

### Document restrictions by channel

Document availability depends on the channel. Instagram does not support document attachments.

This restriction applies to PDF, Markdown, and text files.

***

### Draft Test Widget

Use a **Test Widget** to share an Agent's current Draft with people outside the workspace before publishing it.

* A Test Widget always uses the responder's **Draft** version.
* A regular Widget continues to use the **Production** version.
* Draft changes become available in the Test Widget without publishing the Agent.
* The shared experience is visibly identified as a test environment.
* Publishing remains a separate action and is not triggered by creating or using the Test Widget.
* Disable or remove the Test Widget to end external test access.

Use the Test Widget to validate instructions, tone, tools, and conversation behavior with external reviewers while keeping Production unchanged.


# Conversation History

Let Widget visitors create, revisit, and manage multiple conversations.

The Widget supports multiple persistent conversations for each visitor.\
Visitors can create new conversations and return to previous ones.

A new conversation does not delete previous messages.\
Each conversation remains available in the visitor's history.

### Use conversation history

The chat has two views: the current conversation and its history.

1. Select the back button in the chat header.
2. Browse the conversation history.
3. Select a conversation to reopen it.

The Widget loads the selected conversation and marks it as read.\
History is grouped by day and loads additional conversations as needed.

### Start a new conversation

Select **+** in the conversation history to start a new chat.

The Widget clears the current chat from the interface.\
It creates the new conversation when the visitor sends their first message.\
The new conversation then appears in the history.

The selected conversation is saved locally for each channel.\
Returning visitors continue from their last selected conversation.

### Manage conversations

Visitors can rename a conversation directly from the history list.\
Conversations with unread messages display an unread state until opened.

The empty chat state includes a shortcut to **View history**.\
This helps visitors return to an earlier conversation quickly.

{% hint style="info" %}
Conversation history is not a reset or deletion feature. It only lets visitors navigate between existing conversations.
{% endhint %}

### Availability

This experience is available in these chat surfaces:

* Embedded and public Widgets
* Floating chat
* Vibe Agent

### Widget theme migration

The default user-message colors changed with this release.\
Workspaces using a legacy default Widget theme require the associated migration before release.

This migration prevents low-contrast user messages.\
It only affects Widget channels that use the legacy default theme.


# WhatsApp (Waha)

This option connects the platform to WhatsApp using **Waha API**, which leverages the official WhatsApp Web protocol through QR code authentication.

#### Connection Flow

1. Select **Type: WhatsApp (Waha)**.
2. Define the channel name and description.
3. Assign a responder (Agent or Squad).
4. Click **Create Channel**.
5. A **QR Code** will appear automatically.

#### QR Code Authentication

* Open the WhatsApp app on your phone.
* Navigate to **Linked Devices → Add Device**.
* Scan the QR Code displayed on the screen.
* The connection will be established within a few seconds.

Once the QR code is read successfully, the Agent can send and receive messages through that WhatsApp number.\
If the channel is deactivated, message routing stops immediately.

> 🕐 QR codes are valid for **40 seconds** — if the connection fails, refresh the page or restart the pairing process.

***

### ⚠️ Messaging limitations

WhatsApp (Waha) supports **text messages only**.

It does not support:

* WhatsApp templates
* Template fallback after the 24-hour window
* Official outbound template flows


# WhatsApp (Official)

This connection uses Meta's official WhatsApp Business API, providing a secure, stable, and feature-rich integration for your AI agents.

### 📹 Video Guides

#### Troubles with WhatsApp connection?

{% embed url="<https://www.youtube.com/watch?v=mApSDqLeWcg>" %}

#### Understanding WhatsApp Official API

Before connecting, watch this comprehensive guide to understand how the official API works, pricing models, and the two connection approaches available:

{% embed url="<https://youtu.be/bUV5qWUaOEE>" %}

**Topics covered:**

* How Meta's portfolio structure works
* App + API vs API-only modes
* Pricing model (24-hour conversation windows)
* Two connection paths: Your portfolio vs Client portfolio
* Verification requirements
* Common questions answered

#### Step-by-Step Connection Tutorial

Watch this practical walkthrough showing exactly how to connect WhatsApp through Zaia's interface:

{% embed url="<https://youtu.be/c2rE0-aWzyk>" %}

***

### 🔌 Quick Connection Guide

#### In Zaia

1. Go to **Workspace Settings** → **Connections** → **New Connection**
2. Select **WhatsApp (Official)** and give it a name
3. Click **"Connect"**

> ⚠️ Allow pop-ups when prompted - Meta's authentication opens in a new window.

***

#### In Meta's Flow

**1. Create or Select Portfolio**

* New portfolio? Fill in: name, email, country, website (or Instagram)
* Existing portfolio? Select from dropdown

**2. Choose Connection Type**

| Create WhatsApp Account    | Connect Existing App                          |
| -------------------------- | --------------------------------------------- |
| Brand new number           | Number already using WhatsApp Business app    |
| Number never used WhatsApp | Keep using app + add automation (coexistence) |

**3. Add Phone Number**

* Enter the number with country code
* Info must match your WhatsApp Business app (if connecting existing)

**4. Verify Number** (for existing numbers)

**QR Code Method:**

* You'll receive a message from Facebook Business on WhatsApp
* Click "Connect" button in the message
* Choose "Don't share conversations"
* Scan the QR code

**Access Code Method:**

* Click "Use access code instead"
* Enter the code sent to WhatsApp

> 💡 **New accounts:** If verification fails, wait 15-30 minutes and try again.

**5. Confirm Settings**

* Select timezone
* Review permissions
* Click "Confirm" → "Finish"

***

#### Back in Zaia

1. Create a **Channel** and link it to your new WhatsApp connection
2. Assign an Agent or Squad
3. **Test** by sending a message to your number

✅ Done!

***

### 🔎 View connection details

After the connection is created, open **Workspace Settings** → **Connections** and check the connection details area.

For **WhatsApp (Official)** connections, Zaia shows:

* **Token**
* **Phone Number ID**
* **WABA ID**

Each field is read-only.

Each field also has its own copy action.

For tokens longer than 30 characters, Zaia shows the first 30 characters followed by `...`.

The copy action always copies the complete token.

If a value is empty, Zaia shows **Not available** and disables copy for that field.

Zaia only displays values already returned by the existing connection.

It does not create, edit, or recalculate these identifiers.

{% hint style="info" %}
This details block appears only for **WhatsApp (Official)** connections.

It does not appear for **WhatsApp (Waha)** or other channel types.
{% endhint %}

***

#### ⚠️ Important: New Portfolio Verification

Created a **new portfolio** during setup? You'll need to verify it within a few hours:

* Required docs: Business registration, proof of address
* Processing: 2-5 business days
* Without verification, connection may be restricted after initial period

***

### 🎯 Two Connection Approaches

#### Your Portfolio (Up to 40 numbers)

Add client numbers to **your own** Meta Business portfolio.

**Best for:** Starting out, quick setup, full control\
**Limit:** 40 numbers total (2 portfolios × 20 each)\
**Verification:** Verify YOUR account once, add all 40 numbers without re-verifying

#### Client Portfolio (Unlimited)

Client creates portfolio and adds **you as admin**.

**Best for:** Scaling beyond 40, formal businesses, client ownership\
**Limit:** Unlimited\
**Verification:** Each client may need to verify their portfolio (if formal business)

> 💡 You can **create 2 portfolios** but be **admin on unlimited** client portfolios.

***

### 📱 App + API vs API-Only

#### App + API (Coexistence)

Client keeps using WhatsApp Business app **+** your AI agent responds via API.

**When to use:** Client wants to keep app access, team needs to respond, IA + human together

#### API-Only (Exclusive)

Number becomes 100% API. Client **cannot** use app anymore.

**When to use:** Full automation, client doesn't need app, dedicated new number

> ⚠️ **Warning:** API-only migration is **irreversible** - number can never return to app mode.

***

### 💰 Pricing

* **Client sends message:** FREE
* **You respond (within 24h):** FREE - unlimited replies
* **You initiate conversation:** \~$0.15-0.35 per message (requires template)

> ✅ Perfect for AI agents! Each client message opens a 24h window for unlimited free responses.

***

### 🧩 Templates and outbound messaging

Official WhatsApp supports approved templates for outbound delivery.

In Zaia, this is available in:

* [Message Sending Tool](/tools/available-tools/message-sending-tool)
* [Message Sending Node](/workflows/workflow-nodes/message-sending-node)

#### Supported send modes

When the connection type is **WhatsApp (Official)**, Zaia can send:

* **Text**
* **Template**
* **Text with template fallback**

With fallback enabled, Zaia tries text first. If Meta rejects the send because the 24-hour window expired, Zaia sends the configured template instead.

> ⚠️ Fallback only runs for the specific WhatsApp window-expired error. Other delivery errors do not trigger automatic template usage.

#### Template requirements

Templates only work when:

* The connection is active
* The connection is correctly configured
* The template exists for that WhatsApp account
* The template is approved in Meta

Zaia only lists approved templates from the selected connection. It also builds the required fields dynamically from Meta's template schema.

This includes:

* **Body** variables
* **Header** variables
* **Button** variables
* **Header image** input, when applicable

#### Workflow vs tool behavior

In the Workflow node, all required template fields must be filled during configuration.

In the Agent tool, template fields can be partially filled. Missing values can be completed at execution time from context, execution data, or the LLM output.

When both sources provide values, Zaia keeps the configured values and fills only the missing ones.

#### Validations and restrictions

Zaia validates rendered template fields before sending. This includes limits for body, header, OTP, and button URL suffixes.

Templates with image headers accept a public URL, a stored file, or a data URL. Zaia converts the image to the format accepted by the WhatsApp API before sending.

Template metadata is stored in the delivery record for traceability.

In direct chat message sending, templates cannot be sent together with attachments.

***

### ✅ Verification

#### When Required

* New portfolios (within a few hours of creation)
* High volume (1,000+ messages/day)
* Some advanced features

#### What You Need

* Business documents (CNPJ, registration)
* Proof of address
* Processing: 2-5 business days

#### Key Points

* **Your Portfolio:** Verify once → add all 40 numbers
* **Client Portfolio:** Each client verifies their own (if formal business)
* **Small clients (MEI/PF):** Usually don't need immediate verification

> ⚠️ New portfolios work initially but require verification within hours for continued service.

***

### ❓ FAQ

**Do I need a Facebook Page?**\
No! Connect directly through Business Manager.

**Can I use an existing WhatsApp number?**\
Yes! Choose "Connect existing app" for coexistence mode (App + API).

**Will I see previous conversations?**\
No. Only new conversations from connection time forward (Meta API limitation).

**Can I switch from API-only back to App+API?**\
No. API-only migration is **irreversible**.

**How much does it cost?**\
Receiving + replying (24h): FREE | Initiating: \~$0.15-0.35/message | Billed by Meta, not Zaia.

**When do I need verification?**\
New portfolios need verification within hours. Small clients (MEI/PF) usually don't need immediate verification.

***

### 🔧 Troubleshooting

**QR Code / Verification Code Fails**\
Wait 15-30 minutes (especially for new accounts) and try alternative method (QR ↔ Code).

**Pop-up Blocked**\
Allow pop-ups for Zaia domain. Try Chrome if issues persist.

**Connection Works Then Stops**\
Verification required. Check Meta email and verify business in Business Manager.

**Messages Not Appearing**\
Ensure: Connection → linked to Channel → Channel has active Agent/Squad → Account verified (if needed).

**Can't See Message History**\
Meta API limitation. Only new conversations from connection time forward are visible.

***

### 📚 Resources

* [Meta WhatsApp API Docs](https://developers.facebook.com/docs/whatsapp)
* [Business Manager Help](https://business.facebook.com/business/help)
* [WhatsApp Business Policy](https://www.whatsapp.com/legal/business-policy)

**Need help?** Contact Zaia support through the in-platform chat.


# Instagram

The **Instagram** channel lets your Agent send and receive Instagram direct messages through Zaia.

### Connect an Instagram channel

{% stepper %}
{% step %}

### Open the channel settings

1. Go to **Channels**.
2. Open the **Instagram** channel.
3. Click the pencil icon.
4. In **Connection**, click the plus icon.
   {% endstep %}

{% step %}

### Create the connection

1. Enter a connection name.
2. Click **Connect**.
3. Complete the Instagram login flow in the new tab.
   {% endstep %}

{% step %}

### Approve Instagram access

During authentication, Instagram may ask you to:

* Enter the account credentials.
* Complete verification with a backup code.
* Confirm **Save Info**.
* Review permissions and click **Allow**.

When the success message appears, close the tab.
{% endstep %}

{% step %}

### Finish setup in Zaia

1. Return to the channel settings.
2. Select the new connection.
3. Click **Update channel**.
4. Go back to **Channels**.
5. Enable the channel toggle.
   {% endstep %}
   {% endstepper %}

After activation, the channel is ready to receive and send Instagram messages.

### Validate the connection

Use this quick test after setup:

1. Send a message to the connected Instagram account.
2. Wait for the Agent reply.
3. Open [Chat History](/inbox/chat-history) and confirm the conversation appears with the exchanged messages.

This confirms the connection, delivery flow, and message sync.

***

### Human support on Instagram

Instagram channels support human takeover inside Zaia.

To handle a conversation manually:

1. Open the conversation in Tickets.
2. Click **Take over ticket**.
3. Send the reply as a human attendant.
4. Wait for the user response.
5. Click **Mark as finished** when the conversation is done.

While the ticket is in progress, the Agent stops replying.

{% hint style="info" %}
For eligible conversations outside Instagram's standard 24-hour messaging window, Zaia sends human replies using Meta's **Human Agent** permission flow.
{% endhint %}

This is the flow used when a human needs to continue support after the standard reply window.

***

### Manual takeover outside Zaia

Instagram channels also support manual takeover outside Zaia.

When **Enable manual takeover and interrupt Agent responses** is enabled:

* Proactive messages sent from another platform are treated as human messages.
* The Agent stops replying to that conversation.

#### Return control to the Agent

Instagram requires an extra confirmation before the Agent resumes.

1. React to the user's latest message with the preconfigured emoji.
2. Send a new message.

Both steps are required.

***

### Reuse an existing Instagram connection for Workflow triggers

When an Instagram connection is already valid in Zaia, supported external-event triggers can reuse that connection without asking the user to authenticate again.

* The first use creates the reusable connection link required by the trigger.
* Later uses reuse the same link instead of creating duplicate connections.
* The initial supported provider is Instagram.
* The Workflow remains the place where the external-event trigger is configured.
* Trigger executions remain visible in **Executions**.

If the existing connection cannot be reused, Zaia reports whether the failure happened while importing the credentials, linking the connection, or making the authenticated request. Reauthentication may be required when the original Instagram connection is no longer valid or compatible.


# Telegram

Connect a Telegram bot to handle private 1:1 conversations with text, images, audio, and PDFs.

The **Telegram** channel lets your Agent handle 1:1 conversations through a Telegram bot.

Use it when you need inbound and outbound support on Telegram with text, images, audio, and PDF files.

***

### Connection requirements

Before the channel can work, you need a Telegram **bot token**.

Zaia validates the token before saving the connection.

The connection only activates when:

* The token belongs to a valid Telegram bot
* The bot is not already active in another Telegram connection
* The webhook is configured successfully

If webhook setup fails, the connection stays in **failed** status and does not activate.

***

### Connection flow

1. Go to **Workspace Settings** → **Connections** → **New Connection**.
2. Select **Telegram**.
3. Enter a name and the bot token.
4. Save the connection.
5. Wait for the webhook setup to finish.
6. Create a **Channel** linked to that connection.
7. Assign an Agent or Squad.

Once both the connection and channel are active, Zaia can exchange messages with Telegram users.

***

### Supported conversation scope

Telegram support is limited to **private chats**.

Zaia processes messages sent directly to the bot by an individual user.

Zaia ignores messages from:

* Groups
* Supergroups
* Channels

On the first valid message from a user, Zaia creates the external user and the conversation automatically if they do not exist yet.

Zaia also prevents duplicate processing of the same Telegram message.

***

### Supported message types

#### Incoming from Telegram

Zaia can receive:

* **Text**
* **Image**
* **Audio / voice**
* **PDF document**

#### Outgoing to Telegram

Zaia can send:

* **Text**
* **Image**
* **Audio**
* **PDF document**

***

### Media behavior

#### Images

If the user sends an image with a caption, Zaia stores the caption as the message text.

If Telegram sends multiple versions of the same image, Zaia uses the largest one.

When Zaia sends a reply with **one image** and **text up to 1024 characters**, the text is sent as the image caption.

If the reply includes longer text or another media combination, the text is sent separately from the media.

#### Documents

Document handling is implemented for **PDF** files.

Other document types are not part of the current Telegram scope.

#### Audio

When the user sends audio or voice, Zaia downloads the file and normalizes it to **WAV** for internal processing.

***

### Long message behavior

Telegram has a technical limit for text length.

Zaia always respects that limit and splits oversized replies automatically.

You can also enable **Split long messages** on the channel.

When enabled, long responses are intentionally broken into smaller Telegram messages before delivery.

***

### Important limitations

* Telegram uses a **bot token**. It does not support user login.
* The channel only works when the linked connection is **active**.
* Public channel sharing is disabled for Telegram in the web app.
* **Manual takeover by reaction** is not available for Telegram.
* The Telegram-specific channel option is **Split long messages**.

***

### Best-fit use cases

Telegram works best for:

* 1:1 support conversations
* File and media exchange during support
* Agent flows that react to user text, images, audio, or PDFs

It is not designed for community moderation or group mention workflows.

***

### Current scope vs planned ideas

Some earlier planning considered replying inside groups or communities when the bot was mentioned.

That behavior is **not** part of the current implementation.

Only private chat messages are processed.

***

### Troubleshooting

**Connection does not activate**\
Check whether the token belongs to a bot and whether the bot is already active in another connection.

**Connection enters failed status right after creation**\
Webhook setup likely failed. Recheck the token and try reconnecting.

**Messages do not appear in Zaia**\
Make sure the message came from a private chat and that both the connection and channel are active.


# Overview

Run Zaia under your own brand, domain, and client-facing identity.

Zaia White Label adds your brand, visual identity, and custom domain to the platform.

Your clients see your identity, not Zaia.

Use the Console to manage workspaces, members, plans, billing, checkout, and slots.

***

### Console, White Label, and workspaces

**Console** is the management surface for your account and workspaces. Use it for administration, billing, subscriptions, checkout, and slots.

**White Label** is the branding layer. It provides your visual identity and custom domain.

**Workspace** is the operational environment. It contains your Agents, members, integrations, conversations, and settings.

***

### What White Label includes

White Label removes Zaia from the client-facing experience.

When members and clients access workspaces, they see your branding.

Core benefits include:

* Your brand across the platform.
* Your own custom domain.
* A client-facing identity for your operation.

***

### What changes for your clients

Your clients do not interact with Zaia as a brand.

They access the platform through your identity.

This helps you operate as a full AI agency or technology partner, not just a service reseller.

***

### Who White Label is for

White Label is built for agencies that want recurring revenue with AI agents.

It is designed for partners that want close support and a durable operation.

This program is intentionally selective.

#### Why access is limited

Seats are limited to preserve support quality and partner proximity.

This model helps maintain strong onboarding, real follow-through, and better outcomes for each partner.

***

### Selection process

New openings are released in batches.

Each batch goes through a selection process.

{% stepper %}
{% step %}

### Apply

Submit your application to add White Label to your partner operation.

This step helps evaluate fit and maintain a healthy partner cohort.
{% endstep %}

{% step %}

### Join an interview

Meet with the Zaia team in an individual interview.

The goal is to understand your business and answer open questions on both sides.
{% endstep %}

{% step %}

### Receive the decision

Approval or rejection is shared after the interview.

Final approval is completed after license payment within the defined timeframe.
{% endstep %}
{% endstepper %}

***

### Workspace model for client operations

White Label provides branded access to client workspaces.

You choose how to structure client operations.

Common setups:

* One workspace per client.
* Multiple agents inside one client workspace.
* Mixed structures based on your service model.

The workspace architecture is flexible.

***

### White Label and workspaces

White Label can provide branded access to client workspaces through your custom domain.

When an existing workspace is linked to a White Label operation:

* Its Agents, conversations, Channels, connections, Knowledge Bases, Tables, Workflows, roles, and authentication data remain unchanged.
* Its current billing account and subscription remain attached to that workspace.
* Existing workspace members can access the branded experience.
* Future access happens through the configured domain.

The Console manages workspace billing, checkout, and slots. A workspace can exist before payment. Its billing account is provisioned during the first checkout. Each workspace keeps its own subscription.

> ⚠️ **Before linking an existing workspace:** Confirm the correct White Label operation. This association cannot be changed through self-service. Contact support if you need migration help.

***

### Acceleration Program in the Console

Signed-in users can open the **Acceleration Program** from the Console. Review preconfigured Agent templates before proceeding.

See [Acceleration Program](/white-label/acceleration-program) for the complete flow.

***

### How plan executions work

Executions are counted per agent.

If one workspace has two published agents, both contribute to that workspace's execution total.

This applies whether the agent is active on a channel or not.

The plan limit is shared across all your agents.

For general usage details, see [Understanding Usage Limits](/quick-start/understanding-usage-limits).

***

### Partner plans and White Label

The Console provides the annual partner plans below. White Label is the branding addon for the partner experience.

The annual commitment can be paid in up to 12 credit card installments.

#### Starter

`R$ 990/month`

Includes:

* Console access.
* White Label addon.
* Vibe Agent usage.
* 10 Console slots.
* Up to 10 published agents.
* Up to 50k monthly executions.
* Bring Your Own Key support.
* Access to the private community.
* Access to practical training.
* Monthly group mentoring.

#### Pro

`R$ 2,062/month`

Includes everything in Starter, plus:

* 3x more Vibe Agent usage.
* 25 Console slots.
* Up to 25 published agents.
* Up to 125k monthly executions.
* Individual onboarding.
* Monthly roadmap co-creation sessions.
* Priority support with a 6-hour SLA.

#### Scale

`R$ 4,950/month`

Includes everything in Pro, plus:

* 5x more Vibe Agent usage.
* 45 Console slots.
* Up to 45 published agents.
* Up to 225k monthly executions.
* Dedicated channel with the Zaia team.
* Direct influence on the roadmap.

For broader plan context, see [Plans, Princing and Usage Limits](/quick-start/plans-princing-and-usage-limits) and [Subscription Plans Comparison](/quick-start/subscription-plans-comparison).

***

### Onboarding and support

Individual onboarding is available on the **Pro** and **Scale** plans.

It includes up to 2 hours of guided support.

You can split it into one or two sessions.

Typical use cases:

* White Label custom-domain setup.
* Channel configuration.
* Co-building your first agent.

Priority support is provided through a private partner community channel.

The SLA depends on your plan.

***

### Bring Your Own Key

You can use your own LLM API key.

This is recommended when publishing agents to channels like WhatsApp or Instagram.

BYOK can be configured per workspace or per individual agent.

This gives you direct control over model cost by client or use case.

For provider setup, see [Providers](/settings/providers) and [Model Selection](/agents/agent-settings/model-selection).

***

### External integrations

External integrations are included.

Your agents can query APIs, CRM systems, databases, and other external systems before replying to the user.

There is no additional fee for that capability inside the plan.

To implement this, see [HTTP Request Tool](/tools/available-tools/http-request-tool).

***

### Cancellation policy

You can cancel at any time.

Cancellations do not include refunds or reimbursements.

Access remains active until the end of the contracted period.

The plan does not renew automatically after cancellation.

***

### Workspace ownership

Workspace ownership cannot be transferred to your client.

If a client leaves your operation, you can still keep the workspace active.

The full setup remains intact, including:

* History.
* Agents.
* Knowledge bases.
* Settings.

***

### FAQ

#### Why is there a selection process and limited availability?

Support and proximity cannot scale infinitely.

The program limits seats to keep partner support healthy and focused.

It also helps prioritize partners committed to building a solid business.

#### What is included in White Label?

White Label includes the branded platform experience.

You use your brand and custom domain across the platform. Clients see your identity.

#### How does workspace access work for my clients?

Workspace access is available from the start.

You decide whether each client gets one workspace, multiple agents in one workspace, or another structure.

#### How are plan executions counted?

Executions are counted per agent.

All published agents contribute to the workspace total, and the plan limit is shared across all agents.

#### Do you charge for team members or added clients?

No.

#### Does the plan require annual payment upfront?

The commitment is annual.

Payment can be split into up to 12 installments on a credit card.

#### What does the individual onboarding include?

It includes up to 2 hours of guided support.

You can use it for domain setup, channel setup, first-agent co-creation, or other business needs.

#### Can I cancel the plan?

Yes.

You can cancel at any time, without refund.

Access remains active until the contracted period ends.

#### How does priority support work?

Priority support runs through a private partner community channel.

The SLA depends on the contracted plan.

#### Can I use my own LLM key?

Yes.

BYOK is supported and recommended for some publishing scenarios.

It can be configured per workspace or per agent.

#### Are external system integrations included?

Yes.

API access, CRM lookups, database queries, and other external integrations are included at no extra cost.

#### What happens if one of my clients leaves my operation?

Workspace ownership cannot be transferred to that client.

You can still keep the workspace active with its full configuration and history preserved.


# Acceleration Program

Explore preconfigured Agent templates from the signed-in Console.

The **Acceleration Program** is available in the signed-in Console. It lets Console users explore ready-made Agent templates without leaving the platform.

***

### Accessing the program

1. Sign in to the Console.
2. Open **Acceleration Program** from the authenticated area.
3. Browse the available Agent templates.
4. Select a template to review its configuration and commercial details.
5. Continue with the selected option when you are ready.

If your organization uses White Label, you can access the Console through its custom domain.

***

### What you can review

Each available template can present the resources that support its operation, including:

* The Agent configuration.
* The Tools used by the Agent.
* Compatible MCP integrations.
* The calculated price shown for the selected option.

This makes it easier to understand the template before adding it to your operation.

***

### Before continuing

* Confirm that you are in the correct workspace.
* Review the displayed price before proceeding.
* Check whether the template uses Tools or MCPs that require a connection in your workspace.
* Complete any required connection after selecting the template.

> 💡 **Tip:** Use the template details to compare the setup with your client's use case before continuing.


# Knowledge Base — Overview

The **Knowledge Base** is where your Agents learn what to say, how to say it, and what information to rely on.\
It acts as a structured repository of trusted data — from FAQs and documents to custom training texts — ensuring that your Agents can respond accurately and consistently across all channels.

In Zaia Endless, Knowledge Bases are **independent and reusable** entities.\
They can be linked to multiple **Agents** or **Squads** simultaneously, depending on which Agents have access to a Tool connected to that specific Knowledge Base.

***

### 🧩 Core Concepts

| Concept            | Description                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| **Knowledge Base** | A container that stores curated information used to train or inform Agents.                        |
| **Items**          | Individual pieces of content within a Knowledge Base — such as texts or PDFs.                      |
| **Training**       | The process of embedding and indexing your data so it becomes searchable and understandable by AI. |
| **Linking**        | The mechanism that connects a Knowledge Base to one or more Agents through the **Knowledge Tool**. |

***

### 💡 Why It Matters

Knowledge Bases allow you to separate **intelligence** (the Agent’s reasoning) from **information** (the Agent’s source of truth).\
This modular structure offers three key benefits:

1. **Scalability** — The same knowledge can be shared across multiple Agents or Squads.
2. **Versioning** — You can update a Knowledge Base without rebuilding or reconfiguring Agents.
3. **Precision** — Each Agent retrieves only the information it is authorized to use.

***

### 🧠 How It Works

1. You create one or more Knowledge Bases under the **Builder → Knowledge** section of an Agent.
2. You add content items — either **Text** or **PDF**.
3. The system automatically processes and trains the data.
4. You can link the trained base to any Agent via the **Knowledge Tool**.
5. When a user interacts with the Agent, it retrieves contextually relevant information from that base in real time.

***

### ⚙️ Supported Content Types

| Type     | Description                                                                              |
| -------- | ---------------------------------------------------------------------------------------- |
| **Text** | Raw content written directly in the interface (ideal for FAQs, guides, and definitions). |
| **PDF**  | Uploaded documents such as manuals, reports, or training materials.                      |

Support for other formats (e.g. `.docx`, `.md`, `.csv`) will be added in upcoming releases.

***

### 📈 Knowledge Lifecycle

1. **Creation** — Define the base and its purpose.
2. **Population** — Add items such as text or PDF documents.
3. **Training** — Let the platform process and embed your data.
4. **Linking** — Assign the base to one or more Agents.
5. **Iteration** — Update content and retrain as needed.

***

### 🧭 Example

* **Base Name:** *Cérebro Ju*
* **Used by:** *Agent Ju da Zaia* and *Squad da Zaia*
* **Items:**
  * Text: *Commercial FAQs (bilingual)*
  * PDF: *Product Documentation*

Both the individual Agent and the Squad can query this same base, as long as they’re linked through a **Knowledge Tool**.


# Creating a Knowledge Base

Creating a Knowledge Base in Zaia Endless is a straightforward process.\
Each base can hold multiple items and serve as a reusable knowledge layer for different Agents or Squads.

***

### 🪄 Step 1 — Open the Knowledge Module

1. Navigate to **Builder → Agents → \[Select your Agent] → Knowledge**
2. Click **New Knowledge Base +** in the top-right corner.

***

### 🧠 Step 2 — Define the Base

In the **Add Knowledge Base** window:

* **Name:** Choose a clear and descriptive title (e.g. *Support FAQs*, *Internal Docs*, *Sales Playbook*).
* **Description (optional):** Add internal notes for organization or context.

Click **Create Knowledge Base** to finalize.

Your new base will now appear in the list.

***

### 📚 Step 3 — Add Items

Each Knowledge Base can contain multiple items, which are the actual content sources.

Click **Add Item +**, then select one of the following:

#### 📝 Text

* Ideal for FAQs, structured guides, or internal definitions.
* Paste up to **1,000,000 characters** of content.
* Click **Update** to save and start training.

#### 📄 PDF

* Upload a `.pdf` file from your computer.
* The platform will automatically extract, process, and index the text content.
* Click **Add** to confirm.

***

### 🔄 Step 4 — Training & Status

After adding content, the system automatically begins **training** — converting text into vector embeddings for retrieval.

| Status         | Description                                |
| -------------- | ------------------------------------------ |
| **Pending**    | Waiting to start training.                 |
| **Processing** | Data is being analyzed and embedded.       |
| **Completed**  | Training finished successfully.            |
| **Failed**     | An issue occurred; edit or retry the item. |

You can hover over the **Status** indicator to view detailed information.

***

### 🧩 Step 5 — Update or Manage

At any time:

* Click the **Edit (✏️)** button to rename or update the base description.
* Click the **⋮** menu beside an item to edit, delete, or retrain it.
* Adding new items will automatically trigger training again.

***

### 💡 Tip

Keep content concise, clean, and well-structured.\
Use consistent headings and avoid redundant data to improve embedding quality and retrieval precision.


# Linking a Knowledge Base to an Agent

Creating a Knowledge Base is only the first step — to make it functional, you need to **link** it to an Agent or Squad.\
This connection is established through the **Knowledge Tool**, available inside each Agent’s configuration.

***

### 🧠 How Linking Works

Every Agent has its own list of **Tools**.\
When you add the **Knowledge Tool**, you can choose which Knowledge Bases that Agent will use as reference sources.

An Agent can:

* Use **multiple Knowledge Bases** simultaneously.
* Share the **same Knowledge Base** with other Agents or Squads.
* Retrieve relevant data dynamically based on context.

This flexibility allows you to build complex ecosystems where shared information powers multiple intelligent Agents.

***

### ⚙️ Linking a Knowledge Base

1. Go to **Builder → Agents → \[Select your Agent] → Tools**
2. Click **Add Tool +**
3. Choose the **Knowledge Tool** from the list
4. In the configuration window:
   * Select one or more **Knowledge Bases** to link
   * Adjust retrieval parameters (if available)
   * Save changes

Once linked, the Agent will automatically begin using the data for contextual reasoning and responses.

***

### 🧩 Linking to a Squad

When Agents belong to a **Squad**, any Knowledge Base connected to those Agents via the Knowledge Tool becomes available to the entire Squad context.\
This enables shared knowledge environments for teams of Agents collaborating on the same workflow.

***

### 💬 Example Scenario

**Knowledge Base:** *Zaia Commercial Knowledge*\
**Linked via:** *Knowledge Tool*\
**Used by:**

* Agent Ju da Zaia → Handles customer inquiries
* Agent Alfred → Builds custom workflows
* Squad da Zaia → Combines both agents in collaborative operations

All three entities reference the same Knowledge Base.\
If the base is updated or retrained, the changes immediately propagate to all Agents and Squads that use it.

***

### 🧭 Best Practices

* **Keep one source of truth.** Reuse Knowledge Bases across Agents when possible.
* **Modularize content.** Create separate bases for topics like Sales, Product, and Support.
* **Test context boundaries.** Ensure Agents are not over-retrieving from unrelated sources.
* **Monitor performance.** Retrain or clean content periodically for consistency.


# Best Practices & Optimization

Building a Knowledge Base is not just about uploading documents — it’s about optimizing how your data is understood, embedded, and retrieved by your Agents.\
This section provides advanced guidelines for improving accuracy, reducing noise, and ensuring consistent multi-Agent performance across Zaia Endless.

***

### 🧱 1. Structuring Your Knowledge

The quality of an Agent’s responses depends heavily on how the content inside your Knowledge Base is written and organized.\
Follow these principles to maximize retrieval precision:

#### ✅ Do:

* **Use clear titles and headings.** Structure long texts with `#` or `##` (Markdown syntax) or bold section headers.
* **Keep topics focused.** Each item should represent one domain or subject area.
* **Segment logically.** If a document covers several unrelated subjects, split it into multiple text items.
* **Add context identifiers.** Example:

  ```
  [SECTION: Product Pricing]
  [SECTION: Warranty Policies]
  ```

#### ❌ Avoid:

* Overlapping or redundant information between items.
* Long unstructured paragraphs (over 2000 characters without breaks).
* Mixing unrelated concepts (e.g. pricing + onboarding + troubleshooting in one text).

***

### 🧠 2. Optimizing for Embeddings

Each Knowledge Base undergoes an **embedding process**, where its text is transformed into high-dimensional vectors for semantic retrieval.\
Small changes in structure can significantly affect search quality.

#### 🔍 Embedding Best Practices

* **Shorter segments embed better.** Keep each paragraph or bullet list under \~1500 characters.
* **Avoid repeated keywords.** Semantic models already infer meaning — keyword stuffing lowers quality.
* **Maintain consistent formatting.** Avoid random line breaks, tabs, or inconsistent casing.
* **Include synonyms naturally.** This helps the model connect variations of user queries.

  > Example: “pricing / cost / plan / subscription” within one sentence helps broaden recall.
* **Avoid excessive symbols.** Special characters, emojis, or decorative punctuation can reduce precision.

***

### 🌐 3. Bilingual and Multi-Language Knowledge

Zaia Endless supports multilingual Agents. When building bilingual Knowledge Bases (e.g., Portuguese + English), always separate languages clearly to prevent mixed-context embeddings.

#### 🏗️ Recommended Structure

```
FAQ — English
Q: What is the price of Zaia?
A: Plans start at $X/month depending on usage.

FAQ — Português
P: Qual é o preço da Zaia?
R: Os planos começam em R$X/mês dependendo do uso.
```

**Tips:**

* Keep both languages in the same item only if logically aligned.
* Use language tags `(EN)` and `(PT)` to separate content blocks.
* Do **not** interleave sentences from different languages.

***

### 🔄 4. Managing Updates and Retraining

Whenever a Knowledge Base item is edited or replaced, it automatically re-enters the **training pipeline**.\
To ensure clean retraining cycles:

#### Best Practices

* **Batch updates.** Edit multiple items before retraining to optimize resource usage.
* **Avoid duplicates.** If you replace an item, delete the old one before retraining.
* **Monitor status.** Wait for the `Completed` state before testing the Agent.
* **Periodic refresh.** Retrain major bases every 30–60 days to ensure embeddings stay aligned with evolving models.

***

### 🧩 5. Multi-Agent and Squad Optimization

Since a single Knowledge Base can be shared across **multiple Agents** or an entire **Squad**, consider how each entity interacts with the same data context.

#### Guidelines

* **Centralize shared knowledge.** Keep universal data (e.g., company policies) in one shared base.
* **Isolate specialized data.** Create smaller, domain-specific bases (e.g., “Technical Docs”, “Sales FAQs”).
* **Avoid conflicting sources.** If two bases contain similar topics, Agents may retrieve mixed or inconsistent results.
* **Audit link usage.** Regularly check which Agents and Squads are linked to each base through the Knowledge Tool.

***

### ⚙️ 6. Retrieval Optimization (for Developers)

For technical teams customizing Agents via the API or SDK, consider fine-tuning retrieval settings:

| Parameter                | Description                                   | Recommendation                             |
| ------------------------ | --------------------------------------------- | ------------------------------------------ |
| **Top-k**                | Number of results returned per query          | 3–5 for precision, 8–10 for broader recall |
| **Similarity threshold** | Minimum cosine similarity for match relevance | 0.75–0.85 for most business contexts       |
| **Context window**       | How much text is passed to the LLM            | Keep under 4000 tokens for efficiency      |
| **Cache policy**         | Determines when embeddings are refreshed      | Refresh after major updates only           |

Fine-tuning these parameters helps balance **speed**, **accuracy**, and **token cost**.

***

### 🔐 7. Data Quality and Security

Zaia Endless processes all Knowledge Base content securely, ensuring that:

* Files and texts are encrypted at rest and during transfer.
* Only authorized workspace members can view or modify data.
* Data used for embeddings is **never shared or exposed** to other tenants.

Still, follow these best practices:

* Avoid uploading sensitive credentials or personally identifiable information (PII).
* Sanitize internal notes before including them in Knowledge Bases used by customer-facing Agents.
* Use versioned exports for compliance (e.g., ISO, GDPR, LGPD contexts).

***

### 🧭 8. Performance and Testing

After training or linking Knowledge Bases:

1. Test queries directly through the **Agent Playground** or **CRM Inbox**.
2. Ask questions that closely match and others that differ semantically.
3. Review how the Agent retrieves and synthesizes context.
4. Adjust the base content or retraining if answers are incomplete or redundant.

A well-structured base should produce confident, consistent, and concise answers with minimal hallucination.

***

### 🧩 9. Advanced Techniques (Optional)

For advanced teams:

* **Chunk tuning:** Split documents into smaller logical pieces manually for greater control.
* **Metadata tagging:** Prefix sections with tags (e.g., `[PRICING]`, `[ONBOARDING]`) for scoped retrieval.
* **Hybrid models:** Combine Knowledge Bases with workflow-based tools to pre-filter sources.
* **Evaluation metrics:** Track retrieval accuracy (R\@k) and response satisfaction from real conversations.

***

### ✅ Summary

| Goal                           | Action                                 |
| ------------------------------ | -------------------------------------- |
| Improve accuracy               | Write structured, focused content      |
| Support multilingual retrieval | Separate and label languages           |
| Maintain freshness             | Retrain regularly                      |
| Reduce conflicts               | Centralize or modularize knowledge     |
| Optimize performance           | Tune retrieval parameters per use case |

***

#### 🚀 Final Insight

A well-built Knowledge Base is not just a data repository — it’s a **strategic foundation** for scalable, intelligent, and explainable AI operations.\
In Zaia Endless, every great Agent starts with great knowledge — organized, optimized, and continuously improved.


# Tables — Overview

**Tables** in Zaia Endless are dynamic data structures that allow your Agents to **store, access, and manage information** in real time.\
They act as lightweight, AI-friendly databases that Agents can read from and write to — supporting structured workflows such as contact registration, lead tracking, unresolved inquiries, and feedback collection.

A Table can be fully managed inside the Builder interface, with tools for creating, editing, and linking it to one or more Agents.

***

### 🧩 Core Concepts

| Concept             | Description                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------- |
| **Table**           | A dynamic dataset used by Agents to store or retrieve information.                       |
| **Columns**         | Define the structure of your Table — similar to database fields.                         |
| **Rows**            | Each entry or record in your Table.                                                      |
| **Semantic Search** | A feature that allows Agents to query data using meaning and context, not only keywords. |

***

### 💡 Why Tables Matter

Tables extend your Agents’ memory and logic capabilities by providing:

1. **Persistent storage** — Agents can log user interactions or unresolved questions.
2. **Structured intelligence** — Data can be filtered, queried, and reasoned upon.
3. **Collaboration** — Shared datasets can be used across multiple Agents or Squads.
4. **Automation** — Tables integrate seamlessly with workflows, triggers, and tools.

Example use cases:

* “Unanswered Questions” log for training or review.
* “Contacts” table for lead management.
* “Feedbacks” table for quality tracking.

***

### Loading longer lists

Supported lists load the next page automatically when you reach the end of the scroll area. This replaces the manual **Load more** action in migrated lists and keeps navigation continuous.

The behavior applies to lists for Agents, Squads, Tools, Workflows, Triggers, Datagrids, Datasets, Executions, Tiers, External Groups, and API Keys.

* If the first page does not fill the available height, Zaia continues loading until the list can scroll or no results remain.
* Refreshing, changing a search, or applying a filter prevents results from an earlier request from being appended to the new list.
* Reaching the end after pagination is exhausted does not trigger more requests.
* Removing an item preserves the user's position whenever possible.

Some lists keep a manual **Load more** action when automatic pagination is not appropriate. The External Users list currently follows this exception.


# Creating Tables

Creating a new Table in Zaia Endless is fast and flexible.\
You can create a Table manually or import one from an `XLSX` file, then customize its columns, types, and semantic capabilities.

***

### 🪄 Step 1 — Create a New Table

#### Option A — Create manually

1. Navigate to **Builder → Tables**.
2. Click **Create new table +** in the top-right corner.
3. Enter the following details:
   * **Name** — the Table identifier (e.g. *Unanswered Questions*, *Feedbacks*, *Contacts*).
   * **Description** *(optional)* — for internal use, describing the purpose of this Table.

Click **Create Table** to finish.

#### Option B — Import from XLSX

1. Navigate to **Builder → Tables**.
2. Start the import action from the Table list.
3. In the import modal:
   * Enter the **Table name**.
   * Download the **template file** if needed.
   * Upload **one `XLSX` file**.
4. Confirm the import.

If the file is valid, Zaia Endless creates the Table, redirects you to it, and shows a success message.

> ⚠️ **Review imported columns:**\
> After the import, Zaia Endless keeps a warning visible until every imported column has its **description** and **data type** reviewed.

#### Import rules and validations

* Only `XLSX` files are supported.
* You can upload only one file at a time.
* The attached file shows its **name**, **size**, and a **remove** action before import.
* Use unique column names in the spreadsheet. Duplicate column names prevent the import.
* If the file format is invalid, Zaia Endless shows an error and offers the template download again.
* If the file has row or column count issues, Zaia Endless shows the error directly in the upload area.

***

### 📋 Step 2 — Add or Review Columns

Columns define the structure and behavior of your Table.\
They determine what type of data each record will hold and how the Agent will interpret it.

#### ➕ To add a column:

1. Open your Table.
2. Click **Add Column +**.
3. Configure the following fields:

| Field                      | Description                                                                                                                                                     |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                   | The column name. Each must be unique within the Table.                                                                                                          |
| **Description**            | Clearly describe what the column represents — the Agent uses this to interpret and interact with data correctly.                                                |
| **Type**                   | Choose one of the supported field types (`string`, `boolean`, `number`, or `file`).                                                                             |
| **Enable Semantic Search** | When enabled, allows the Agent to query this column based on meaning and context, not just exact text matches. Recommended for descriptive or free-text fields. |

Click **Add Column** to save.

> 🧠 **Tip:** Write clear and specific descriptions — the Agent reads them to infer intent and understand how to use the data.

If you imported the Table from `XLSX`, review each imported column before using it in production.

***

### 🔧 Supported Column Types

Zaia Endless currently supports four data types for Table columns:

| Type        | Description                                                                          | Example                                                       |
| ----------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| **string**  | Textual information, such as names, messages, or identifiers.                        | `"John Doe"`, `"user_123"`, `"Asked about campaign creation"` |
| **boolean** | Logical values representing `true` or `false`. Ideal for flags or conditional logic. | `true`, `false`                                               |
| **number**  | Numeric data, such as counters, scores, or ratings.                                  | `42`, `3.14`                                                  |
| **file**    | Uploaded files stored in the Table. Supports `PNG` and `PDF` files up to `10 MB`.    | `contract.pdf`, `receipt.png`                                 |

> ⚙️ **Best practice:**\
> Use `string` for most descriptive text fields, and enable **semantic search** for fields where Agents need to interpret meaning — e.g. questions, feedbacks, or messages.

> 📎 **File column limit:**\
> File columns accept only `PNG` and `PDF` uploads, with a maximum size of `10 MB` per file.

***

### 🧱 Step 3 — Add and Edit Rows

Rows represent the actual data stored inside the Table.\
You can manually add rows or have them created dynamically by Agents or Workflows.

#### ➕ To add a row:

* Click **Add row +** and fill in each column’s value.

#### ✏️ To edit a row:

* Hover over a record, click the **⋮ (Edit)** icon, and modify as needed.

Example — Table **Unanswered Questions**:

| chatId                                 | Name | Question                                                     |
| -------------------------------------- | ---- | ------------------------------------------------------------ |
| `5edca67d-dd2d-41e4-b7c0-23e4858f05e6` | —    | “User asked if it’s possible to create proactive campaigns…” |

***

### 📤 Export a Table to XLSX

You can export a Table in two places:

* From **Builder → Tables**.
* From inside the Table itself.

When you export, Zaia Endless processes the file and sends it by email.\
It does not start an immediate download in the browser.

The interface shows whether the export request succeeded or failed.

***

### 🧩 Step 4 — Update or Delete Tables

You can modify a Table’s metadata at any time:

* Click the **✏️ Edit** button to update the name or description.
* Click the **⋮ menu** to rearrange or delete a Table.

> ⚠️ **Warning:**\
> Deleting a Table permanently removes all its data — this action cannot be undone.


# Semantic Search

Semantic Search enhances the way Agents interact with Tables by allowing **contextual** and **meaning-based** queries.\
When this option is enabled on a column, the system uses vector embeddings to interpret user input.

#### Example:

If a user asks:

> “Show all users who asked about campaigns”

An Agent can retrieve rows from a “Questions” column even if none explicitly mention “campaigns”, as long as the semantic meaning aligns (e.g., “marketing flows”, “mass messages”).

***

### 🧩 When to Enable Semantic Search

✅ **Recommended for:**

* Descriptive or natural language fields (`string`)
  * Examples: *Question*, *Feedback*, *Message*, *Description*

❌ **Avoid enabling for:**

* Short categorical or structured fields
  * Examples: *ID*, *Status*, *Type*, *Boolean flags*


# Integrating Tables with Agents

Zaia Endless allows Agents to interact with **Tables** (also known internally as *Datagrids*) through specialized **Tools** that provide permission-based access to perform specific operations — such as inserting, updating, or retrieving data.

These Tools act as **capability enablers**: each one grants a distinct level of interaction between the Agent and the Table.\
Without an appropriate Datagrid Tool assigned, an Agent cannot read or write data to that Table.

***

### 🧠 How Integration Works

Each Table can be linked to one or multiple Agents.\
However, instead of a direct connection, integration is managed through **Datagrid Tools** — each representing a precise permission scope.

When a Datagrid Tool is attached to an Agent, it defines *what kind of actions that Agent can perform* on the target Table.

> ⚙️ **Note:**\
> Workflows currently **cannot** interact directly with Tables.\
> Only Agents can perform these operations, and if needed, they can **pass the retrieved data to a Workflow** through a Request Node.

***

### 🧩 Available Datagrid Tools

Below is a list of the available **Datagrid interaction Tools** and their purposes:

#### 1. 🟣 Datagrid Row Insertion

**Function:**\
Allows the Agent to insert a new row into a specific Table based on structured or contextual information gathered during a conversation.

**Typical use cases:**

* Logging user inquiries or form submissions.
* Saving contact data, tickets, or feedback.

**Example:**

> “Store this user’s question in the *Unanswered Questions* table.”

***

#### 2. 🟣 Datagrid Row Update

**Function:**\
Allows the Agent to modify existing rows in a Table by matching a unique identifier or condition.

**Typical use cases:**

* Updating the status of a contact or request.
* Changing the sentiment field in a feedback record.

**Example:**

> “Update the *status* field of chat `5edca67d-dd2d...` to `resolved`.”

***

#### 3. 🟣 Datagrid Row Semantic Search

**Function:**\
Grants the Agent permission to **search Table rows using semantic understanding** — meaning queries are based on contextual similarity, not only keywords.

**Typical use cases:**

* Retrieving questions similar to a current user inquiry.
* Searching for feedback containing specific intent or emotion.

**Example:**

> “Find all feedbacks that mention onboarding issues.”

***

#### 4. 🟣 Datagrid Row Similarity Search

**Function:**\
Allows the Agent to perform **similarity-based vector searches** among Table rows, often used for advanced matching or clustering operations.

**Typical use cases:**

* Identifying duplicate records or repeated questions.
* Finding content with semantic similarity to a new input.

**Example:**

> “Search for entries similar to this user’s message.”

***

### 🔐 Permission-Based Architecture

Each Datagrid Tool represents a **permission level** within the Agent’s operational scope:

| Tool                               | Permission Level     | Read / Write | Semantic Access |
| ---------------------------------- | -------------------- | ------------ | --------------- |
| **Datagrid Row Insertion**         | Create               | ✅ Write      | ❌               |
| **Datagrid Row Update**            | Modify               | ✅ Write      | ❌               |
| **Datagrid Row Semantic Search**   | Query (contextual)   | ✅ Read       | ✅               |
| **Datagrid Row Similarity Search** | Query (vector-based) | ✅ Read       | ✅               |

> ⚙️ Assigning a tool effectively grants that Agent the associated Table capability.\
> Without it, the Agent cannot perform those actions, even if it references the Table in conversation.

***

### 🔗 Connecting a Table to an Agent

To link a Table to an Agent, follow these steps:

1. Open the **Agent Builder**.
2. Go to the **Tools** tab.
3. Click **Add Tool +** and select one of the **Datagrid Row Tools**.
4. Configure:
   * The **target Table** you want the Agent to access.
   * Any specific parameters or permissions.

Once added, the Agent can interact with the Table within the defined tool boundaries.

***

### 🔁 Example — Using Multiple Tools

An Agent may require more than one Datagrid Tool to fully manage a Table.\
For example, a *Support Agent* may need:

* **Datagrid Row Insertion** → to record new issues.
* **Datagrid Row Update** → to mark them as resolved.
* **Datagrid Row Semantic Search** → to check if a similar issue already exists.

Each of these tools would be individually added to the Agent to grant the corresponding capabilities.

***

### 🧩 Data Flow Example (Agent + Workflow)

While Workflows cannot access Tables directly, Agents can serve as **data intermediaries**:

1. The Agent performs a **Semantic Search** in a Table.
2. It retrieves the result in context.
3. The Agent then sends this structured data forward through a **Request Node** (e.g., HTTP or Workflow call).
4. The Workflow processes the received data for automation or analytics purposes.

This architecture maintains **data integrity**, ensures **AI-controlled access**, and prevents unauthorized manipulation of Table data.

***

### ⚙️ Best Practices

| Recommendation                      | Description                                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| **Use precise column descriptions** | Helps the Agent understand each field’s purpose when inserting or updating data.        |
| **Assign only necessary Tools**     | Avoid giving Agents permissions they don’t need (e.g., write access when only reading). |
| **Combine Tools logically**         | Agents can use multiple Datagrid Tools for full CRUD-like control when needed.          |
| **Monitor output via logs**         | Review Agent logs to confirm correct table operations and semantic matches.             |
| **Avoid redundancy**                | Use Similarity Search only when precise vector comparison is required.                  |

#### Final Note

In Zaia Endless, Tables are not just passive data containers — they’re part of the **Agent’s extended cognitive framework**.\
By combining Tables with the right Datagrid Tools, your Agents gain the ability to **reason contextually, act autonomously, and persist knowledge** — safely, intelligently, and under precise permission control.


# Overview

#### Manage the main data of your workspace

The **Overview** section allows you to view and edit the key details of your current workspace in Zaia Endless.\
Your workspace is the central environment where all **Agents, Workflows, Tables, and Tools** are stored and managed.

Each user can belong to one or multiple workspaces — ideal for separating projects, environments, or client accounts.

***

### 🔹 Workspace Information

In this section, you can view or edit the following details:

| Field                 | Description                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Workspace Picture** | Optional image or logo representing the workspace. Click the **“+”** button to upload or update it.                           |
| **Workspace Name**    | The name that identifies this workspace in the Endless platform. Can be changed anytime.                                      |
| **Workspace ID**      | Unique identifier automatically generated by the system. Used for API references and support. You can copy it with one click. |

***

### 🔹 Workspace and Subscription Relationship

Every **plan and subscription** in Zaia Endless is directly linked to a **specific workspace**.\
That means:

* Each workspace has its **own billing cycle, credits, and usage limits**.
* If you create multiple workspaces (for example, one for each client or project), you’ll need a **separate subscription plan** for each one.
* Upgrading or changing a plan affects only the selected workspace — not all of your workspaces.

> 💡 **Example:**\
> If you manage two client environments, “Client A” and “Client B,” and both need Agents running simultaneously, each workspace must have its own plan (e.g., both on *Pro* or *Agency*).

This structure provides flexibility and isolation between different projects or clients — ensuring each workspace has its own resources, limits, and billing management.

***

### 🔹 Actions

| Action     | Description                                                                             |
| ---------- | --------------------------------------------------------------------------------------- |
| **Update** | Saves any changes to the workspace name or image.                                       |
| **Delete** | Permanently deletes the workspace and all associated data. This action is irreversible. |
| **Cancel** | Discards any unsaved changes.                                                           |

> ⚠️ **Important:**\
> Deleting a workspace will also delete all connected data — including Agents, Tables, Knowledge Bases, and Workflows.\
> Make sure to back up any essential data before proceeding.


# Providers

#### Connect and manage your AI model providers

The Providers section allows you to use your own LLM API tokens (like OpenAI, Anthropic, and Gemini) in Zaia Endless.

### 🔹 OpenAI

#### **Steps:**

1. Create or log in to your OpenAI account at the [OpenAI Platform](https://platform.openai.com/).
2. Navigate to the [creation key page](https://platform.openai.com/api-keys).
3. Click the `+ Create new secret key` button in the top-right corner
4. Give your key a descriptive name.
   1. Optional → Select a specific project to restrict the key.
5. Click `Create secret key`.
6. Copy your key, save it in a secure location, and add it as a Provider in Zaia.

{% hint style="info" %}
⚠️ **Important:**\
Copy the key immediately. This is the only time you will see the full secret key.
{% endhint %}

***

### 🔹 **Anthropic (Claude)**

#### **Steps:**

1. Create or log in to your account at the [Claude Platform](https://platform.claude.com).
2. Click the `+ Create key` button in the top-right corner.
3. Give your key a descriptive name.
   1. Optional → Select a specific workspace to restrict the key.
4. Click  `Add`.
5. Click `Copy Key` .
6. Copy your key, save it in a secure location, and add it as a Provider in Zaia.

{% hint style="info" %}
&#x20;⚠️ **Important:**\
Copy the key immediately. This is the only time you will see the full secret key.
{% endhint %}

***

### 🔹 **Google Gemini (Google AI Studio)**

#### **Steps:**

1. Create or log in to your Google account at [Google AI Studio](https://aistudio.google.com/app/)
2. Click on `Get API Key` in the bottom-left sidebar.
3. Click the `Create API key` button in the top-right corner.
4. Give your key a descriptive name.
   1. Optional → Select a specific project to restrict the key.
5. Click `Create API key`.
6. Copy your key, save it in a secure location, and add it as a Provider in Zaia.

{% hint style="info" %}
💡 Note:\
Google allows you to view your existing keys at any time in the AI Studio dashboard.
{% endhint %}

***

### **4. OpenRouter**

#### **Steps:**

1. Create or log in to your OpenRouter at [Open Router](https://openrouter.ai/)
2. Click `Get API Key` .
3. Click `Create` .
4. Give your key a descriptive name.
   1. Credit limit (optional): Configure a spending limit for this key.
   2. Reset limit every...: Configure how often the credits reset.
   3. Expiration: Set an automatic expiration date for the key.
5. Click `Create` .
6. Copy your key, save it in a secure location, and add it as a Provider in Zaia.

{% hint style="info" %}
&#x20;⚠️ **Important:**\
Copy the key immediately. This is the only time you will see the full secret key.
{% endhint %}

***

### How to configure your provider inside Zaia Endless

You can configure your provider key within Zaia Endless in two ways: via the **Workspace Settings** under the **Integrations** section or page or on **Agent Instructions Page**.

### Option 1: Through Main Workspace page

#### **Steps:**

1. Once logged in, click the workspace selector in the top-left corner.
   1. Click the **cog icon** (Settings) next to your workspace name.
2. In the `Integrations` section, click the `Providers` button.
3. Click the `+ Configure Provider` button.

### Option 2: Through an Agent page

#### **Steps:**

1. Once logged in, click `Builder` in the left-hand main menu.
2. Select an existing agent or click to create a new one.
3. Within the agent configuration, locate the Provider section.
4. Click `Configure Provider +` button.

### Configure the Provider

Regardless of the path you chose above, the final configuration steps are the same:

#### **Steps:**

1. **Name**: Give your provider a recognizable name.
2. **Description (Optional)**: Add a brief description if needed.
3. **Select Provider**: Choose your desired provider from the list.
4. **Provider Token**: Enter your specific provider API token/key.
5. Click in `create` to save your settings.


# Members

Manage your workspace members and roles

The **Members** section allows you to manage all users who have access to your workspace in Zaia Endless.\
From this page, you can invite new collaborators, assign roles, and control each member’s level of access and permissions.

Each **workspace** has its own independent list of members — adding someone to one workspace does not grant access to others.

> ⚠️ **Important:**\
> Each plan includes a limited number of members.\
> To check the exact number available in your plan, visit **Settings → Subscriptions** and review your active plan’s details.

***

### 🔹 Adding Members

To invite a new member to your workspace:

1. Click **Add Member** in the top-right corner.
2. Enter the person’s **email address**.
3. Click **Invite**.
4. The invited user will receive an email to join the workspace.

Once the invitation is accepted, the user’s status will change from **Pending** to **Active**.

| Status      | Description                                                                 |
| ----------- | --------------------------------------------------------------------------- |
| **Pending** | The invitation has been sent but not yet accepted.                          |
| **Active**  | The member has accepted the invitation and now has access to the workspace. |

***

### 🔹 Updating or Removing Members

You can modify an existing member’s role or remove them at any time.

* Click the **⋯ (three dots)** icon next to the user’s row.
* Choose **Edit permissions** or **Remove member**.
* Select a new role (Admin, Member, or Ops) if updating.
* Confirm your changes.

Changes take effect immediately and apply to all sections of the workspace.

***

### 🔹 Roles and Permissions

Each member is assigned a **role**, defining what actions they can perform inside the workspace.

| Role       | Access Level          | Description                                                                                                                                                                                             |
| ---------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin**  | 🔧 Full Access        | Has unrestricted control over the entire workspace. Can manage billing, Agents, Workflows, Tables, Knowledge Bases, human support settings, teams, and all configurations.                              |
| **Member** | ⚙️ Standard Access    | Can manage Agents, Workflows, Tables, Knowledge Bases, and team settings, but **cannot access billing or global workspace configurations**. Functionally equivalent to Admin within project operations. |
| **Ops**    | 💬 Operational Access | Designed for support or operational staff. Can only interact with human handoff conversations assigned to them. **Cannot modify Agents, Teams, or global workspace settings.**                          |

> 💡 **Tip:**\
> Use the **Ops** role for staff who only need access to the operational interface or human handoff management — not configuration or billing.
>
> Vibe Agent is visible to workspace users even when they are not the workspace owner. This does not expand the permissions granted by their role in other areas.

***

### 🔹 Removing Access

To remove a user:

1. Open the member’s menu (**⋯**).
2. Click **Remove member**.
3. Confirm the action.

The user will immediately lose access to all workspace resources.\
This does not affect other workspaces the user may belong to.

***

### 🔹 Best Practices

* Assign **Admin** only to trusted users responsible for workspace or billing management.
* Use **Member** for general collaborators, developers, or AI builders.
* Use **Ops** for agents or support roles focused on operational execution.
* Review member permissions periodically to ensure least-privilege access.
* Monitor your member usage in **Settings → Usage** to keep track of your workspace limits.


# Billing

Manage your workspace billing and payment methods

The Console **Billing** section centralizes financial and payment settings for your workspace.\
From the Console, you can define the payment responsible, manage your active billing method, and view historical statements.

> ⚠️ **Important:**\
> Billing is managed **per workspace** — each workspace has its **own subscription plan, billing cycle, and payment method**.\
> If you manage multiple workspaces, ensure that each one has an active payment configuration.

***

### 🔹 Overview

The Console displays key details about your workspace’s payment setup:

| Field                   | Description                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------ |
| **Payment Responsible** | The email of the user who owns or manages billing for this workspace.                |
| **Payment Method**      | The registered payment source (credit card or other method, depending on region).    |
| **Statement**           | Historical billing data, including transaction ID, date, amount, and payment status. |

If no payment method is registered, the Console shows an **Add** button.

***

### 🔹 Adding or Updating a Payment Method

To add or update your payment method:

1. Click **Add** or **Change Payment Method**.
2. A secure modal will open for you to fill in your credit card information.
3. Provide:
   * **Card Number**
   * **Expiration Date**
   * **Security Code (CVC)**
   * **Billing Country**
4. Click **Register** to confirm.

Zaia Endless uses a PCI-compliant payment gateway, ensuring all sensitive information is encrypted and stored securely.

> 💡 **Tip:**\
> You can update your card details at any time — this won’t interrupt your active plan or current billing cycle.

***

### 🔹 Payment Statements

The **Statement** section displays your billing history for transparency and control.

| Column           | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| **Statement ID** | Unique identifier for each billing cycle or transaction.          |
| **Billing Date** | The date on which the charge occurred or was scheduled.           |
| **Status**       | Indicates whether the payment was successful, pending, or failed. |
| **Amount**       | Total billed value for that period.                               |

If no payments have been made yet, you’ll see a *“No results”* message.

***

### 🔹 Workspace and Billing Relationship

Each workspace is billed **independently**, allowing organizations to isolate budgets and client accounts.\
For example:

* Your **main workspace** might use a corporate credit card.
* Your **client-specific workspace** could use a different payment source or plan.

Changing the billing method in one workspace does **not** affect others.

***

### 🔹 Subscribing and Upgrading

You can start a subscription or change the current plan from the signed-in Console.

1. Open the workspace you want to manage.
2. Go to **Settings → Billing**.
3. Choose the plan and billing cycle that match the workspace.
4. Review the price and payment details shown at checkout.
5. Confirm the payment to activate the plan or apply the upgrade.

Checkout validates payment information before completing the change. If the payment provider rejects a field or transaction, the Console shows a specific message.

> 💡 **Tip:** Plan changes apply only to the workspace selected at checkout.

***

### 🔹 Managing slots in the Console

When slot management is available, use the Console Billing stepper. Review each increase or decrease before confirming it.

For annual plans, the checkout displays the adjusted amount for the slot change before payment confirmation.

Some subscriptions created through an earlier Stripe checkout follow legacy slot rules. When this applies, a **?** icon appears next to the slot control. Hover over it to read the guidance for that subscription before changing the quantity.

***

### 🔹 Billing Activation for New Workspaces

A workspace can be created before payment. The Console provisions billing during its first checkout.

Subscriptions remain independent per workspace. Creating or linking another workspace does not move, replace, or combine its current billing information.

***

### 🔹 Best Practices

* Keep your payment method updated to avoid service interruptions.
* Assign billing management to an **Admin** user only.
* Download or record your Statement IDs for financial tracking.
* If you manage multiple workspaces, ensure each one has its own valid payment setup.
* Check your **Usage** section regularly to anticipate upcoming billing cycles.


# Usage

Monitor your workspace resource consumption and plan limits

The Usage section gives you a complete overview of how your workspace is consuming resources based on your active plan.

Here you can track execution volume across all three usage pillars, see the limits for Internal Test Usage and Vibe Agent Usage, and monitor the structural limits of your workspace.

***

#### 🔹 Overview

Each workspace in Zaia has its own usage dashboard, displaying two main types of information:

* **Renewable limits (monthly)** → tied to execution consumption. Reset automatically at the start of each billing cycle.
* **Permanent limits (plan-based)** → tied to the structure of your workspace. Fixed until you upgrade your plan.

The Usage page also shows the current consumption and available limit for **Internal Test Usage** and **Vibe Agent Usage** in the same dashboard.

***

#### 🔄 Renewable Usage (Resets Monthly)

These metrics renew automatically at the start of each new billing cycle.

Renewable usage tracks the three main pillars of your plan:

* **External Executions** — interactions your agents have with real users across active channels (WhatsApp, Instagram, Widget, etc.)
* **Internal Test Usage** — interactions made through the Internal Chat, your private testing environment inside the platform
* **Vibe Agent Usage** — interactions with Vibe Agent to create, configure, or diagnose agents through natural language

You can see both usage and limit for **Internal Test Usage** and **Vibe Agent Usage** directly on the Usage page.

When the monthly cycle resets, all three counters return to zero — allowing continuous operation.

⚠️ **Important:** If you reach your execution limit before the cycle resets, your agents will stop responding to users until the limit renews or your plan is upgraded.

***

#### 🏗️ Permanent Usage (Plan-Based Limits)

Some resources are structural — they are tied to your current plan and do not reset monthly.

These define how much your workspace can scale in data and organization:

* **Members** — team members with access to the workspace
* **Connections** — integrations with external services
* **Tables** and **Table rows** — structured data storage
* **Knowledge Bases** and **Knowledge Base characters** — content available to agents
* **Workflow concurrent executions** — parallel workflow runs
* **Rollback versions** — previous agent versions available for restore

These limits remain fixed until you upgrade your plan.

***

#### 🔍 Inspecting Execution Details per Agent

You can view how executions are consumed during conversations by inspecting an Agent's response.

To do this, open any ticket or conversation and click the credit counter in the top-right panel.

This will display:

* Total credits used in that response
* Execution time per step
* Tool calls and reasoning iterations with detailed logs

💡 **Tip:** This feature is especially useful for understanding which Agents consume more resources and optimizing prompt efficiency.

***

#### 🔌 Custom Providers

Custom Providers allow you to connect an Agent to your own LLM API key — such as OpenAI, Anthropic, Google Gemini, or others — instead of using Zaia's default model.

This affects **which model** the Agent uses, but does not impact execution limits or usage tracking in any way. All plan limits still apply normally.

***

#### ✅ Best Practices

* Check your Usage panel regularly to anticipate limit exhaustion before it affects live users
* Inspect Agent response logs to understand which Agents consume more resources
* Use Custom Providers for high-volume or specialized deployments
* Review your active plan under **Settings → Subscriptions** for upgrade options

***

⚠️ **Disclaimer:** This page explains how usage tracking works in Zaia. For current plan limits and details, always refer to the **Plans page inside the platform**.

***

#### ❓ Common Questions

**Q: Do renewable limits reset every month?** A: Yes. External executions, internal test usage, and Vibe Agent usage all reset at the start of each billing cycle.

**Q: Do permanent limits reset monthly?** A: No. Structural limits (Tables, Knowledge Bases, Members, etc.) are tied to your plan and remain fixed until you upgrade.

**Q: Can I continue using Agents after reaching my execution limit?** A: No. Once your execution limit is reached, agents stop responding until the limit resets at the next billing cycle or you upgrade your plan.

**Q: Are limits shared across workspaces?** A: No. Each workspace has its own independent usage tracking and limits.

**Q: Can I see which Agent uses more resources?** A: Yes — open the Inspect Response panel on any conversation to see a detailed breakdown per Agent action.

**Q: Where can I see my Internal Test Usage and Vibe Agent limits?** A: Open **Settings → Usage**. The page shows both current consumption and the available limit for each metric.

**Q: Does Vibe Agent usage count toward my external executions?** A: No. Vibe Agent usage is tracked separately as its own renewable metric.


# Egress IPs

This page documents the egress IP addresses reserved for Zaia.

Customers and partners that use IP allowlists should allow the egress IPs listed on this page.

### Concepts

#### Egress IP

Unline the ingress IP which is the IP that, for example, the api.endless.zaia.app domain points to, the **egress IP** is the public IP address used by a service when it sends outbound requests to external systems.

In this case, when Zaia connects to a customer API, partner service, private integration, firewall, or third-party platform, the external system may see the request coming from one of the egress IPs listed on this page.

***

#### IPv4 and IPv6

IP addresses can be represented in two main formats: **IPv4** and **IPv6**.

**IPv4** is the older and most widely supported format. It is commonly used by firewalls, security groups, allowlists, APIs, and network configurations.

Example:

> `209.71.78.101`

**IPv6** is a newer format created to support a much larger number of addresses. Some modern services and networks support IPv6, but not every external system accepts IPv6 allowlists.

Example:

> `2a09:8280:e615:1:0:92:2c77:0`

When configuring access to external systems, use the IP version supported by that system.

If the external system only supports IPv4, allowlist only the IPv4 addresses.

If the external system supports both IPv4 and IPv6, allowlist both versions when possible.

***

### Zaia Egress IPs

The following IP addresses are the current egress IPs reserved for Zaia.

<table><thead><tr><th width="88.96875">Region</th><th width="223.66015625">Location</th><th width="161.75390625">IPv4</th><th>IPv6</th></tr></thead><tbody><tr><td><code>gru</code></td><td>São Paulo, Brazil</td><td><code>209.71.78.101</code></td><td><code>2a09:8280:e615:1:0:92:2c77:0</code></td></tr><tr><td><code>iad</code></td><td>Ashburn, Virginia, United States</td><td><code>209.71.102.8</code></td><td><code>2a09:8280:e618:1:0:92:2c77:0</code></td></tr><tr><td><code>lax</code></td><td>Los Angeles, California, United States</td><td><code>209.71.84.42</code></td><td><code>2a09:8280:e621:1:0:92:2c77:0</code></td></tr><tr><td><code>fra</code></td><td>Frankfurt, Germany</td><td><code>209.71.75.217</code></td><td><code>2a09:8280:e612:1:0:92:2c77:0</code></td></tr><tr><td><code>syd</code></td><td>Sydney, Australia</td><td><code>209.71.97.254</code></td><td><code>2a09:8280:e634:1:0:92:2c77:0</code></td></tr></tbody></table>

{% hint style="info" %}
Requests may be routed through farther regions, so when registering the IPs above in the allow list, make sure to setup every region regardless of your service's closest region.
{% endhint %}


# Notifications

Configure workspace email alerts for operational events

Configure email alerts for important workspace events. Each notification type has its own activation and recipients.

Go to **Platform → Settings → Notifications** to manage these alerts.

***

### 🔹 Configure notifications

1. Turn on the event you want to monitor.
2. Select recipients when the event supports them.
3. Save your changes.

Settings apply to the current workspace only. When you enable an event without recipients, workspace owners are selected automatically where recipient selection is available.

Email addresses are normalized and deduplicated before delivery.

{% hint style="info" %}
**New message in human ticket** uses automatic recipients. You cannot select recipients for this event.
{% endhint %}

***

### 🔔 Available events

#### New message in human ticket

Sends an email when a user messages a chat with an open human ticket.

The channel owner receives the email. If the channel has no owner, the ticket assignee receives it instead.

Alerts are limited to one email per chat every five minutes.

#### Human ticket opened

Sends an email when a human ticket is created.

If the ticket has an assignee, that member receives the email. Otherwise, the event's configured recipients receive it.

#### Low credits

Sends an email when workspace consumption reaches 90% or more. It can also send after the limit is reached.

The email shows the consumed percentage. It does not show the remaining credit count.

Alerts are limited to one email per workspace every 24 hours.

#### Agent execution failure

Sends an email when an agent execution fails.

Choose the workspace members who receive these alerts. Failures are grouped for five minutes before delivery.

The email links to **Executions** for investigation.

#### Workflow execution failure

Sends an email when a workflow execution fails.

Choose the workspace members who receive these alerts. Failures are grouped for five minutes before delivery.

The email links to **Executions** for investigation.

{% hint style="warning" %}
Workflow node tests can currently trigger this alert. This also applies to non-production tests.
{% endhint %}

#### Channel disconnection

Sends an email when a connection disconnects. This includes authentication failures and similar connection errors.

Choose the workspace members who receive these alerts. The email includes the connection, provider, affected channels, and reason.

***

### 🔗 Email links and branding

Operational emails use a consistent layout and localized content. Each recipient receives the email in their selected language.

The email button opens the relevant platform area:

* Execution failures open **Executions**. A specific execution opens when available.
* Human ticket alerts open **Tickets**. The correct pending or ongoing ticket opens when available.
* Channel disconnections open **Channels**.
* Low-credit alerts open **Settings → Credits**.

Links preserve the workspace and version context. This ensures the destination opens in the right workspace.

For workspaces using White Label, emails use the active brand and custom domain. The link also opens on that domain when configured.

***

### 🔹 Delivery behavior

Disabled events never send emails. Events without valid recipients are skipped safely.

Recipient selection is available for all events except **New message in human ticket**. That event always follows its automatic routing rules.


# Welcome to the Zaia Endless Cookbook

This cookbook is a collection of **practical recipes** for building real agents on Zaia — so you don't have to figure everything out from scratch. Each recipe starts from a concrete problem and ends with an agent running on your client's channel.

No theory for theory's sake. Just what you need to build, configure, and ship.

***

#### How this cookbook works

**🎯 Problem-first**\
Every recipe starts from a real situation, not a feature name. Search for what you need to solve — not the name of a screen or setting.

**⚡ Straight to the point**\
Each recipe has the minimum context you need to understand the setup and get your agent live as quickly as possible.

**🔁 Built to evolve**\
Every recipe comes with variations and next steps. Where one recipe ends, the next one usually begins.

***

#### How to navigate

Use the sidebar to browse recipes organized by vertical and complexity level.

* **Just getting started?** Look for recipes tagged as `beginner`.
* **Already have agents running?** Jump straight to the **Squads** and **Integrations** sections.
* **Stuck mid-recipe?** Each recipe includes a troubleshooting section and a validation checklist before you move on.

***

> *"A great agent isn't the one with the most features. It's the one that solves the right problem, in the right way, for the right person."*\
> — Zaia Endless Team


# How to diagnose issues with your Official WhatsApp connection

It's important to show you how to easily identify when there is a problem with the Official WhatsApp connection with Zaia.

Whenever Zaia receives an authentication error or any other error from Meta that affects the connection, the platform **automatically disables it**.

When this happens:

* You will be notified with details about the issue.
* You will also be able to view this information directly on the connections screen within the platform.

For more details about WhatsApp Official connection and values, access: <https://docs.zaia.app/channels/channel-types/whatsapp-official>

{% embed url="<https://www.youtube.com/watch?v=mApSDqLeWcg>" %}

***

### 🔍 How to Check Connection Errors

1. Click on your **`workspace name`**
2. Go to the **`settings (gear icon)`**
3. In the left-side menu, select **`Connections`**
4. Locate the WhatsApp connection you created
   * Check the **current connection status.**
   * Hover over the warning message to see the error details.

Additionally, more detailed information **will also be sent to your email**.

***

### ⚙️ Checking Meta Settings

If the connection is not working as expected, it's important to also review the settings on Meta’s side.

#### Steps:

1. Go to: [**https://business.facebook.com**](https://business.facebook.com/)
2. Access your **Business Portfolio.**
3. Click on **`WhatsApp Accounts`**
4. Select your **WhatsApp Account.**

***

### 💳 Payment Configuration

One of the main things to verify is your payment setup.

#### How to check:

1. Click on **`Payment Settings`**
2. You will be redirected to the **Billing & Payments** page

#### What to verify:

* If no payment method is registered:
  * Select your currency
  * Fill in your details
  * Click **`Save`**
* If a payment method already exists:
  * Make sure it is:
    * Valid
    * Up to date
    * Not declined

***

### 💰 Pricing Overview

Meta charges based on conversation type.

* Each account gets **1,000 free service conversations per month.**
* In some cases (e.g., "Click to WhatsApp" ads), the free window can extend up to **72 hours**

> ⚠️ These values may change. Always refer to Meta’s official documentation for updated pricing.

***

### 🏷️ WhatsApp Display Name

Another common issue is the rejection of the display name.

#### How to check:

1. Open the **WhatsApp Manager.**
2. Select the **connected number.**
3. Go to the **Profile** tab.

#### Best practices:

The display name should:

* Align with your business or brand.
* Not be too generic
* Follow Meta’s naming guidelines

> ❌ Meta may reject names that don’t match the business or violate their policies.

***

### 🏢 Business Verification

This is a **critical step** that can impact your account functionality.

#### How to check:

1. Go to your **Business Portfolio settings**.
2. Click on **`Business Information`**
3. Check the verification status

> ⚠️ Even if the connection works initially, Meta may require verification later.

***

### 🔐 Starting the Verification Process

1. Click on **`View Details`**
2. You will be redirected to **Meta’s Security Center**.

There, you may see:

* Risks
* Alerts
* Pending issues (e.g., trusted domain)

> Follow the instructions provided by Meta on this screen.

***

### 📝 Verification Steps

1. Scroll to the **Business Verification** section
2. Click on **`Start Verification`**

You may need to:

* Confirm business details.
* Validate contact information.
* Submit documents.

#### Required information:

* Country.
* Business type.
* Legal name.
* Tax ID (e.g., CNPJ).
* Address.

***

### ⏳ Final Steps

* You can pause and continue the process later.
* After submission, **wait** for Meta’s review.

If there are any issues:

* Meta will indicate what needs to be corrected.


# How to disconnect your WhatsApp Business account from another integration or automation

## How to Disconnect a WhatsApp Account from Another Platform or Portfolio

In this guide, you will learn how to disconnect or unlink a WhatsApp account that is currently connected to another portfolio or platform, in order to avoid conflicts when creating a new connection.

This situation can happen, for example, when:

* The number was previously connected to another company
* It was used in another tool or platform
* It was connected through a previous Zaia integration

Currently, there are two main ways to unlink an account. The correct method depends on how the account was previously connected.

{% embed url="<https://www.youtube.com/watch?v=5kSRvj9b7k4>" %}

***

### 🔗 Method 1: Disconnect via Coexistence Mode

This method applies when the number is:

* Still linked to the **WhatsApp Business app on your phone**
* And also connected to a platform

#### Steps:

1. Open the **WhatsApp Business app**
2. Go to **Settings**
3. Tap on **Account**
4. Select **WhatsApp Business Platform**

On this screen, you will see the platform currently connected.

This could be:

* Another company
* Another tool
* A previous connection you want to remove

#### To disconnect:

1. Tap on the connected platform
2. Select **Disconnect**
3. Confirm the action

✅ Done! Your account is now unlinked from the previous connection.

***

### ⏳ Important Waiting Time

After disconnecting:

* Wait at least **1–2 minutes** before creating a new connection

This allows Meta to:

* Recognize the disconnection
* Properly release the number for reuse

***

### ⚙️ Method 2: Disconnect via Meta Business Manager

Use this method if:

* The previous connection was **not made via coexistence**, or
* You want to ensure **no remaining links exist** in your Meta portfolio

***

#### Steps:

1. Go to: **<https://business.facebook.com>**
2. Access the portfolio used in the previous connection
3. Go to **Settings**
4. Click on **WhatsApp Accounts**
5. Select your WhatsApp account

> If this is the only account, it may already be opened automatically.

***

### 🤝 Removing Partner Access

1. Navigate to the **Partners** tab
2. You will see platforms or companies that previously had access to your WhatsApp account

This may include:

* Other platforms you used before
* Integrations linked to this number

***

#### To remove access:

1. Click **Manage**
2. Remove the access of the platform/company
3. Confirm by clicking **Remove Portfolio**

> ⚠️ Meta may display a warning that message sending could be temporarily unavailable after removal.

If needed, click **Learn More** to understand this message.

***

### ⏳ Final Waiting Time

After removing access:

* Wait at least **1–2 minutes** before creating a new connection

This ensures Meta:

* Processes the change
* Releases the number correctly

***

### ✅ You're Ready

After completing these steps:

* Your WhatsApp account will be fully disconnected
* You can safely create a new connection

Now, simply return to **Zaia** and continue the setup process as usual.


# How to Fix Follow-ups Not Triggering

Follow-ups are powerful for re-engagement, but they fail silently when **Conversation Stage** or **Scheduling Prompt** are misconfigured. This guide shows exactly what goes wrong and how to fix it.

> 💡 **Tip:** While creating or editing Follow-ups, you can use the **AI Assistant** available in the tool modal to get contextual help. If you're unsure about how to structure your Conversation Stage or Scheduling Prompt, click the AI button for instant guidance.

***

### 🧠 How Follow-ups Actually Work

**Critical concept:** The Agent evaluates follow-up conditions **at the moment it sends a message** — not in the future.

* The Agent **cannot predict** if the user will reply
* It **evaluates the present state**: Is information missing? Is the conversation open?
* If the condition matches → it schedules the follow-up message

**This is why future assumptions break follow-ups:**

❌ **Wrong:** "If the user doesn't reply..." (Agent can't know this yet) ✅ **Right:** "The user asked about pricing but didn't confirm the plan" (present state)

***

### 🔧 Troubleshooting: Why Follow-ups Don't Trigger

#### 1️⃣ Conversation Stage Uses Future Assumptions

**Problem:** You write conditions about what *might* happen, not what *is* happening.

| ❌ Wrong                               | ✅ Correct                                                 |
| ------------------------------------- | --------------------------------------------------------- |
| "If the user doesn't reply in 10 min" | "User asked for proposal but hasn't shared details"       |
| "If they need more time"              | "User showed interest but paused the conversation"        |
| "If they don't choose"                | "User requested info but stopped before selecting option" |

**Fix:** Describe the **current conversation state**, not future outcomes.

***

#### 2️⃣ Scheduling Prompt Is Too Vague

**Problem:** No specific time or unclear action.

| ❌ Wrong           | ✅ Correct                                              |
| ----------------- | ------------------------------------------------------ |
| "Follow up later" | "After 30 minutes, ask if they need help choosing"     |
| "Send a reminder" | "In 1 hour, remind them support is available"          |
| "Check in"        | "After 10 minutes, ask if I can send the full catalog" |

**Fix:** Always include **time + specific action**.

***

#### 3️⃣ Ignoring WhatsApp/Instagram 24-Hour Window

**Problem:** Follow-up scheduled beyond 24 hours from user's last message.

**Solution:** On WhatsApp/Instagram, follow-ups must be within 24 hours. After that, the message won't deliver (Meta's policy).

***

#### 4️⃣ Follow-up Canceled by User Response

**Problem:** User replies before the scheduled time → all pending follow-ups auto-cancel.

**This is expected behavior.** If the user re-engages, the Agent may schedule new follow-ups based on updated context.

***

### 📋 Before/After Examples

#### Example 1: Car Sales Agent

| Aspect                 | ❌ Before                      | ✅ After                                                       |
| ---------------------- | ----------------------------- | ------------------------------------------------------------- |
| **Conversation Stage** | "If customer doesn't respond" | "Customer asked about models but hasn't specified preference" |
| **Scheduling Prompt**  | "Send follow-up"              | "After 15 minutes, ask which model interests them most"       |
| **Result**             | Never triggers                | Triggers when condition matches                               |

#### Example 2: Pricing Inquiry

| Aspect                 | ❌ Before                 | ✅ After                                                    |
| ---------------------- | ------------------------ | ---------------------------------------------------------- |
| **Conversation Stage** | "If they need more info" | "User requested pricing but didn't confirm plan selection" |
| **Scheduling Prompt**  | "Follow up later today"  | "In 2 hours, check if they're ready to choose a plan"      |
| **Result**             | Vague, unreliable        | Clear, predictable                                         |

***

### ✅ Validation Checklist

Before activating follow-ups, verify:

* [ ] **Conversation Stage** describes present state (not "if user doesn't...")
* [ ] **Scheduling Prompt** includes specific time (10 min, 1 hour, etc.)
* [ ] **Scheduling Prompt** includes specific action (ask, remind, check)
* [ ] On WhatsApp/Instagram: follow-up is within 24 hours of user's last message
* [ ] You tested in Internal Chat and saw the follow-up schedule correctly
* [ ] You understand that user replies before scheduled time = auto-cancel

***

### 🚀 Next Steps

* Review your existing follow-ups against this checklist
* Edit Conversation Stages to describe present context
* Update Scheduling Prompts with specific times and actions
* Test in Internal Chat before deploying to production




---

[Next Page](/llms-full.txt/1)