ManyChat AI Agent
A production-shaped, provider-agnostic AI agent that answers customer questions on WhatsApp, Instagram and Facebook Messenger through ManyChat, escalating to a human rather than guessing. Each turn is a LangGraph.js graph over LangChain.js models, served by Fastify, and traceable to your own LangSmith: its shape, never its text.
Switching the model is one environment variable. Switching the chat platform is one adapter.
It is for anyone putting an LLM behind a platform that enforces a hard webhook timeout: ManyChat is the adapter that ships, and the race and the outbox below are what carries over to any other.
git clone https://github.com/pedronastasi/manychat-ai-agent.git
cd manychat-ai-agent
pnpm install && pnpm bootstrap && pnpm devThat runs with no API key and no database to install — an offline mock model and an embedded PGlite Postgres. In another terminal, pnpm simulate answers one question and hands one off:
That clone is for trying the agent and working on it. To run one for your own business, generate a project of your own instead, which depends on the published package rather than a copy of this repository:
npm create manychat-ai-agent@latest my-agentStarting a new agent walks through it, from the offline first run to a deployment.
The problem this solves
ManyChat can call an external endpoint, but it terminates the request after 10 seconds. An LLM call plus database work sometimes fits in that budget and sometimes does not, so the obvious synchronous design drops replies under exactly the conditions where a customer is already waiting.
This project takes the position that neither "always answer inline" nor "always queue" is right, and races them.
inbound message
│
├─ guards: keywords, turn cap, rate limit, daily budget ── denied ──▶ escalate to human
│ (model never runs)
▼
Promise.race
├── model answered (< 8s) ──▶ reply inline + re-register callback
│
└── deadline hit (= 8s) ──▶ short ack
│
└─ model keeps running ──▶ outbox ──▶ worker ──▶ Send APIThe losing model call is not cancelled. Those tokens are already paid for and the answer is still wanted, so it completes into a Postgres outbox and a worker delivers it seconds later. The reply is never dropped, only deferred.
The conversation loop lives in this service rather than in ManyChat's visual flow builder, via Dynamic Block's external_message_callback. That is what keeps the agent portable instead of welded to one vendor's UI.
The full design — what fails closed, how spend is bounded, and every decision record — is in How it works.
What it can do
- Answer from the catalog, or hand off. Every fact it may state lives in
config/catalog.json; anything else escalates to a person rather than being guessed (spec 001). - Run on any model. The model is one environment variable —
anthropic:claude-haiku-4-5,openai:gpt-5-mini,ollama:llama3.1:8b, or the offlinemock:demo— and onlysrc/agent/registry.tsimports a provider. - Keep each contact's history theirs. A token held in the contact's own ManyChat field, not the shared secret, unlocks their conversation (spec 019).
- Answer WhatsApp, Instagram and Messenger from one deployment. Each request names its channel, and the reply, a deferred delivery and a follow-up go back on that channel alone. A contact ManyChat has merged across channels keeps one conversation (spec 048).
- Read voice notes, images and videos sent on any of the three (spec 020).
- Act in ManyChat and sell. Optionally send flows, set tags and fields, read the contact, schedule a follow-up, and take a lead to the payment link (spec 012, spec 023).
- Learn from outcomes, offline and only after a person approves (spec 031).
Stack
| Layer | What | Where |
|---|---|---|
| HTTP | Fastify 5, Zod type provider, helmet, rate limiting, under-pressure | src/server.ts |
| Orchestration | LangGraph.js StateGraph | src/agent/langgraph-runner.ts |
| Models | LangChain.js chat models (Anthropic, OpenAI, Gemini, Ollama, offline mock:); openai client for transcription | src/agent/registry.ts |
| Tracing | LangSmith, off unless TRACE_TURNS=langsmith | src/observability/ |
| Tools | LangChain.js tool() from @langchain/core/tools, with Zod input schemas | src/agent/tools/define.ts |
| Data | Postgres via Drizzle; PGlite for development and tests. ManyChat via manychat-sdk | src/db/ |
Architecture: one turn
Three nodes, no checkpoint, between checks that hand off to a person:
tools runs reads and send_flow now and stages other writes until after the reply, dropping them on an escalation. A turn escalates before the graph on a keyword, the turn cap, the rate limit or the daily budget; in it when the model sets escalate; after it when the reply fails its schema, falls below confidenceThreshold, leaks working notes past one rewrite, or the call fails. The contact gets the tenant's escalation message; the conversation is marked escalated. A lost race is no escalation: the reply finishes into the outbox.
Channels
Each channel's ManyChat flow calls one Dynamic Block endpoint and names its channel, which must be in CHANNELS. The reply and a callback for the next message return in the response; a deferred reply goes into a ManyChat field and out through the channel's reply flow (limits):
| Channel | Messages per reply | Deferred reply after Meta's 24-hour window | Reply flow |
|---|---|---|---|
| 1: the rest are joined into it | Sent; the reply flow's template carries it | MANYCHAT_REPLY_FLOW_NS | |
| Up to 10 | Refused as window_closed, conversation escalated | MANYCHAT_REPLY_FLOW_NS_INSTAGRAM | |
| Messenger | Up to 10 | Refused as window_closed, conversation escalated | MANYCHAT_REPLY_FLOW_NS_MESSENGER |
Configuration
All in .env.example: the model and its key, PUBLIC_BASE_URL (HTTPS), MANYCHAT_SHARED_SECRET, DATABASE_URL, CHANNEL/CHANNELS. Tracing is TRACE_TURNS=langsmith, LANGSMITH_API_KEY=<your-key> and LANGSMITH_PROJECT=<your-project>; LangChain's own LANGSMITH_TRACING and its siblings stop boot when true (spec 052).
Documentation
The same pages, with search, are on the docs site.
| To… | Read |
|---|---|
| Deploy an agent for your own business | Starting a new agent |
| Try it from a clone, with curl or Docker | Running it locally |
| Point ManyChat at it | Connecting ManyChat |
| Turn on tools, follow-ups or the funnel | Agent tools and the sales funnel |
| Write the tenant's prompt, catalog and rules | Tenant configuration |
| Understand the design | How it works and the decision records |
| Know exactly what it must do | The specs, starting from the constitution |
| Contribute | CONTRIBUTING |
Development
pnpm bootstrap # local config + .env from the committed examples
pnpm dev # offline by default: mock model, embedded Postgres
pnpm simulate "…" # send a Dynamic Block request as ManyChat would
pnpm test # unit + integration
pnpm eval:mock # golden set, offline and free
pnpm eval:conversations:validate # check the scripted conversations, no model call
pnpm lint && pnpm typecheckStatus
MVP. Answers, escalates, and calls the tools a tenant turns on: flows, tags, fields, contact reads, notes, follow-ups and the payment link. It does not book or process a payment.
License
MIT — see LICENSE.