{"id":21864173,"url":"https://github.com/pablocerdeira/whatsapp-bot","last_synced_at":"2025-04-14T20:53:24.543Z","repository":{"id":261980044,"uuid":"884471580","full_name":"pablocerdeira/whatsapp-bot","owner":"pablocerdeira","description":"This project is an advanced WhatsApp bot that leverages artificial intelligence for automated audio transcription, document summarization, and scheduling of future messages. It uses Whisper for transcription and offers a choice between OpenAI's API and the Ollama local model for document summarization.","archived":false,"fork":false,"pushed_at":"2024-11-27T01:49:22.000Z","size":45,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T09:11:10.488Z","etag":null,"topics":["api","api-rest","artificial-intelligence","automation","bot","ollama","openai","whatsapp","whatsapp-bot","whisper"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/pablocerdeira.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":"2024-11-06T20:12:58.000Z","updated_at":"2024-12-31T05:02:29.000Z","dependencies_parsed_at":"2024-11-09T17:50:48.193Z","dependency_job_id":null,"html_url":"https://github.com/pablocerdeira/whatsapp-bot","commit_stats":null,"previous_names":["pablocerdeira/whatsapp-bot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablocerdeira%2Fwhatsapp-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablocerdeira%2Fwhatsapp-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablocerdeira%2Fwhatsapp-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablocerdeira%2Fwhatsapp-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pablocerdeira","download_url":"https://codeload.github.com/pablocerdeira/whatsapp-bot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248961048,"owners_count":21189990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["api","api-rest","artificial-intelligence","automation","bot","ollama","openai","whatsapp","whatsapp-bot","whisper"],"created_at":"2024-11-28T04:07:44.436Z","updated_at":"2025-04-14T20:53:24.519Z","avatar_url":"https://github.com/pablocerdeira.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WhatsApp Bot with AI-Powered Transcription, Document Summarization, and Advanced Scheduling\n\nThis project is an advanced WhatsApp bot that leverages artificial intelligence for automated audio transcription, document summarization, and scheduling of future messages. It uses Whisper for transcription and offers a choice between OpenAI's API and the Ollama local model for document summarization.\n\n## Key Features\n\n- **Message Backup**: Automatically saves all received messages, including text, audio, images, and other media.\n- **AI-Powered Audio Transcription**:\n  - In **private chats**, it transcribes all audio messages automatically and replies in the same chat.\n  - In **groups**, transcription is performed only if enabled in the `config.json` file.\n- **AI-Powered Document Summarization (PDF, DOC, DOCX)**:\n  - In **private chats**, it summarizes documents automatically and replies with the summary.\n  - In **groups**, summarization is performed only if enabled in the `config.json` file.\n- **Configurable Options**: Use `config.json` to define specific settings for each group and choose between using OpenAI's API or the local Ollama model.\n- **Advanced Message Scheduling**: Schedule messages to be sent at a future date and time using:\n  - Direct JSON file updates (`scheduled-messages.json`).\n  - Web interface with form submission and autocomplete for contacts.\n  - REST API for integration with external applications.\n\n## Requirements\n\n- Node.js (version 16 or higher)\n- An OpenAI developer account for using the GPT-4 API\n- Ollama installed locally for using the Llama model\n- Whisper installed for audio transcription\n- Additional packages for document processing and API requests:\n\n```bash\nnpm install whatsapp-web.js qrcode-terminal fs path child_process pdf-parse mammoth textract openai axios express express-fileupload ejs\n```\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/pablocerdeira/whatsapp-bot\ncd whatsapp-bot\n```\n\n2. Install the dependencies:\n\n```bash\nnpm install\n```\n\n3. Configure your API keys:\n\nCreate a `.env` file in the project root and add your OpenAI API key:\n\n```bash\nOPENAI_API_KEY=YOUR_OPENAI_API_KEY\n```\n\n4. Set up the configuration file:\n\nRefer to the `config.json.example` for setting your preferences:\n\n- Choose between OpenAI (`service: \"openai\"`) or Ollama (`service: \"ollama\"`) for document summarization.\n- Set the model and base URL for Ollama if using it locally.\n\n## Running the Bot as a Service\n\nYou can use `pm2` to run the bot as a service for better reliability and easier management.\n\n### Install `pm2`:\n\n```bash\nnpm install -g pm2\n```\n\n### Start the bot with `pm2`:\n\n```bash\npm2 start bot.js --name whatsapp-bot\n```\n\n### Save the process list and enable startup on system boot:\n\n```bash\npm2 save\npm2 startup\n```\n\n### View logs:\n\n```bash\npm2 logs whatsapp-bot\n```\n\n## Advanced Message Scheduling\n\n### JSON File\n\nYou can directly add new scheduled messages to `scheduled-messages.json` with the following format:\n\n```json\n{\n    \"id\": \"1731530653175\",\n    \"recipient\": \"5521979327997@c.us\",\n    \"message\": \"Scheduled message example\",\n    \"attachment\": \"./attachments/sample.pdf\",\n    \"scheduledAt\": \"2024-11-13T17:30:00\",\n    \"status\": \"approved\",\n    \"sentAt\": null\n}\n```\n\n### Web Interface\n\nAccess the web interface at `http://localhost:3000/` (or the port specified in your `config.json`). It allows you to:\n\n- View all scheduled messages.\n- Create new scheduled messages with autocomplete for contacts.\n- Upload attachments directly from the web form.\n\n### REST API\n\nYou can also schedule messages via the REST API, enabling integration with other applications.\n\n#### API Endpoint: Create a Scheduled Message\n\n- **URL**: `/api/schedule`\n- **Method**: `POST`\n- **Content-Type**: `multipart/form-data`\n- **Body Parameters**:\n  - `recipient`: WhatsApp ID of the recipient (e.g., \"5521979327997@c.us\").\n  - `message`: The message text.\n  - `scheduledAt`: Date and time for the message to be sent (e.g., \"2024-11-13T17:30:00\").\n  - `attachment` (optional): File attachment.\n\n**Example using `curl`**:\n\n```bash\ncurl -X POST http://localhost:3000/api/schedule \\\n  -F \"recipient=5521979327997@c.us\" \\\n  -F \"message=This is a test message with an attachment\" \\\n  -F \"scheduledAt=2024-11-13T17:30:00\" \\\n  -F \"attachment=@/path/to/file.pdf\"\n```\n\n#### API Endpoint: List Scheduled Messages\n\n- **URL**: `/api/scheduled-messages`\n- **Method**: `GET`\n\n```bash\ncurl http://localhost:3000/api/scheduled-messages\n```\n\n#### API Endpoint: Update a Scheduled Message\n\n- **URL**: `/api/schedule/:id`\n- **Method**: `PUT`\n- **Body Parameters**:\n  - `recipient`, `message`, `scheduledAt`, `status` (optional).\n\n```bash\ncurl -X PUT http://localhost:3000/api/schedule/1731530653175 \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status\": \"approved\"}'\n```\n\n#### API Endpoint: Delete a Scheduled Message\n\n- **URL**: `/api/schedule/:id`\n- **Method**: `DELETE`\n\n```bash\ncurl -X DELETE http://localhost:3000/api/schedule/1731530653175\n```\n\n## Configuration (`config.json`)\n\nExample configuration file (`config.json`):\n\n```json\n{\n    \"service\": \"openai\",\n    \"schedulerPort\": 3000,\n    \"openai\": {\n        \"model\": \"gpt-4o-mini\"\n    },\n    \"ollama\": {\n        \"model\": \"llama2\",\n        \"base_url\": \"http://localhost:11434\"\n    },\n    \"whisperPath\": \"/path/to/whisper\",\n    \"chats\": {\n        \"transcriptionGroup\": \"[your-user-or-grupo-to-send-transcriptions-if-not-same_chat]\",\n        \"group-id-1\": {\n            \"transcribeAudio\": true,\n            \"sendAudioToTranscriptGroup\": false,\n            \"sendTranscriptionTo\": \"same_chat\",\n            \"summarizeDocuments\": true\n        }        },\n        \"group-id-2\": {\n            \"transcribeAudio\": true,\n            \"sendAudioToTranscriptGroup\": true,\n            \"sendTranscriptionTo\": \"transcription_group\",\n            \"summarizeDocuments\": false\n        }\n    }\n}\n```\n## Features Overview\n\n### Message Backup\n\n- Saves all received messages in `.json` files, creating a history for each chat or group.\n- Media files are stored in a dedicated `media` folder within each chat's directory.\n\n### AI-Powered Transcription\n\n- Uses Whisper to transcribe `.ogg` audio files.\n- Automatically transcribes audio in private chats and responds with the text.\n- In groups, transcription is enabled based on the `config.json` settings.\n\n### AI-Powered Document Summarization\n\n- Supports PDF, DOC, and DOCX files.\n- Offers a choice between using OpenAI's GPT model or the local Ollama model for summarization.\n- In private chats, documents are summarized automatically.\n- In groups, summarization is performed only if configured.\n\n### Advanced Message Scheduling\n**Flexible Scheduling Options:**\n- Schedule messages for a specific date and time, with support for different time formats.**\n- Supports both private chats and group messages.\n\n**Multiple Scheduling Methods:**\n- JSON File: Directly add or edit scheduled messages in the scheduled-messages.json file for quick manual entries.\n- Web Interface: A user-friendly web interface with search and autocomplete features for selecting contacts, and file upload for attachments. Easily create, edit, and delete scheduled messages.\n- API Integration: An API endpoint for programmatically scheduling messages. Ideal for integrating with external applications, task automation, or other bots.\n\n**Attachment Support:**\n- Upload and send attachments such as PDF, DOC, or image files along with the scheduled message.\n- Automatically saves attachments to a dedicated attachments folder.\n\n**Real-Time Monitoring:**\n- Watches for updates in the scheduled-messages.json file and immediately processes changes.\n- Performs periodic checks to ensure scheduled messages are sent on time, even if the file was edited manually or by an external tool.\n\n### Error Handling and Logging\n\n- **Retry Mechanism**: Includes retry logic for API rate limits with exponential backoff.\n- **Ignored Status Messages**: Automatically ignores messages from `status@broadcast` to prevent unnecessary processing.\n- **Verification**: Verifies scheduled time format and adjusts if necessary.\n- **Logging**: Provides detailed logs for each scheduled action, including message creation, attachment handling, and errors during scheduling or sending.\n\n## Contributions\n\nContributions are welcome! Please submit a pull request or open an issue to discuss any changes.\n\n## License\n\nThis project is licensed under the MIT License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpablocerdeira%2Fwhatsapp-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpablocerdeira%2Fwhatsapp-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpablocerdeira%2Fwhatsapp-bot/lists"}