{"id":35887395,"url":"https://github.com/lucasboscatti/Whatsapp-Langgraph-Agent-Integration","last_synced_at":"2026-01-15T06:00:43.649Z","repository":{"id":279065533,"uuid":"937620768","full_name":"lucasboscatti/Whatsapp-Langgraph-Agent-Integration","owner":"lucasboscatti","description":"A WhatsApp AI Agent powered by LangGraph, FastAPI, and Groq. Acts as an empathetic therapist, Dr. Sofia, handling text and voice messages with natural conversations. Supports multi-language, PostgreSQL-backed memory, and real-time synthesis.","archived":false,"fork":false,"pushed_at":"2025-02-23T14:45:56.000Z","size":96,"stargazers_count":74,"open_issues_count":0,"forks_count":19,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-03T17:21:38.328Z","etag":null,"topics":["agents","fastapi","groq","langchain","langgraph","langgraph-chabot","langgraph-python","python","whatsapp","whatsapp-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucasboscatti.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-23T14:12:39.000Z","updated_at":"2026-01-03T13:32:31.000Z","dependencies_parsed_at":"2025-02-23T15:28:40.338Z","dependency_job_id":"883b569f-a46e-4606-98f9-15ee7d0cde7c","html_url":"https://github.com/lucasboscatti/Whatsapp-Langgraph-Agent-Integration","commit_stats":null,"previous_names":["lucasboscatti/whatsapp-langgraph-agent-integration"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lucasboscatti/Whatsapp-Langgraph-Agent-Integration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasboscatti%2FWhatsapp-Langgraph-Agent-Integration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasboscatti%2FWhatsapp-Langgraph-Agent-Integration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasboscatti%2FWhatsapp-Langgraph-Agent-Integration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasboscatti%2FWhatsapp-Langgraph-Agent-Integration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucasboscatti","download_url":"https://codeload.github.com/lucasboscatti/Whatsapp-Langgraph-Agent-Integration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasboscatti%2FWhatsapp-Langgraph-Agent-Integration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28444124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T05:05:00.929Z","status":"ssl_error","status_checked_at":"2026-01-15T05:04:58.515Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","fastapi","groq","langchain","langgraph","langgraph-chabot","langgraph-python","python","whatsapp","whatsapp-bot"],"created_at":"2026-01-08T22:00:39.536Z","updated_at":"2026-01-15T06:00:43.641Z","avatar_url":"https://github.com/lucasboscatti.png","language":"Python","funding_links":[],"categories":["Agent Categories"],"sub_categories":["\u003ca name=\"LangGraph\"\u003e\u003c/a\u003eLangGraph"],"readme":"# WhatsApp AI Agent powered by LangGraph \u0026 Groq\n\nThis project implements a **WhatsApp AI Agent** that engages in natural conversations through WhatsApp, providing support and responses in both text and voice formats. Using **LangGraph**, **FastAPI**, **PostgreSQL**, and the **Groq** LLM, this agent can understand text messages, transcribe voice notes, and respond in a synthesized speech.\n\n👉 The agent acts as a therapist named Dr. Sofia, providing compassionate and empathetic guidance to users!\n\n💡 You can modify the agent's personality by editing the `system_prompt.py` file:\n\n```python\nprompt = \"\"\"You are Dr. Sofia, a compassionate and empathetic therapist.\nIts goal is to provide supportive, non-judgmental guidance and help users \nto explore your emotions and thoughts.\"\"\"\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/wpp.png\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Table of Contents\n1. [Key Features](#key-features)\n2. [Built With](#built-with)\n3. [Use Cases](#use-cases)\n4. [Project Structure](#project-structure)\n5. [Get Started](#get-started)\n6. [Development Notes](#development-notes)\n7. [Troubleshooting](#troubleshooting)\n\n---\n\n## Key Features\n\nThe WhatsApp AI Agent provides:\n\n1. **Multi-Modal Communication:**\n   - Process both text and voice messages\n   - Respond with synthesized voice\n   - Transcribe voice messages using Whisper\n\n2. **Conversation Management:**\n   - Message aggregation with configurable wait time\n   - Persistent conversation state using PostgreSQL\n   - Support for multiple languages\n\n3. **Natural Language Understanding:**\n   - Powered by Groq's LLMs. Visit [Groq](https://groq.com/) to create your API key and see the available LLMs\n   - Contextual responses maintaining conversation flow\n   - Customizable system prompt for different personalities\n\n---\n\n## Built With\n\n- **LangGraph:** Enables sophisticated, stateful agent workflows\n- **FastAPI:** Provides the webhook endpoint and API infrastructure\n- **PostgreSQL:** Manages conversation states and history\n- **WPPConnect:** Handles WhatsApp integration\n- **Groq:** Powers the language model for natural conversations and transcribes voice messages to text\n- **gTTS:** Converts text responses to speech\n\n---\n\n## Use Cases\n\nThis WhatsApp AI Agent is perfect for:\n- **Mental Health Support:** Providing initial emotional support and guidance\n- **Customer Service:** Automating responses in multiple modalities\n- **Educational Support:** Offering explanations and guidance\n- **Information Services:** Delivering information through voice and text\n\n---\n\n## Project Structure\n\n```\n.\n├── app/\n│   ├── agent.py               # LangGraph agent implementation\n│   ├── config/\n│   │   ├── config.py         # Configuration management\n│   │   └── logging.py        # Logging setup\n│   ├── src/\n│   │   └── wppconnect/\n│   │       └── api.py        # WhatsApp integration\n│   └── utils/\n│       └── graph_utils.py    # Graph utilities\n├── main.py                   # FastAPI application\n├── system_prompt.py          # Agent personality definition\n├── requirements.txt          # Project dependencies\n└── .env-example             # Environment variables template\n```\n\n---\n\n## Get Started\n\n### Prerequisites\n\n- Python 3.10+\n- PostgreSQL\n- Node.js 14+\n\n### Installation Steps\n\n1. **Clone WPPConnect Server:**\n   ```bash\n   git clone https://github.com/wppconnect-team/wppconnect-server.git\n   cd wppconnect-server\n   ```\n\n2. **Install WPPConnect Dependencies:**\n   ```bash\n   npm install\n   ```\n\n3. **Configure Webhook:**\n   - Open `src/config.ts`\n   - Update webhook configuration:\n   ```typescript\n   webhook: {\n       url: 'http://localhost:8000/webhook',\n   }\n   ```\n\n4. **Start WPPConnect Server:**\n   ```bash\n   npm run dev\n   ```\n\n5. **Configure WhatsApp Connection:**\n   a. Access Swagger UI at `http://localhost:21465/api-docs`\n   b. Generate Token:\n      - Execute the `generate-token` endpoint\n      - Copy the returned token (starts with `$`)\n   c. Configure Token:\n      - Add to `.env` as `WPPCONNECT_TOKEN`\n      - Authorize in Swagger UI\n   d. Start Session:\n      ```json\n      {\n        \"webhook\": \"\",\n        \"waitQrCode\": true\n      }\n      ```\n   e. Scan QR Code:\n      - Convert base64 to QR code at https://codebeautify.org/base64-to-image-converter\n      - Scan with WhatsApp\n\n6. **Set Up PostgreSQL:**\n   ⚠️ **Important Database Setup:**\n   - First run only: Uncomment in `agent.py`:\n     ```python\n     await checkpointer.setup()  # Uncomment for first execution\n     ```\n   - After first run: Comment out this line to avoid errors\n\n7. **Configure Environment:**\n   Copy `.env.example` to `.env` and configure:\n   ```env\n   # WPPConnect Configuration\n   WPPCONNECT_BASE_URL=http://localhost:21465\n   WPPCONNECT_SECRET_KEY=THISISMYSECURETOKEN\n   WPPCONNECT_SESSION_NAME=NERDWHATS_AMERICA\n   WPPCONNECT_TOKEN=your_generated_token\n\n   # GROQ Configuration\n   GROQ_API_KEY=your_groq_api_key\n\n   # Postgres Configuration\n   PSQL_USERNAME=db_user\n   PSQL_PASSWORD=db_password\n   PSQL_HOST=db_host\n   PSQL_PORT=5432\n   PSQL_DATABASE=db_name\n   PSQL_SSLMODE=db_sslmode\n   PSQL_CONNECTION_STRING=postgresql://${PSQL_USERNAME}:${PSQL_PASSWORD}@${PSQL_HOST}/${PSQL_DATABASE}?sslmode=${PSQL_SSLMODE}\n\n   # Whatsapp Configuration\n   WAIT_TIME=1\n   LANGUAGE=en\n   ```\n\n8. **Start the Application:**\n   ```bash\n   uvicorn main:app --host 0.0.0.0 --port 8000 --reload\n   ```\n\n---\n\n## Development Notes\n\n- Adjust `WAIT_TIME` to balance response time and message aggregation\n- Set `LANGUAGE` based on your target audience\n- Monitor PostgreSQL storage for conversation histories\n\n### Resetting Conversations\n\nTo start fresh conversations, run:\n```sql\nDO $$\nBEGIN\n    EXECUTE format('DELETE FROM checkpoint_blobs');\n    EXECUTE format('DELETE FROM checkpoint_migrations');\n    EXECUTE format('DELETE FROM checkpoint_writes');\n    EXECUTE format('DELETE FROM checkpoints');\nEND $$;\n```\n⚠️ WARNING: This deletes ALL conversation histories. Backup important data first.\n\n---\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n1. **Database Connection Issues:**\n   - Verify PostgreSQL credentials\n   - Check connection string format\n   - Ensure database exists\n\n2. **WPPConnect Problems:**\n   - Confirm server is running\n   - Verify token authorization\n   - Check webhook URL configuration\n\n3. **Voice Message Issues:**\n   - Verify file permissions\n   - Check temporary storage space\n   - Confirm language configuration\n\n4. **Agent Response Problems:**\n   - Monitor Groq API status\n   - Verify PostgreSQL checkpointer setup\n\nFor detailed error messages, check the application logs.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasboscatti%2FWhatsapp-Langgraph-Agent-Integration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucasboscatti%2FWhatsapp-Langgraph-Agent-Integration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasboscatti%2FWhatsapp-Langgraph-Agent-Integration/lists"}