{"id":26059472,"url":"https://github.com/megagarra/super-chatbot","last_synced_at":"2026-04-12T03:03:16.615Z","repository":{"id":281230078,"uuid":"944631703","full_name":"megagarra/SUPER-CHATBOT","owner":"megagarra","description":"Um bot completo, tanto para WhastApp, Web, Rede Sociais ","archived":false,"fork":false,"pushed_at":"2025-03-07T17:35:05.000Z","size":15,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-07T18:31:21.380Z","etag":null,"topics":["agent","agents","assistant","assistant-chat-bots","chatbot","openai","openai-api","whastapp-bot","whastappassistentplaygroundopenai","whatsapp","whatsappassistentopenai","whatsappopenaiassistent"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/megagarra.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-03-07T17:31:10.000Z","updated_at":"2025-03-07T17:36:47.000Z","dependencies_parsed_at":"2025-03-07T18:43:18.942Z","dependency_job_id":null,"html_url":"https://github.com/megagarra/SUPER-CHATBOT","commit_stats":null,"previous_names":["megagarra/super-chatbot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megagarra%2FSUPER-CHATBOT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megagarra%2FSUPER-CHATBOT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megagarra%2FSUPER-CHATBOT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megagarra%2FSUPER-CHATBOT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/megagarra","download_url":"https://codeload.github.com/megagarra/SUPER-CHATBOT/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242552942,"owners_count":20148257,"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":["agent","agents","assistant","assistant-chat-bots","chatbot","openai","openai-api","whastapp-bot","whastappassistentplaygroundopenai","whatsapp","whatsappassistentopenai","whatsappopenaiassistent"],"created_at":"2025-03-08T13:13:23.966Z","updated_at":"2025-12-24T03:46:45.685Z","avatar_url":"https://github.com/megagarra.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BOT WHATSAPP\n![image](https://github.com/user-attachments/assets/0e1770b3-4c2b-43b2-b1d4-05d6a4f779bc)\n\n\nUm bot para WhatsApp com uma persona que utiliza a API Assistant da OpenAI, oferecendo uma experiência de companhia de IA através do WhatsApp.\n\n## Visão Geral\n\nO Garra AI Companion é um bot para WhatsApp que conecta a poderosa API Assistant da OpenAI com o WhatsApp, permitindo que os usuários interajam com um assistente de IA através de suas mensagens no WhatsApp. O bot suporta mensagens de texto, notas de voz (com transcrição), imagens (com análise de visão) e processamento de arquivos (PDFs, TXT).\n\n## Funcionalidades Principais\n\n- **Integração com WhatsApp**: Conecte-se com usuários via WhatsApp\n- **API Assistant da OpenAI**: Aproveite as capacidades de IA usando a API Assistant da OpenAI\n- **Suporte a Multimídia**:\n  - Transcrição de notas de voz usando a API Whisper\n  - Análise de imagens com GPT-4 Vision\n  - Processamento de arquivos PDF e TXT\n- **Integração com API Externa**: Conecte-se a serviços externos através de um serviço de API flexível\n- **Gerenciamento de Configuração**: Configuração armazenada em banco de dados com interface web\n- **Persistência de Mensagens**: Armazene o histórico de conversas em um banco de dados PostgreSQL\n- **Gerenciamento de Conversas**: Pause/retome conversas\n- **Fila de Mensagens**: Fila baseada em Redis para processar mensagens em ordem\n- **Autenticação**: Autenticação baseada em código QR para WhatsApp Web\n\n## Arquitetura\n\nA aplicação consiste em vários componentes:\n\n### Componentes Principais\n\n1. **Cliente WhatsApp**: Gerencia a conexão com o WhatsApp Web usando `@periskope/whatsapp-web.js`\n2. **Cliente OpenAI**: Lida com interações com a API da OpenAI para Assistant, Vision e Whisper\n3. **Banco de Dados**: Banco de dados PostgreSQL para armazenar conversas, mensagens e configurações\n4. **Fila Redis**: Para processamento assíncrono de mensagens\n5. **Servidor Express**: Fornece uma API REST para gerenciar o bot\n6. **Serviço de API Externa**: Proxy genérico para conexão com APIs externas\n\n### Modelos de Banco de Dados\n\n- **Thread**: Representa uma conversa com um usuário\n- **ThreadMessage**: Mensagens individuais em uma thread\n- **Config**: Valores de configuração do sistema\n\n### Fluxo de Serviço\n\n1. Usuário envia uma mensagem para o número do WhatsApp\n2. Bot recebe a mensagem via cliente WhatsApp Web\n3. Para mensagens de texto:\n   - As mensagens são agregadas com debounce (3s) para combinar mensagens fragmentadas\n   - A thread é criada ou recuperada do banco de dados\n   - A mensagem é enviada para a API Assistant da OpenAI\n   - A resposta é enviada de volta ao usuário\n4. Para mídia (notas de voz, imagens, arquivos):\n   - A mídia é processada imediatamente (transcrição, análise de visão, extração de texto)\n   - O resultado é enviado para a API Assistant da OpenAI\n   - A resposta é enviada de volta ao usuário\n5. Todas as mensagens são armazenadas no banco de dados\n\n## Instalação\n\n### Pré-requisitos\n\n- Node.js (v14+)\n- Banco de dados PostgreSQL\n- Servidor Redis\n- Chave de API da OpenAI\n- Conta de WhatsApp\n\n### Variáveis de Ambiente\n\nCrie um arquivo `.env` no diretório raiz com as seguintes variáveis:\n\n```\n# Configuração Principal\nOPENAI_API_KEY=sua_chave_api_openai\nASSISTANT_ID=seu_id_de_assistente\nBOT_NAME=Garra\nWHATSAPP_NUMBER=seu_numero_whatsapp\n\n# Configuração do Banco de Dados\nDATABASE_URL=postgres://usuario:senha@localhost:5432/nome_do_banco\n\n# Configuração do Redis\nREDIS_URL=redis://localhost:6379\n\n# Configuração da API\nAPI_BASE_URL=https://sua-api-externa.com\n```\n\n### Configuração\n\n1. Instale as dependências:\n```bash\nnpm install\n```\n\n2. Migre o banco de dados:\n```bash\nnpm run migrate\n```\n\n3. Inicie o bot:\n```bash\nnpm start\n```\n\n4. Escaneie o código QR exibido com o WhatsApp para autenticar\n\n## Uso\n\n### Endpoints da API REST\n\nO bot fornece uma API REST para gerenciamento:\n\n#### Endpoints de Configuração\n\n- `GET /api/config`: Obter todas as configurações\n- `GET /api/config/:key`: Obter uma configuração específica\n- `POST /api/config`: Criar ou atualizar uma configuração\n- `PUT /api/config/:key`: Atualizar uma configuração específica\n- `DELETE /api/config/:key`: Excluir uma configuração\n\n#### Configuração de API Externa\n\n- `POST /api/config/external-api/config`: Configurar as configurações da API externa\n- `POST /api/config/external-api/mappings`: Configurar mapeamentos de função\n- `POST /api/config/external-api/clear-cache`: Limpar cache da API\n- `POST /api/config/test-api`: Testar conexão com a API\n\n#### Gerenciamento de Conversas\n\n- `GET /api/conversations`: Obter todas as conversas (com paginação)\n- `GET /api/conversations/:id`: Obter uma conversa específica com mensagens\n- `POST /api/conversations`: Criar uma nova conversa\n- `POST /api/conversations/:id/pause`: Pausar uma conversa\n- `POST /api/conversations/:id/resume`: Retomar uma conversa\n- `GET /api/conversations/:id/status`: Obter status da conversa\n- `POST /api/conversations/:id/messages`: Adicionar uma mensagem a uma conversa\n- `GET /api/conversations/search/messages`: Pesquisar mensagens\n\n#### Endpoints Legados (Obsoletos)\n\n- `POST /conversation/:id/pause`: Pausar uma conversa\n- `POST /conversation/:id/resume`: Retomar uma conversa\n- `GET /conversation/:id/status`: Obter status da conversa\n\n### Comandos do Bot\n\nO bot não possui comandos específicos. Os usuários podem simplesmente enviar mensagens, e o assistente de IA responderá de acordo com suas capacidades e persona.\n\n## Gerenciamento de Configuração\n\nO sistema usa uma abordagem de configuração em camadas:\n\n1. **Configuração de Banco de Dados**: Fonte primária de configuração\n2. **Cache de Memória**: Para acesso rápido à configuração\n3. **Variáveis de Ambiente**: Fallback e valores iniciais\n\nA configuração pode ser atualizada via API ou através de scripts de banco de dados.\n\n## Integração com API Externa\n\nO sistema inclui um Serviço de API Externa flexível para conexão com serviços externos:\n\n- Cliente HTTP genérico com suporte para múltiplos métodos (GET, POST, PUT, DELETE, PATCH)\n- Mapeamento de funções para traduzir chamadas de função da IA para endpoints de API\n- Suporte a autenticação (Basic, Bearer, API Key)\n- Cache de requisições\n- Mecanismo de retry com backoff exponencial\n- Sistema de logging\n\n## Desenvolvimento\n\n### Scripts\n\n- `npm start`: Iniciar a aplicação\n- `npm run migrate`: Executar migrações de banco de dados\n- `npm run update-openai-key`: Atualizar chave da API OpenAI\n- `npm run migrate-env-to-db`: Migrar variáveis de ambiente para o banco de dados\n\n### Notas Importantes\n\n1. **Cache de Threads**: As threads são armazenadas em cache na memória para melhor desempenho\n2. **Agregação de Mensagens**: Mensagens de texto são agregadas por 3 segundos para melhorar a experiência do usuário\n3. **Tratamento de Erros**: O sistema implementa mecanismos robustos de tratamento de erros e retry\n4. **Logging**: Logging extensivo para fins de depuração\n\n## Considerações de Segurança\n\n- Chaves de API da OpenAI são mascaradas nos logs\n- Valores sensíveis (chaves de API, URLs de banco de dados) são mascarados nas respostas da API\n- Autenticação é necessária para o WhatsApp Web usando código QR\n- Valores de configuração podem ser criptografados no banco de dados\n- Proteção CORS no servidor da API\n\n## Limitações\n\n- Requer uma sessão ativa do WhatsApp (re-autenticação necessária se desconectado)\n- Depende da disponibilidade do serviço da OpenAI\n- Limitado pela taxa da API da OpenAI\n- Limitações de tamanho de arquivo para processamento de mídia\n\n## Solução de Problemas\n\n### Problemas Comuns\n\n1. **Falha na Autenticação**: A sessão do WhatsApp pode ter expirado. Reinicie o bot e escaneie o código QR novamente.\n2. **Erros da API OpenAI**: Verifique a validade da chave de API e limites de cota.\n3. **Problemas de Conexão com o Banco de Dados**: Verifique se o DATABASE_URL está correto e o banco de dados está acessível.\n4. **Problemas de Conexão com o Redis**: Certifique-se de que o Redis está em execução e o REDIS_URL está correto.\n\n### Logs\n\nA aplicação registra logs extensivamente para ajudar a diagnosticar problemas. Verifique a saída do console para:\n\n- Status da conexão do WhatsApp\n- Detalhes de processamento de mensagens\n- Chamadas e respostas da API\n- Alterações de configuração\n- Mensagens de erro com stack traces\n\n## Licença\n\nEste projeto é um software proprietário. Distribuição não autorizada é proibida.\n\n## Contribuidores\n\nEste projeto foi desenvolvido por mim mesmo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegagarra%2Fsuper-chatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmegagarra%2Fsuper-chatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegagarra%2Fsuper-chatbot/lists"}