We open-sourced our AI agent engine, all of it

Ecbot's AI agent engine is open source under AGPL-3.0, and it is the same code that runs Ecbot Cloud, with every feature included. If you need an agent that sells and supports customers on Messenger, Zalo, WhatsApp, Telegram and your website, you can now read every line, run it on your own server and change what you don't like.

The repo went public in September 2026 at github.com/blackmouse572/ecbot. This post covers what is in it, why we didn't hold anything back, and when you should pick the hosted version instead.

One Zalo message at 11:40 pm, traced through the engine

A dress shop in Ho Chi Minh City sells mostly on Zalo. At 11:40 pm a customer sends three messages in four seconds:

c ơi còn sz M màu xanh k ship q7 bn

("Hi", "still got size M in blue?", "how much to ship to District 7?")

Here is what the engine does with them, in order:

1. Each message lands in a durable queue before Ecbot answers Zalo's webhook, so a restart halfway through can't drop it.
2. Duplicates are dropped. Platforms retry webhooks, and one Redis check per message ID catches every repeat.
3. The three messages become one turn. Messages inside a 3-second window are answered together, once, while Zalo shows "typing".
4. The agent finds the customer behind the Zalo account. She ordered through the shop's Facebook page last month, and staff confirmed the merge suggestion Ecbot made from her phone number, so her profile, tags and notes are already there.
5. It loads one playbook. The shop wrote a skill called "size and shipping questions". The agent only knew its name until now; it pulls in the full text because this turn needs it.
6. It calls the shop's stock API. Two blue dresses left in M. The call, its arguments and its result are logged, so the owner can see exactly what the agent did.
7. It replies with the stock, the District 7 shipping fee from the shop's price list, and an offer to hold one.

Two days later the same customer writes "sao chưa giao nữa, bực ghê" ("why hasn't it shipped yet, so annoyed"). The agent tags her "Angry", a tag the owner marked as a handoff trigger. The bot goes quiet in that conversation, staff get notified, and someone replies from the same inbox with the whole history in front of them.

Every step above runs from the public repo, with no paid license key.

Why we didn't keep the good parts closed

Most open source AI products ship a core and charge for the parts a business needs in production: the inbox, team roles, the integrations. We decided against that for three reasons.

• You should be able to check what the agent does. An agent that talks to your customers, reads your price list and calls your order system has a lot of access. The code shows what it does with that access, line by line.
• The hard parts took the longest. Webhook retries, message bursts, stale replies and customer identity across apps took us months to get right. An open repo without them would be a demo.
• Hosting pays our bills. Ecbot Cloud runs the engine for you: servers, model access, Facebook and Zalo app approvals, updates. It is in beta. If you'd rather do that work yourself, self-hosting costs you the server and your own model usage.

What you get in the repo

What the engine does	How it works
One customer across every app	One profile per person, with each Messenger, Zalo, WhatsApp or Telegram identity attached. Shared phone or email creates a merge suggestion that a person confirms.
An agent that does the work	Tools from your own REST endpoints, any MCP server, or the Composio marketplace (700+ integrations). Every call is logged.
Playbooks loaded on demand	Skills written in markdown. The agent sees only their names until a conversation needs one, which keeps the prompt short.
Staff stay in charge	Handoff on request, on low confidence, on a guardrail hit, or on a tag you mark as urgent. Operators reply from one inbox.
No dropped messages	Durable BullMQ queue, deduplication, and a per-conversation lease that cancels a reply when a newer message arrives.
Set up from one sentence	Describe the business and the agent builder drafts persona, tone, goals and rules for you to edit.
Knowledge in your own database	Embeddings in Postgres with pgvector, next to the rest of your data, scoped per agent.

Six channels work today: Facebook Messenger, Zalo OA, WhatsApp Business, Telegram, a website widget and a REST API channel. The stack is NestJS for the API, Python with FastAPI for the AI service, and React for the operator app. Models go through OpenRouter, so you pick one per agent and pay the provider directly.

If "agent" still sounds vague, What is an AI agent? explains it with a sales example and no jargon.

How it compares with what developers stitch together today

Builders who want an AI agent on chat apps usually combine an agent builder, an inbox and an automation tool. Here is how those pieces cover the job, based on each project's public docs in October 2026.

If you already run Chatwoot for support and only need a small AI step, adding one to it may be enough. Ecbot fits when you want the agent, the inbox and the channels to share one database and one customer record.

When you should not self-host Ecbot

• You have no one to run servers. Self-hosting means Postgres, Redis, two services, backups and upgrades. Ecbot Cloud exists for this case.
• You only need Facebook and Zalo, this week. Both require your own platform app with messaging permissions approved, and that review can take a while. Telegram, the website widget and the REST channel need no approval.
• Your customers are on LINE, Shopee or TikTok Shop. Those channels are not supported yet, each with an open issue: #23, #24 and #80. Instagram's adapter is merged but needs Meta App Review.
• You want a visual flow builder. Ecbot has none. Behaviour lives in the persona, skills, tools and handoff rules.
• You plan to sell a modified version as a service and keep the changes private. AGPL-3.0 requires you to share them.

Run it on your machine

You need Node 20+, pnpm 9, Docker, and uv with Python 3.12+.

git clone https://github.com/blackmouse572/ecbot.git
cd ecbot
pnpm install
pnpm setup:local                 # writes .env files, asks for OPENROUTER_API_KEY
docker compose up -d             # Postgres + pgvector, Redis
pnpm --filter api migration:up
pnpm dev:app                     # API + operator app
pnpm --filter ai dev             # AI service, in a second shell

Open the app on localhost:5173, create an agent from one sentence, and connect a Telegram bot. You can be chatting with your own agent a few minutes after the stack is up.

Each channel is a small adapter class, and deduplication, bursts, guardrails and handoff sit above it, so a new channel gets all of them for free. The three open channel issues above are labelled good first issue.

Clone the repo, connect a Telegram bot, and open an issue wherever it breaks for you.

Câu hỏi thường gặp