Repolode
Submit
csr1010

csr1010/whatsapp-ai-agent-sdk

Open-source TypeScript SDK for building a self-hosted AI agent that runs on WhatsApp, with your own model key and data.

View on GitHubWebsite
Stars
252
Forks
53
Open issues
1
Last commit
5 days ago

What is it?

Wappy is a TypeScript SDK and project generator for building an AI agent that talks to users over WhatsApp through the official WhatsApp Cloud API. Running `npm create @wappy_ai/agent` produces a project that wires up the agent loop, memory, tool calling and reply formatting, and you supply your own model provider key (Anthropic, OpenAI, Gemini, or a local Ollama model).

Conversations and memory are stored locally by default in SQLite/LibSQL, with BM25 retrieval for ingested documents. Cognee can be chosen instead as a self-hosted or cloud knowledge graph backend. An optional Gmail and Google Calendar assistant ships as a read-only tool example, using your own Google OAuth credentials.

The project is pre-1.0 and split into packages: core contracts, the harness that runs the agent, a WhatsApp package handling formatting, retries and webhooks, and the installer. Your business logic, such as ticketing or booking integrations, is added on top of the generated project.

Key features

  • 01Generates a WhatsApp agent project with one `npm create` command.
  • 02Supports Anthropic, OpenAI, Gemini, and local Ollama models with your own keys.
  • 03Stores conversations and ingested knowledge locally in SQLite/LibSQL by default.
  • 04Offers Cognee as an optional self-hosted or cloud knowledge graph backend.
  • 05Includes a read-only Gmail and Google Calendar tool example.

Use cases

  • Building a private personal assistant that remembers context across WhatsApp conversations.
  • Answering questions over your own notes or documents without sending them to a third-party cloud.
  • Prototyping a customer support or booking bot reachable on WhatsApp.
  • Running a fully offline agent against a local Ollama model.

Quick start

  1. 1

    Generate the project with the installer

    npm create @wappy_ai/agent
  2. 2

    Copy the env sample and fill in your model key and WhatsApp credentials

    cp .env.sample .env
  3. 3

    Install dependencies

    npm install
  4. 4

    Start the dev server and open the tunnel, then set the printed URL as Meta's webhook

    npm run dev

Things to know

  • The project is pre-1.0 and still in early days, so expect changes.
  • It requires Node.js 22 or newer and a WhatsApp Cloud API app from Meta.
  • You need your own model API key, or a local Ollama setup, to run the agent.

In collections

Open-source AI agent frameworks & appsPrivacy & local-first toolsAI chatbots & chat clientsOpen-source personal AI agents

Topics

#whatsapp#ai-agent#llm#typescript#local-first#chatbot#personal-agent#agent-framework#instinct#muse

FAQ

What is whatsapp-ai-agent-sdk?
Open-source TypeScript SDK for building a self-hosted AI agent that runs on WhatsApp, with your own model key and data. Wappy is a TypeScript SDK and project generator for building an AI agent that talks to users over WhatsApp through the official WhatsApp Cloud API. Running `npm create @wappy_ai/agent` produces a project that wires up the agent loop, memory, tool calling and reply formatting, and you supply your own model provider key (Anthropic, OpenAI, Gemini, or a local Ollama model).
Is whatsapp-ai-agent-sdk free to use? What license does it have?
whatsapp-ai-agent-sdk is open source under the MIT license. Check the license terms before using it in commercial products.
Is whatsapp-ai-agent-sdk still maintained?
Actively maintained. The last commit to whatsapp-ai-agent-sdk was on Nov 2, 2026.
What can I use whatsapp-ai-agent-sdk for?
Building a private personal assistant that remembers context across WhatsApp conversations. Answering questions over your own notes or documents without sending them to a third-party cloud. Prototyping a customer support or booking bot reachable on WhatsApp. Running a fully offline agent against a local Ollama model.
How do I install whatsapp-ai-agent-sdk?
Generate the project with the installer: npm create @wappy_ai/agent Copy the env sample and fill in your model key and WhatsApp credentials: cp .env.sample .env Install dependencies: npm install Start the dev server and open the tunnel, then set the printed URL as Meta's webhook: npm run dev
Where can I get whatsapp-ai-agent-sdk?
The source code and installation instructions are on GitHub: https://github.com/csr1010/whatsapp-ai-agent-sdk

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects