Future Systems Connector for n8n

Exclusive Future Systems GoHighLevel connector for n8n workflow automation.

Features

• Complete GoHighLevel Integration: Full support for contacts, tags, notes, courses, workflows, and DND settings
• Robust Error Handling: Automatic retries with exponential backoff and fallback endpoints
• Proxy Support: Route requests through proxy servers for enhanced security
• Idempotency: Prevent duplicate operations with idempotency keys
• Future-Proof: Built with TypeScript and comprehensive endpoint fallbacks

Installation

Community Nodes (Recommended)

1. In your n8n instance, go to Settings → Community Nodes
2. Click Install a community node
3. Enter: n8n-nodes-future-systems-connector
4. Click Install

Docker Installation

If you're running n8n in Docker, you can install the node by copying it to your n8n container:

# Copy the built node to your n8n container
docker cp dist/ your-n8n-container:/home/node/.n8n/nodes/

# Restart your n8n container
docker restart your-n8n-container

Credentials Setup

1. Create a new credential of type Future Systems API
2. Configure the following fields:
   • Base URL: https://rest.gohighlevel.com (default)
   • API Key: Your GoHighLevel Location API key
   • Use Proxy: Enable if routing through a proxy server
   • Proxy Base URL: Your proxy server URL (only shown when Use Proxy is enabled)

Getting Your API Key

1. Log into your GoHighLevel account
2. Go to Settings → API Keys
3. Create a new API key with appropriate permissions
4. Copy the key and paste it into the credentials

Operations

Contact Operations

Create Contact

Creates a new contact in GoHighLevel.

Required Fields:

• Email

Optional Fields:

• First Name
• Last Name
• Phone
• Tags (comma-separated)
• Custom Fields (key-value pairs)
• Idempotency Key

Example:

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "tags": "lead,premium",
  "customFields": {
    "source": "website",
    "priority": "high"
  }
}

Update Contact

Updates an existing contact.

Required Fields:

• Contact ID

Optional Fields:

• First Name
• Last Name
• Phone
• Tags (comma-separated)
• Custom Fields (key-value pairs)

Find by Email

Finds a contact by their email address.

Required Fields:

• Email

Tag Operations

Add Tags

Adds tags to a contact.

Required Fields:

• Contact ID
• Tag List (comma-separated)

Example:

Contact ID: contact_123
Tag List: premium,engaged,hot-lead

Remove Tags

Removes tags from a contact. Automatically tries JSON body first, then falls back to query parameters.

Required Fields:

• Contact ID
• Tag List (comma-separated)

Note Operations

Add Note

Adds a note to a contact.

Required Fields:

• Contact ID
• Note

Example:

Contact ID: contact_123
Note: Customer called asking about pricing. Very interested in premium package.

Course Operations

Enroll

Enrolls a contact in a course.

Required Fields:

• Contact ID
• Course ID

Optional Fields:

• Offer ID
• Idempotency Key

Unenroll

Unenrolls a contact from a course.

Required Fields:

• Contact ID
• Course ID

Workflow Operations

Add to Workflow

Adds a contact to a workflow.

Required Fields:

• Contact ID
• Workflow ID
• Idempotency Key

Remove from Workflow

Removes a contact from a workflow.

Required Fields:

• Contact ID
• Workflow ID

Do Not Disturb Operations

Enable DND

Enables do not disturb for specified channels.

Required Fields:

• Contact ID
• Channels (multi-select: SMS, Email, Call, WhatsApp)

Disable DND

Disables do not disturb for specified channels.

Required Fields:

• Contact ID
• Channels (multi-select: SMS, Email, Call, WhatsApp)

Raw API Operations

Passthrough

Makes a raw API request to GoHighLevel.

Required Fields:

• Method (GET, POST, PUT, DELETE, PATCH)
• Path

Optional Fields:

• Body (JSON for POST/PUT/PATCH requests)

Example:

Method: GET
Path: /v1/contacts?limit=10&startAfterId=contact_123

Error Handling

The connector includes robust error handling:

• Automatic Retries: 3 attempts with exponential backoff for 5xx errors and rate limits (429)
• Fallback Endpoints: Tries alternative API endpoints when primary endpoints fail
• Continue on Fail: Returns errors as items instead of stopping the workflow
• Informative Errors: Includes status codes, paths, and response bodies in error messages

Output Format

All operations return data in the following format:

{
  "success": true,
  "data": {
    // Response data from GoHighLevel API
  },
  "meta": {
    "statusCode": 200,
    "responseTime": 150,
    "attemptedPaths": ["POST /v1/contacts/", "POST /v1/contacts"]
  }
}

When errors occur and "Continue on Fail" is enabled:

{
  "error": "Error message describing what went wrong"
}

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Project Structure

├── credentials/
│   └── FutureSystemsApi.credentials.ts    # Credential configuration
├── nodes/
│   └── FutureSystems/
│       ├── FutureSystems.node.ts          # Main node implementation
│       └── descriptions.ts                # Resource and operation descriptions
├── utils/
│   ├── apiRequest.ts                      # HTTP request helper with retries
│   ├── endpoints.ts                       # API endpoint configuration
│   └── __tests__/                        # Unit tests
├── dist/                                 # Built files (generated)
├── package.json                          # Package configuration
├── tsconfig.json                         # TypeScript configuration
└── README.md                             # This file

Changelog

v1.0.0 (2024-01-XX)

Initial Release

• ✅ Complete GoHighLevel API integration
• ✅ Contact management (create, update, find by email)
• ✅ Tag management (add, remove with fallback support)
• ✅ Note management (add with fallback support)
• ✅ Course enrollment (enroll, unenroll with fallback support)
• ✅ Workflow management (add, remove)
• ✅ Do Not Disturb settings (enable, disable)
• ✅ Raw API passthrough
• ✅ Proxy support for enhanced security
• ✅ Idempotency key support
• ✅ Comprehensive error handling with retries
• ✅ Fallback endpoint support
• ✅ TypeScript strict mode
• ✅ Unit tests for critical functionality
• ✅ Continue on Fail support

Support

For support and questions:

• Documentation: Future Systems Docs
• Issues: GitHub Issues
• Email: [email protected]

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions! Please see our contributing guidelines for more information.

Future Systems Connector - Making GoHighLevel automation simple and reliable.