NucleusNucleus

Developers

Plugin Quick Start

Build and install your first plugin in 15 minutes.

What you'll build

In this guide, you'll create a simple plugin that gives the AI agent a "get_weather" tool. When a customer asks about the weather, the agent will call your plugin to get the answer.

Step 1: Create your manifest

Create a JSON file that describes your plugin. This is the manifest — it tells the platform what your plugin does and what tools it provides.

Create a file called manifest.json:

json
{
  "slug": "WEATHER_DEMO",
  "version": "1.0.0",
  "name": "Weather Demo",
  "description": "A demo plugin that returns weather information",
  "baseUrl": "https://your-server.com",
  "auth": {
    "type": "none"
  },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather for a city. Call this when a user asks about the weather in a specific location.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city name to get weather for"
          }
        },
        "required": ["city"]
      }
    }
  ]
}

Host this file at a public URL (e.g., https://your-server.com/manifest.json).

Step 2: Build your endpoint

Create an HTTP server that handles tool calls. The platform will send POST requests to your baseUrl when the agent uses your tools.

Here's a simple example using Node.js and Express:

javascript
const express = require('express');
const app = express();
app.use(express.json());
 
app.post('/execute', (req, res) => {
  const { tool, input, context } = req.body;
 
  if (tool === 'get_weather') {
    // In a real plugin, you'd call a weather API here
    res.json({
      city: input.city,
      temperature: '24°C',
      condition: 'Partly cloudy',
      humidity: '65%'
    });
  } else {
    res.status(404).json({ error: 'Unknown tool' });
  }
});
 
app.listen(3000, () => {
  console.log('Plugin server running on port 3000');
});

The request body your endpoint receives looks like this:

json
{
  "tool": "get_weather",
  "input": {
    "city": "Nairobi"
  },
  "context": {
    "organizationId": "org_abc123",
    "instanceId": "inst_xyz789",
    "user": {
      "id": "hashed_user_id",
      "hashVersion": 1
    },
    "config": {}
  }
}

Your endpoint should return a JSON response with the result. The agent will use whatever you return to inform its response to the customer.

Step 3: Install in sandbox mode

  1. Go to the Plugin Dev Portal in the dashboard sidebar
  2. Click Install Sandbox Plugin
  3. Enter the URL to your hosted manifest (e.g., https://your-server.com/manifest.json)
  4. Click Install

The platform will:

  • Fetch and validate your manifest
  • Create the plugin entry
  • Generate a sandbox secret (shown once — save it)
  • Send a confirmation email with the secret

The sandbox secret is used to verify that tool calls are coming from the platform. See Authentication for details.

Step 4: Grant the plugin to your instance

  1. Go to your instance's Integrations page
  2. Find your newly installed plugin
  3. Grant it access to the instance

Step 5: Test it

Send a message to your connected WhatsApp number asking about the weather:

"What's the weather like in Nairobi?"

The AI agent should:

  1. Recognize this is a weather question
  2. Call your get_weather tool with { "city": "Nairobi" }
  3. Receive the result from your endpoint
  4. Respond to the customer with the weather information

Importing from OpenAPI

If you already have an API with an OpenAPI (Swagger) specification, you can automatically generate a plugin manifest from it:

  1. Go to the Plugin Dev Portal
  2. Use the Generate from OpenAPI option
  3. Enter the URL to your OpenAPI spec
  4. The platform converts your API operations into plugin tools (up to 20 tools)
  5. Review the generated manifest and install it

This is the fastest way to turn an existing API into a plugin.

Next steps