Skip to content

Latest commit

 

History

History
270 lines (207 loc) · 5.99 KB

README.md

File metadata and controls

270 lines (207 loc) · 5.99 KB

Chatwoot-Gupshup Integration Service

This service provides a bridge between Chatwoot and Gupshup, enabling seamless WhatsApp communication through Chatwoot's interface. It handles message synchronization, media transfers, and conversation management between both platforms.

Features

  • Bidirectional message sync between Chatwoot and Gupshup
  • Support for various message types:
    • Text messages
    • Images with captions
    • Audio messages
    • Video messages
    • Document files
    • Contact cards
    • Location sharing
    • Button responses
    • List responses
  • Automatic contact creation and management
  • Conversation state management
  • Support for customer satisfaction surveys

Prerequisites

  • Node.js (v14 or higher)
  • npm or yarn
  • A Chatwoot instance with API access
  • A Gupshup WhatsApp Business API account
  • Environment variables configuration

Installation

  1. Clone the repository:
git clone https://github.com/hirotadev/chatwoot-gupshup-integration.git
cd chatwoot-gupshup-integration
  1. Install dependencies:
npm install
  1. Create a .env file in the root directory with the following variables:
# Server Configuration
PORT=3000

# Chatwoot Configuration
CHATWOOT_BASE_URL=https://your-chatwoot-instance.com
CHATWOOT_API_TOKEN=your_chatwoot_api_token
CHATWOOT_ACCOUNT_ID=your_chatwoot_account_id
INBOX_ID=your_chatwoot_inbox_id

# Gupshup Configuration
GUPSHUP_API_KEY=your_gupshup_api_key
GUPSHUP_PHONE=your_whatsapp_phone_number
GUPSHUP_SRC_NAME=your_gupshup_source_name
GUPSHUP_APP_ID=your_gupshup_app_id
  1. Start the service:
# Development mode
npm run dev

# Production mode
npm start

Webhook Configuration

Gupshup Webhook Setup

  1. Log in to your Gupshup dashboard
  2. Navigate to WhatsApp API > Configuration
  3. Set the webhook URL to:
https://your-domain.com/webhook/gupshup

Chatwoot Webhook Setup

  1. Go to your Chatwoot installation
  2. Navigate to Settings > Integrations > Webhooks
  3. Add a new webhook with the URL:
https://your-domain.com/webhook/chatwoot
  1. Enable the following events:
    • Message Created
    • Conversation Updated

Architecture

The service is built using a modular architecture with the following components:

  • src/config: Environment configuration
  • src/services: Core business logic for Chatwoot and Gupshup integration
  • src/utils: Utility functions for message parsing and phone number formatting
  • src/routes: API endpoint definitions

Development

Project Structure

.
├── README.md
├── index.js
├── package.json
└── src
    ├── config
    │   └── environment.js
    ├── routes
    │   └── webhooks.js
    ├── services
    │   ├── chatwootService.js
    │   └── gupshupService.js
    └── utils
        ├── messageParser.js
        └── phoneUtils.js

Running Tests

TODO

Code Style

This project uses ESLint and Prettier for code formatting. Run the following commands:

TODO

Error Handling

The service implements comprehensive error handling:

  • All API endpoints return 200 status codes to acknowledge webhook receipt
  • Errors are logged but don't interrupt service operation
  • Failed message deliveries are logged for manual review
  • Phone number validation ensures E.164 format compliance

Production Deployment

Using Docker

  1. Build the Docker image:
docker build -t chatwoot-gupshup-integration .
  1. Run the container:
docker run -d \
  --name chatwoot-gupshup \
  -p 3000:3000 \
  --env-file .env \
  chatwoot-gupshup-integration

Using PM2

  1. Install PM2:
sudo npm install -g pm2
  1. Start the service:
pm2 start npm --name "chatwoot-gupshup" -- start

Nginx Configuration

If using Nginx as a reverse proxy:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Security Considerations

  • All environment variables should be kept secure
  • Use HTTPS for webhook endpoints
  • Implement rate limiting in production
  • Regular security audits recommended
  • Keep dependencies updated

Monitoring

The service includes basic logging through Fastify's logger. For production monitoring:

  1. Use tools like:

    • PM2 for process management
    • Datadog or New Relic for application monitoring
    • ELK Stack for log management

  2. Monitor key metrics:

    • Message delivery rates
    • API response times
    • Error rates
    • System resource usage

Troubleshooting

Common issues and solutions:

  1. Message not being delivered:

    • Check webhook configurations
    • Verify API credentials
    • Check phone number format

  2. Connection errors:

    • Verify network connectivity
    • Check API endpoint availability
    • Validate environment variables

  3. Media upload failures:

    • Check file size limits
    • Verify supported file types
    • Ensure proper URL formatting

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support:

  1. Check the issues section for known problems
  2. Create a new issue for unreported problems
  3. Contact the maintainers for critical issues

Acknowledgments

  • Chatwoot team for their excellent platform
  • Gupshup team for their WhatsApp Business API
  • Contributors and community members

Roadmap

Future planned features:

  • Support for template messages
  • Advanced message queueing
  • Dashboard for monitoring
  • Automated testing improvements
  • Multi-language support