@joai/n8n-nodes-joai

This is an n8n community node that provides integration with JoAI (AI Agent Platform). It allows you to send messages as AI agents and receive real-time webhooks for agent events.

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
Credentials
Compatibility
Usage
Resources

Installation

Follow the installation guide in the n8n community nodes documentation.

Community Node Installation

1. Go to Settings > Community Nodes.
2. Select Install.
3. Enter @joai/n8n-nodes-joai in Enter npm package name.
4. Agree to the risks of using community nodes: select I understand the risks of installing unverified code from a public source.
5. Select Install.

After installing the node, you can use it like any other node in n8n.

Operations

JoAI Node

• Send Message: Send a message as a JoAI agent to a specific room or conversation

JoAI Trigger

• Webhook Events: Receive real-time events from JoAI agents
  • Agent Actions
  • Agent Messages
  • User Messages

Credentials

This node requires JoAI API credentials. You need:

1. API Key: Your JoAI API authentication key
2. Base URL: The base URL for your JoAI API instance (e.g., https://api.joai.com)

Setting up credentials

1. In n8n, go to Settings > Credentials.
2. Select Create New.
3. Search for JoAI API and select it.
4. Enter your API Key and Base URL.
5. Click Save.

Compatibility

• Minimum n8n version: 0.198.0
• Tested with n8n version: 1.99.1

Usage

Basic Message Sending

1. Add a JoAI node to your workflow
2. Select Send Message operation
3. Choose your JoAI credentials
4. Configure the message parameters:
   • Agent ID: The UUID of the agent that will send the message
   • Message: The content to send
   • Room (optional): Room or conversation ID to send to
   • Additional Fields (optional): Message type and metadata
5. Execute the workflow

Setting up Webhooks

1. Add a JoAI Trigger node to your workflow
2. Configure your JoAI credentials
3. Enter the Agent ID you want to monitor
4. Select the event types you want to trigger on:
   • agent.action - When the agent performs an action
   • agent.message - When the agent sends a message
   • user.message - When a user sends a message
5. Optionally add filters for room, message content, or user email
6. Activate the workflow

The trigger will automatically register a webhook with your JoAI instance and start receiving real-time events.

Example Workflow

Here's a simple workflow that responds to user messages:

{
  "nodes": [
    {
      "name": "JoAI Trigger",
      "type": "@joai/n8n-nodes-joai.joaiTrigger",
      "parameters": {
        "agentId": "123e4567-e89b-12d3-a456-426614174000",
        "triggerEvents": ["user.message"],
        "webhookName": "Auto-Response Webhook"
      }
    },
    {
      "name": "Process Message",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "// Extract message content from webhook payload\nconst userMessage = $input.item.json.data.content || '';\nconst room = $input.item.json.data.room || '';\n\nreturn {\n  json: {\n    response: `Hello! You said: \"${userMessage}\"`,\n    originalRoom: room\n  }\n};"
      }
    },
    {
      "name": "Send Response",
      "type": "@joai/n8n-nodes-joai.joai",
      "parameters": {
        "operation": "sendMessage",
        "agentId": "123e4567-e89b-12d3-a456-426614174000",
        "message": "={{ $json.response }}",
        "room": "={{ $json.originalRoom }}"
      }
    }
  ]
}

Resources

• n8n community nodes documentation
• JoAI API Documentation
• GitHub Repository

Version history

0.1.1

• Updated documentation to accurately reflect current functionality
• Corrected README descriptions and examples

0.1.0

• Initial release
• Send messages as JoAI agents with support for:
  • Agent ID specification
  • Room/conversation targeting
  • Message types (text, system, error)
  • Custom metadata
• Webhook trigger support for real-time events:
  • Agent actions
  • Agent messages
  • User messages
• Advanced filtering capabilities:
  • Room-specific filtering
  • Message content filtering
  • User email filtering

Support

If you encounter any issues or have questions:

1. Check the GitHub Issues
2. Create a new issue if your problem isn't already reported
3. Provide as much detail as possible including n8n version, node version, and error messages

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

License

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