{"id":28715177,"url":"https://github.com/green-api/greenapi-integration-gohighlevel","last_synced_at":"2026-04-24T12:31:28.957Z","repository":{"id":294154209,"uuid":"983880782","full_name":"green-api/greenapi-integration-gohighlevel","owner":"green-api","description":"GREEN-API integration GoHighLevel","archived":false,"fork":false,"pushed_at":"2025-07-21T23:52:33.000Z","size":872,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-22T06:33:44.962Z","etag":null,"topics":["chatbot","gohighlevel","gohighlevel-api","green-api","greenapi","whatsapp","whatsapp-api"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/green-api.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2025-05-15T04:08:41.000Z","updated_at":"2025-07-21T23:52:33.000Z","dependencies_parsed_at":"2025-05-19T06:24:54.587Z","dependency_job_id":"15f304cb-a4ea-405d-8c26-04cef5088d3e","html_url":"https://github.com/green-api/greenapi-integration-gohighlevel","commit_stats":null,"previous_names":["green-api/greenapi-integration-gohighlevel"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/green-api/greenapi-integration-gohighlevel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fgreenapi-integration-gohighlevel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fgreenapi-integration-gohighlevel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fgreenapi-integration-gohighlevel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fgreenapi-integration-gohighlevel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/green-api","download_url":"https://codeload.github.com/green-api/greenapi-integration-gohighlevel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fgreenapi-integration-gohighlevel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32223803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T10:26:35.452Z","status":"ssl_error","status_checked_at":"2026-04-24T10:25:27.643Z","response_time":64,"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":["chatbot","gohighlevel","gohighlevel-api","green-api","greenapi","whatsapp","whatsapp-api"],"created_at":"2025-06-15T02:01:00.728Z","updated_at":"2026-04-24T12:31:28.952Z","avatar_url":"https://github.com/green-api.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [GREEN-API](https://green-api.com/en) Integration with [GoHighLevel](https://www.gohighlevel.com)\n\nThis integration enables WhatsApp communication within [GoHighLevel](https://www.gohighlevel.com) (GHL) using\nthe [GREEN-API](https://green-api.com/en) platform. Built on\nthe [Universal Integration Platform](https://github.com/green-api/greenapi-integration)\nby [GREEN-API](https://green-api.com/en), it consists of a\nNestJS adapter service that bridges the connection between the two platforms.\n\n## Overview\n\nThis documentation guides you through setting up your own integration between [GREEN-API](https://green-api.com/en)\nand [GoHighLevel](https://www.gohighlevel.com). You will:\n\n1. Create your own [GoHighLevel](https://www.gohighlevel.com) Marketplace app\n2. Configure and deploy the adapter service\n3. Link one or multiple [GREEN-API](https://green-api.com/en) instances with\n   your [GoHighLevel](https://www.gohighlevel.com)\n   sub-account through an easy-to-use management interface\n\n## Architecture\n\n### Adapter Service\n\nThe NestJS application that:\n\n- Handles message mapping between [GoHighLevel](https://www.gohighlevel.com) and WhatsApp\n- Manages [GoHighLevel](https://www.gohighlevel.com) OAuth authentication and token management for sub-accounts\n- Provides webhook endpoints for both [GoHighLevel](https://www.gohighlevel.com)\n  and [GREEN-API](https://green-api.com/en)\n- Creates and manages contacts from WhatsApp in [GoHighLevel](https://www.gohighlevel.com)\n- Supports multiple [GREEN-API](https://green-api.com/en) instances per sub-account with a user-friendly management\n  interface\n\n## Prerequisites\n\n- MySQL database (5.7 or higher)\n- Node.js 20 or higher\n- [GREEN-API](https://green-api.com/en) account and instance(s)\n- A [GoHighLevel](https://www.gohighlevel.com) **Developer Account**. You can create one\n  at [https://marketplace.gohighlevel.com/](https://marketplace.gohighlevel.com/)\n- A [GoHighLevel](https://www.gohighlevel.com) **Sub-Account** for testing the app installation and functionality\n- A publicly accessible URL for the adapter service (for webhooks)\n\n## Step 1: Setting Up the [GoHighLevel](https://www.gohighlevel.com) Marketplace App\n\nBefore deploying the adapter service, you need to create and configure a [GoHighLevel](https://www.gohighlevel.com)\nMarketplace app:\n\n1. **Register and log in** at [https://marketplace.gohighlevel.com/](https://marketplace.gohighlevel.com/)\n\n2. **Create a new app:**\n    - Navigate to the Apps section and click \"Create New App\"\n    - Fill in your app's basic information (name, description, etc.)\n\n3. **Configure listing settings:**\n    - In the app configuration, find \"Listing Configuration\"\n    - **IMPORTANT:** Select **only \"Sub-Account\"** as the installation option\n    - Do NOT select \"Agency\" or \"Both\" as this can cause functionality issues\n\n4. **Set up OAuth:**\n    - Go to \"Advanced Settings\" -\u003e \"Auth\"\n    - Configure the redirect URL: `YOUR_APP_URL/oauth/callback`\n    - Select the required scopes:\n        - contacts.readonly\n        - contacts.write\n        - conversations.readonly\n        - conversations.write\n        - conversations/message.readonly\n        - conversations/message.write\n        - locations.readonly\n        - users.readonly\n\n5. **Generate credentials:**\n    - Go to the \"Client Keys\" section\n    - Generate a Client ID and Client Secret\n    - A little below there will be \"Shared Secret\" section — generate it as well.\n    - Save these values - you'll need them for the adapter configuration\n\n6. **Create a Conversation Provider:**\n    - Navigate to \"Conversation Provider\" in the app settings\n    - Name: \"[GREEN-API](https://green-api.com/en)\" (or any name you prefer)\n    - Type: **SMS**\n    - Delivery URL: `YOUR_APP_URL/webhooks/ghl` (same as webhook URL)\n    - Check both \"Is this a Custom Conversation Provider?\" and \"Always show this Conversation Provider?\"\n    - Add an alias and logo if desired\n    - Save the Conversation Provider ID - you'll need it for configuration\n\n7. **Configure Custom Page:**\n    - Enable Custom Page functionality\n    - Set Custom Page URL to: `YOUR_APP_URL/app/whatsapp`\n    - This will provide users with an interface to manage their GREEN-API instances\n\n## Step 2: Setting Up the Adapter\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/green-api/greenapi-integration-gohighlevel.git\n   cd greenapi-integration-gohighlevel\n   ```\n\n2. **Install dependencies:**\n\n   ```bash\n   npm install\n   ```\n\n3. **Set up environment variables:**\n\n   Create a `.env` file in the root of the project with the following variables:\n\n   ```env\n   DATABASE_URL=\"mysql://USER:PASSWORD@HOST:PORT/DATABASE_NAME\"\n   APP_URL=\"https://your-adapter-domain.com\"\n   GHL_CLIENT_ID=\"your_ghl_client_id_from_developer_portal\"\n   GHL_CLIENT_SECRET=\"your_ghl_client_secret_from_developer_portal\"\n   GHL_CONVERSATION_PROVIDER_ID=\"your_ghl_conversation_provider_id_from_app_settings\"\n   GHL_SHARED_SECRET=\"your_shared_secret_from_developer_portal\"\n   ```\n\n    - `DATABASE_URL`: Your MySQL connection string\n    - `APP_URL`: The public URL where your adapter will be deployed\n    - `GHL_CLIENT_ID` and `GHL_CLIENT_SECRET`: From step 5 in the GHL app setup\n    - `GHL_CONVERSATION_PROVIDER_ID`: From step 7 in the GHL app setup\n    - `GHL_SHARED_SECRET`: From step 5 in the GHL app setup\n\n4. **Apply database migrations:**\n\n   ```bash\n   npx prisma migrate deploy\n   ```\n\n5. **Build and start the adapter:**\n\n   ```bash\n   # Build the application\n   npm run build\n\n   # Start in production mode\n   npm run start:prod\n   ```\n\n## Step 3: Deployment\n\nThe adapter can be deployed using Docker. Configuration files:\n\n### Docker Compose Setup (`docker-compose.yml`)\n\n```yaml\nversion: '3.8'\n\nservices:\n  adapter:\n    build: .\n    ports:\n      - \"3000:3000\"\n    environment:\n      - DATABASE_URL=${DATABASE_URL}\n      - APP_URL=${APP_URL}\n      - GHL_CLIENT_ID=${GHL_CLIENT_ID}\n      - GHL_CLIENT_SECRET=${GHL_CLIENT_SECRET}\n      - GHL_CONVERSATION_PROVIDER_ID=${GHL_CONVERSATION_PROVIDER_ID}\n      - GHL_SHARED_SECRET=${GHL_SHARED_SECRET}\n    depends_on:\n      - db\n    restart: unless-stopped\n\n  db:\n    image: mysql:8\n    environment:\n      - MYSQL_ROOT_PASSWORD=your_strong_root_password\n      - MYSQL_USER=your_db_user\n      - MYSQL_PASSWORD=your_db_password\n      - MYSQL_DATABASE=ghl_adapter\n    volumes:\n      - mysql_data:/var/lib/mysql\n    restart: unless-stopped\n\nvolumes:\n  mysql_data:\n```\n\n### Dockerfile\n\n```dockerfile\nFROM node:20-alpine\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci\nCOPY . .\nRUN npx prisma generate\nRUN npm run build\nEXPOSE 3000\nCMD npx prisma migrate deploy \u0026\u0026 npm run start:prod\n```\n\nTo deploy using Docker Compose:\n\n```bash\n# Start all services\ndocker-compose up -d\n\n# Check logs\ndocker-compose logs -f\n\n# Stop all services\ndocker-compose down\n```\n\nNote: The deployment configuration is provided as a reference and may need adjustments based on your specific\nenvironment and requirements.\n\n## Step 4: Installing and Using the Integration\n\nOnce your [GoHighLevel](https://www.gohighlevel.com) app is configured and your adapter service is deployed, you can\ninstall and use the integration:\n\n1. **Install the app in your [GoHighLevel](https://www.gohighlevel.com) sub-account:**\n    - Go to \"App Marketplace\" (located in the side panel)\n    - If your app is private:\n        - Copy your app's ID from marketplace.gohighlevel.com\n        - Click on any app and modify the URL by replacing the app ID portion with your app's ID\n    - If your app is public, you can just search for it\n    - Click \"Install\" on your app's page and then \"Allow and Install\"\n\n2. **Access the WhatsApp Instance Management Interface:**\n    - After installation, you can go to the custom page to manage your GREEN-API instances (will appear in the side\n      panel)\n    - The interface will allow you to add/manage multiple instances\n\n3. **Add GREEN-API Instances:**\n    - Use the management interface to add your GREEN-API instances\n    - For each instance, provide:\n        - Instance Name (optional, for easy identification)\n        - Instance ID (from console.green-api.com)\n        - API Token (from console.green-api.com)\n    - You can add multiple instances and manage them independently\n\n4. **Manage Your Instances:**\n    - View all your connected GREEN-API instances\n    - Edit instance names\n    - Delete instances when no longer needed\n    - Monitor instance status and authorization state\n\n## How the Integration Works\n\nOnce installed, the integration works automatically:\n\n### Incoming Messages (WhatsApp → GHL)\n\n1. When a customer sends a message to any of your WhatsApp numbers:\n    - [GREEN-API](https://green-api.com/en) receives the message and sends it to your adapter\n    - The adapter creates or updates the contact in GHL\n    - The contact is tagged with the specific instance ID they contacted (You must not change this tag in any way)\n    - The message appears in GHL's conversation interface\n\n2. Supported incoming message types:\n    - Text messages\n    - Media (images, videos, documents, audio)\n    - Location shares\n    - Contact cards\n    - And more (stickers, polls, etc.)\n\n3. **Group Support:**\n    - **Group messages are fully supported** - when someone sends a message in a WhatsApp group\n    - **Group contacts** are created with names like `[Group] Sales Team` to clearly identify them as groups\n    - **Group \"phone\" numbers** are actually the group's chat ID (a long numeric identifier like `120363418570879210`)\n    - **Group messages** show the sender's name and their phone number: `John Doe (+1234567890): Hello everyone!`\n\n### Outgoing Messages (GHL → WhatsApp)\n\n1. To reply to a WhatsApp contact:\n    - Use GHL's standard messaging interface\n    - The message will be routed through your adapter to the appropriate [GREEN-API](https://green-api.com/en) instance\n      based on the contact's tag\n\n2. Supported outgoing message types:\n    - Text messages\n    - File attachments\n\n### Important Note\n\n**⚠️ Multi-Instance Conversations:** If the same phone number writes to multiple of your GREEN-API instances (different WhatsApp numbers),\nthis integration will **not** create separate conversations. All messages from that phone number, regardless of which\ninstance they contact, will appear in a **single conversation thread**.\n\n**📱 Group Identification:** Group contacts can be easily identified by:\n\n- Contact name starting with `[Group]`\n- Phone field containing a long numeric ID instead of a traditional phone number\n- `whatsapp-group` tag automatically applied to group contacts\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Messages not being delivered:**\n    - Check adapter logs for any errors\n    - Ensure webhook URLs are correctly configured\n    - Verify instance status in the management interface\n\n2. **Instance management problems:**\n    - Verify OAuth authentication is completed first\n    - Check that all required environment variables are set\n    - Ensure the custom page can communicate with your adapter service\n\n3. **Database connection errors:**\n    - Verify your DATABASE_URL is correct\n    - Ensure the database user has proper permissions\n    - Check that database migrations have been applied\n\n## License\n\n[MIT](./LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-api%2Fgreenapi-integration-gohighlevel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgreen-api%2Fgreenapi-integration-gohighlevel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-api%2Fgreenapi-integration-gohighlevel/lists"}