# Omago documentation

Source: https://www.omago.ai/docs — machine-readable copy for AI assistants and agents.
Learn how to set up and run your Omago AI customer-service agent — create an agent, add your knowledge base, connect channels, build flows, and manage billing.

Omago is a 24/7 AI customer-service agent for small businesses. It answers enquiries on your website, WhatsApp, and Telegram, captures leads, and books appointments — so you never miss a customer. This guide is organized by what you are trying to do, not by where things sit in the menu.

### Conventions

- **Bold names** are labels you will see in the Omago dashboard.
- Screenshots are taken from the English dashboard; the app itself also runs in your language.
- Stuck? Use the **Ask** bar at the bottom of any page — it is Omago answering questions about Omago.

## Contents
- [Getting started](https://www.omago.ai/docs/getting-started)
- [Building your agent](https://www.omago.ai/docs/building-your-agent)
- [Knowledge base](https://www.omago.ai/docs/knowledge-base)
- [Channels & deploy](https://www.omago.ai/docs/channels)
- [Flows & automations](https://www.omago.ai/docs/flows)
- [Billing & team](https://www.omago.ai/docs/billing)

## Getting started

https://www.omago.ai/docs/getting-started — Create your first Omago agent, test it, and go live in minutes.

Omago is an AI agent that answers customer questions on your website, WhatsApp, and Telegram around the clock, using your own business content as its knowledge base. This guide walks you through creating your first agent, testing it, and publishing it live.

### Create your first agent

1. Click **Agents** in the left sidebar.
2. Click **Create**.
3. **Step 1 — Basics:** name your agent, optionally pick a prompt template, and attach or create a knowledge base.
4. **Step 2 — Select Pages** (only shown if you added a website URL): choose which crawled pages to use.
5. **Step 3 — Configure & Create:** write the system prompt, set the widget color and theme, and add a welcome message, then click **Create**.

You don't need a knowledge base to finish this wizard — if the attachment fails or you skip it, the agent is still created, and you can attach knowledge bases later from the Playground.

After you click Create, you land on the agent's Playground.

### Add your business basics

Give the agent something to answer from before you test it.

1. From the agent, go to **Playground**.
2. Enable **Knowledge Bases** and click **Add KB** to attach one, or create a new knowledge base first (**Knowledge Base** in the sidebar → **Create Knowledge Base**) by crawling your website or uploading text, Q&A, or files (.txt/.pdf/.docx/.csv/.xlsx/.json).
3. Set a **priority** for each attached knowledge base (0–10, higher is searched first), and a **weight** if you attach more than one.

Knowledge base changes apply immediately to live chat — they are not held as a draft the way prompt edits are.

### Test before going live

1. Open the agent's **Playground**.
2. Type into the **sandbox chat** on the right. This sandbox is not saved to your logs, so you can experiment freely.
3. Adjust the **System Prompt** on the left — this defines your agent's personality, tone, and behavior — and re-test in the sandbox.
4. Optionally set the **Response Language** (default `auto`, or force English, Traditional Chinese, Simplified Chinese, Japanese, or Korean).
5. Turn on **Show Sources** if you want the agent to cite the knowledge base passages it used.

![Playground with system prompt editor and sandbox chat](https://www.omago.ai/docs/playground.webp)

System prompt and response language edits are drafts until you publish them — the sandbox always reflects your latest draft, but real users keep getting the last published version until you publish.

6. When you're happy with the results, click **Publish** in the draft status bar to make the changes live. Click **Discard** instead if you want to revert to the last published version.

### Go live

Publishing your prompt makes it active, but customers still can't reach the agent until you deploy it.

1. Open the agent's **Channels** tab.
2. Turn on the **Public** toggle. The agent must be public before you can generate widget URLs or embed it anywhere.

![Channels tab with Public toggle and Web deployment options](https://www.omago.ai/docs/deploy.webp)

3. Under **Web**, choose how you want to deploy:
   - **Floating bubble** or **Ask bar**: click **Copy** to get your snippet, then paste it into your website's HTML for a chat widget.
   - **Embed / Direct Link**: copy the iframe code, or use the direct link for a full-page chat.
4. Optionally connect messaging channels under **Messaging** (availability may depend on your plan — check the Messaging section or **Settings → Billing → Plan**):
   - **WhatsApp**: click **Connect** and complete the Facebook Embedded Signup flow.
   - **Telegram**: click **Connect** and paste your bot token.

Conversations from every connected channel appear in the agent's **Logs** tab.

### Next steps

- Style the widget's color, icon, and welcome message in the **Widget** tab.
- Build an automation to capture leads or book appointments in **Automations**.
- Invite teammates from **Settings → Members**.

## Building your agent

https://www.omago.ai/docs/building-your-agent — Shape your agent's instructions, personality, language, and model — and review its conversations.

Your agent's behavior is controlled from the **Playground** — the config rail on the left holds the system prompt, response language, and knowledge base settings, next to a live chat sandbox on the right where you test changes before they go live. This page covers instructions and personality, response language, model selection, and reviewing past conversations.

### Open the Playground

1. In the left sidebar, open the **Agents** group and pick your agent from the switcher.
2. Select the **Playground** tab (route `/agents/<agentId>/playground`).

![Playground with system prompt editor and sandbox chat](https://www.omago.ai/docs/playground.webp)

### Change your agent's instructions and personality

The **System Prompt** defines your agent's personality, tone, and behavior guidelines.

1. In the Playground, find the **System Prompt** textarea.
2. Write or edit your instructions. Use the expand control for a larger writing surface, or open **Template Reference** for example prompts.
3. Test your changes in the sandbox chat on the right — it always reflects your current draft, not what's published.
4. When you're satisfied, click **Publish** in the draft status bar to make the changes live. Click **Discard** instead to revert to the last published version.

Prompt edits are **draft-buffered**: typing saves automatically as you go, but nothing reaches real users until you click Publish. The header shows an "All changes published" indicator once there's nothing pending.

### Set your agent's response language

By default, your agent auto-detects the language to reply in based on context.

1. In the Playground config rail, find the **Response Language** combobox.
2. Choose a language to force it, or leave it on **auto** (default).
3. Click **Publish** to apply the change.

Available options: `auto` (auto-detect), English (`en`), Traditional Chinese (`zh-Hant`), Simplified Chinese (`zh-Hans`), Japanese (`ja`), Korean (`ko`).

Like the system prompt, this setting is draft-buffered — it only affects live conversations after you publish.

### Choose your agent's AI model

Model selection isn't configured per agent — the underlying AI model is managed for you, and the specific model available may vary by your workspace's plan tier.

To see what's included on your plan, check **Settings → Billing**. Response randomness (temperature) and maximum reply length (max tokens) are also set at the plan-tier level and aren't editable per agent.

### Review your agent's conversations

The **Logs** tab is your agent's conversation history — every real conversation it has had, searchable and readable in full.

1. Open the agent → **Logs** tab (route `/agents/<agentId>/logs`).
2. Browse or search the conversation list on the left (by visitor name or email). The list shows 20 conversations per page.
3. Select a conversation to read its full transcript in the center panel. Use **Copy transcript** to copy it as plain text.
4. Check the visitor info panel on the right for identity (name, email, phone), channel (widget, WhatsApp, Messenger, Instagram, Telegram), linked lead status, and related conversations from the same visitor.

#### Correct a wrong answer

If your agent gives a bad answer, you can fix it directly from the transcript.

1. Open the conversation in **Logs**.
2. Click the edit control on the assistant's message.
3. Enter the corrected answer in the dialog that opens and submit.

The correction is stored and feeds back into the agent's knowledge as a corrections source, so future answers on that topic improve.

Sandbox chats in the Playground are never logged here — only real conversations from deployed channels appear in Logs.

## Knowledge base

https://www.omago.ai/docs/knowledge-base — Feed your agent your business knowledge — website, text, Q&A, and files — and keep it current.

A knowledge base (KB) is where your agent's business knowledge lives. You add sources — a crawled website, pasted text, Q&A pairs, or uploaded files — and Omago chunks and indexes them so your agent can retrieve the right passage when it answers a question. A knowledge base is shared at the workspace level: one KB can power several agents, and one agent can draw on several KBs.

### Create a knowledge base

1. Click **Knowledge Base** in the left sidebar.
2. Click **Create Knowledge Base**.
3. Name it, add an optional description and tags, then save.

![A knowledge base showing a crawled website source, with Add content and Testing](https://www.omago.ai/docs/knowledge-base.webp)

A new knowledge base is an empty container. It doesn't do anything until you add content.

### Add your website (web crawl)

1. Open your knowledge base and click **Add content → Start web crawl**.
2. Enter your website's URL.
3. Set the crawl depth (1–3).
4. Run the crawl.

The crawl runs in the background: it discovers and fetches your pages, then embeds them. The source's status moves from **Processing** to **Ready** — wait for **Ready** before expecting the agent to use it.

### Add text, Q&A, or a file

Besides crawling a website, you can add content directly:

1. Open your knowledge base and click **Add content**.
2. Choose one of:
   - **Add text** — paste plain text; it's ready instantly.
   - **Add Q&A** — enter question/answer pairs; ready instantly.
   - **Upload file** — upload a `.txt`, `.pdf`, `.docx`, `.csv`, `.xlsx`, or `.json` file; this processes in the background, so it takes a moment to reach **Ready**.

Each source in the **Documents** tab shows its type, status (Ready / Processing / Failed), and how many chunks and vectors it produced.

### Connect a knowledge base to your agent

Adding content to a knowledge base doesn't automatically make an agent use it — you need to attach the KB to the agent.

1. Open your agent and go to **Playground**.
2. Turn on **Knowledge Bases**.
3. Click **Add KB** and select the knowledge base.
4. Set its **priority** (higher priority is searched first) — and, if you've attached more than one KB, set the **weight** to control how much each one contributes.

Unlike most Playground settings, knowledge base attachments apply immediately to live chat — you don't need to publish a draft for this change to take effect.

You can also turn on **Show Sources** so the agent displays inline citations and a source list when it uses knowledge base results.

### Check the knowledge base is working

1. Open your knowledge base and go to the **Testing** tab.
2. Type a question a customer might ask.
3. Confirm it returns the passages you'd expect the agent to use.

If the right passages don't come back, check that the source has finished processing (status **Ready**, with chunks and vectors populated) and that it actually covers the topic you asked about.

### Update your knowledge base after your site changes

You don't need to delete and re-add a website source when your site's content changes.

1. Open your knowledge base and go to the **Documents** tab.
2. Find the web source and click **Re-crawl source**.

Re-crawling is rate-limited — if you try again too soon, the dashboard shows a countdown before you can re-crawl again.

### Limits

Knowledge base content counts against your plan's storage cap, summed across every knowledge base in your workspace. For example, Plus includes 100 MB of training data and Max includes 500 MB. Check your current storage limit and usage on **Settings → Billing → Plan**.

### Troubleshooting

- **A source is stuck on Processing.** Crawling and embedding run asynchronously — large sites take longer. If it doesn't resolve, check for failed URLs and try re-crawling.
- **The agent isn't using your knowledge.** Confirm the KB is attached to the agent in **Playground** with **Knowledge Bases** turned on, and that the source status is **Ready**.
- **The agent gives outdated answers after a site change.** Re-crawl the source from the **Documents** tab — updates aren't picked up automatically.

## Channels & deploy

https://www.omago.ai/docs/channels — Put your agent on your website, WhatsApp, and Telegram — and brand it to match.

The **Channels** tab (labeled **Deploy**) is where you make an agent live and connect it to the places customers actually reach you: your website, WhatsApp, and Telegram. A single **Public** toggle gates everything — your agent must be public before you can generate a widget URL or embed it anywhere.

### Make your agent public

1. Open the agent → **Channels**.
2. Turn on the **Public** toggle at the top of the page.

![Channels tab with the Public toggle and Web deployment cards](https://www.omago.ai/docs/deploy.webp)

If you try to copy a widget URL while the agent is still private, you'll get an error telling you to make it public first.

### Add the chat widget to your website

The chat widget is a floating chat window that sits in the corner of your site. It's included on every plan, including the free Starter plan.

1. Open the agent → **Channels**, and make sure **Public** is on.
2. Under **Web → Chat Widget**, click **Setup**.
3. Click **Copy** to get your snippet.
4. Paste it into your website's HTML, ideally just before the closing `</body>` tag.

Style and brand the widget — colors, icon, welcome message, suggested questions — in the **Widget** tab (see [Style your widget](#style-your-widget) below).

### Embed the chat as an iframe or full page

If you'd rather embed the chat inside a page you control, or link straight to it, use Embed / Direct Link instead of the floating widget.

1. Open the agent → **Channels**, and make sure **Public** is on.
2. Under **Web → Embed / Direct Link**, click **Setup**.
3. Click **Copy** on the **Embed / Direct Link** card to get the iframe code, or grab the direct URL to link straight to a full-page chat.

### Connect WhatsApp

WhatsApp availability may depend on your plan — open **Channels → Messaging** to see whether it's available on your current plan, or check **Settings → Billing → Plan**.

1. Open the agent → **Channels** → **Messaging**.
2. Next to **WhatsApp**, click **Connect**.
3. Complete the Facebook **Embedded Signup** flow.

Once connected, Omago stores your WhatsApp business phone number, display name, and connection status, and the channel badge switches to **Connected**.

### Connect Telegram

Telegram availability may also depend on your plan — check the **Messaging** section or **Settings → Billing → Plan** if you don't see it.

1. Open the agent → **Channels** → **Messaging**.
2. Next to **Telegram**, click **Connect**.
3. Paste your **bot token**. Omago validates it and shows an error in a toast if it's invalid.

Once connected, the channel badge switches to **Connected** and you can manage the bot from the same card.

### Messenger and Instagram

Messenger and Instagram are **not available yet**. Both show as **"Coming soon"** in the Messaging section and their Connect buttons are disabled. Today you can deploy through **Web** (widget and embed/direct link), **WhatsApp**, and **Telegram** only — don't tell customers Messenger or Instagram support is live.

### Style your widget

Branding lives in the **Widget** tab, separate from Channels (which only handles deployment).

1. Open the agent → **Widget**.
2. Set the **Primary Color** and **Color Scheme** (Light or Dark) to match your site.
3. Upload an **Icon** (PNG, JPEG, GIF, WebP, or SVG, up to 5 MB) — this is reused as both the welcome icon and the agent's avatar.
4. Write a welcome **Title** and **Description**.
5. Add up to **6 Suggested Questions** (100 characters each) for customers to tap, and drag to reorder them.

Changes preview live next to the settings panel as you edit.

### Remove the "Powered by Omago" badge

By default, the widget shows a "Powered by Omago" badge. Hiding it requires the **Remove Branding** add-on (included free on Enterprise) — see current pricing on **Settings → Billing → Add-ons**.

1. Buy the add-on: **Settings → Billing → Add-ons**.
2. Open the agent → **Widget**.
3. Turn off the **Show "Powered by"** toggle.

Without the add-on, this toggle is visible but locked on, with an "Unlock" link back to the Add-ons page.

## Flows & automations

https://www.omago.ai/docs/flows — Automate what happens in a conversation — triggers, steps, hand-off to a human, and in-chat booking or payment.

A flow is a visual, deterministic script that runs on top of your agent's AI — for lead capture, qualification, support hand-offs, bookings, payments, and integrations. Flows remember answers across turns, pause and resume around off-topic messages, and run alongside your agent's normal AI replies.

### Where to build a flow

1. Open the agent → **Automations**.
2. The Automations list shows your flows for this agent. Click one to open its editor, or create a new flow.
3. In the editor, drag nodes from the palette and connect them to build your logic.

![Flow editor with connected nodes](https://www.omago.ai/docs/flows.webp)

### How a flow starts

Every flow begins with a **Start** node that defines when it fires. When a message comes in, a router checks it against every active flow's Start trigger; if more than one flow could match, the one with the higher priority is checked first, and the first match wins.

Start triggers support four modes:

| Mode | Behavior |
|---|---|
| **Keyword** | Fires on a case-insensitive substring match against a list of keywords |
| **Regex** | Fires when the message matches one of your regex patterns |
| **AI decides** | An LLM scores the message against a prompt you write, and fires once it's confident enough that the message matches |
| **Always** | Fires on any message, as long as the flow is active |

### How a flow runs

Once a conversation enters a flow, the runtime walks through the connected nodes step by step, following the output of each node to the next one.

- **Questions pause the flow.** Nodes that ask the customer something (like Ask Question or Form) stop and wait for their reply before continuing.
- **Answers are remembered.** Whatever the customer provides is stored and can be reused later in the flow — for example, in a message or a webhook.
- **Customers can go off-topic.** If someone asks something unrelated mid-flow, the agent can still answer with normal AI chat; the flow itself is paused and the customer can pick it up again or start a different one.
- **Actions don't double-fire.** If a step runs an action (like sending a webhook or creating a lead), re-running that step won't repeat the action.

There's a cap on how many steps a flow can take in a single turn, so a flow can't loop forever on one message.

### Draft vs published — edits aren't live until you publish

Every flow has two versions:

- **Draft** — what you see and edit in the flow editor. The draft is never run for real customers.
- **Published** — the version that actually runs in live conversations.

When you click **Publish**, Omago checks that your flow is valid (it needs a Start node, valid node settings, and properly connected paths) and creates a new published version. If validation fails, publish is blocked and your draft stays editable so you can fix it.

**This is the most common flow issue: editing a flow and not seeing the change in live chat.** The router only ever tests the published version — after every edit, you need to publish again, even for small changes.

### Building blocks: nodes

Flows are built from nodes you connect on the canvas. Each node does one job and passes control to the next node through an output port. Common ones you'll use in most flows:

- **Start** — defines the trigger that opens the flow.
- **Send Message** — sends a message to the customer, which can include earlier answers.
- **Ask Question** / **Form** — collects information from the customer and pauses until they respond.
- **Save Contact** — creates or updates a lead from the information collected so far.
- **Handoff** — routes the customer to a human (see below).
- **Payment Link** / **Booking Link** — lets the customer pay or book without leaving the chat (see below).

There are more node types beyond this list, covering branching logic, AI-generated replies, support tickets, webhooks, and CRM sync — open the node palette in the flow editor to see the full set, grouped by category (Routing, Messaging, Input, Actions, Lead Management, Support).

### Handing a conversation off to a human

Add a **Handoff** node where you want the flow to route the customer to a person. It generates a WhatsApp deep-link or a link card the customer can click to reach a human directly.

This is not a live in-app takeover — nobody is silently listening in or can jump into the existing chat thread. It hands the customer a way to start a conversation with a person on WhatsApp or another link you configure.

Input nodes (Ask Question, Form) also route to their handoff path automatically if the customer doesn't answer after several attempts, so you should always design a handoff (or another way out) for anyone who gets stuck.

### Letting customers pay or book inside the chat

1. Connect the relevant integration first: **Stripe** for payments, or your booking provider (Calendly or Cal.com) for scheduling. Do this under **Settings → Integrations**.
2. In your flow, add a **Payment Link** node to generate a payment URL, or a **Booking Link** node to generate a scheduling link pre-filled with the customer's details.
3. **Publish** the flow — like any other change, this won't reach live chat until you do.

Both nodes hand the customer a link or card to complete the action; if the request fails (for example, the integration isn't connected), the flow can route down a separate error path instead of treating it as a success.

### Next steps

- Explore the full node palette in the flow editor to see every available node type.
- Connect Stripe, booking, and CRM providers in **Settings → Integrations**.
- Review captured leads in the **Leads** tab.

## Billing & team

https://www.omago.ai/docs/billing — Manage your plan, usage, and limits, and invite teammates with the right roles.

Your workspace's plan controls how many messages, agents, team members, and how much knowledge base storage you get. This page covers checking usage, changing plans, buying add-ons, inviting teammates, and managing workspace-level settings.

### Check your plan, usage, and limits

1. Click **Settings** in the left sidebar.
2. Open the **Billing** tab, then the **Plan** sub-tab.
3. Review your current plan name, status, billing cycle, and next billing date.
4. Check the **Usage** meters for messages, agents, team members, and training data (knowledge base storage) used against your plan's limits.

![Billing Plan tab with current plan and usage meters](https://www.omago.ai/docs/billing.webp)

Message usage resets each billing period. Agents, team members, and storage are ongoing counts — they don't reset.

#### Plan limits at a glance

Omago has five plans, from lowest to highest: Starter, Core, Plus, Max, and Enterprise. Each higher tier raises your message allowance, number of agents, team members, and knowledge base storage. For example, Plus includes 8,000 messages/mo, 3 agents, 3 team members, and 100 MB of training data, while Max includes 25,000 messages/mo, 30 agents, 10 team members, and 500 MB of training data.

For current pricing and the full breakdown across every plan, go to **Settings → Billing → Plan** — your plan's limits are shown there alongside your usage.

Billing is processed by Stripe. Storage is counted across all knowledge bases in your workspace, not per agent.

If you're on your plan's message limit, you're notified as you approach it. At the limit, your agents stop responding until you buy extra conversations or upgrade.

### Upgrade, downgrade, or cancel your plan

1. Go to **Settings → Billing → Plan**.
2. Use the plan action buttons — for example **Downgrade to Plus** or **Cancel plan**.
3. Confirm the change.

Upgrades and downgrades take effect at the start of your next billing cycle. If you downgrade to a plan with lower limits than what you're currently using — for example, more agents or more storage than the new plan allows — check **Settings → Billing → Plan** for how your account is affected before confirming.

### Buy add-ons

Add-ons raise a specific limit without moving you to a higher plan tier.

1. Go to **Settings → Billing → Add-ons** (or open the direct link to the Add-ons sub-tab).
2. Choose an add-on and complete the purchase.

| Add-on | What it does |
|---|---|
| Extra conversations | Raises your monthly message allowance |
| Extra agents | Adds one AI agent beyond your plan's cap |
| Remove branding | Unlocks the toggle to hide "Powered by Omago" on your chat widget (included free on Enterprise) |

See current add-on pricing on **Settings → Billing → Add-ons**.

To finish removing the badge after buying **Remove branding**, go to your agent's **Widget** tab and turn off **Show "Powered by"** — that toggle stays locked until the add-on is purchased.

If a single limit is blocking you but a full plan upgrade doesn't make sense, you can also ask Omago support to raise it individually.

### Manage your payment method

1. Go to **Settings → Billing → Payment**.
2. Update your payment method and billing details.

Omago accepts all major credit cards. Enterprise plans can be invoiced.

### Invite a teammate

1. Click **Settings** in the left sidebar, then open the **Members** tab.
2. Click **Invite Member**.
3. Enter their email address and pick a role — **Viewer**, **Member**, or **Admin** (default is **Member**).
4. Click **Send Invitation**.

The invite appears under the **Invitations** tab until the person accepts — it doesn't count as an active member until then.

#### What the roles mean

| Role | Access |
|---|---|
| Owner | Created the workspace. Full access. |
| Admin | Full access. |
| Member | Can edit. |
| Viewer | View-only. |

Team member count is limited by your plan (see the table above). If you're at your limit, upgrade your plan or free up a seat before inviting someone new.

### Rename your workspace or change its logo

1. Go to **Settings → Organization**.
2. Under **General Information**, edit the **Organization Name**.
3. Optionally upload a **Logo** — PNG, JPEG, GIF, WebP, or SVG, up to 5 MB.
4. Click **Save Changes**.

Nothing is saved until you click **Save Changes**. This logo is your workspace-level logo, separate from an individual agent's widget icon or avatar, which is set in that agent's Widget tab.

### Delete your workspace

1. Go to **Settings → Organization → Danger Zone**.
2. Click **Delete Organization**.
3. Confirm the deletion.

This permanently removes the entire workspace — agents, knowledge bases, leads, members, and billing data. It cannot be undone.